Warden Artifacts: Durable Scan Outputs and Schemas

Warden writes a predictable bundle of files to scan-results/ after every run. These artifacts are the product of the control plane — not the terminal output. Terminal logs are ephemeral; artifacts are durable. A CI job can assert on agent-run-record.json. A dashboard can parse history.json to plot risk-score trends. A downstream agent can read agent-run-record.json to understand what happened in a previous run without replaying it. Every JSON artifact has a corresponding schema in schemas/ so consumers can validate structure without reading source code.

Artifacts Reference

scan-results.json — Normalized scanner output

Written by the scanner (Watchman agent) immediately after a successful scan. Contains the raw, normalized vulnerability data that every downstream step operates on.Location: scan-results/scan-results.jsonSchema: schemas/scan-results.schema.jsonKey fields:

Field	Type	Description
`timestamp`	`string`	ISO 8601 timestamp of when the scan ran
`scanner`	`string`	Scanner that produced the result (`snyk`, `npm-audit`, `pip-audit`, `nmap`, `metasploit`, `mock`)
`scanMode`	`"sast" \| "dast"`	Which workflow produced the result
`projectPath`	`string`	Target path or URL
`summary.total`	`number`	Total vulnerability count
`summary.critical`	`number`	Count of critical-severity findings
`summary.high`	`number`	Count of high-severity findings
`summary.medium`	`number`	Count of medium-severity findings
`summary.low`	`number`	Count of low-severity findings
`vulnerabilities[]`	`Vulnerability[]`	Full list of findings

Each Vulnerability object is required to carry id, title, severity, packageName, version, fixedIn, and description. DAST findings additionally carry targetHost, targetPort, service, serviceVersion, exploitAvailable, and exploitModule.

{
  "timestamp": "2025-01-15T10:30:00.000Z",
  "scanner": "npm-audit",
  "scanMode": "sast",
  "projectPath": "/workspace/my-app",
  "summary": { "total": 3, "critical": 1, "high": 1, "medium": 1, "low": 0 },
  "vulnerabilities": [
    {
      "id": "GHSA-1234-abcd-5678",
      "title": "Prototype Pollution in lodash",
      "severity": "critical",
      "packageName": "lodash",
      "version": "4.17.15",
      "fixedIn": ["4.17.21"],
      "description": "Versions before 4.17.21 are vulnerable to Prototype Pollution.",
      "cvssScore": 9.8
    }
  ]
}

warden-report.md — Human-readable operator report

A Markdown document written for human operators and reviewers. Summarizes the scan, remediation plan, applied fixes, and any warnings from the run.Location: scan-results/warden-report.mdContents:

Run metadata: timestamp, mode, target, finding counts, fix counts, risk score, and posture.
Summary paragraph from the remediation plan.
Immediate Actions — prioritized list of recommended next steps.
Manual Follow-Ups — packages that have no available automated fix.
Strategic Improvements — longer-term recommendations derived from scan patterns and run warnings.
Automation Output — branches created and pull request URLs opened during the run.
Findings — one line per vulnerability with severity, ID, package, version, and fix versions.
Warnings — any non-fatal issues encountered during the run (scanner fallbacks, missing tokens, etc.).

scan-results.html — HTML report

A self-contained HTML report generated by the HtmlReportGenerator Watchman agent. Suitable for sharing with stakeholders who prefer a browser-viewable format without requiring a Markdown renderer.Location: scan-results/scan-results.htmlThe HTML report is derived from the same ScanResult data as the Markdown report. It does not embed policy decision or remediation plan data — for machine-readable decision context, use agent-run-record.json.

agent-run-record.json — The handoff record

