Skip to content

Commit bf64bae

Browse files
theop-ddtheop-dd
committed
[WP] Autogenerate config doc
1 parent 4b71c7a commit bf64bae

11 files changed

Lines changed: 1279 additions & 152 deletions

File tree

‎docs/cloud-workload-security/BUILD.bazel‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,19 @@ run_binary(
8181
tool = "//tasks/libs/cws:secl_doc_gen",
8282
)
8383

84-
# Umbrella target: updates all four CWS markdown docs in one shot using the
84+
run_binary(
85+
name = "workload_protection_agent_config_doc_gen",
86+
srcs = ["workload_protection_agent_config.schema.json"],
87+
outs = ["workload_protection_agent_config_doc_gen/workload_protection_agent_config.md"],
88+
args = [
89+
"$(execpath workload_protection_agent_config.schema.json)",
90+
"$(execpath workload_protection_agent_config_doc_gen/workload_protection_agent_config.md)",
91+
"workload_protection_agent_config.md",
92+
],
93+
tool = "//tasks/libs/cws:config_doc_gen",
94+
)
95+
96+
# Umbrella target: updates all five CWS markdown docs in one shot using the
8597
# committed JSON schemas as inputs. Platform-neutral — can run on any OS.
8698
# The JSON schemas themselves are updated by backend_linux_schema /
8799
# backend_windows_schema (Linux-only), called from cws_go_generate.
@@ -92,6 +104,7 @@ write_source_files(
92104
"backend_windows.md": ":backend_windows_doc_gen/backend_windows.md",
93105
"linux_expressions.md": ":secl_linux_doc_gen/linux_expressions.md",
94106
"windows_expressions.md": ":secl_windows_doc_gen/windows_expressions.md",
107+
"workload_protection_agent_config.md": ":workload_protection_agent_config_doc_gen/workload_protection_agent_config.md",
95108
},
96109
visibility = ["//visibility:public"],
97110
)

