[WP] Autogenerate config doc

docs/cloud-workload-security/BUILD.bazel

@@ -81,7 +81,19 @@ run_binary(
     tool = "//tasks/libs/cws:secl_doc_gen",
 )
 
-# Umbrella target: updates all four CWS markdown docs in one shot using the
+run_binary(
+    name = "workload_protection_agent_config_doc_gen",
+    srcs = ["workload_protection_agent_config.schema.json"],
+    outs = ["workload_protection_agent_config_doc_gen/workload_protection_agent_config.md"],
+    args = [
+        "$(execpath workload_protection_agent_config.schema.json)",
+        "$(execpath workload_protection_agent_config_doc_gen/workload_protection_agent_config.md)",
+        "workload_protection_agent_config.md",
+    ],
+    tool = "//tasks/libs/cws:config_doc_gen",
+)
+
+# Umbrella target: updates all five CWS markdown docs in one shot using the
 # committed JSON schemas as inputs. Platform-neutral — can run on any OS.
 # The JSON schemas themselves are updated by backend_linux_schema /
 # backend_windows_schema (Linux-only), called from cws_go_generate.
@@ -92,6 +104,7 @@ write_source_files(
         "backend_windows.md": ":backend_windows_doc_gen/backend_windows.md",
         "linux_expressions.md": ":secl_linux_doc_gen/linux_expressions.md",
         "windows_expressions.md": ":secl_windows_doc_gen/windows_expressions.md",
+        "workload_protection_agent_config.md": ":workload_protection_agent_config_doc_gen/workload_protection_agent_config.md",
     },
     visibility = ["//visibility:public"],
 )

docs/cloud-workload-security/README.md

@@ -16,9 +16,13 @@ docs/cloud-workload-security/
     # event types and fields of the SECL language
 --- secl.json
 
+    # workload protection agent configuration settings
+--- workload_protection_agent_config.schema.json
+
     # final documentation files
 --- agent_expressions.md # SECL part
 --- backend.md # backend event part
