StackState version 4.6
🔧
Configure
Set up a security backend for Linux
StackState Self-hosted v4.6.x
This document explains the process of setting up a security backend on a Linux system. You can find more information in the Secrets Management section.
Security agent requirements
The Agent V2 runs the
secret_backend_command executable as a sub-process. On Linux, the executable set as secret_backend_command is required to:- Belong to the same user running the Agent (or
rootinside a container). - Have no rights for group or other.
- Have at least exec rights for the owner.
How to use the executable API
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 that is being decrypted is considered faulty and is dropped.
Input
The executable receives a JSON payload from the standard input, containing the list of secrets to fetch:
1
{
2
"version": "1.0",
3
"secrets": ["secret1", "secret2"]
4
}
Copied!
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.
Output
The executable is expected to output to the standard output a JSON payload containing the:
1
{
2
"secret1": {
3
"value": "secret_value",
4
"error": null
5
},
6
"secret2": {
7
"value": null,
8
"error": "could not fetch the secret"
9
}
10
}
Copied!
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 that is used in the check configurationserror: 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.
Example
The following is a dummy implementation of the secret reader that is prefixing every secret with
decrypted_:1
package main
2
3
import (
4
"encoding/json"
5
"fmt"
6
"io/ioutil"
7
"os"
8
)
9
10
type secretsPayload struct {
11
Secrets []string `json:secrets`
12
Version int `json:version`
13
}
14
15
func main() {
16
data, err := ioutil.ReadAll(os.Stdin)
17
18
if err != nil {
19
fmt.Fprintf(os.Stderr, "Could not read from stdin: %s", err)
20
os.Exit(1)
21
}
22
secrets := secretsPayload{}
23
json.Unmarshal(data, &secrets)
24
25
res := map[string]map[string]string{}
26
for _, handle := range secrets.Secrets {
27
res[handle] = map[string]string{
28
"value": "decrypted_" + handle,
29
}
30
}
31
32
output, err := json.Marshal(res)
33
if err != nil {
34
fmt.Fprintf(os.Stderr, "could not serialize res: %s", err)
35
os.Exit(1)
36
}
37
fmt.Printf(string(output))
38
}
Copied!
Above example updates the following configuration (from the check file):
1
instances:
2
- server: db_prod
3
user: ENC[db_prod_user]
4
password: ENC[db_prod_password]
Copied!
into this in the Agent's memory:
1
instances:
2
- server: db_prod
3
user: decrypted_db_prod_user
4
password: decrypted_db_prod_password
Copied!
Troubleshooting secrets
Listing detected secrets
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 are located.On Linux, the command outputs file mode, owner and group for the executable. Example:
1
gt; stackstate-agent secret
2
=== Checking executable rights ===
3
Executable path: /path/to/you/executable
4
Check Rights: OK, the executable has the correct rights
5
6
Rights Detail:
7
file mode: 100700
8
Owner username: stackstate-agent
9
Group name: stackstate-agent
10
11
=== Secrets stats ===
12
Number of secrets decrypted: 3
13
Secrets handle decrypted:
14
- api_key: from stackstate.yaml
15
- db_prod_user: from postgres.yaml
16
- db_prod_password: from postgres.yaml
Copied!
Checking configurations after secrets were injected
To quickly see how the check’s configurations are resolved, you can use the
configcheck command:1
sudo -u stackstate-agent -- stackstate-agent configcheck
2
3
=== a check ===
4
Source: File Configuration Provider
5
Instance 1:
6
host: <decrypted_host>
7
port: <decrypted_port>
8
password: <decrypted_password>
9
~
10
===
11
12
=== another check ===
13
Source: File Configuration Provider
14
Instance 1:
15
host: <decrypted_host2>
16
port: <decrypted_port2>
17
password: <decrypted_password2>
18
~
19
===
Copied!
Note: The Agent needs to be restarted to pick up changes on configuration files.
Debugging secret_backend_command
secret_backend_commandTo test or debug outside of the Agent, you can mimic how the Agent runs it:
1
sudo su stackstate-agent - bash -c "echo '{\"version\": \"1.0\", \"secrets\": [\"secret1\", \"secret2\"]}' | /path/to/the/secret_backend_command"
Copied!
The stackstate-agent user is created when you install the StackState Agent.
Last modified 3d ago