Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DevDonzo/warden/llms.txt

Use this file to discover all available pages before exploring further.

Warden orchestrates a multi-stage pipeline each time you run warden scan: pre-flight validation, dependency scanning via your chosen scanner, agentic triage, posture assessment, memory tracking, report generation, and policy evaluation. This guide walks you through the entire flow from a clean terminal to a written artifact bundle in scan-results/.

​
Prerequisites

  • Node.js ≥ 18 — required by the Warden CLI itself
  • Git — required for branch and PR operations
  • A Node.js project (contains package.json) or a Python project (contains requirements.txt) in the directory you plan to scan
Install Warden globally if you haven’t already: 
npm install -g @devdonzo/warden

​
Walk Through Your First Scan

1

Validate your environment

Before scanning, confirm that Warden can see everything it needs:
warden validate
This runs validator.validateAll() and prints one line per check — Node version, Git, npm, and optionally Snyk. For a deeper diagnosis with fix suggestions, run:
warden doctor
warden doctor reports on each dependency (Node.js ≥ 18, Git, npm, Snyk CLI), token availability (GITHUB_TOKEN, SNYK_TOKEN), and whether package.json is present in the working directory.Fix any errors before continuing. Warnings (e.g., Snyk not installed) are safe to ignore if you plan to use npm-audit.
2

Run a dry-run scan

A dry-run lets you see exactly what Warden would do — findings, triage, policy decisions — without creating any branches or PRs.
warden scan . --dry-run --scanner npm-audit --severity high --max-fixes 2
Flag breakdown:
FlagWhat it does
.Scan the current directory
--dry-runSuppress branch creation and PR opening
--scanner npm-auditUse npm audit as the primary scanner
--severity highOnly triage vulnerabilities rated high or critical
--max-fixes 2Plan at most 2 auto-fixes (dry-run won’t apply them)
Always start with --dry-run when scanning a repository for the first time. It writes every artifact to scan-results/ without touching Git, so you can review the agent’s reasoning before authorizing real changes.
3

Read the terminal output sections

Warden structures its output into labelled sections. Here is what each one means:🔍 Pre-flight ValidationRuns before the scan. Any hard failure here (missing package.json, invalid Git state) will stop the run with exit code 1.Scan resultsThe raw finding counts from the scanner:
Total: 14  Critical: 1  High: 3  Medium: 7  Low: 3
🧠 Agentic AssessmentThe advisor’s computed posture, risk score, and one-line summary:
Posture:    elevated
Risk Score: 58/100
3 high-severity findings — 2 are auto-fixable via dependency upgrades.
📈 TrendCompares the current run against the previous one stored in scan-results/history.json:
Trend: improving
Values are improving, worsening, unchanged, or first-run.🧠 MemoryShows recurring vulnerable packages tracked across runs:
Tracked Runs: 4
lodash: 3 hit(s), last severity high
axios:  2 hit(s), last severity medium
📝 ReportsPaths of every artifact written during the run:
Markdown:        scan-results/warden-report.md
HTML:            scan-results/scan-results.html
Agent Run Record: scan-results/agent-run-record.json
🚦 PolicyThe policy engine’s verdict — whether approval is required and whether the pipeline should fail:
Approval Required: no
Pipeline Failure:  no
4

Inspect the scan artifact

Open scan-results/scan-results.json to see the normalized scanner output. Every scanner writes to this file using the same schema:
{
  "timestamp": "2025-01-15T14:23:07.412Z",
  "scanner": "npm-audit",
  "summary": {
    "total": 14,
    "critical": 1,
    "high": 3,
    "medium": 7,
    "low": 3
  },
  "vulnerabilities": [
    {
      "id": "NPM-lodash-1523",
      "title": "Prototype Pollution in lodash",
      "severity": "high",
      "packageName": "lodash",
      "version": "4.17.15",
      "fixedIn": ["4.17.21"],
      "description": "Dependency path: lodash. Direct dependency can be upgraded to 4.17.21."
    }
  ]
}
The full agent handoff record is in scan-results/agent-run-record.json. It includes the risk score, posture, the IDs of every vulnerability selected for remediation, the policy decision, and a whyMatters field explaining the agent’s reasoning — written as a durable artifact so future runs, reviewers, or other agents can understand what happened.
5

Open the local console

Warden ships a local web console that renders the full artifact bundle as a readable dashboard:
warden console
The console binds to http://127.0.0.1:8787 by default and opens in your browser. It shows:
  • The latest scan summary and posture gauge
  • A filterable vulnerability table
  • Trend chart across historical runs
  • The memory hotspot list
  • Links to every generated report
Press Ctrl+C to stop the console server.

​
Choosing a Scanner

Pass --scanner <type> to warden scan to control which tool produces the raw findings.

snyk

Recommended for production. Uses the Snyk CLI and requires SNYK_TOKEN. Delivers rich CVE metadata, CVSS scores, and fix versions. Falls back to npm-audit automatically when Snyk is unavailable and scanner.fallback: true is set in .wardenrc.json.

npm-audit

Best for local and CI use without a Snyk account. Runs npm audit --json in the project directory. No token required. Severity mapping normalises npm’s moderate label to medium.

pip-audit

Use for Python projects. Runs python3 -m pip_audit -r requirements.txt --format=json. Requires requirements.txt and pip-audit installed in the Python environment.

all

Runs every registered scanner and merges the results. Useful when a project contains both package.json and requirements.txt.
If you specify --scanner snyk but the Snyk CLI is not installed or SNYK_TOKEN is not set, Warden automatically falls back to npm-audit when scanner.fallback: true is configured in .wardenrc.json (the default). The fallback chain is: Snyk → npm-audit.

​
Severity Levels

The --severity flag sets the minimum severity that Warden will triage and consider for auto-fixing. Findings below that threshold are still recorded in the artifact but are excluded from the remediation plan.
LevelWhen to use
criticalSuppress all noise; only act on the most dangerous findings
highRecommended starting point — catches real-world exploitable issues without overwhelming the fix budget
mediumUseful in hardening phases once critical and high findings are resolved
lowComprehensive audits only; generates significant volume

​
Understanding Posture

Warden’s advisor computes a posture value that summarises the overall security health of the scanned project:
PostureWhat it means
criticalOne or more critical findings with exploit potential, or risk score ≥ 80. Immediate action required.
elevatedHigh-severity findings present, or risk score between 50 and 79. Plan remediation this sprint.
guardedMedium findings present, risk score between 25 and 49. Monitor and schedule fixes.
stableOnly low-severity or no findings. Risk score below 25.
A critical posture triggers an error severity notification and an elevated posture triggers a warning notification when notifications are configured. The posture also drives the --ci policy gate — see the Policy Gates page for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us