The most important artifact for downstream automation. agent-run-record.json is the complete handoff record: it captures what Warden found, what it decided, what it changed, and why it mattered — in a machine-readable format that CI jobs, dashboards, and other agents can consume without parsing terminal output.Location: scan-results/agent-run-record.jsonSchema: schemas/agent-run-record.schema.jsonFull schema structure:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://warden.dev/schemas/agent-run-record.schema.json",
  "title": "Warden Agent Run Record",
  "type": "object",
  "required": [
    "generatedAt", "mode", "targetPath", "scanTimestamp",
    "scanSummary", "riskScore", "posture",
    "selectedVulnerabilityIds", "attemptedFixes", "appliedFixes",
    "branches", "pullRequestUrls", "warnings", "whyMatters", "topFindings"
  ],
  "properties": {
    "generatedAt":               { "type": "string", "format": "date-time" },
    "mode":                      { "enum": ["sast", "dast"] },
    "targetPath":                { "type": "string" },
    "repository":                { "type": "string" },
    "scanTimestamp":             { "type": "string" },
    "scanSummary":               { "$ref": "#/$defs/scanSummary" },
    "riskScore":                 { "type": "number", "minimum": 0, "maximum": 100 },
    "posture":                   { "enum": ["critical", "elevated", "guarded", "stable"] },
    "selectedVulnerabilityIds":  { "type": "array", "items": { "type": "string" } },
    "attemptedFixes":            { "type": "number", "minimum": 0 },
    "appliedFixes":              { "type": "number", "minimum": 0 },
    "branches":                  { "type": "array", "items": { "type": "string" } },
    "pullRequestUrls":           { "type": "array", "items": { "type": "string" } },
    "advisoryPath":              { "type": "string" },
    "policyDecision": {
      "type": "object",
      "required": ["shouldBlockFixes", "shouldFailPipeline",
                   "approvalRequired", "approvalSatisfied", "reasons"],
      "properties": {
        "shouldBlockFixes":    { "type": "boolean" },
        "shouldFailPipeline":  { "type": "boolean" },
        "approvalRequired":    { "type": "boolean" },
        "approvalSatisfied":   { "type": "boolean" },
        "reasons":             { "type": "array", "items": { "type": "string" } }
      }
    },
    "warnings":     { "type": "array", "items": { "type": "string" } },
    "whyMatters":   { "type": "array", "items": { "type": "string" } },
    "topFindings":  { "type": "array", "items": { "$ref": "#/$defs/topFinding" } }
  }
}

whyMatters is a string array that answers “why did this run matter?” in plain language. It always contains four entries: total vulnerability breakdown, fix ratio, risk score with posture, and the remediation plan summary.topFindings is the top five vulnerabilities sorted by severity then CVSS score. Each entry carries id, title, severity, packageName, and version.policyDecision records the exact output of evaluatePolicy(), including which gates fired and whether the approval requirement was satisfied.

warden-approval-request.json — Blocked-fix notice

Written only when the requireApprovalAboveSeverity policy gate fires and no valid --approval-token approved was provided. The file signals to a human reviewer or downstream system that Warden identified fixable vulnerabilities but was not authorized to apply them.Location: scan-results/warden-approval-request.json

{
  "generatedAt": "2025-01-15T10:30:00.000Z",
  "highestSeverity": "high",
  "posture": "elevated",
  "riskScore": 72,
  "reasons": [
    "Approval required before auto-remediation because highest severity is high and policy threshold is high."
  ],
  "nextStep": "Re-run with --approval-token approved after human review."
}

After review, re-run with --approval-token approved to allow the fix loop to execute. See Policy Gates for the full approval flow.

history.json — Longitudinal run history

An append-only array of RunHistoryEntry objects, one per Warden run. Used by RunHistoryService to compute the run trend (improving, worsening, unchanged, first-run) and expose longitudinal data to dashboards and reporting tools.Location: scan-results/history.jsonSchema: schemas/history.schema.jsonThe schema defines an array where each entry is required to have:

Field	Type	Description
`timestamp`	`string`	Scan timestamp from `ScanResult`
`mode`	`"sast" \| "dast"`	Workflow that ran
`targetPath`	`string`	Path or URL scanned
`repository`	`string` (optional)	Remote repository URL if cloned
`totalVulnerabilities`	`number`	Total finding count
`critical`	`number`	Critical finding count
`high`	`number`	High finding count
`medium`	`number`	Medium finding count
`low`	`number`	Low finding count
`appliedFixes`	`number`	Fixes successfully applied
`attemptedFixes`	`number`	Fixes attempted (selected for remediation)
`autoFixableCount`	`number`	Vulnerabilities with a `fixedIn` version
`manualCount`	`number`	Vulnerabilities requiring manual remediation
`riskScore`	`number` (0–100)	Risk score at time of run

