Skip to content

Commit 65f6341

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

11 files changed

Lines changed: 1283 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: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
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+
15+
## `security-agent` configuration parameters
16+
<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>
17+
18+
<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>
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+
<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/system-probe.yaml</code> configuration file.</div>
29+
30+
| Environment variable | `system-probe.yaml` attribute | Type | Default | Description |
31+
| -------------------- | ----------------------------- | ---- | ------- | ----------- |
32+
| `DD_RUNTIME_SECURITY_CONFIG_ENABLED` | `runtime_security_config.enabled` | bool | false | Defines if the runtime security module should be enabled |
33+
| `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 |
34+
| `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 |
35+
| `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 |
36+
| `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 |
37+
| `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 |
38+
| `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 |
39+
| `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 |
40+
| `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 |
41+
42+
### `system-probe` advanced settings
43+
44+
<div class="alert alert-warning">The following settings are intended for advanced use cases only. Modifying them without fully understanding their impact may disrupt Datadog Workload Protection or affect the behavior of the Datadog Agent and the host system.</div>
45+
46+
| Environment variable | `system-probe.yaml` attribute | Type | Default | Description |
47+
| -------------------- | ----------------------------- | ---- | ------- | ----------- |
48+
| `DD_RUNTIME_SECURITY_CONFIG_EBPFLESS_ENABLED` | `runtime_security_config.ebpfless.enabled` | bool | false | EBPFLessEnabled enables the ebpfless probe |
49+
50+
[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)