Configuration

The configuration is a single YAML file, devguard.yml by default, committed next to the project it describes. Every command reads its path from the global --config flag.

organization: <your organization id>

collectors:
  - name: npm-audit
    command: npm audit --json
    evidence: 42
    allowExitCodes: [0, 1]
    expiresAt: 7d

  - name: vulnerability-scan
    uses: scan
    evidence: 57
    expiresAt: 7d

Unknown fields are rejected rather than ignored, at every level, so a typo fails immediately instead of quietly doing nothing.

Top-level fields

Field	Required	Notes
`organization`	no	The organization id. Optional when `devguard login` stored a default; `--org` overrides both.
`collectors`	yes	At least one collector. Names must be unique within the file.

Collector fields

A collector declares either a command or uses: scan, never both.

Field	Required	Default	Notes
`name`	yes		Slug matching `^[a-z0-9][a-z0-9_-]*$`, at most 100 characters. The file's identity: every push replaces this collector's previous file, and renaming starts a new series.
`command`	yes		The command to run. Not allowed together with `uses`.
`evidence`	yes		`42` or `EV-42`. The record must already exist.
`output`	no	`stdout`	A file path when the command writes to disk.
`expiresAt`	no	`30d`	Freshness window, or `never`.
`timeout`	no	`10m`	At most `24d` (a Node timer caps at 2³¹−1 milliseconds).
`allowExitCodes`	no	`[0]`	Exit codes accepted as success. Set `[0, 1]` for scanners that exit 1 on findings.
`allowSecrets`	no	`false`	Skips the secret-scan block for this collector only.

The scan recipe

A collector with uses: scan replaces command:

  - name: vulnerability-scan
    uses: scan
    scanner: trivy # optional: trivy | osv-scanner | grype | npm-audit
    evidence: 57

It picks the first installed scanner, or the one forced with scanner:, and fills in the command, the output file, and the exit codes. The scanner must already be installed on the machine. A recipe collector accepts the shared fields (name, evidence, expiresAt, timeout, allowSecrets) plus scanner; command, output, and allowExitCodes belong to command collectors only.

Durations

expiresAt, timeout, and the --expires flag share one syntax: a number followed by a unit, one of s, m, h, d, or w. Use 12w for a quarter; months and years are not units the CLI understands. expiresAt also accepts never.

Secret scanning

Before anything uploads, every artifact is checked against a built-in pattern pack covering cloud keys, private keys, tokens, and high-entropy assignments. A match blocks the push and prints a masked report. A collector whose output legitimately contains matches can set allowSecrets: true on that one entry, which stays visible in the change that introduces it; the --allow-secrets flag disables the block for a whole run.

The staging folder

Artifacts are staged in .devguard/, next to the configuration file, before they upload. Add it to your .gitignore; devguard init offers to do this.

How is this guide?