The trend is derived by comparing the current entry’s riskScore and totalVulnerabilities to the previous entry. A lower risk score or lower total vulnerability count is improving; higher is worsening; equal is unchanged.

memory.json — Recurring vulnerable package hotspots

Tracks which packages have appeared as vulnerabilities across multiple runs for a given repository or target path. The MemoryService uses this data to surface persistent hotspots that survive individual fix cycles — packages that keep reappearing despite remediation attempts.Location: scan-results/memory.jsonSchema: schemas/memory.schema.jsonThe memory store is a JSON object keyed by repoKey (the repository URL or target path). Each entry holds:

Field	Type	Description
`runCount`	`number`	Total number of Warden runs recorded for this repo
`packages`	`object`	Map of package name → `{ occurrences, lastSeverity }`

occurrences increments once per scan in which the package appears vulnerable. lastSeverity is promoted (never demoted) — if a package was medium last run and high this run, lastSeverity becomes high.The MemorySnapshot returned to the run result exposes the top five hotspots sorted by occurrences descending, then lastSeverity descending:

{
  "https://github.com/org/my-app": {
    "runCount": 12,
    "packages": {
      "lodash": { "occurrences": 10, "lastSeverity": "critical" },
      "axios":  { "occurrences": 4,  "lastSeverity": "high" }
    }
  }
}

.warden-baseline.json — Accepted-risk baseline

A committed snapshot of a scan result that defines the accepted-risk state of the repository. Once a baseline exists, warden baseline --check compares the current scan against it and flags only new or worsened findings — ignoring vulnerabilities that were already known and accepted at baseline creation time.Location: .warden-baseline.json (repository root, committed to version control)The baseline is created with warden baseline --create and should be committed alongside your source code.Key fields from WardenBaseline:

Field	Type	Description
`schemaVersion`	`1`	Always `1` — used for forward-compatibility checks
`generatedAt`	`string`	ISO 8601 timestamp of baseline creation
`scanTimestamp`	`string`	Timestamp from the source `ScanResult`
`scanner`	`ScannerType`	Scanner that produced the baseline scan
`scanMode`	`"sast" \| "dast"`	Mode of the baseline scan
`riskScore`	`number`	Risk score at baseline creation
`summary`	`ScanSummary`	Severity counts at baseline
`findings[]`	`BaselineFinding[]`	Fingerprinted snapshot of each vulnerability

Each BaselineFinding carries a deterministic fingerprint built from ecosystem, package name (or host:port:service for DAST), and vulnerability ID. Fingerprints are what allow compareBaseline() to identify new, resolved, and worsened findings regardless of ordering changes between runs.

# Create baseline from current scan
warden baseline --create
git add .warden-baseline.json
git commit -m "chore: accept current vulnerability state as baseline"

# Check for regressions only (ignores accepted-risk findings)
warden baseline --check --severity high

Why Schemas Matter

Every JSON artifact in scan-results/ has a corresponding schema in schemas/ that follows the JSON Schema 2020-12 specification. This enables:

CI assertion jobs — validate that agent-run-record.json matches the expected schema before consuming its fields, catching Warden version mismatches before they cause silent failures.
Dashboards and reporting tools — parse history.json with confidence about field names and types without coupling to Warden’s TypeScript internals.
Downstream agents — a subsequent AI agent can read agent-run-record.json and understand whyMatters, policyDecision, and topFindings as structured data rather than scraping terminal logs.
Cross-run comparisons — the deterministic structure of history.json and memory.json makes it straightforward to build trend analysis on top of multiple runs without a dedicated database.

Reference schemas/agent-run-record.schema.json in your CI validation step to ensure the artifact contract is intact before downstream jobs depend on it:

npx ajv validate -s schemas/agent-run-record.schema.json -d scan-results/agent-run-record.json

Get Started

Core Concepts

Configuration

CI Integration

Guides

Warden Artifacts: Durable Scan Outputs and Schemas

Artifacts Reference

Why Schemas Matter

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

CI Integration

Guides

Documentation Index

​Artifacts Reference

​Why Schemas Matter

Build docs developers (and LLMs) love

Artifacts Reference

Why Schemas Matter