Warden is built around a single, repeatable pipeline. Every time you invokeDocumentation 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 scan or warden dast, the same orchestrator fires — loading your rules and specs, selecting the right workflow strategy, running the scan, evaluating policy gates, writing durable artifacts, and optionally pushing branches and opening pull requests. The pipeline is intentionally linear so every run produces the same categories of output regardless of which scanner ran or what it found.
The Orchestration Pipeline
TherunWarden function in orchestrator.ts is the entry point for every scan. It is kept deliberately thin: all the domain logic lives in workflow strategy classes (SastWorkflow and DastWorkflow) so adding a new scan mode only requires implementing the IWorkflow interface and adding a branch.
Load Configuration
The orchestrator calls
loadRules() first. If WARDEN_CORE.md is missing, the process throws immediately — a scan cannot proceed without its rules of engagement. After rules are confirmed, loadSpecs() reads every .md file from the SPEC/ directory and makes them available to the workflow. If no spec files are found, Warden continues with default behaviour and logs a warning.Select and Execute Workflow
Based on the
scanMode field in WardenOptions, the orchestrator instantiates either SastWorkflow (the default) or DastWorkflow and calls .run(options). The workflow owns all scanner invocation, fix application, and advisory generation for its mode. The result is a WardenRunResult object that carries the raw ScanResult alongside fix counts, branch names, and PR URLs.Build the Remediation Plan
Once the workflow returns a
ScanResult, the orchestrator calls buildRemediationPlan(). This function computes a risk score (0–100), classifies the current posture (stable, guarded, elevated, or critical), counts auto-fixable vs. manual findings, and produces structured immediateActions, manualFollowUps, and strategicImprovements lists. The plan is attached to the run result and referenced by every downstream step.Evaluate Policy Gates
evaluatePolicy() compares the scan result and remediation plan against your .wardenrc.json policy block. It produces a PolicyDecision that records whether fixes should be blocked, whether the pipeline should fail, and which specific reasons triggered those decisions. See Policy Gates for the full gate reference.Write Reports
Three report files are written to
scan-results/:warden-report.md— human-readable operator summary.scan-results.html— browser-viewable HTML report.agent-run-record.json— machine-readable handoff record consumed by CI jobs, dashboards, and downstream agents.
warden-approval-request.json is also written to scan-results/.Append Run History
RunHistoryService.append() reads the existing scan-results/history.json, pushes a new RunHistoryEntry, and persists the file. It also computes the run trend — first-run, improving, worsening, or unchanged — by comparing the current risk score and total vulnerability count to the previous entry.Update Memory
MemoryService.update() maintains scan-results/memory.json, a per-repository record of which packages have appeared vulnerable across runs. Each invocation increments occurrences for every vulnerable package and promotes lastSeverity if the new finding is more severe. The top five hotspots are returned as a MemorySnapshot.Send Notifications
Finally,
NotificationService.send() dispatches a completion notification. The severity of the notification mirrors the posture from the remediation plan: a critical posture sends an error-level notification; elevated sends a warning; anything else sends success. Notifications are no-ops unless notifications.enabled is true in .wardenrc.json.Core Agent Roles
Three named agents handle the work that the orchestrator delegates inside each workflow.Watchman
The scanner layer. Watchman agents (
SnykScanner, NpmAuditScanner, PipAuditScanner, NmapScanner, MetasploitScanner) execute the underlying security tools, normalize their output into the shared ScanResult schema, and return structured Vulnerability[] arrays. The SAST workflow applies a fallback chain — Snyk → npm-audit → mock — so a scan always completes even when primary tools are unavailable.Engineer
The fix-application layer. After Watchman produces a scan result,
EngineerAgent reads the normalized findings, generates Diagnosis objects (including structured FixInstruction data for auto-fixable packages), and applies package-manager-level fixes. Only vulnerabilities that meet the configured minSeverity threshold and fall within the maxFixes cap are passed to the Engineer.Diplomat
The PR-creation layer.
DiplomatAgent creates a Git branch for each applied fix, pushes it, and opens a pull request on GitHub. For SAST runs, each fix gets its own branch and PR. For DAST runs, a single advisory PR is opened containing the full infrastructure findings report. Diplomat is skipped entirely in dry-run mode or when GITHUB_TOKEN is not set.Rules of Engagement: WARDEN_CORE.md
WARDEN_CORE.md is Warden’s rules file. It is loaded unconditionally at the start of every run via loadRules(), which will throw a critical error and abort if the file does not exist. The file encodes directives that constrain how the agent is permitted to behave — for example, limiting the scope of automated changes, requiring human review for certain finding types, or setting guardrails on which packages are eligible for automated fixes.
loadRules() resolves WARDEN_CORE.md relative to the package’s own installation directory (WARDEN_HOME), not the current working directory. This ensures the rules file is always the one shipped with the installed version of Warden, not one that might be present in the target repository.The Spec System
TheSPEC/ directory sits alongside WARDEN_CORE.md in Warden’s home directory. Each .md file in SPEC/ is a specification document loaded by loadSpecs() at startup. Specs carry supplementary context — for example, project-specific remediation guidance, approved dependency lists, or team-level escalation paths — that workflows and agents can reference during their execution. Spec files are optional: Warden continues normally when the directory is empty, logging a warning instead of aborting.