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’s policy system is what separates an autonomous security tool from an uncontrolled one. Before any fix is applied and before the process exits, Warden evaluates the scan result and remediation plan against your configured policy rules. The result is a PolicyDecision — a structured object that records exactly which gates fired, whether fixes are blocked, whether the pipeline should fail, and what the exit code will be. Every policy decision is written into agent-run-record.json so the rationale is always auditable after the fact.

​
The Three Gate Types

Policy gates are configured in the policy block of .wardenrc.json. All three gates are evaluated on every run; they are not mutually exclusive.

​
1. failOnSeverity

Fails the pipeline when the highest-severity finding in the scan result meets or exceeds the configured threshold. 
{
  "policy": {
    "failOnSeverity": "critical"
  }
}
Mechanics: evaluatePolicy() identifies the highest present severity by walking critical → high → medium → low and checking which count in ScanSummary is non-zero. If the highest present severity is at or above failOnSeverity, a reason string is appended: 
Pipeline gate triggered: highest severity critical meets failOnSeverity=critical.
shouldFailPipeline is set to true only when the --ci flag is active and at least one reason contains "Pipeline gate triggered". In interactive runs, the gate reason is logged but the process exits with code 0.

​
2. failOnPosture

Fails the pipeline when the computed security posture meets or exceeds the configured posture level. 
{
  "policy": {
    "failOnPosture": "elevated"
  }
}
Posture levels and their risk score ranges:
PostureRisk Score RangePriorityValid failOnPosture value
stable0 – 290No — stable cannot be configured as a gate value
guarded30 – 591Yes
elevated60 – 892Yes
critical90 – 1003Yes
failOnPosture accepts "guarded", "elevated", or "critical" only — "stable" is not a valid gate value because it represents the absence of a security concern. The posture priority order means failOnPosture: "guarded" will also trigger on elevated and critical. Setting it to "critical" only fires when the risk score reaches 90 or above. Mechanics: buildRemediationPlan() derives the posture from riskScore. The risk score is computed as a weighted sum across all vulnerabilities: each finding contributes SEVERITY_PRIORITY × 20 base points, plus up to 30 points from its CVSS score, plus 25 points if a known exploit is available. The total is capped at 100.

​
3. requireApprovalAboveSeverity

Blocks automated fix application — without failing the pipeline — when the highest finding meets or exceeds the configured severity. A warden-approval-request.json file is written to scan-results/ so a human or downstream system can review and re-authorize the run. 
{
  "policy": {
    "requireApprovalAboveSeverity": "high"
  }
}
Mechanics: When the gate fires and the approval token is absent or wrong, shouldBlockFixes is set to true. The fix loop is skipped entirely and the approval request artifact is written. The pipeline continues to report generation and history/memory updates — it does not halt.

​
The Approval Flow

Approval is a two-step human-in-the-loop mechanism:
1

Gate fires — approval request written

Warden detects that the highest severity meets requireApprovalAboveSeverity. Because no approval token was provided, shouldBlockFixes: true and approvalSatisfied: false are set. warden-approval-request.json is written to scan-results/ containing the highest severity, posture, risk score, gate reasons, and the next-step instruction.
{
  "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."
}
2

Human reviews the approval request

A reviewer reads warden-approval-request.json (or the agent-run-record.json policyDecision block) and decides whether automated remediation should proceed. This is the control point — a team lead, security engineer, or automated review system makes the call.
3

Re-run with approval token

The operator re-runs Warden with --approval-token approved. The approval check passes (approvalSatisfied: true), shouldBlockFixes becomes false, and the fix loop executes normally.
warden scan . --approval-token approved --scanner npm-audit --severity high
The only accepted approval token value is the literal string approved. Any other value leaves approvalSatisfied: false and the fix loop remains blocked. This is intentional — the token is a boolean gate, not a passphrase.

​
CI Mode and Exit Codes

Without --ci, Warden always exits with code 0 regardless of what the policy evaluation found. Gate reasons are logged and recorded in artifacts, but they do not affect process exit. With --ci, shouldFailPipeline is evaluated and the exit code changes:
ConditionExit Code
No gates fired0
failOnSeverity or failOnPosture gate fired2
Exit code 2 is specifically chosen to distinguish a policy gate failure from a generic tool error (exit code 1). Configure your CI system to treat exit code 2 as a hard gate failure that blocks merge, not just a build warning.
# CI pipeline — fail on critical findings
warden scan . --ci --scanner npm-audit --severity high

# Check exit code explicitly
echo "Exit code: $?"

​
Full Policy Configuration Example

{
  "scanner": {
    "primary": "snyk",
    "fallback": true,
    "timeout": 300000,
    "retries": 3
  },
  "fixes": {
    "maxPerRun": 2,
    "minSeverity": "high",
    "autoMerge": false,
    "branchPrefix": "warden/fix"
  },
  "policy": {
    "failOnSeverity": "critical",
    "failOnPosture": "elevated",
    "requireApprovalAboveSeverity": "high"
  }
}
With this configuration:
  • Any critical finding fails the CI pipeline.
  • An elevated or critical posture (risk score ≥ 60) fails the CI pipeline.
  • Any high or critical finding blocks automated fixes until --approval-token approved is provided.

​
The PolicyDecision Type

Every policy evaluation produces a PolicyDecision object that is embedded verbatim into agent-run-record.json: 
interface PolicyDecision {
  shouldBlockFixes: boolean;       // Fix loop is skipped when true
  shouldFailPipeline: boolean;     // true only in --ci mode when a gate fires
  exitCode: number;                // 0 or 2
  reasons: string[];               // Human-readable gate trigger descriptions
  approvalRequired: boolean;       // requireApprovalAboveSeverity gate fired
  approvalSatisfied: boolean;      // true when --approval-token approved was provided
}
Read policyDecision.reasons[] in agent-run-record.json to understand exactly which gates fired and why. This is especially useful when debugging CI failures in pipelines where terminal output is not preserved.

Build docs developers (and LLMs) love

Get started for freeTalk to us