Best Practices: Running Cognitive Toolkit as an elevated user without credentials
Objective of Cognitive Toolkit Runner
A user needs to run Shinydocs Cognitive Toolkit with elevated permissions, but the user cannot know the credentials for the elevated user. For security purposes, this prevents the user from gaining additional network privileges. When the operator runs cognitivetoolkitrunner.exe, it will execute Cognitive Toolkit as the elevated user using saved credentials.
How does it work?
The storage mechanism for the service account operates in the following manner:
The username, password and domain are stored encrypted in a file named runner-credentials.yaml located in the same directory as the CognitiveToolkitRunner.exe
The credentials are encrypted using the Windows Data Protection API, and encrypted so that only the current user can decrypt them. This prevents users from sharing credential files.
The CognitiveToolkit.exe is expected to be in the same directory as the CognitiveToolkitRunner.exe.
The CognitiveToolkitRunner.exe verifies that the CognitiveToolkit.exe is digitally signed and ensures that it has the appropriate Shinydocs certificate. This prevents users from swapping CognitiveToolkit.exe with a malicious executable.
Step-by-step:
To save credentials, run:
CognitiveToolkitRunner.exe SaveCredentials
Cognitive Toolkit will need to be activated as the elevated user, since Cognitive Toolkit is activated on a per user basis:
1 CognitiveToolkitRunner Activate --path <path to license file>
2. The user will be prompted for the domain, username and password. In the case of the local system, the domain will be the machine name:
3. A file containing the encrypted domain, username and password will be created. This file is called runner-credentials.yaml:
4. The runner will check to ensure the cognitivetoolkit.exe is digitally signed by the Shinydocs Corporation certificate. For security purposes, this prevents a malicious user from copying in a different exe with the name CognitiveToolkit.exe, and getting it to run under the elevated permissions.
5. The default action of the CognitiveToolkitRunner is to run CognitiveToolkit as the elevated user using the arguments provided to it. By default it will redirect output from the cognitivetoolkit.exe into the window being used to run cognitivetoolkitrunner.exe.
CognitiveToolkitRunner.exe CrawlFileSystem --path C:\files\to\crawl --index-server-url http://localhost:9200 --index-name crawledfiles6. Some tools have a progress indicator. If the user wishes to see the progress on text extraction for example, they can provide the argument -show or --show-cog-window to display cog in a new window. This window will close once the process is complete to avoid giving a user an elevated command prompt. It is useful for being able to see the process of a long running operation, but not for seeing the end result.
CognitiveToolkitRunner.exe --show-cog-window AddExtractedText --index-server-url http://localhost:9200 --index-name crawledfiles --query C:\matchall.json