draugr

Draugr

Developer-first, descriptor-driven security scanning orchestration.

Describe your app. Draugr figures out the rest.

You declare what you know about your software — where the repos are, what container images it builds, what endpoints it exposes, what infrastructure it runs on — in a single descriptor (draugr.saga.yaml). Draugr infers which security controls apply, runs the right scanner for each, and produces pass/fail evidence you can trust. Swap scanners freely — use the tools you already pay for, or Draugr's open-source defaults. Every result is normalized to SARIF.

This is the open-source core engine.

Status

🚧 Early, and moving fast. Working today:

• Controls: images (Trivy), sca (Trivy fs), secrets (Gitleaks), sast (Semgrep, plus opt-in gosec for Go), iac (Trivy config), headers (native HTTP-header analyzer). See the integrations catalog.
• Pipeline: end-to-end scan (plan → scan → judge → report), content-hash caching, tunable parallelism (-j), results normalized to SARIF.
• Prioritization: declare a component's exposure and criticality and Draugr ranks every finding P1–P4 (--min-priority to focus, --fail-on-priority to gate); optional KEV/EPSS enrichment for real-world exploitability.
• Discovery ("the Ravens"): survey for Kubernetes images and GitHub org repositories.
• Preflight & tooling: validate (schema-check a Saga), doctor (which scanner tools are present/missing), tools install (fetch pinned, checksum- and cosign-verified scanners — and cosign itself — into ~/.draugr/bin), and self-update (update draugr itself, verified).

More controls (DAST, TLS, SBOM, …) are on the roadmap. See docs/concepts.md for what maps to what.

Quickstart

Requirements: the external scanners for the controls you use — Trivy (images, sca, iac), Gitleaks (secrets), Semgrep (sast); git for repo scans. Or run draugr tools install to fetch pinned, verified copies. Go 1.26+ only to build from source.

Install from a release (recommended):

gh release download --repo draugr-dev/draugr \
  -p "draugr_*_$(uname -s | tr A-Z a-z)_amd64.tar.gz"   # omit a tag = latest
tar -xzf draugr_*_amd64.tar.gz draugr
sudo mv draugr /usr/local/bin/ && draugr version

Releases are cosign-signed with SBOMs and SLSA build provenance — see install & verifying downloads for the verifying curl recipe. Once installed, update in place with draugr self-update.

Or build from source:

git clone https://github.com/draugr-dev/draugr.git
cd draugr && make build      # produces ./bin/draugr
./bin/draugr version

Write a draugr.saga.yaml (see examples/):

release:
  name: my-app
  version: "1.0"
config:
  controllers:
    images:
      enabled: true
components:
  - name: web
    images:
      - image: alpine:3.19

Scan it:

draugr scan draugr.saga.yaml            # prints a JSON verdict; exits non-zero on fail
draugr scan draugr.saga.yaml -o out/    # also writes out/report.json + out/results.sarif
draugr scan draugr.saga.yaml --fail-on warning

Let discovery write the descriptor for you (the Ravens):

draugr survey --github-org my-org -o draugr.saga.yaml
draugr survey --k8s-images --k8s-namespace prod --merge -o draugr.saga.yaml

Full walkthrough: docs/quickstart.md.

Use in CI (GitHub Actions)

Add Draugr to a repository's CI and code scanning with the first-party action. It downloads a cosign-verified Draugr release, runs the scan, and hands the merged SARIF to GitHub code scanning — one clean Draugr tool in the Security tab:

permissions:
  contents: read
  security-events: write   # upload SARIF to code scanning

steps:
  - uses: actions/checkout@v4
  - id: draugr
    uses: draugr-dev/draugr@v0.16.0     # pin a release; installs Draugr for you
    with:
      saga: draugr.saga.yaml
      fail-on: warning                  # optional gate (default: error)
  - if: always()                        # publish findings even when the gate fails
    uses: github/codeql-action/upload-sarif@v3
    with:
      sarif_file: ${{ steps.draugr.outputs.sarif }}

The scanners each control needs (Trivy, Gitleaks, …) still have to be on the runner — install them alongside, or gate their presence with draugr doctor. See Run it in CI for the full workflow and all inputs.

Documentation

Full documentation index → (grouped by task, with a "building blocks" glossary of Saga / Norn / Skald / the Ravens).

• Quickstart — install, first scan, first survey, CI usage
• Concepts — Saga, controllers, scanners, surveyors, the pipeline, verdicts
• Pipeline stages — each stage in depth, incl. how the Norn (gate) works
• Glossary — security categories explained (SCA, SAST, DAST, SBOM, …)
• Integrations catalog — every controller/scanner/surveyor, with per-component docs + licenses
• Changelog — user-facing release notes
• CLI reference — every command and flag
• Saga reference — the descriptor, field by field
• Architecture · Plugin API · Naming

Security & supply chain

A security tool should hold itself to what it checks. Draugr does:

• Standard output — every finding is normalized to SARIF 2.1.0 (OASIS), so results flow into GitHub / GitLab / Azure DevOps code scanning and any SARIF-aware tool.
• Signed releases + provenance — release archives' checksums.txt is keyless-signed with cosign (Sigstore) into a checksums.txt.sigstore.json bundle, and each release publishes SLSA build-provenance attestations (gh attestation verify …); verify before installing (recipe).
• SBOMs — a Syft SBOM is published for every release archive.
• Verified tooling — draugr tools install fetches scanners pinned by SHA-256 and, where the upstream signs them, verifies the cosign signature too — and cosign itself is installable, so verification is self-sufficient.
• We scan ourselves — Draugr runs on its own repo every PR (dogfood self-scan), and we track our supply-chain posture with the OpenSSF Scorecard (badge above).
• Report a vulnerability — see SECURITY.md.

Development

Requires Go 1.26+.

make build   # build ./bin/draugr
make gate    # full local gate: fmt, vet, golangci-lint, race tests + coverage, govulncheck
make test    # run tests

Observability

Draugr uses Cobra for the CLI, log/slog for structured logging (--log-level, --log-format json|text), and OpenTelemetry for traces and metrics. Telemetry is opt-in via the standard OTEL_* environment variables (e.g. OTEL_EXPORTER_OTLP_ENDPOINT) — a no-op with zero overhead when unset. Logs and spans never carry secrets.

License

Draugr is licensed under the Apache License 2.0.