draugr

# Draugr

> Developer-first, descriptor-driven security scanning orchestration.

[![CI](https://github.com/draugr-dev/draugr/actions/workflows/ci.yml/badge.svg)](https://github.com/draugr-dev/draugr/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/draugr-dev/draugr/badge)](https://scorecard.dev/viewer/?uri=github.com/draugr-dev/draugr)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13631/badge)](https://www.bestpractices.dev/projects/13631)
[![Latest release](https://img.shields.io/github/v/release/draugr-dev/draugr?sort=semver)](https://github.com/draugr-dev/draugr/releases)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue)](LICENSE)

**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.

## See it in action

![Draugr scanning a repository with zero config](contrib/demo/scan.gif)

`draugr scan .` on the demo sandbox — no descriptor, just a prioritized verdict:

```text
Draugr — FAIL   (draugr-demo 0.0.0)

Priorities:  P1 21   P2 25   P3 13   P4 0

Controls:
  iac      FAIL  4 high  5 medium  12 low
  sast     FAIL  7 high  12 medium
  sca      FAIL  3 critical  6 high  8 medium  1 low
  secrets  FAIL  1 high

Fix first:
  Priority  Severity  Score  Rule              Control  Scanner       Location
  P1        critical  9.8    CVE-2019-20477    sca      trivy-fs      app/requirements.txt:4
  P1        critical  9.8    CVE-2020-14343    sca      trivy-fs      app/requirements.txt:4
  P1        high      8.0    KSV-0014          iac      trivy-config  deploy/pod.yaml:8
  P1        high      8.0    KSV-0118          iac      trivy-config  deploy/pod.yaml:6
  P1        high      7.5    CVE-2018-1000656  sca      trivy-fs      app/requirements.txt:2
  …

… and 49 more finding(s). Use --format json for the full report, or -o <dir> for report.json + results.sarif.
```

On a terminal the verdict, priorities, and severities are color-coded (disable with `NO_COLOR`).
Findings are ranked by **priority (P1–P4)** = severity × the component's exposure & criticality;
**severity** (critical/high/medium/low) comes from the CVSS score when a scanner provides one,
else from the finding's level. The gate and `--format json`/`sarif` still use SARIF levels.

**[draugr-dev/draugr-demo](https://github.com/draugr-dev/draugr-demo)** is an intentionally
vulnerable sample app wired to Draugr. Every control lights up, the findings are prioritized
P1–P4, and results land in the repo's **Security → Code scanning** tab — a safe sandbox to see
exactly what Draugr delivers before pointing it at your own code. The example PRs there also show
the **new-vs-fixed PR diff** and the sticky comment.

## 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),
  `dast` (Nuclei), `tls` (native TLS/certificate probe).
  See the [integrations catalog](docs/reference/catalog.md).
- **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.
- **Zero-config & scaffolding:** `scan .` scans the current repo with no descriptor
  (sca/secrets/sast/iac); `init` scaffolds a stack-detected `draugr.saga.yaml` to customize.
- **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 (SBOM, infrastructure, threat intelligence) are on the roadmap. See
[controls & scanners](docs/concepts/controls-and-scanners.md) for what maps to what.

## Quickstart

**Requirements:** the external scanners for the controls you use —
[Trivy](https://github.com/aquasecurity/trivy) (`images`, `sca`, `iac`),
[Gitleaks](https://github.com/gitleaks/gitleaks) (`secrets`),
[Semgrep](https://semgrep.dev) (`sast`); `git` for repo scans. Or run
`draugr tools install` to fetch pinned, verified copies. Go 1.26+ only to build from source.

**Install (recommended):**

```bash
curl -fsSL https://draugr.dev/install.sh | sh
```

Detects your OS and architecture and installs to `~/.local/bin` — no `sudo`. It **verifies before
it installs and says which checks ran**: the archive's SHA-256 against the release's
`checksums.txt` always, plus the cosign signature on `checksums.txt` when
[cosign](https://docs.sigstore.dev/cosign/) is on your `PATH`. Nothing is installed if a check
fails.

Piping a script into a shell means trusting the host that served it. The script is
[readable in the repo](install.sh), and
[install & verifying downloads](docs/getting-started/install.md) has the manual steps, the
`DRAUGR_*` knobs, and Homebrew. Once installed, update in place with **`draugr self-update`**.

**Or build from source:**

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

**Fastest path — zero config.** Point Draugr at a repo and go; no descriptor needed:

```bash
draugr scan .        # scans the current repo: sca, secrets, sast, iac
draugr init          # or scaffold a draugr.saga.yaml (stack-detected) to customize
```

For full control, write a Saga — any `*.saga.yaml` file (see [`examples/`](examples/draugr.saga.yaml)):

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

Scan it:

```bash
draugr scan draugr.saga.yaml            # console summary; 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
draugr scan draugr.saga.yaml --format markdown   # or html, junit, json, sarif
```

**Your editor already knows this file.** Draugr's
[JSON Schema](https://draugr.dev/schema/draugr.saga.schema.json) is registered with
[SchemaStore](https://www.schemastore.org/), which VS Code's YAML extension and JetBrains IDEs
consult by default — so any `*.saga.yaml` gets completion, hover docs and typo warnings on open,
with nothing to configure. For an editor that doesn't use the catalog, `draugr init` also writes:

```yaml
# yaml-language-server: $schema=https://draugr.dev/schema/draugr.saga.schema.json
```

`draugr schema -o .saga.schema.json` writes the copy embedded in your binary instead, if you'd
rather validate offline or pin to exactly the version you run. See
[editor support](docs/reference/saga-schema.md#editor-support-autocomplete-hover-docs-validation).

Compare two scans to see what a change introduced (and gate a PR on *new* findings only):

```bash
draugr diff base/results.sarif head/results.sarif                     # new / fixed / unchanged
draugr diff base/results.sarif head/results.sarif --fail-on-new-priority P1
```

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

```bash
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/getting-started/quickstart.md`](docs/getting-started/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:

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

steps:
  - uses: actions/checkout@v4
  - id: draugr
    uses: draugr-dev/draugr@v0     # latest v0.x; pin @vX.Y.Z for reproducible CI (installs Draugr for you)
    with:
      saga: draugr.saga.yaml
      tools: true                       # provision the scanners the controls need
      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 }}
```

With `tools: true` the action provisions the scanners each control needs (Trivy, Gitleaks,
Semgrep). See the [GitHub Action guide](docs/guides/github-action.md) for the full workflow and
all inputs.

## Use from an AI coding assistant

Ask a coding assistant *"is this safe to ship?"* and it answers either way — usually by running
whatever scanner it can find, over a scope it invented, and reading the raw output. That answer
has no relationship to the one your pipeline will give.

`draugr mcp` serves Draugr over the [Model Context Protocol](https://modelcontextprotocol.io),
so the assistant reads your **committed** Saga instead:

```bash
claude mcp add draugr -- draugr mcp
```

It can list the controls that exist, hand back the descriptor schema *your build* enforces,
validate a Saga before you write it, and rank an existing report by priority. Every
`*.saga.yaml` nearby is exposed as a resource, so t