Security Agent

Active contributors: Paul Cacheux, Sylvain Baubeau, Sylvain Afchain

Purpose

The Security Agent is the user-space front-end for Datadog's security products:

• Cloud Workload Security (CWS) — runtime threat detection using eBPF + Linux Security Modules. Rules are written in SECL (Security Expression Language).
• Cloud Security Posture Management (CSPM) — compliance benchmarks (CIS, etc.) evaluated periodically.
• Container Image Vulnerability scanning via SBOM extraction and CVE matching.

CWS detection itself runs inside the System Probe address space (privileged, with eBPF). The Security Agent is the user-space process that loads SECL policies, talks to the system probe over its UDS, sends events to the Datadog backend, and runs the CSPM check loop.

Directory layout

cmd/security-agent/
├── main_nix.go             # Linux/macOS entrypoint
├── main_windows.go         # Windows entrypoint
├── command/                # Cobra root
├── api/                    # HTTP API
├── config/                 # Config loading
└── subcommands/            # `start`, `runtime`, `compliance`, `flare`, `version`, …

pkg/security/               # The CWS data plane
├── agent/                  # The runtime that connects security-agent ↔ system-probe
├── secl/                   # SECL parser and evaluator
├── rules/                  # Rule loading and indexing
├── probe/                  # Kernel probes (eBPF, LSM, ptrace, …)
├── ebpf/                   # CWS-specific eBPF programs
├── module/                 # CWS event monitor module loaded into system-probe
├── events/                 # Event types
├── resolvers/              # Container/process/cgroup resolvers
├── reporter/               # Outbound event reporter
├── serializers/            # Event serialization
├── security_profile/       # Activity profiles, anomaly detection
├── seclog/                 # CWS-specific logger
├── seclwin/                # Windows-specific helpers
├── tests/                  # Functional tests
└── ptracer/                # ptrace-based fallback for environments without eBPF

pkg/compliance/             # CSPM benchmarks
└── ...

cmd/cws-instrumentation/    # Helper binary injected into containers for CWS

CWS event flow

graph LR
    KERNEL[Linux kernel] -->|eBPF / LSM hooks| PROBE[Probe<br/>pkg/security/probe]
    PROBE -->|raw events| RESOLV[Resolvers<br/>process / container / cgroup]
    RESOLV --> EVAL[SECL evaluator<br/>pkg/security/secl]
    RULES[Rules<br/>SECL policies] --> EVAL
    EVAL -->|matched events| AGENT[Agent<br/>pkg/security/agent]
    AGENT -->|gRPC| SAGENT[security-agent]
    SAGENT -->|HTTP| INTAKE[Datadog intake]

The kernel-side hooks live in pkg/security/ebpf/c/ and pkg/security/probe/. They produce raw events; resolvers enrich them with process tree, container, and cgroup context. SECL rules then filter the enriched events; matches become runtime events shipped to Datadog.

SECL — Security Expression Language

pkg/security/secl/ is one of the more substantial pieces of the codebase. It defines:

• A grammar for filter expressions (open.file.path == "/etc/passwd" && process.parent.comm in ["bash", "sh"]).
• A lexer + parser (secl/parser/).
• An AST and evaluator (secl/compiler/).
• A model of the event surface (secl/model/) with tens of event types and hundreds of fields.
• Code generators that produce reflective accessors for every model field.

A SECL rule is a YAML document (a "policy") consisting of one or more SECL expressions plus metadata. The Security Agent loads policies from disk and from Remote Config.

CSPM

pkg/compliance/ runs compliance checks (CIS Kubernetes, CIS Linux, etc.). Each benchmark is a YAML file under compliance/benchmarks/ (the directory at the repo root) describing checks in terms of files to read, processes to inspect, or kubectl commands to run. The CSPM loop evaluates them on a schedule and reports findings.

Subcommands

The Security Agent exposes a focused set of subcommands:

Subcommand	Purpose
start	Long-running daemon (default).
status	Health and counter snapshot.
flare	Build a flare archive.
runtime	CWS runtime helpers: policy, download, reload, dump_*.
compliance	CSPM helpers: event, check.
version	Print version.

agent runtime policy check and agent runtime policy download are common entry points for debugging rule loading.

Windows variant

Windows CWS is a more recent addition. It does not use eBPF; instead it relies on Event Tracing for Windows (ETW), the Windows Filtering Platform driver, and pkg/security/seclwin/ Windows-specific resolvers. The same SECL grammar and policy format apply.

Container instrumentation

cmd/cws-instrumentation/ is a small helper binary that the Security Agent injects into customer containers to support certain CWS features (e.g., when ptrace-based detection is needed). It is shipped as a separate binary so it can be embedded as a sidecar without dragging the full Agent.

pkg/security/ptracer/ implements the ptrace-based fallback for environments where eBPF is unavailable.

Key abstractions

Type / package	Location	Description
Module	pkg/security/module/	The system-probe module that hosts CWS
Probe	pkg/security/probe/probe.go	Kernel probe abstraction
Resolvers	pkg/security/resolvers/	Process / container / cgroup enrichment
RuleSet	pkg/security/rules/ruleset.go	Compiled set of SECL rules
Evaluator	pkg/security/secl/compiler/eval/	SECL evaluator
Reporter	pkg/security/reporter/	Event sender

Entry points for modification

• Adding a new SECL field: extend pkg/security/secl/model/ and rerun the field-accessor generator.
• Adding a new event type: define the event in the model and add the kernel hook(s).
• Adding a new compliance check: write a YAML file under compliance/ referencing existing primitives.
• Modifying CWS kernel probes: changes typically span pkg/security/ebpf/c/, pkg/security/probe/, the model, and the resolvers. Run KMT (tasks/kmt.py) to verify across kernel versions.

Related pages

• Features: Cloud Workload Security — end-to-end CWS story.
• Apps: System Probe — host of the CWS module.
• Features: eBPF / system probe — the eBPF infrastructure.