Warden — AI Agent Governance Scanner

Open-source, local-only CLI scanner that evaluates AI agent governance posture across 12 scan layers and 17 dimensions. Scans code patterns, MCP configs, infrastructure, secrets, agent architecture, dependencies, audit compliance, CI/CD pipelines, IaC security, framework-specific governance, multi-language code, and cloud AI services. No data leaves the machine.

Website: sharkrouter.ai · PyPI: warden-ai

Quick Start

# With uv (zero setup, one-shot — recommended)
uvx --from warden-ai warden scan /path/to/your-agent-project

# With pip
pip install warden-ai
warden scan /path/to/your-agent-project

# Optional extras
pip install 'warden-ai[pdf]'   # adds `--format pdf` (weasyprint)

From zero to governance score in under 60 seconds.

HTML Report

Warden generates a self-contained HTML report with interactive score breakdown, actionable recommendations, and a comparison card — works offline and in air-gapped environments.

What It Does

Warden scores your AI agent project across 17 governance dimensions (out of 235 raw points, normalized to /100):

Score Levels

CLI Commands

# Scan a project (generates HTML + JSON + SARIF reports)
warden scan .
warden scan /path/to/project --format json
warden scan /path/to/project --format sarif
warden scan /path/to/project --format pdf       # requires pip install 'warden-ai[pdf]'
warden scan /path/to/project --output-dir /path/to/reports

# Skip specific layers
warden scan . --skip secrets,deps

# Run only specific layers
warden scan . --only code,mcp,cloud

# CI mode: exit code reflects governance level
warden scan . --ci                    # 0=governed, 1=partial, 2=at_risk, 3=ungoverned
warden scan . --min-score 60          # exit 1 if score < 60

# Baseline: track only new findings (brownfield adoption)
warden baseline .                     # saves .warden-baseline.json
warden scan . --baseline .warden-baseline.json  # shows only NEW findings

# Compare two reports
warden diff before.json after.json    # score delta, new/resolved findings

# Auto-fix common findings
warden fix . --dry-run                # preview fixes
warden fix .                          # apply fixes

# View the scoring methodology
warden methodology

# See the market leaderboard (20 vendors x 17 dimensions)
warden leaderboard

Config File (.warden.toml)

Warden reads project-level defaults from .warden.toml or a [tool.warden] table in pyproject.toml. Values apply when the matching CLI flag is left at its default — explicit flags always win.

# .warden.toml — checked into your repo
format = "all"
output_dir = "reports"
skip = ["secrets", "deps"]
only = []
min_score = 60
baseline = ".warden-baseline.json"
ci = true

Or alongside other tooling in pyproject.toml:

[tool.warden]
format = "sarif"
min_score = 70
skip = ["multilang"]

Warden searches upward from the scan path until it finds a config file or hits a VCS root (.git, .hg, .svn). Paths like output_dir and baseline are resolved relative to the config file. Pass --no-config to ignore any discovered config.

GitHub Action

Warden ships as a GitHub Action so every push and PR scores governance posture and publishes findings to Code Scanning.

# .github/workflows/warden.yml
name: Warden governance scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  security-events: write   # required for SARIF upload

jobs:
  warden:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SharkRouter/warden@v1
        with:
          path: .
          # Optional gates:
          # min-score: 60          # fail the build if score < 60
          # fail-on-level: at_risk # fail if posture is AT_RISK or worse

Key action inputs: path, format (json/html/sarif/all), min-score, fail-on-level, skip, only, baseline, upload-sarif, warden-version, python-version. Outputs: score, raw-score, level, findings-count, critical-count, report-json, report-html, report-sarif. See action.yml for the full interface and .github/workflows/warden-example.yml.sample for a full example workflow.

Layer Keys for --skip / --only

12 Scan Layers

