gauntlex-ai 1.0.0

Adversarial Co-Generation Engine — concurrent Builder + Breaker agents for production-grade AI-generated code

⚔️ GAUNTLEX

Adversarial Co-Generation Engine

Generates code and adversarial attacks from the same specification, at the same time — before a commit exists.

What it is · See it run · Quickstart · Commands · Domains · IDE Integrations · Deep Dive

---

What it is

Every AI coding tool ships code and hopes someone tests it for security later. GAUNTLEX removes the "later." It runs two agents concurrently against the same specification:

• Builder — generates the implementation
• Breaker — generates adversarial attacks against the same spec, at the same instant

An Arbiter scores every attack (mitigated / partial / missed) and produces an Adversarial Resilience Score (ARS). A configurable gate blocks your CI pipeline when the score falls below threshold — the same way a failing test suite blocks a merge.

No manual test authoring. No separate security review step. No waiting for a scanner to catch up to code that shipped last week.

---

See it run

📊 One-page overview — what it is, what's different, how it deploys. Built for sharing with a technical lead or architecture review board.

Download the full PDF

▶ Watch the demo — setup through CI gate, real terminal output, real dashboard.

---

Why it's structurally different

Three properties, not features — the reasoning behind each is in the Deep Dive:

1. Concurrent, not sequential. Builder and Breaker fire at the same instant via asyncio.gather(). The Breaker never sees generated code — it reasons from the specification alone, the same surface a real attacker would work from before your implementation choices exist.
2. A native MCP integration, both directions. GAUNTLEX exposes itself as an MCP server so Claude Code, Cursor, Windsurf, or Zed can trigger and poll runs directly from your coding tool — and it consumes external MCP servers (plus built-in CISA KEV / NIST NVD feeds) to enrich every run with live threat data. See the Domain Intelligence page for exactly what's live vs. static.
3. Regulatory domains as first-class input. FINRA, HIPAA, PCI DSS, SOC 2, and OWASP Top 10 playbooks steer the Breaker toward the scenarios that actually matter for a regulated codebase — not a generic scan re-labeled per industry.

---

Quickstart

# 1. Install — pick one
pip install gauntlex-ai
# or, zero-install (the package is gauntlex-ai, the command is gauntlex):
uvx --from gauntlex-ai gauntlex setup   # swap `setup` for any command below

# 2. Interactive setup — detects and validates the best model for your environment
#    (Ollama for free/air-gapped, OpenRouter free tier, or your own API key)
gauntlex setup

# 3. Run on the included demo spec
gauntlex run --issue examples/demo_issue.md --mode quick --pretty

gauntlex setup writes your model provider and credentials to .env for you — there is no manual configuration step, and no fallback to whatever API key happens to be lying around the environment. What you configure during setup is what runs, always (run gauntlex init separately if you also want a .gauntlex.yml with tunable defaults like rounds_max or the gate threshold).

──────────────────────────────────────────────────────────────────────
  GAUNTLEX Adversarial Run
  Mode:      quick (5 attacks)
  Language:  python  [signals: filesystem, async]
  Domain:    owasp_top10
──────────────────────────────────────────────────────────────────────
  ARS Score: 0.87  ✅  PASSED  (gate: ≥ 0.80)

  ✅ CWE-89  SQL Injection via username param     mitigated
  ✅ CWE-502 Unsafe deserialization                mitigated
  ✅ CWE-78  OS command injection in file path     mitigated
  ✅ CWE-22  Path traversal in upload handler       mitigated
  ❌ CWE-79  Reflected XSS in error message         MISSED
──────────────────────────────────────────────────────────────────────

Wall-clock time depends on which model you configure — anywhere from single-digit seconds with a fast paid API to several minutes with a free-tier or local model. Attack count targets 5/20/50 by mode (quick/standard/thorough), spread across the adversarial rounds — actual totals land close to but not always exactly at the target (a thorough run might fire ~30–50, for example), since it depends on how many attacks the model actually returns per round.

Run against a GitHub issue directly

gauntlex run --issue https://github.com/your-org/your-repo/issues/42 --mode standard --domain hipaa --pretty

Requirements

• Python 3.11+
• macOS, Linux, or Windows (WSL2 recommended on Windows)
• One model provider: Ollama (free, local), OpenRouter free tier, or an Anthropic/OpenAI API key

---

CLI reference

All 22 commands, grouped by when you'd reach for them:

Getting started
gauntlex setup	Configure model provider and integrations (run any time to reconfigure)
gauntlex init	Scaffold .gauntlex.yml with sensible defaults
gauntlex doctor	Full environment health check
gauntlex validate	Dry run — checks config and connectivity, fires zero attacks

Running assessments
gauntlex run	Run adversarial Builder + Breaker on a spec
gauntlex status	Show running and recently completed runs
gauntlex findings	Vulnerability findings from the last run — fix-first, score last
gauntlex compare	Diff two Resilience Reports — ARS delta and attack-level changes
gauntlex learn	Feed a run into the Knowledge Forge + Forge Ledger (runs automatically after every gauntlex run — use this to re-process an older run)

