Documentation menu

📎 Unreleased docs. This is the next version (from main), features here may change or not be in a release yet.See the latest release →

Getting started

Write your first Saga

The Saga (draugr.saga.yaml) is Draugr's descriptor, a declarative account of an application's security surface and the controls that must pass. This page walks you from a one-component file to a classified, multi-control descriptor. For the exhaustive field list, see the Saga schema.

Shortcut: draugr init scaffolds this file for you, detecting your stack (Go, a Dockerfile, dependency manifests) to pre-fill sensible controls, a good starting point to edit. And if you just want a scan now, draugr scan . needs no Saga at all.

The smallest thing that runs#

A Saga names its project, gives a version, and declares at least one component with an enabled control:

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

Run it with draugr scan draugr.saga.yaml. A control only runs when it is enabled, globally under config.controllers, or on an individual component.

Add more of your surface#

Each component is one logical part of your app. List whatever applies, repositories, images, hosts, infrastructure, and enable the controls that should cover it:

config:
  controllers:
    images:  { enabled: true }
    sca:     { enabled: true }   # dependency scanning
    secrets: { enabled: true }   # leaked-credential detection
components:
  - name: web
    repositories:
      - url: https://github.com/acme/web.git
        revision: main
    images:
      - image: registry.example.com/acme/web:1.0
        digest: sha256:…            # optional. Pin the immutable content digest

A repository scan needs git on your PATH; an image scan needs Trivy. Run draugr doctor draugr.saga.yaml to confirm the tools each enabled control needs are present.

It answers a second question at the same time, and this is the moment it is most worth asking: whether anything is set to look at what you just declared. A descriptor that names images while the images control is off scans clean over them, and a first Saga is exactly where that happens:

Not checked:
      web declares images, and images is not enabled

Classify components so priority means something#

Two optional attributes turn a wall of findings into a ranked list, exposure (how reachable the component is) and criticality (the business impact if it fails):

components:
  - name: web
    exposure: public          # public | authenticated | internal | restricted
    criticality: critical     # critical | important | supporting
    images:
      - image: registry.example.com/acme/web:1.0

Draugr combines these with each finding's severity to assign a P1–P4 priority. See prioritization. You can set them by hand, or let the guided draugr classify wizard write them for you.

Reference environment variables, not secrets#

Any string value may reference an environment variable with ${{ VAR_NAME }}; loading fails fast if a referenced variable is unset. Never put a token in the Saga itself:

project: my-app
release:
  version: "${{ RELEASE_VERSION }}"

Next steps#