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.

When Warden finds a vulnerability that has a known safe upgrade, the Engineer agent applies the fix in an isolated Git branch and the Diplomat agent opens a pull request with full context. Every step is governed by the limits and policies you define in .wardenrc.json, so fixes never happen silently or beyond your configured blast radius. The result is a human-reviewable PR that records exactly what changed, why, what the policy decided, and what the risk score was at the time — a durable audit trail for every automated security change.

​
Prerequisites

  • A GitHub repository with a Git remote pointing to github.com
  • GITHUB_TOKEN set in the environment with repo scope (required to push branches and open PRs)
  • A package.json (npm) or requirements.txt (Python) project in the scan target directory
GITHUB_TOKEN must have write access to the repository’s contents (to push branches) and pull-requests: write permission (to open PRs). A Fine-Grained PAT scoped to the specific repository is recommended over a classic token with broad repo scope.

​
The Fix PR Workflow

1

Configure GITHUB_TOKEN and the fixes section

Export your token in the shell (or add it to your CI secrets):
export GITHUB_TOKEN=ghp_your_token_here
Add a fixes section to .wardenrc.json:
{
  "scanner": {
    "primary": "snyk",
    "fallback": true
  },
  "fixes": {
    "maxPerRun": 2,
    "minSeverity": "high",
    "autoMerge": false
  },
  "policy": {
    "failOnSeverity": "critical",
    "failOnPosture": "critical",
    "requireApprovalAboveSeverity": "high"
  },
  "notifications": {
    "enabled": false
  }
}
FieldDefaultDescription
fixes.maxPerRun1Maximum number of fix branches and PRs to create in a single run
fixes.minSeverity"high"Only fix vulnerabilities at or above this severity level
fixes.autoMergefalseWhether Warden should auto-merge fix PRs after they pass CI
fixes.autoMerge is false by default and should remain that way in most teams. Auto-merge removes the human review step that makes Warden’s fixes auditable. Enable it only on repositories where every security fix PR is already gated by required status checks and CODEOWNERS approval.
2

Run a scan with fix parameters

warden scan . --scanner npm-audit --severity high --max-fixes 2
The --max-fixes flag overrides fixes.maxPerRun for this run without changing the config file. The --severity flag overrides fixes.minSeverity.To preview what would happen without creating any branches or PRs, add --dry-run:
warden scan . --scanner npm-audit --severity high --max-fixes 2 --dry-run
--dry-run is the safest way to test fix configuration changes. Warden writes all artifacts — including the remediation plan and policy decision — but skips git checkout -b, git push, and PR creation. Inspect scan-results/agent-run-record.json to see what would have been fixed.
3

Engineer agent creates a fix branch

For each fixable vulnerability, the Engineer agent:
  1. Validates that no uncommitted changes are present (refuses to proceed if there are any)
  2. Creates or checks out a branch named warden/fix-<package-name>
  3. Locates the package in package.json (dependencies or devDependencies) or requirements.txt
  4. Writes the target version to the manifest, preserving the existing range prefix (^, ~, or none)
  5. Runs npm install --package-lock-only to regenerate the lockfile
  6. Runs npm test (if a test script exists) to verify the fix; reverts on failure
  7. Stages all changes and commits with message: fix(<package>): resolve <vulnerability-id>
For Python projects, the PipFixer updates the pinned version in requirements.txt and runs python3 -m pytest if a pytest suite is detected.Branch naming convention:
warden/fix-lodash
warden/fix-axios
4

Diplomat agent opens the pull request

Once the branch is committed, the Diplomat agent:
  1. Pushes the branch to origin via git push -u origin <branch>
  2. Detects the repository owner and name from git config --get remote.origin.url
  3. Resolves the default base branch via git symbolic-ref refs/remotes/origin/HEAD
  4. Calls the GitHub Pulls API (octokit.pulls.create) to open the PR
  5. Adds labels: security, automated, and severity:<level> (e.g. severity:high)
  6. Assigns the PR to GITHUB_ASSIGNEE (env var) or the repository owner
The Diplomat’s PR body includes:
  • Vulnerability Details — ID, severity, description
  • Changes Made — what manifest and lockfile lines changed
  • Review Checklist — a human-readable checklist to verify the fix
The full risk score, posture, and policy decision are captured in scan-results/agent-run-record.json and linked from the PR description.
5

Review and merge the PR

Navigate to the PR URL printed in the terminal output (also stored in scan-results/agent-run-record.json under pullRequestUrls).Review the diff: it will show exactly one change to package.json (and package-lock.json) or requirements.txt. The PR body tells you the vulnerability ID, the before/after version, and whether tests passed during the fix.Merge the PR through your normal review process. Warden does not auto-merge unless fixes.autoMerge: true is explicitly set.

​
Fix Limits and How to Change Them

Warden is deliberately conservative about how many fixes it applies per run. The default limit is one fix per run to keep PRs focused and reviewable. 
# Apply up to 5 fixes in this run
warden scan . --scanner npm-audit --severity high --max-fixes 5
Setting a large maxPerRun value creates one branch and one PR per fix, not a single giant PR. Each fix is isolated so reviewers can merge or revert individual changes without affecting others.

​
Approval Gates

When policy.requireApprovalAboveSeverity is set, Warden will plan a fix but block execution until a human provides an approval token: 
{
  "policy": {
    "requireApprovalAboveSeverity": "high"
  }
}
With this configuration, any fix at high or critical severity triggers a block. Warden writes scan-results/warden-approval-request.json and prints: 
🚦 Policy
  Approval Required: yes
  Pipeline Failure:  no
  [WARN] Approval required for high-severity fix: lodash (NPM-lodash-1523)
To unblock the fix, re-run with --approval-token approved: 
warden scan . --scanner npm-audit --severity high --max-fixes 2 --approval-token approved
The approval token is recorded in the agent-run-record.json artifact so there is a permanent record of who authorized the fix and when (via the Git commit that triggered the run).

​
Complete .wardenrc.json Fixes Section

{
  "scanner": {
    "primary": "snyk",
    "fallback": true
  },
  "fixes": {
    "maxPerRun": 2,
    "minSeverity": "high",
    "autoMerge": false
  },
  "policy": {
    "failOnSeverity": "critical",
    "failOnPosture": "critical",
    "requireApprovalAboveSeverity": "high"
  },
  "notifications": {
    "enabled": true,
    "slack": {
      "webhook": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
      "channel": "#security-alerts"
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us