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.

The .wardenrc.json file is Warden’s primary configuration file. It controls every aspect of how Warden scans your project, creates pull requests, enforces security policies, and delivers notifications. You can override individual settings without touching defaults — Warden performs a deep merge so any key you omit falls back to its built-in default.

​
Creating a Config File

Run the following command in your project root to scaffold a .wardenrc.json with all defaults pre-filled: 
warden config --create
Warden resolves your config file by checking the following paths in order, stopping at the first match:
  1. .wardenrc.json in the current working directory
  2. .wardenrc in the current working directory
  3. warden.config.json in the current working directory
  4. ~/.wardenrc.json in your home directory
If none of these files exist, Warden falls back to built-in defaults for every setting.

​
scanner

Controls which vulnerability scanner Warden uses and how it behaves.
​
scanner.primary
"snyk" | "npm-audit" | "all"
default:"\"snyk\""
The primary scanner to use. "snyk" uses the Snyk CLI and provides richer vulnerability data. "npm-audit" uses the built-in npm audit command and requires no extra credentials. "all" runs both scanners and merges the results.
​
scanner.fallback
boolean
default:"true"
When true, Warden automatically falls back to npm-audit if the primary scanner (Snyk) fails — for example, when SNYK_TOKEN is not set or the Snyk CLI is unavailable.
​
scanner.timeout
number
default:"300000"
Maximum time in milliseconds to wait for a scanner to complete. Defaults to 300,000 ms (5 minutes). Increase this value for very large monorepos.
​
scanner.retries
number
default:"3"
Number of times Warden retries a failed scan before giving up.
"scanner": {
  "primary": "snyk",
  "fallback": true,
  "timeout": 300000,
  "retries": 3
}

​
fixes

Controls automated fix behavior — how many fixes Warden applies per run, which severity threshold triggers a fix, and how branches and PRs are named.
​
fixes.maxPerRun
number
default:"1"
Maximum number of vulnerability fixes Warden will attempt in a single run. Keep this low (1–3) to ensure PRs remain focused and easy to review.
​
fixes.minSeverity
"low" | "medium" | "high" | "critical"
default:"\"high\""
Minimum severity level required before Warden attempts a fix. Vulnerabilities below this threshold are reported but not auto-fixed.
​
fixes.autoMerge
boolean
default:"false"
When true, Warden will attempt to auto-merge fix PRs after creation. Requires the GitHub token to have merge permissions and branch protection rules to allow it.
​
fixes.branchPrefix
string
default:"\"warden/fix\""
Prefix for fix branches created by Warden. The full branch name will be {branchPrefix}/{vulnerability-id}, e.g. warden/fix/SNYK-JS-LODASH-123.
"fixes": {
  "maxPerRun": 1,
  "minSeverity": "high",
  "autoMerge": false,
  "branchPrefix": "warden/fix"
}

​
github

Controls how Warden interacts with GitHub when creating pull requests.
​
github.assignees
string[]
default:"[]"
GitHub usernames to assign to every PR Warden creates. Overrides GITHUB_ASSIGNEE env var for all PRs.
​
github.labels
string[]
default:"[\"security\", \"automated\"]"
Labels to apply to every PR. Labels must already exist in the repository.
​
github.reviewers
string[]
default:"[]"
GitHub usernames to request reviews from on every PR.
​
github.autoAssign
boolean
default:"true"
When true, Warden automatically assigns the PR to the GitHub user associated with the GITHUB_TOKEN if no explicit assignees are configured.
"github": {
  "assignees": [],
  "labels": ["security", "automated"],
  "reviewers": ["security-team"],
  "autoAssign": true
}

​
policy

Defines exit-code and gating behavior for CI pipelines. Policy settings let you fail a pipeline or block fixes based on vulnerability severity or the overall security posture score.
​
policy.failOnSeverity
"low" | "medium" | "high" | "critical"
default:"\"critical\""
If any discovered vulnerability meets or exceeds this severity, Warden exits with a non-zero exit code, failing the pipeline step.
​
policy.failOnPosture
"guarded" | "elevated" | "critical"
default:"\"critical\""
Warden computes a holistic security posture (guarded, elevated, or critical) based on the full scan result. If the posture meets or exceeds this threshold, the pipeline fails.
​
policy.requireApprovalAboveSeverity
"low" | "medium" | "high" | "critical"
default:"\"critical\""
Fixes for vulnerabilities at or above this severity level require a human approval token before Warden will apply them. See the --approval-token CLI flag.
"policy": {
  "failOnSeverity": "high",
  "failOnPosture": "elevated",
  "requireApprovalAboveSeverity": "critical"
}