1. Code Patterns — AST-based Python + regex JS/TS analysis (unprotected LLM calls, agent loops, unrestricted tool access)
2. MCP Servers — Config file analysis (write tools without auth, missing schemas, non-TLS transport)
3. Infrastructure — Dockerfile, docker-compose, K8s manifests (root containers, exposed secrets, missing healthchecks)
4. Secrets — 15+ credential patterns with value masking (OpenAI, Anthropic, AWS, GitHub, Stripe, etc.)
5. Agent Architecture — Agent class analysis (no permissions, no cost tracking, unlimited sub-agent spawning)
6. Supply Chain — Dependency analysis (unpinned AI packages, typosquat detection via Levenshtein distance)
7. Audit & Compliance — Audit logging, structured logging, retention policies, compliance framework mapping
8. CI/CD Governance — GitHub Actions analysis (missing approvals, exposed secrets, no branch protection, CODEOWNERS)
9. IaC Security — Terraform, Pulumi, and CloudFormation analysis (unencrypted storage, open security groups, IAM wildcards, missing remote backend)
10. Framework Governance — LangChain callbacks, CrewAI guardrails, AutoGen sandboxing, LlamaIndex limits
11. Multi-Language Governance — Go (context timeouts, unsafe exec), Rust (unsafe blocks, .unwrap() on API calls), Java (Spring AI @Tool auth, audit logging)
12. Cloud AI Governance — AWS Bedrock guardrails, Azure AI Content Safety, GCP Vertex AI safety settings, managed identity vs hardcoded keys

Plus D17: Adversarial Resilience — 8 sub-checks based on Google DeepMind's "AI Agent Traps" paper (Franklin et al., March 2026).

Scoring Integrity

Warden v1.5+ includes 6 anti-inflation mechanisms to prevent score gaming:

• Strong/weak pattern tiers — generic matches (e.g., import logging) score 1 point; governance-specific patterns (e.g., audit_log_tamper_proof) score 3
• Co-occurrence requirements — dimensions like D3 (Policy) and D11 (Cloud/Platform) require 3+ distinct patterns to score, preventing single-keyword inflation
• Boolean dimension scoring — each dimension scores from code patterns OR absence, never both
• CRITICAL finding deductions — each CRITICAL finding deducts 2 points (capped at 60% of earned score)
• MCP absence-vs-compliance fix — "no tools found = no violations" no longer counts as compliant; only inline tool definitions earn credit
• Positive-signal scoring — clean dependencies and zero secrets earn modest credit (1-3 pts), not full dimension scores; real points require active governance patterns (secrets managers, compliance frameworks, lockfiles)

HTML Report Features

The HTML report is fully self-contained (no CDN, no external fonts, no network requests):

• Score gauge with per-dimension breakdown bars
• Summary grid — MCP-focused when MCP tools detected, findings-focused otherwise
• Discovered tools — MCP tool inventory with risk classification (destructive, financial, exfiltration, write-access, read-only)
• Governance detection — which governance layers were found in your codebase
• Recommendations — prioritized remediation steps mapped to compliance frameworks
• Comparison card — side-by-side score projection with biggest gap dimensions
• Competitor detection — identifies 20 governance/security tools in your codebase (shown only when detected, requires 2+ signals)
• Email form — optional report delivery (score metadata only, never source code or secrets)

Output Formats

Language Support

Architecture Constraints

1. Zero network access — Scanners never import httpx/requests/urllib. CI-enforced.
2. Zero SharkRouter imports — Standalone package with no internal dependencies. CI-enforced.
3. Secrets never stored — Only file, line, pattern name, and masked preview (first 3 + last 4 chars).
4. HTML report self-contained — No CDN, no Google Fonts. Works in air-gapped environments.
5. 2 runtime dependencies — click + rich. Nothing else.

Development

# With uv (recommended)
uv sync --extra dev
uv run pytest tests/ -v

# With pip
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
pytest tests/ -v

Known Limitations

• Static analysis: Warden detects governance patterns, not enforcement. High score = controls present, not proven correct.
• Framework vocabulary: Scoring is optimized for recognized AI frameworks. Custom frameworks may score lower despite equivalent governance.
• IaC depth: Terraform has the deepest analysis. Pulumi and CloudFormation checks are regex-based heuristics.
• Multi-language AST: Go/Rust/Java analysis uses regex, not AST parsing. Fewer patterns detected than Python.
• Local filesystem scope: Warden scans files on disk, including gitignored files. Secrets in .env files are flagged even if not committed.

See SCORING.md for full methodology details.

License

MIT

Research Citation

Adversarial resilience dimension (D17) cites:

Franklin, Tomasev, Jacobs, Leibo, Osindero. "AI Agent Traps." Google DeepMind, March 2026.

Every D17 finding maps to EU AI Act articles, OWASP LLM Top 10, and MITRE ATLAS techniques.