⚔️ 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.

Related MCP server: TuringWell MCP Server

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 the CI gate, real terminal output, real dashboard — concurrent Builder + Breaker, HIPAA domain testing, and every IDE integration in one pass.

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.

Where GAUNTLEX fits vs. other security testing

Not a replacement for any of these — a different point in the lifecycle. Static analysis and pentests are still worth doing; GAUNTLEX exists because neither of them runs while the code is being generated.

Quickstart

gauntlex setup        # start here — interactive, detects and validates the best
                       # model for your environment (Ollama, OpenRouter free
                       # tier, or your own API key)

gauntlex run --issue examples/demo_issue.md --mode quick --pretty   # then run the demo spec

Install first with pip install gauntlex-ai, or skip the install entirely with uvx --from gauntlex-ai gauntlex setup.

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

Add business intent — attack surface = spec + why it's needed

--issue is the spec — precise enough for the Builder and Breaker to implement and attack. It answers what to build. --intent adds a second, separate input answering why it's needed, pulled from wherever your team actually tracks that: a Jira key, a Confluence page, or an Aha! roadmap item. GAUNTLEX reasons from both together, not just the spec alone.

gauntlex run --issue SPEC.md --intent PROJ-123 --domain hipaa --pretty

gauntlex setup connects Jira/Confluence/Aha! automatically if it detects credentials in your environment — see the interactive wizard's business intent step.

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:

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

Language support

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

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:

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.

Key terms

• Adversarial Resilience Score (ARS) — the mean of per-attack scores (mitigated=1.0, partial=0.5, missed=0.0) across every attack fired at a run. Range [0.0, 1.0]. The core metric GAUNTLEX produces.

• Builder — the agent that generates code from the specification.

• Breaker — the agent that generates adversarial attacks from the same specification, at the same instant, without seeing the Builder's output.

• Concurrent co-generation — Builder and Breaker running via asyncio.gather() against the same spec at the same time, instead of testing after code is written.

• Resilience Report — the tamper-evident output of a GAUNTLEX run, including a SHA-256 hash over the ordered attack results, independently verifiable via gauntlex verify.

• Gate — the CI check that blocks a merge when a run's ARS falls below the configured threshold (default 0.80).

FAQ

How do I test AI-generated code for security vulnerabilities? Point GAUNTLEX at the same specification your AI coding tool used: gauntlex run --spec your_spec.md --mode quick. It fires adversarial attacks derived from that spec and returns an Adversarial Resilience Score in under a minute.

What is an Adversarial Resilience Score (ARS)? The mean of per-attack scores (mitigated = 1.0, partial = 0.5, missed = 0.0) across every attack fired at a run — a continuous [0.0, 1.0] measure of how well the generated code holds up, not a simple pass/fail count. Full formula and reasoning: the ARS explainer.

Does GAUNTLEX test code before or after it's generated? At the same instant. The Breaker agent reasons from the specification directly, concurrently with the Builder — it never waits for code to exist first, which is what "concurrent, not sequential" means in practice.

Which compliance frameworks does GAUNTLEX support? OWASP Top 10, HIPAA, FINRA, PCI DSS, and SOC 2 out of the box, with NIST SSDF and OWASP API Security available as installable extensions. See Domain Intelligence for exactly what's covered per domain.

Can GAUNTLEX run without sending code to an external API? Yes — the full engine runs on local Ollama with zero outbound calls, for air-gapped or compliance-restricted environments.

More questions, including gating thresholds and contributing a new policy domain: full FAQ in the Deep Dive.

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.

Where to find GAUNTLEX

Package & registries

• PyPI — pip install gauntlex-ai

• Official MCP Registry — listed as io.github.sanjoy1234/gauntlex

Writing

• dev.to — "Why I Built an Adversarial Co-Generation Engine"

• LinkedIn Article — "The Math That Breaks When AI Writes a Million Lines of Code"

Community

• GitHub Discussions — questions, feedback, and "I built X with this" show-and-tell

Acknowledgments

• Deven Samant — early feedback and validation

MIT License · Built by Sanjoy Ghosh