​
notifications

Configures Warden to send scan summaries and fix notifications to Slack, Discord, or email.
​
notifications.enabled
boolean
default:"false"
Master switch for all notifications. When false, no messages are sent regardless of other notification settings.

​
notifications.slack

​
notifications.slack.webhook
string
Incoming Webhook URL for a Slack workspace. Create one at api.slack.com/apps.
​
notifications.slack.channel
string
Optional channel override, e.g. #security-alerts. If omitted, messages go to the channel configured in the webhook itself.

​
notifications.discord

​
notifications.discord.webhook
string
Discord channel webhook URL. Find this in your Discord server’s channel settings under Integrations → Webhooks.

​
notifications.email

​
notifications.email.to
string[]
List of recipient email addresses.
​
notifications.email.from
string
Sender address, e.g. "Warden <warden@example.com>".
​
notifications.email.provider
"resend" | "webhook"
Email delivery provider. "resend" uses the Resend API (requires RESEND_API_KEY). "webhook" posts a JSON payload to the URL specified in email.webhook.
​
notifications.email.apiKeyEnv
string
Name of the environment variable that holds the provider API key, e.g. "RESEND_API_KEY". Warden reads the key at runtime from process.env.
​
notifications.email.webhook
string
Webhook URL used when provider is "webhook". Warden POSTs a JSON body containing scan summary data.
​
notifications.email.subjectPrefix
string
Optional prefix for email subject lines, e.g. "[Warden]".
"notifications": {
  "enabled": true,
  "slack": {
    "webhook": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
    "channel": "#security-alerts"
  },
  "discord": {
    "webhook": "https://discord.com/api/webhooks/YOUR/WEBHOOK/URL"
  },
  "email": {
    "to": ["security@example.com"],
    "from": "Warden <warden@example.com>",
    "provider": "resend",
    "apiKeyEnv": "RESEND_API_KEY",
    "subjectPrefix": "[Warden]"
  }
}

​
logging

​
logging.level
"error" | "warn" | "info" | "debug"
default:"\"info\""
Log verbosity level. Use "debug" to see every internal step Warden takes, which is helpful when troubleshooting scan issues.
​
logging.file
boolean
default:"true"
When true, Warden writes logs to a file inside the logs/ directory in addition to console output.
​
logging.console
boolean
default:"true"
When true, Warden prints log output to stdout/stderr. Set to false to suppress terminal output in CI environments where only structured JSON output is wanted.
"logging": {
  "level": "info",
  "file": true,
  "console": true
}

​
exclude

Suppresses specific packages, vulnerability IDs, or whole severity levels from scan results. Exclusions apply before policy evaluation and fix selection, so excluded items never trigger pipeline failures or auto-fixes.
​
exclude.packages
string[]
default:"[]"
Package names to exclude from all scan results, e.g. ["lodash", "moment"].
​
exclude.vulnerabilities
string[]
default:"[]"
Specific vulnerability IDs to suppress, e.g. ["SNYK-JS-LODASH-567746", "GHSA-29mw-wpgm-hmr9"].
​
exclude.severities
string[]
default:"[]"
Severity levels to ignore entirely, e.g. ["low", "medium"]. Use this to focus Warden on actionable findings only.
"exclude": {
  "packages": ["some-legacy-package"],
  "vulnerabilities": ["SNYK-JS-EXAMPLE-000000"],
  "severities": ["low"]
}

​
Complete Example

The following is the full example from examples/.wardenrc.example.json: 
{
  "scanner": {
    "primary": "snyk",
    "fallback": true,
    "timeout": 300000,
    "retries": 3
  },
  "fixes": {
    "maxPerRun": 1,
    "minSeverity": "high",
    "autoMerge": false,
    "branchPrefix": "sentinel/fix"
  },
  "github": {
    "assignees": [],
    "labels": [
      "security",
      "automated",
      "sentinel"
    ],
    "reviewers": [],
    "autoAssign": true
  },
  "notifications": {
    "enabled": false,
    "slack": {
      "webhook": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
      "channel": "#security-alerts"
    },
    "discord": {
      "webhook": "https://discord.com/api/webhooks/YOUR/WEBHOOK/URL"
    },
    "email": {
      "to": [
        "security@example.com"
      ],
      "from": "Warden <warden@example.com>",
      "provider": "resend",
      "apiKeyEnv": "RESEND_API_KEY",
      "subjectPrefix": "Warden"
    }
  },
  "logging": {
    "level": "info",
    "file": true,
    "console": true
  },
  "exclude": {
    "packages": [],
    "vulnerabilities": [],
    "severities": []
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us