README
¶
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. Working today: the images control (via Trivy),
the end-to-end scan pipeline (plan → scan → judge → report), content-hash caching, and
survey discovery for Kubernetes images and GitHub org repositories. More controls
(SAST, SCA, DAST, headers, certificates, …) are on the roadmap. See
docs/concepts.md for what maps to what.
Quickstart
Requirements: Trivy on your PATH (for the
images and sca controls; git for repo scans). Go 1.26+ only to build from source.
Install from a release (recommended) — download the archive for your OS/arch from the releases page, or:
VERSION=v0.1.0
curl -sSL "https://github.com/draugr-dev/draugr/releases/download/${VERSION}/draugr_${VERSION#v}_linux_amd64.tar.gz" | tar -xz draugr
sudo mv draugr /usr/local/bin/ && draugr version
Releases are cosign-signed with SBOMs — see verifying downloads.
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.
Documentation
- 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
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.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
draugr
command
Command draugr is the Draugr CLI: developer-first, descriptor-driven security scanning orchestration.
|
Command draugr is the Draugr CLI: developer-first, descriptor-driven security scanning orchestration. |
|
internal
|
|
|
builtins
Package builtins assembles the default registry of controllers and scanners that ship with Draugr.
|
Package builtins assembles the default registry of controllers and scanners that ship with Draugr. |
|
cli
Package cli assembles the Draugr command-line interface on top of Cobra.
|
Package cli assembles the Draugr command-line interface on top of Cobra. |
|
controllers
Package controllers holds Draugr's built-in controllers (e.g.
|
Package controllers holds Draugr's built-in controllers (e.g. |
|
git
Package git provides repository checkouts for scanners that operate on source trees.
|
Package git provides repository checkouts for scanners that operate on source trees. |
|
observability
Package observability provides Draugr's logging and telemetry foundations: structured logging via log/slog and distributed tracing via OpenTelemetry.
|
Package observability provides Draugr's logging and telemetry foundations: structured logging via log/slog and distributed tracing via OpenTelemetry. |
|
scanners
Package scanners holds Draugr's built-in scanners, which wrap individual security tools and normalize their output to SARIF.
|
Package scanners holds Draugr's built-in scanners, which wrap individual security tools and normalize their output to SARIF. |
|
surveyors
Package surveyors holds Draugr's built-in surveyors ("the Ravens").
|
Package surveyors holds Draugr's built-in surveyors ("the Ravens"). |
|
version
Package version carries build metadata, injected at link time via -ldflags.
|
Package version carries build metadata, injected at link time via -ldflags. |
|
pkg
|
|
|
cache
Package cache stores scan results keyed by content hash so unchanged targets are not re-scanned.
|
Package cache stores scan results keyed by content hash so unchanged targets are not re-scanned. |
|
engine
Package engine orchestrates a run: it expands a Saga into scan jobs (controllers × components), executes them with bounded parallelism, and aggregates each control's results.
|
Package engine orchestrates a run: it expands a Saga into scan jobs (controllers × components), executes them with bounded parallelism, and aggregates each control's results. |
|
norn
Package norn evaluates scan results against policy to produce a verdict (pass/fail) per control and overall.
|
Package norn evaluates scan results against policy to produce a verdict (pass/fail) per control and overall. |
|
plugin
Package plugin is the Draugr plugin SDK.
|
Package plugin is the Draugr plugin SDK. |
|
saga
Package saga defines the Draugr descriptor ("Saga") — the declarative account of an application's security surface (repositories, images, hosts, infrastructure) plus the controller configuration that drives a scan.
|
Package saga defines the Draugr descriptor ("Saga") — the declarative account of an application's security surface (repositories, images, hosts, infrastructure) plus the controller configuration that drives a scan. |
|
sarif
Package sarif provides Draugr's result currency: a pragmatic model of SARIF 2.1.0 findings, plus merge and deduplication.
|
Package sarif provides Draugr's result currency: a pragmatic model of SARIF 2.1.0 findings, plus merge and deduplication. |
|
skald
Package skald renders scan results and verdicts into evidence: a JSON summary and merged SARIF.
|
Package skald renders scan results and verdicts into evidence: a JSON summary and merged SARIF. |
|
surveyor
Package surveyor is the Raven framework: discovery plugins that inspect an environment and return Saga fragments, which are merged so the descriptor can write itself.
|
Package surveyor is the Raven framework: discovery plugins that inspect an environment and return Saga fragments, which are merged so the descriptor can write itself. |
|
tooladapter
Package tooladapter turns an external command-line security tool into a Draugr Scanner declaratively: describe how to build the command for a target, and the adapter runs it and parses its SARIF output.
|
Package tooladapter turns an external command-line security tool into a Draugr Scanner declaratively: describe how to build the command for a target, and the adapter runs it and parses its SARIF output. |