Set up a security backend for Windows
StackState Self-hosted v5.1.x
Last updated
StackState Self-hosted v5.1.x
Last updated
This document explains the process of setting up a security backend on a Windows system. You can find more information in the .
StackState Agent V2 runs the secret_backend_command
executable as a sub-process. On Windows, the executable set as secret_backend_command
must:
Have read/exec for stsagentuser
(the user used to run the Agent).
Have no rights for any user or group except Administrator
or LocalSystem
.
Be a valid Win32 application so the Agent can execute it.
Note: The executable shares the same environment variables as the Agent V2.
Don't output sensitive information on stderr
. If the binary exits with a different status code than 0, the Agent V2 logs the standard error output of the executable to ease troubleshooting.
The executable respects a simple API that reads JSON structures from the standard input, and outputs JSON containing the decrypted secrets to the standard output. If the exit code is anything other than 0, then the integration configuration being decrypted is considered faulty and is dropped.
The executable receives a JSON payload from the standard input, containing the list of secrets to fetch:
version
: is a string containing the format version.
secrets
: is a list of strings; each string is a handle from a configuration file corresponding to a secret to fetch.
The executable is expected to output to the standard output a JSON payload containing the:
The expected payload is a JSON object, where each key is one of the handles requested in the input payload. The value for each handle is a JSON object with two fields:
value
: a string; the actual value used in the check configurations
error
: a string; the error message, if needed. If error is anything other than null, the integration configuration that uses this handle is considered erroneous and is dropped.
The following is a dummy implementation of the secret reader that's prefixing every secret with decrypted_
:
Above example updates the following configuration (from the check file):
into this in the Agent's memory:
The secret
command in the Agent CLI shows any errors related to your setup. For example, if the rights on the executable are incorrect. It also lists all handles found, and where they're located.
The command outputs ACL rights for the executable, as in the example from an Administrator PowerShell below:
secret_backend_command
If any other group or user than needed has rights on the executable, a similar error to the following is logged:
If stsagentuser
doesn't have read and execute right on the file, a similar error logged:
Your executable needs to be a valid Win32 application. If not, the following error is logged:
Your executable is executed by the Agent V2 when fetching your secrets. StackState Agent V2 runs using the stsagentuser. This user has no specific rights, but it's part of the Performance Monitor Users group. The password for this user is randomly generated at install time and is never saved anywhere.
This means that your executable might work with your default user or development user — but not when it's run by the Agent, since stsagentuser has more restricted rights.
To test your executable in the same conditions as the Agent V2, update the password of the stsagentuser on your dev box. This way, you can authenticate as stsagentuser and run your executable in the same context the Agent would.
To do so, follow steps below:
Remove stsagentuser
from the Local Policies/User Rights Assignement/Deny Log on locally
list in the Local Security Policy
.
Set a new password for stsagenuser
(as the one generated during install isn't saved anywhere). In Powershell, run:
Update the password to be used by StackStateAgent service in the Service Control Manager. In PowerShell, run:
You can now log in as stsagentuser to test your executable. StackState has a PowerShell script to help you test your executable as another user. It switches user contexts and mimics how the Agent runs your executable. Usage example:
The first thing the Agent V2 does on startup is to load stackstate.yaml
and decrypt any secrets in it. This is done before setting up the logging. This means that on platforms like Windows, errors occurring when loading stackstate.yaml
aren't written in the logs, but on stderr
. This can occur when the executable given to the Agent for secrets returns an error.
If you have secrets in stackstate.yaml
and the Agent refuses to start:
Try to start the Agent manually to be able to see stderr
.
Remove the secrets from stackstate.yaml
and test with secrets in a check configuration file.