draugr

module
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: Apache-2.0

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, and moving fast. Working today:

  • Controls: images (Trivy), sca (Trivy fs), secrets (Gitleaks), sast (Semgrep), iac (Trivy config). See the integrations catalog.
  • Pipeline: end-to-end scan (plan → scan → judge → report), content-hash caching, 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).
  • Discovery ("the Ravens"): survey for Kubernetes images and GitHub org repositories.
  • Preflight & tooling: validate (check a Saga against the schema), doctor (report which scanner tools are present/missing/version), and tools install (fetch pinned, checksum-verified scanners into ~/.draugr/bin) — catch problems, and get set up, before a scan.

More controls (DAST, headers, 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) and Gitleaks (secrets); git for repo scans. Go 1.26+ only to build from source.

Install from a release (recommended). While this repo is private, download with the GitHub CLI (plain curl returns 404 on private assets — it needs auth):

gh release download --repo draugr-dev/draugr -p 'draugr_*_linux_amd64.tar.gz'   # omit tag = latest
tar -xzf draugr_*_linux_amd64.tar.gz draugr
sudo mv draugr /usr/local/bin/ && draugr version

Releases are cosign-signed with SBOMs — see install & verifying downloads (includes the curl recipe for once the repo is public).

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

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

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").
tools
Package tools describes the external command-line scanners Draugr orchestrates and detects whether they are installed.
 Package tools describes the external command-line scanners Draugr orchestrates and detects whether they are installed.
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.
exploit
Package exploit enriches a finding's severity with real-world exploitability signals: CISA KEV (Known Exploited Vulnerabilities — confirmed exploited in the wild) and FIRST EPSS (Exploit Prediction Scoring System — probability of exploitation).
 Package exploit enriches a finding's severity with real-world exploitability signals: CISA KEV (Known Exploited Vulnerabilities — confirmed exploited in the wild) and FIRST EPSS (Exploit Prediction Scoring System — probability of exploitation).
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.
prioritization
Package prioritization turns a finding's severity and its component's risk classification (exposure × business criticality) into a single Priority band.
 Package prioritization turns a finding's severity and its component's risk classification (exposure × business criticality) into a single Priority band.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.