This guide walks you from a fresh install to a completed dry-run scan. By the end you will have Warden installed globally, your environment validated, a set of scan artifacts written toDocumentation 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.
scan-results/, and a clear picture of what a CI-mode run looks like. No GitHub token or Snyk account is required for the dry-run steps.
Dry-run mode (
--dry-run) never creates branches, commits, or pull requests. It is always safe to run against any local repository — including repositories with uncommitted changes.Install Warden
Install Warden globally from the npm registry:Confirm the installation succeeded:You should see the current version number (
1.8.0 or later). If the command is not found, ensure your global npm bin directory is on your PATH.Validate your environment
Before running a scan, check that all required tools and credentials are present:
Errors block the scan by default. Warnings are informational — missing
warden validate runs four checks in sequence:| Check | What it inspects |
|---|---|
| Environment | GITHUB_TOKEN, SNYK_TOKEN, .env file presence |
| Dependencies | git, node, npm, snyk, pip-audit, gh in PATH |
| Git repository | .git directory, configured remotes, uncommitted changes |
| Project manifest | package.json (Node.js) or requirements.txt / pyproject.toml (Python) |
SNYK_TOKEN is a warning, not a hard failure, because Warden will fall back to npm-audit automatically.To check your environment in more detail, including Node.js version, Git, npm, and token status, run:Run a dry-run scan
Run a safe dry-run scan against the current directory using Flag breakdown:
Warden will run pre-flight validation, invoke the scanner, triage findings against policy, plan remediations, write artifacts to
npm-audit as the scanner:| Flag | Effect |
|---|---|
--dry-run | Plan fixes without creating branches, commits, or PRs |
--scanner npm-audit | Use npm audit as the vulnerability scanner |
--severity high | Only select findings at high severity or above |
--max-fixes 2 | Attempt at most 2 automated fixes per run |
scan-results/, and print an agentic assessment to the terminal. Because --dry-run is set, no code is modified.Other valid scanner values are snyk, pip-audit, and all. Valid severity levels are low, medium, high, and critical.Review the output artifacts
After the scan completes, inspect the Warden writes a consistent set of artifacts on every run. The table below describes each file:
The JSON artifacts conform to schemas in the
scan-results/ directory:| Artifact | Purpose |
|---|---|
scan-results.json | Normalized scanner output with all vulnerability fields |
warden-report.md | Human-readable operator report with findings, posture, and remediation summary |
scan-results.html | Standalone HTML version of the operator report |
agent-run-record.json | Agent handoff record: findings, attempted fixes, applied fixes, policy decisions, and why-it-matters context |
warden-approval-request.json | Written when policy blocks risky remediation pending human approval |
history.json | Longitudinal run history with trend data (improving, worsening, unchanged) |
memory.json | Recurring vulnerable package memory with per-package occurrence counts |
.warden-baseline.json | Accepted-risk baseline (written by warden baseline --create, not the scan command) |
schemas/ directory of the Warden package. Any CI job, dashboard, or downstream agent can consume them without parsing terminal output.Open the HTML report in a browser for a formatted view:Run with CI policy gates
Once you are comfortable with the dry-run output, run with CI mode enabled to see deterministic exit codes in action:Additional flags:
Exit code contract:
In CI, the
| Flag | Effect |
|---|---|
--ci | Enable CI policy gates; exit with a non-zero code if policy fails |
--json | Print the full run result as JSON to stdout instead of the interactive console output |
| Code | Meaning |
|---|---|
0 | Scan complete, policy passed |
1 | Fatal error during scan |
2 | Baseline regression detected (used by warden baseline --check) |
| Non-zero set by policy | Pipeline failure threshold crossed (severity gate, posture gate) |
--json flag suppresses all interactive output and writes a single JSON object to stdout. This makes it straightforward to pipe results to jq, upload them as artifacts, or feed them to a downstream job.Output Artifacts Reference
Every Warden scan writes the following files intoscan-results/ in the project root:
| Artifact | Format | Always written |
|---|---|---|
scan-results.json | JSON | ✓ |
warden-report.md | Markdown | ✓ |
scan-results.html | HTML | ✓ |
agent-run-record.json | JSON | ✓ |
warden-approval-request.json | JSON | Only when policy blocks remediation |
history.json | JSON | ✓ |
memory.json | JSON | ✓ |
.warden-baseline.json | JSON | Only after warden baseline --create |