Evidence & compliance
gauntlex report	Render a stored report in any output format (HTML/SARIF/JUnit/JSON)
gauntlex verify	Re-derive SHA-256 integrity hash, confirm a report hasn't been altered
gauntlex audit	List all reports with compliance control mapping over a time window
gauntlex vault	Browse the Forge Ledger — human-readable Markdown attack records
gauntlex stats	ARS trends, learning-curve, and cost metrics

Domains & policy
gauntlex policy	List, install, search, or validate policy domains — see Domain Intelligence

Team & CI deployment
gauntlex integrate	One command: wire GAUNTLEX into Claude Code, Cursor, Windsurf, Copilot, Codex, Zed, Antigravity, or GitHub Actions
gauntlex mcp-server	Start GAUNTLEX as an MCP server (stdio transport) for local IDE use
gauntlex serve	Start GAUNTLEX as a webhook/CI service, with optional GitHub team-based RBAC
gauntlex dashboard	Launch the GAUNTLEX dashboard web UI
gauntlex leaderboard	Build an ARS leaderboard across multiple agents/runs
gauntlex forge-network	Opt-in community adversarial pattern sharing
gauntlex prune	Remove expired reports

Full usage, flags, and examples for every command: Deep Dive → Complete CLI Reference.

---

Language support

Auto-detected from the specification — no per-project configuration:

Language	Priority CWEs (examples)
Python	SQL injection, OS command injection, unsafe deserialization, path traversal
JavaScript / TypeScript	Prototype pollution, XSS, CSRF, SSRF
Java	Deserialization, XXE, authorization bypass
Go	Race conditions, nil-pointer dereference, resource exhaustion

---

Compliance & domain coverage

5 regulated-industry playbooks ship today — 43 attack scenarios total, each mapped to a specific rule or control, not a generic label:

Domain	Scenarios	Regulatory framework
owasp_top10	12	OWASP Top 10 (2021/2025)
finra	9	FINRA Rules 4370, 3110; SEC Rule 17a-4
hipaa	9	HIPAA Security Rule (45 CFR §§160, 164)
soc2	7	AICPA SOC 2 Trust Service Criteria
pci_dss	6	PCI DSS v4.0

Two more (owasp_api_security, nist_ssdf) are available via gauntlex policy install. GDPR, FedRAMP, and DORA are on the roadmap — not available today.

For exactly what's live threat data vs. static playbook content, and how to bring your own domain, see the full Domain Intelligence page.

---

IDE & agent integrations

One command wires GAUNTLEX into whatever AI coding tool you already have open:

gauntlex integrate --dry-run               # preview every config it would write, writes nothing
gauntlex integrate                         # wire up every supported target at once
gauntlex integrate --platform claude-code  # or just one — .mcp.json
gauntlex integrate --platform cursor       # .cursor/mcp.json
gauntlex integrate --platform windsurf     # ~/.codeium/windsurf/mcp_config.json
gauntlex integrate --platform copilot      # .vscode/mcp.json
gauntlex integrate --platform codex        # ~/.codex/config.toml
gauntlex integrate --platform zed          # .zed/settings.json
gauntlex integrate --platform antigravity  # ~/.gemini/config/mcp_config.json
gauntlex integrate --platform github-actions  # .github/workflows/gauntlex.yml CI gate

Each target gets the right file, format, and schema for that specific tool — this command handles the differences so you don't have to — and it merges into any config you already have rather than overwriting it, so other MCP servers you've already configured survive.

Claude Code users can also install via the plugin marketplace instead of integrate:

/plugin marketplace add sanjoy1234/gauntlex
/plugin install gauntlex@gauntlex

This registers the MCP server and all /gauntlex:* skills (run, verify, doctor, compare, report, learn, validate) in one step, updated via /plugin update. Requires gauntlex on PATH (pip install gauntlex-ai).

Zero-config: this repo ships an AGENTS.md that Codex, Cursor, Cline, Windsurf, and Gemini CLI read automatically with no install step at all — copy the pattern into your own repo if you're building on top of GAUNTLEX rather than just using it.

Exact file paths per platform, the merge-safety guarantees, and the MCP tools GAUNTLEX exposes (gauntlex_run, gauntlex_status, gauntlex_verify, and more): Integrations guide.

---

Enterprise deployment

• gauntlex dashboard — ARS trend, gate status, and attack-outcome breakdown across every connected repository. One URL for the team.
• gauntlex serve --rbac — GitHub team-based access control (admin / reviewer / developer) across a shared instance.
• gauntlex audit — every run listed with NIST SSDF / OWASP SAMM / SOC 2 control mapping, for a configurable window.
• Air-gapped operation — the full engine runs on local Ollama with zero outbound calls, for environments that can't reach the internet.

Full detail on each: Deep Dive → Enterprise Features.

---

Learn more

• Deep Dive — the full story: why concurrent execution matters, how GAUNTLEX compares to SAST/DAST/pentest, the complete CLI and configuration reference, architecture, FAQ, and roadmap.
• Domain Intelligence — exactly what's covered per regulated domain, what's live vs. static, and how to extend it.
• Contributing — how to add a policy domain, a language profile, or a feature.

---

MIT License · Built by Sanjoy Ghosh