+--- workload_protection_agent_config.md
 ```
 
 ### Agent Expressions - SECL
@@ -65,6 +69,70 @@ These lines generate this field for all events containing a File sub-event, for
 
 The rest of the file is copied verbatim from the template file (modulo the `raw` tags, see [Jinja 2 templates](#jinja2-templates)).
 
+### Workload Protection Agent configuration
+
+The Workload Protection Agent configuration documentation is based on the following files:
+
+- `pkg/security/config/config.go` - the source code of the `RuntimeSecurityConfig` struct containing the settings documentation
+- `pkg/security/generators/config_doc/main.go` - the Go generator that extracts public and warning settings into JSON
+- `docs/cloud-workload-security/workload_protection_agent_config.schema.json` - the JSON representing the documented settings extracted from the source code
+- `tasks/libs/cws/templates/workload_protection_agent_config.md` - the Jinja2 template used for the final generation
+- `tasks/libs/cws/config_doc_gen.py` - the Python script that renders the template
+
+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`.
+
+#### Editing files
+
+Documented settings are defined as comments on fields of the `RuntimeSecurityConfig` struct in `pkg/security/config/config.go`.
+
+Supported comment keys:
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `description` | yes | Human-readable description of the setting |
+| `visibility` | yes | `public`, `warning`, or `private` |
+| `default_value` | recommended | Default value displayed in the documentation |
+
+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.
+
+The YAML key is automatically inferred from `NewRuntimeSecurityConfig` (and helper functions returning a config key). The environment variable name is automatically inferred from that 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`.
+
+For example, the following comments are located on the `RuntimeEnabled` field in `config.go`:
+
+```go
+// description: Defines if the runtime security module should be enabled
+// visibility: public
+// default_value: false
+RuntimeEnabled bool
+
+| Environment variable | `system-probe.yaml` attribute | Type | Default | Description |
+| -------------------- | ----------------------------- | ---- | ------- | ----------- |
+| `DD_RUNTIME_SECURITY_CONFIG_ENABLED` | `runtime_security_config.enabled` | bool | false | Defines if the runtime security module should be enabled |
+
+Settings with `visibility: warning` are documented in a separate table:
+
+```go
+// description: EBPFLessEnabled enables the ebpfless probe
+// visibility: warning
+// default_value: false
+EBPFLessEnabled bool
+```
+
+#### Generating the documentation
+
+1. Extract the JSON schema from `config.go`:
+
+```sh
+go generate ./pkg/security/config/config.go
+```
+
+2. Render the final Markdown file:
+
+```sh
+dda inv -e security-agent.generate-cws-documentation
+# or directly:
+bazel run //docs/cloud-workload-security:cws_docs
+
 ### Backend event
 
 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

@@ -0,0 +1,53 @@
+---
+title: Workload Protection Agent configuration
+description: Public Workload Protection Agent configuration settings
+disable_edit: true
+further_reading:
+- link: "/security/workload_protection/getting_started/"
+  tag: "Documentation"
+  text: "Get started with Datadog Workload Protection"
+---
+
+<!-- THIS FILE IS AUTOGENERATED. PLEASE EDIT THE FILE IN THE SCRIPTS/TEMPLATES FOLDER -->
+
+The Workload Protection Agent has several configuration settings to modify the agent and its behavior. The following parameters are available for both `system-probe` and the `security-agent`, two components that are required for Workload Protection to function properly.
+
+## `security-agent` configuration parameters
+<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>
+
+<div class="alert alert-info">Parameters can be provided in two 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>
+
+| Environment variable | `security-agent.yaml` attribute | Type | Default | Description |
+| -------------------- | ----------------------------- | ---- | ------- | ----------- |
+| `DD_RUNTIME_SECURITY_CONFIG_ENABLED`  | `runtime_security_config.enabled`  | bool | false| Enables Workload Protection for agent versions < `7.77`. |
+
+## `system-probe` configuration parameters
+
+The following settings can be configured under `runtime_security_config` in the system-probe configuration file.
+
+<div class="alert alert-info">Parameters can be provided in two 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>
+
+| Environment variable | `system-probe.yaml` attribute | Type | Default | Description |
+| -------------------- | ----------------------------- | ---- | ------- | ----------- |
+| `DD_RUNTIME_SECURITY_CONFIG_ENABLED` | `runtime_security_config.enabled` | bool | false | Defines if the runtime security module should be enabled |
+| `DD_RUNTIME_SECURITY_CONFIG_ENFORCEMENT_EXCLUDE_BINARIES` | `runtime_security_config.enforcement.exclude_binaries` | []string | [] | EnforcementBinaryExcluded defines the list of binaries that are excluded from the enforcement |
+| `DD_RUNTIME_SECURITY_CONFIG_ENFORCEMENT_RULE_SOURCE_ALLOWED` | `runtime_security_config.enforcement.rule_source_allowed` | []string | ["file", "remote-config"] | EnforcementRuleSourceAllowed defines the list of rule sources that are allowed |
+| `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 |
+| `DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_ENABLED` | `runtime_security_config.hash_resolver.enabled` | bool | true | HashResolverEnabled defines if the hash resolver should be enabled |
+| `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 |
+| `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 |
+| `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 |
+| `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 |
+| `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 |
+| `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 |
+| `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 |
+
+### `system-probe` advanced settings
+
+<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>
+
+| Environment variable | `system-probe.yaml` attribute | Type | Default | Description |
+| -------------------- | ----------------------------- | ---- | ------- | ----------- |
+| `DD_RUNTIME_SECURITY_CONFIG_SYSCALLS_CAPTURE_ALL_ERRORS_ENABLED` | `runtime_security_config.syscalls.capture_all_errors.enabled` | bool | false | CaptureAllSyscallErrorsEnabled defines if the agent should capture all syscall errors |
+
+[1]: /security/workload_protection/

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

@@ -0,0 +1,123 @@
+{
+  "public_settings": [
+    {
+      "name": "RuntimeEnabled",
+      "config_key": "runtime_security_config.enabled",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_ENABLED",
+      "description": "Defines if the runtime security module should be enabled",
+      "type": "bool",
+      "default_value": "false",
+      "visibility": "public"
+    },
+    {
+      "name": "EnforcementBinaryExcluded",
+      "config_key": "runtime_security_config.enforcement.exclude_binaries",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_ENFORCEMENT_EXCLUDE_BINARIES",
+      "description": "EnforcementBinaryExcluded defines the list of binaries that are excluded from the enforcement",
+      "type": "[]string",
+      "default_value": "[]",
+      "visibility": "public"
+    },
+    {
+      "name": "EnforcementRuleSourceAllowed",
+      "config_key": "runtime_security_config.enforcement.rule_source_allowed",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_ENFORCEMENT_RULE_SOURCE_ALLOWED",
+      "description": "EnforcementRuleSourceAllowed defines the list of rule sources that are allowed",
+      "type": "[]string",
+      "default_value": "[\"file\", \"remote-config\"]",
+      "visibility": "public"
+    },
+    {
+      "name": "HashResolverCacheSize",
+      "config_key": "runtime_security_config.hash_resolver.cache_size",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_CACHE_SIZE",
+      "description": "HashResolverCacheSize defines the number of hashes to keep in cache",
+      "type": "int",
+      "default_value": "500",
+      "visibility": "public"
+    },
+    {
+      "name": "HashResolverEnabled",
+      "config_key": "runtime_security_config.hash_resolver.enabled",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_ENABLED",
+      "description": "HashResolverEnabled defines if the hash resolver should be enabled",
+      "type": "bool",
+      "default_value": "true",
+      "visibility": "public"
+    },
+    {
+      "name": "HashResolverEventTypes",
+      "config_key": "runtime_security_config.hash_resolver.event_types",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_EVENT_TYPES",
+      "description": "HashResolverEventTypes defines the list of event which files may be hashed",
+      "type": "[]model.EventType",
+      "default_value": "[\"exec\", \"open\"]",
+      "visibility": "public"
+    },
+    {
+      "name": "HashResolverHashAlgorithms",
+      "config_key": "runtime_security_config.hash_resolver.hash_algorithms",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_HASH_ALGORITHMS",
+      "description": "HashResolverHashAlgorithms defines the hashes that hash resolver needs to compute",
+      "type": "[]model.HashAlgorithm",
+      "default_value": "[\"sha1\", \"sha256\", \"ssdeep\"]",
+      "visibility": "public"
+    },
+    {
+      "name": "HashResolverMaxFileSize",
+      "config_key": "runtime_security_config.hash_resolver.max_file_size",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_MAX_FILE_SIZE",
+      "description": "HashResolverMaxFileSize defines the maximum size of the files that the hash resolver is allowed to hash",
+      "type": "int64",
+      "default_value": "5242880",
+      "visibility": "public"
+    },
+    {
+      "name": "HashResolverMaxHashRate",
+      "config_key": "runtime_security_config.hash_resolver.max_hash_rate",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_MAX_HASH_RATE",
+      "description": "HashResolverMaxHashRate defines the rate at which the hash resolver may compute hashes",
+      "type": "int",
+      "default_value": "500",
+      "visibility": "public"
+    },
+    {
+      "name": "HashResolverReplace",
+      "config_key": "runtime_security_config.hash_resolver.replace",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_HASH_RESOLVER_REPLACE",
+      "description": "HashResolverReplace is used to apply specific hash to specific file path",
+      "type": "map[string]string",
+      "default_value": "{}",
+      "visibility": "public"
+    },
+    {
+      "name": "RemoteConfigurationDumpPolicies",
+      "config_key": "runtime_security_config.remote_configuration.dump_policies",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_REMOTE_CONFIGURATION_DUMP_POLICIES",
+      "description": "RemoteConfigurationDumpPolicies defines whether to dump remote config policy",
+      "type": "bool",
+      "default_value": "false",
+      "visibility": "public"
+    },
+    {
+      "name": "SSHUserSessionsEnabled",
+      "config_key": "runtime_security_config.user_sessions.ssh.enabled",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_USER_SESSIONS_SSH_ENABLED",
+      "description": "SSHUserSessionsEnabled defines if SSH user session features should be enabled",
+      "type": "bool",
+      "default_value": "true",
+      "visibility": "public"
+    }
+  ],
+  "warning_settings": [
+    {
+      "name": "CaptureAllSyscallErrorsEnabled",
+      "config_key": "runtime_security_config.syscalls.capture_all_errors.enabled",
+      "env_var": "DD_RUNTIME_SECURITY_CONFIG_SYSCALLS_CAPTURE_ALL_ERRORS_ENABLED",
+      "description": "CaptureAllSyscallErrorsEnabled defines if the agent should capture all syscall errors",
+      "type": "bool",
+      "default_value": "false",
+      "visibility": "warning"
+    }
+  ]
+}