‎docs/cloud-workload-security/README.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,13 @@ docs/cloud-workload-security/
1616
# event types and fields of the SECL language
1717
--- secl.json
1818
19+
# workload protection agent configuration settings
20+
--- workload_protection_agent_config.schema.json
21+
1922
# final documentation files
2023
--- agent_expressions.md # SECL part
2124
--- backend.md # backend event part
25+
--- workload_protection_agent_config.md
2226
```
2327

2428
### Agent Expressions - SECL
@@ -65,6 +69,79 @@ These lines generate this field for all events containing a File sub-event, for
6569

6670
The rest of the file is copied verbatim from the template file (modulo the `raw` tags, see [Jinja 2 templates](#jinja2-templates)).
6771

72+
### Workload Protection Agent configuration
73+
74+
The Workload Protection Agent configuration documentation is based on the following files:
75+
76+
- `pkg/security/config/config.go` - the source code of the `RuntimeSecurityConfig` struct containing the settings documentation
77+
- `pkg/security/generators/config_doc/main.go` - the Go generator that extracts public and warning settings into JSON
78+
- `docs/cloud-workload-security/workload_protection_agent_config.schema.json` - the JSON representing the documented settings extracted from the source code
79+
- `tasks/libs/cws/templates/workload_protection_agent_config.md` - the Jinja2 template used for the final generation
80+
- `tasks/libs/cws/config_doc_gen.py` - the Python script that renders the template
81+
82+
The generated markdown file is published on the documentation site at `/security/workload_protection/workload_protection_agent_config`. It is pulled from this repository during the documentation build (see `pull_config.yaml` in the `documentation` repository), the same way as `linux_expressions.md`.
83+
84+
#### Editing files
85+
86+
Documented settings are defined as comments on fields of the `RuntimeSecurityConfig` struct in `pkg/security/config/config.go`.
87+
88+
Supported comment keys:
89+
90+
| Key | Required | Description |
91+
| --- | --- | --- |
92+
| `description` | yes | Human-readable description of the setting |
93+
| `visibility` | yes | `public`, `warning`, or `private` |
94+
| `default_value` | recommended | Default value displayed in the documentation |
95+
| `config_key` | no | Override for the YAML key when it cannot be inferred from `NewRuntimeSecurityConfig` |
96+
97+
The Go type is inferred from the struct field declaration. Settings with `visibility: public` are included in the main `system-probe` table. Settings with `visibility: warning` are included in a separate **Advanced settings** table preceded by a disruption warning. Settings with `visibility: private` are omitted from the generated documentation.
98+
99+
The `config_key` is automatically inferred from `NewRuntimeSecurityConfig` (and helper functions returning a config key) when possible.
100+
101+
The environment variable name is automatically inferred from the `config_key` using the same convention as the Agent config (`DD_` prefix, uppercase, `.` replaced by `_`). For example, `runtime_security_config.hash_resolver.max_file_size` becomes `DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_MAX_FILE_SIZE`.
102+
103+
For example, the following comments on the `RuntimeEnabled` field in `config.go`:
104+
105+
```go
106+
// description: Defines if the runtime security module should be enabled
107+
// visibility: public
108+
// default_value: false
109+
RuntimeEnabled bool
110+
```
111+
112+
generate the following table row:
113+
114+
| Environment variable | `system-probe.yaml` attribute | Type | Default | Description |
115+
| -------------------- | ----------------------------- | ---- | ------- | ----------- |
116+
| `DD_RUNTIME_SECURITY_CONFIG_ENABLED` | `runtime_security_config.enabled` | bool | false | Defines if the runtime security module should be enabled |
117+
118+
Settings with `visibility: warning` are documented in a separate table:
119+
120+
```go
121+
// description: EBPFLessEnabled enables the ebpfless probe
122+
// visibility: warning
123+
// default_value: false
124+
EBPFLessEnabled bool
125+
```
126+
127+
#### Generating the documentation
128+
129+
1. Extract the JSON schema from `config.go`:
130+
131+
```sh
132+
go generate ./pkg/security/config/config.go
133+
```
134+
135+
2. Render the final markdown file:
136+
137+
```sh
138+
dda inv -e security-agent.generate-cws-documentation
139+
# or directly:
140+
bazel run //docs/cloud-workload-security:cws_docs
141+
```
142+
143+
`cws_docs` regenerates all CWS markdown files, including `workload_protection_agent_config.md`, from their committed JSON schemas.
144+
68145
### Backend event
69146

70147
The Cloud Workload Security (CWS) part of the Agent sends events to the backend. Those events conform to a JSON schema (this is tested in functional tests of the Agent). This documentation is based on the following files:

‎docs/cloud-workload-security/workload_protection_agent_config.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: Workload Protection Agent configuration
3+
description: Public Workload Protection Agent configuration settings
4+
disable_edit: true
5+
further_reading:
6+
- link: "/security/workload_protection/getting_started/"
7+
tag: "Documentation"
8+
text: "Get started with Datadog Workload Protection"
9+
---
10+
11+
<!-- THIS FILE IS AUTOGENERATED. PLEASE EDIT THE FILE IN THE SCRIPTS/TEMPLATES FOLDER -->
12+
13+
The Workload Protection Agent has several configuration knobs that can be used to tweak the agent and its behavior. You'll find below the list of available parameters for both `system-probe` and the `security-agent`, two components that are required for Workload Protection to function properly.
14+
<div class="alert alert-info">Parameters can be provided in 2 different manners: through environment variables (given to the Datadog Agent container for example) or by editing the <code>/etc/datadog-agent/security-agent.yaml</code> configuration file.</div>
15+
16+
17+
## `security-agent` configuration parameters
18+
<div class="alert alert-warning">From <code>7.77</code>, the security-agent runtime for CWS is effectively deprecated: it is not used anymore and this section can be ignored.</div>
19+
20+
| Environment variable | `security-agent.yaml` attribute | Type | Default | Description |
21+
| -------------------- | ----------------------------- | ---- | ------- | ----------- |
22+
| `DD_RUNTIME_SECURITY_CONFIG_ENABLED` | `runtime_security_config.enabled` | bool | `false`| Enables Workload Protection for agent versions < `7.77`. |
23+
24+
## `system-probe` configuration parameters
25+
26+
The following settings can be configured under `runtime_security_config` in the system-probe configuration file.
27+
28+
| Environment variable | `system-probe.yaml` attribute | Type | Default | Description |
29+
| -------------------- | ----------------------------- | ---- | ------- | ----------- |
30+
| `DD_RUNTIME_SECURITY_CONFIG_ENABLED` | `runtime_security_config.enabled` | bool | false | Defines if the runtime security module should be enabled |
31+
| `DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_CACHE_SIZE` | `runtime_security_config.hash_resolver.cache_size` | int | 500 | HashResolverCacheSize defines the number of hashes to keep in cache |
32+
| `DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_EVENT_TYPES` | `runtime_security_config.hash_resolver.event_types` | []model.EventType | ["exec", "open"] | HashResolverEventTypes defines the list of event which files may be hashed |
33+
| `DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_HASH_ALGORITHMS` | `runtime_security_config.hash_resolver.hash_algorithms` | []model.HashAlgorithm | ["sha1", "sha256", "ssdeep"] | HashResolverHashAlgorithms defines the hashes that hash resolver needs to compute |
34+
| `DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_MAX_FILE_SIZE` | `runtime_security_config.hash_resolver.max_file_size` | int64 | 5242880 | HashResolverMaxFileSize defines the maximum size of the files that the hash resolver is allowed to hash |
35+
| `DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_MAX_HASH_RATE` | `runtime_security_config.hash_resolver.max_hash_rate` | int | 500 | HashResolverMaxHashRate defines the rate at which the hash resolver may compute hashes |
36+
| `DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_REPLACE` | `runtime_security_config.hash_resolver.replace` | map[string]string | {} | HashResolverReplace is used to apply specific hash to specific file path |
37+
| `DD_RUNTIME_SECURITY_CONFIG_REMOTE_CONFIGURATION_DUMP_POLICIES` | `runtime_security_config.remote_configuration.dump_policies` | bool | false | RemoteConfigurationDumpPolicies defines whether to dump remote config policy |
38+
| `DD_RUNTIME_SECURITY_CONFIG_USER_SESSIONS_SSH_ENABLED` | `runtime_security_config.user_sessions.ssh.enabled` | bool | true | SSHUserSessionsEnabled defines if SSH user session features should be enabled |
39+
40+
## Advanced settings
41+
42+
<div class="alert alert-warning">The following settings are exposed for advanced use cases. Changing them without understanding their impact can disrupt Workload Protection monitoring or alter agent behavior.</div>
43+
44+
| Environment variable | `system-probe.yaml` attribute | Type | Default | Description |
45+
| -------------------- | ----------------------------- | ---- | ------- | ----------- |
46+
| `DD_RUNTIME_SECURITY_CONFIG_EBPFLESS_ENABLED` | `runtime_security_config.ebpfless.enabled` | bool | false | EBPFLessEnabled enables the ebpfless probe |
47+
48+
[1]: /security/workload_protection/

‎docs/cloud-workload-security/workload_protection_agent_config.schema.json‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
{
2+
"public_settings": [
3+
{
4+
"name": "RuntimeEnabled",
5+
"config_key": "runtime_security_config.enabled",
6+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_ENABLED",
7+
"description": "Defines if the runtime security module should be enabled",
8+
"type": "bool",
9+
"default_value": "false",
10+
"visibility": "public"
11+
},
12+
{
13+
"name": "HashResolverCacheSize",
14+
"config_key": "runtime_security_config.hash_resolver.cache_size",
15+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_CACHE_SIZE",
16+
"description": "HashResolverCacheSize defines the number of hashes to keep in cache",
17+
"type": "int",
18+
"default_value": "500",
19+
"visibility": "public"
20+
},
21+
{
22+
"name": "HashResolverEventTypes",
23+
"config_key": "runtime_security_config.hash_resolver.event_types",
24+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_EVENT_TYPES",
25+
"description": "HashResolverEventTypes defines the list of event which files may be hashed",
26+
"type": "[]model.EventType",
27+
"default_value": "[\"exec\", \"open\"]",
28+
"visibility": "public"
29+
},
30+
{
31+
"name": "HashResolverHashAlgorithms",
32+
"config_key": "runtime_security_config.hash_resolver.hash_algorithms",
33+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_HASH_ALGORITHMS",
34+
"description": "HashResolverHashAlgorithms defines the hashes that hash resolver needs to compute",
35+
"type": "[]model.HashAlgorithm",
36+
"default_value": "[\"sha1\", \"sha256\", \"ssdeep\"]",
37+
"visibility": "public"
38+
},
39+
{
40+
"name": "HashResolverMaxFileSize",
41+
"config_key": "runtime_security_config.hash_resolver.max_file_size",
42+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_MAX_FILE_SIZE",
43+
"description": "HashResolverMaxFileSize defines the maximum size of the files that the hash resolver is allowed to hash",
44+
"type": "int64",
45+
"default_value": "5242880",
46+
"visibility": "public"
47+
},
48+
{
49+
"name": "HashResolverMaxHashRate",
50+
"config_key": "runtime_security_config.hash_resolver.max_hash_rate",
51+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_MAX_HASH_RATE",
52+
"description": "HashResolverMaxHashRate defines the rate at which the hash resolver may compute hashes",
53+
"type": "int",
54+
"default_value": "500",
55+
"visibility": "public"
56+
},
57+
{
58+
"name": "HashResolverReplace",
59+
"config_key": "runtime_security_config.hash_resolver.replace",
60+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_REPLACE",
61+
"description": "HashResolverReplace is used to apply specific hash to specific file path",
62+
"type": "map[string]string",
63+
"default_value": "{}",
64+
"visibility": "public"
65+
},
66+
{
67+
"name": "RemoteConfigurationDumpPolicies",
68+
"config_key": "runtime_security_config.remote_configuration.dump_policies",
69+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_REMOTE_CONFIGURATION_DUMP_POLICIES",
70+
"description": "RemoteConfigurationDumpPolicies defines whether to dump remote config policy",
71+
"type": "bool",
72+
"default_value": "false",
73+
"visibility": "public"
74+
},
75+
{
76+
"name": "SSHUserSessionsEnabled",
77+
"config_key": "runtime_security_config.user_sessions.ssh.enabled",
78+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_USER_SESSIONS_SSH_ENABLED",
79+
"description": "SSHUserSessionsEnabled defines if SSH user session features should be enabled",
80+
"type": "bool",
81+
"default_value": "true",
82+
"visibility": "public"
83+
}
84+
],
85+
"warning_settings": [
86+
{
87+
"name": "EBPFLessEnabled",
88+
"config_key": "runtime_security_config.ebpfless.enabled",
89+
"env_var": "DD_RUNTIME_SECURITY_CONFIG_EBPFLESS_ENABLED",
90+
"description": "EBPFLessEnabled enables the ebpfless probe",
91+
"type": "bool",
92+
"default_value": "false",
93+
"visibility": "warning"
94+
}
95+
]
96+
}

0 commit comments

Comments
 (0)