DataDog/guarddog

What it is

GuardDog is Datadog's CLI for detecting malicious packages across PyPI, npm, Go, Rust (crates), RubyGems, GitHub Actions, and VSCode extensions. The summary covers its correlation model; this page carries the operational details — how you actually run it, the scoring thresholds it reports, and the sandbox's fail-closed default.

How it works

Two commands per ecosystem: scan (a single named package or a local/remote archive) and verify (every dependency in a lockfile-style manifest). Score labels are concrete: 0 none, 0.1–3 low, 3.1–7.5 medium (partial chain or metadata-only), 7.6–10 high (multi-stage chain with source evidence, described as near-certainty of compromise). Cross-file capability+threat matches still form risks but with downgraded severity.

The sandbox has a three-phase privilege split for remote packages, worth understanding before wiring into CI:

flowchart TD
    A[Download + metadata analysis] -->|network allowed, no sandbox| B{Sandbox available?}
    B -->|yes| C[Archive extraction: network blocked, FS restricted]
    B -->|no, default| D[Scan FAILS — exits with error]
    B -->|--no-sandbox| E[Runs unprotected]
    C --> F[Source code analysis]

Preconditions / Affected

The sandbox is required by default (Linux via Landlock, macOS via Seatbelt, using nono). If it isn't available on the platform, the scan fails rather than running unprotected — a CI runner on an unsupported kernel will error out unless you opt out. On Windows the only supported install is Docker.

What to do

Run without installing via uvx, or install locally:

uvx guarddog pypi scan requests
uv tool install guarddog
pip install guarddog
docker pull ghcr.io/datadog/guarddog

Useful invocations beyond the basics:

# Pin a version
guarddog pypi scan requests --version 2.28.1

# Select or exclude specific heuristics
guarddog pypi scan requests --rules exec-base64 --rules code-execution
guarddog pypi scan requests --exclude-rules exec-base64

# Scan local paths or S3 objects/prefixes
guarddog pypi scan /tmp/triage.tar.gz
guarddog pypi scan s3://my-bucket/path/to/package/

# Verify a whole manifest; SARIF output is verify-only
guarddog pypi verify workspace/guarddog/requirements.txt
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt

# JSON works on every command
guarddog pypi scan requests --output-format=json

# Explicitly run without the sandbox (accepts the risk)
guarddog pypi scan requests --no-sandbox

verify targets are ecosystem-specific manifests (requirements.txt, go.mod, Cargo.lock, Gemfile.lock, workflow YAML). For detection pipelines, note the page mentions a Datadog Agent integration and a Cloud SIEM content pack for GuardDog.

Caveats

--output-format=sarif is stated to work only with verify, not scan — relevant if you expected SARIF from single-package scans in CI. Cross-file risk matches are deliberately downgraded, so a real multi-file attack chain may score lower than a single-file one.