{
  "markdown": "<div align=\"center\">\n\n# ⚔️ GAUNTLEX\n\n### Adversarial Co-Generation Engine\n\n**Generates code and adversarial attacks from the same specification, at the same time — before a commit exists.**\n\n<!-- mcp-name: io.github.sanjoy1234/gauntlex -->\n\n[![Tests](https://img.shields.io/badge/tests-612%20passing-brightgreen)](https://github.com/sanjoy1234/gauntlex/actions)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/gauntlex-ai/)\n[![PyPI](https://img.shields.io/pypi/v/gauntlex-ai)](https://pypi.org/project/gauntlex-ai/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![OS](https://img.shields.io/badge/OS-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#requirements)\n\n[**What it is**](#what-it-is) ·\n[**See it run**](#see-it-run) ·\n[**Quickstart**](#quickstart) ·\n[**Commands**](#cli-reference) ·\n[**Domains**](#compliance--domain-coverage) ·\n[**IDE Integrations**](#ide--agent-integrations) ·\n[**Deep Dive**](docs/DEEP_DIVE.md)\n\n</div>\n\n---\n\n## What it is\n\nEvery AI coding tool ships code and hopes someone tests it for security later.\nGAUNTLEX removes the \"later.\" It runs two agents concurrently against the same\nspecification:\n\n- **Builder** — generates the implementation\n- **Breaker** — generates adversarial attacks against the same spec, at the same instant\n\nAn **Arbiter** scores every attack (mitigated / partial / missed) and produces\nan **Adversarial Resilience Score (ARS)**. A configurable gate blocks your CI\npipeline when the score falls below threshold — the same way a failing test\nsuite blocks a merge.\n\nNo manual test authoring. No separate security review step. No waiting for a\nscanner to catch up to code that shipped last week.\n\n---\n\n## See it run\n**📊 One-page overview** — what it is, what's different, how it deploys. Built for sharing with a technical lead or architecture review board.\n\n<img src=\"docs/media/GAUNTLEX_Overview_slide1.jpg\" alt=\"GAUNTLEX overview — slide 1\" width=\"800\">\n<img src=\"docs/media/GAUNTLEX_Overview_slide2.jpg\" alt=\"GAUNTLEX overview — slide 2\" width=\"800\">\n\n**[Download the full PDF](docs/media/GAUNTLEX_Overview.pdf)**\n\n**Watch the Demo**\n<video src=\"https://github.com/user-attachments/assets/c1a5dcb6-b4ac-4699-ab3a-0ca58e78dd90\" controls muted></video>\nSetup through the CI gate, real terminal output, real dashboard — concurrent Builder + Breaker, HIPAA domain testing, and every IDE integration in one pass.\n\n---\n\n## Why it's structurally different\n\nThree properties, not features — the reasoning behind each is in the [Deep Dive](docs/DEEP_DIVE.md):\n\n1. **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.\n2. **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](docs/DOMAIN_INTELLIGENCE.md) page for exactly what's live vs. static.\n3. **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.\n\n---\n\n## Where GAUNTLEX fits vs. other security testing\n\nNot 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*.\n\n| | Traditional SAST (Semgrep, Snyk, etc.) | Manual pentest | No dedicated testing | GAUNTLEX |\n|---|---|---|---|---|\n| **When it runs** | After code is written | After code is written, periodically | Never, until an incident | Same instant as generation |\n| **What it tests** | Known vulnerability patterns in existing code | The live, deployed system | Nothing dedicated | The spec-to-code pipeline itself |\n| **Speed** | Minutes per scan | Days to weeks per engagement | — | ~45s–12min per run (mode-dependent) |\n| **Cost** | Free–moderate | High (specialist time) | \"Free\" until it isn't | Free, open source |\n| **Compliance mapping** | Varies by tool | Manual, engagement-specific | None | Built-in — OWASP/HIPAA/FINRA/PCI-DSS/SOC2 + CWE + NIST SSDF/SAMM/ISO 27001 |\n| **Output you can verify later** | Scan report | Pentest report | — | SHA-256 tamper-evident report (`gauntlex verify`) |\n\n---\n\n## Quickstart\n\n```bash\ngauntlex setup        # start here — interactive, detects and validates the best\n                       # model for your environment (Ollama, OpenRouter free\n                       # tier, or your own API key)\n\ngauntlex run --issue examples/demo_issue.md --mode quick --pretty   # then run the demo spec\n```\n\nInstall first with `pip install gauntlex-ai`, or skip the install entirely with `uvx --from gauntlex-ai gauntlex setup`.\n\n`gauntlex setup` writes your model provider and credentials to `.env` for\nyou — there is no manual configuration step, and no fallback to whatever API\nkey happens to be lying around the environment. What you configure during\nsetup is what runs, always (run `gauntlex init` separately if you also want\na `.gauntlex.yml` with tunable defaults like `rounds_max` or the gate\nthreshold).\n\n```\n──────────────────────────────────────────────────────────────────────\n  GAUNTLEX Adversarial Run\n  Mode:      quick (5 attacks)\n  Language:  python  [signals: filesystem, async]\n  Domain:    owasp_top10\n──────────────────────────────────────────────────────────────────────\n  ARS Score: 0.87  ✅  PASSED  (gate: ≥ 0.80)\n\n  ✅ CWE-89  SQL Injection via username param     mitigated\n  ✅ CWE-502 Unsafe deserialization                mitigated\n  ✅ CWE-78  OS command injection in file path     mitigated\n  ✅ CWE-22  Path traversal in upload handler       mitigated\n  ❌ CWE-79  Reflected XSS in error message         MISSED\n──────────────────────────────────────────────────────────────────────\n```\n\nWall-clock time depends on which model you configure — anywhere from single-digit\nseconds with a fast paid API to several minutes with a free-tier or local model.\nAttack count *targets* 5/20/50 by mode (`quick`/`standard`/`thorough`), spread\nacross the adversarial rounds — actual totals land close to but not always\nexactly at the target (a `thorough` run might fire ~30–50, for example),\nsince it depends on how many attacks the model actually returns per round.\n\n### Run against a GitHub issue directly\n\n```bash\ngauntlex run --issue https://github.com/your-org/your-repo/issues/42 --mode standard --domain hipaa --pretty\n```\n\n### Add business intent — attack surface = spec + why it's needed\n\n`--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.\n\n```bash\ngauntlex run --issue SPEC.md --intent PROJ-123 --domain hipaa --pretty\n```\n\n`gauntlex setup` connects Jira/Confluence/Aha! automatically if it detects credentials in your environment — see the interactive wizard's business intent step.\n\n### Requirements\n\n- Python 3.11+\n- macOS, Linux, or Windows (WSL2 recommended on Windows)\n- One model provider: [Ollama](https://ollama.com) (free, local), OpenRouter free tier, or an Anthropic/OpenAI API key\n\n---\n\n## CLI reference\n\nAll 22 commands, grouped by when you'd reach for them:\n\n| Getting started | |\n|---|---|\n| `gauntlex setup` | Configure model provider and integrations (run any time to reconfigure) |\n| `gauntlex init` | Scaffold `.gauntlex.yml` with sensible defaults |\n| `gauntlex doctor` | Full environment health check |\n| `gauntlex validate` | Dry run — checks config and connectivity, fires zero attacks |\n\n| Running assessments | |\n|---|---|\n| `gauntlex run` | Run adversarial Builder + Breaker on a spec |\n| `gauntlex status` | Show running and recently completed runs |\n| `gauntlex findings` | Vulnerability findings from the last run — fix-first, score last |\n| `gauntlex compare` | Diff two Resilience Reports — ARS delta and attack-level changes |\n| `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) |\n\n| Evidence & compliance | |\n|---|---|\n| `gauntlex report` | Render a stored report in any output format (HTML/SARIF/JUnit/JSON) |\n| `gauntlex verify` | Re-derive SHA-256 integrity hash, confirm a report hasn't been altered |\n| `gauntlex audit` | List all reports with compliance control mapping over a time window |\n| `gauntlex vault` | Browse the Forge Ledger — human-readable Markdown attack records |\n| `gauntlex stats` | ARS trends, learning-curve, and cost metrics |\n\n| Domains & policy | |\n|---|---|\n| `gauntlex policy` | List, install, search, or validate policy domains — see [Domain Intelligence](docs/DOMAIN_INTELLIGENCE.md) |\n\n| Team & CI deployment | |\n|---|---|\n| `gauntlex integrate` | One command: wire GAUNTLEX into Claude Code, Cursor, Windsurf, Copilot, Codex, Zed, Antigravity, or GitHub Actions |\n| `gauntlex mcp-server` | Start GAUNTLEX as an MCP server (stdio transport) for local IDE use |\n| `gauntlex serve` | Start GAUNTLEX as a webhook/CI service, with optional GitHub team-based RBAC |\n| `gauntlex dashboard` | Launch the GAUNTLEX dashboard web UI (also serves a live leaderboard at `/leaderboard`) |\n| `gauntlex leaderboard` | Build a *static* ARS leaderboard HTML page across multiple agents/runs — e.g. for GitHub Pages |\n| `gauntlex forge-network` | Opt-in community adversarial pattern sharing |\n| `gauntlex prune` | Remove expired reports |\n\nFull usage, flags, and examples for every command: [Deep Dive → Complete CLI Reference](docs/DEEP_DIVE.md#complete-cli-reference).\n\n---\n\n## Language support\n\nAuto-detected from the specification — no per-project configuration:\n\n| Language | Priority CWEs (examples) |\n|---|---|\n| Python | SQL injection, OS command injection, unsafe deserialization, path traversal |\n| JavaScript / TypeScript | Prototype pollution, XSS, CSRF, SSRF |\n| Java | Deserialization, XXE, authorization bypass |\n| Go | Race conditions, nil-pointer dereference, resource exhaustion |\n\n---\n\n## Compliance & domain coverage\n\n5 regulated-industry playbooks ship today — **43 attack scenarios total**, each\nmapped to a specific rule or control, not a generic label:\n\n| Domain | Scenarios | Regulatory framework |\n|---|---|---|\n| `owasp_top10` | 12 | OWASP Top 10 (2021/2025) |\n| `finra` | 9 | FINRA Rules 4370, 3110; SEC Rule 17a-4 |\n| `hipaa` | 9 | HIPAA Security Rule (45 CFR §§160, 164) |\n| `soc2` | 7 | AICPA SOC 2 Trust Service Criteria |\n| `pci_dss` | 6 | PCI DSS v4.0 |\n\nTwo more (`owasp_api_security`, `nist_ssdf`) are available via `gauntlex\npolicy install`. GDPR, FedRAMP, and DORA are on the [roadmap](docs/DEEP_DIVE.md#roadmap)\n— not available today.\n\n**For exactly what's live threat data vs. static playbook content, and how to\nbring your own domain, see the full\n[Domain Intelligence page](docs/DOMAIN_INTELLIGENCE.md).**\n\n---\n\n## IDE & agent integrations\n\nOne command wires GAUNTLEX into whatever AI coding tool you already have open:\n\n```bash\ngauntlex integrate --dry-run               # preview every config it would write, writes nothing\ngauntlex integrate                         # wire up every supported target at once\ngauntlex integrate --platform claude-code  # or just one — .mcp.json\ngauntlex integrate --platform cursor       # .cursor/mcp.json\ngauntlex integrate --platform windsurf     # ~/.codeium/windsurf/mcp_config.json\ngauntlex integrate --platform copilot      # .vscode/mcp.json\ngauntlex integrate --platform codex        # ~/.codex/config.toml\ngauntlex integrate --platform zed          # .zed/settings.json\ngauntlex integrate --platform antigravity  # ~/.gemini/config/mcp_config.json\ngauntlex integrate --platform github-actions  # .github/workflows/gauntlex.yml CI gate\n```\n\nEach target gets the right file, format, and schema for that specific tool —\nthis command handles the differences so you don't have to — and it **merges**\ninto any config you already have rather than overwriting it, so other MCP\nservers you've already configured survive.\n\n**Claude Code users** can also install via the plugin marketplace instead of\n`integrate`:\n```\n/plugin marketplace add sanjoy1234/gauntlex\n/plugin install gauntlex@gauntlex\n```\nThis registers the MCP server and all `/gauntlex:*` skills (`run`, `verify`,\n`doctor`, `compare`, `report`, `learn`, `validate`) in one step, updated via\n`/plugin update`. Requires `gauntlex` on `PATH` (`pip install gauntlex-ai`).\n\n**Zero-config:** this repo ships an [AGENTS.md](AGENTS.md) that Codex, Cursor,\nCline, Windsurf, and Gemini CLI read automatically with no install step at\nall — copy the pattern into your own repo if you're building on top of\nGAUNTLEX rather than just using it.\n\nExact file paths per platform, the merge-safety guarantees, and the MCP\ntools GAUNTLEX exposes (`gauntlex_run`, `gauntlex_status`, `gauntlex_verify`,\nand more): **[Integrations guide](docs/INTEGRATIONS.md)**.\n\n---\n\n## Enterprise deployment\n\n- **`gauntlex dashboard`** — ARS trend, gate status, and attack-outcome breakdown across every connected repository. One URL for the team.\n- **`gauntlex serve --rbac`** — GitHub team-based access control (admin / reviewer / developer) across a shared instance.\n- **`gauntlex audit`** — every run listed with NIST SSDF / OWASP SAMM / SOC 2 control mapping, for a configurable window.\n- **Air-gapped operation** — the full engine runs on local Ollama with zero outbound calls, for environments that can't reach the internet.\n\nFull detail on each: [Deep Dive → Enterprise Features](docs/DEEP_DIVE.md#enterprise-features).\n\n---\n\n## Key terms\n\n- **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.\n- **Builder** — the agent that generates code from the specification.\n- **Breaker** — the agent that generates adversarial attacks from the same specification, at the same instant, without seeing the Builder's output.\n- **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.\n- **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`.\n- **Gate** — the CI check that blocks a merge when a run's ARS falls below the configured threshold (default 0.80).\n\n---\n\n## FAQ\n\n**How do I test AI-generated code for security vulnerabilities?**\nPoint GAUNTLEX at the same specification your AI coding tool used: `gauntlex run --issue your_spec.md --mode quick`. It fires adversarial attacks derived from that spec and returns an Adversarial Resilience Score in under a minute.\n\n**What is an Adversarial Resilience Score (ARS)?**\nThe 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](https://dev.to/sanjoy1234/the-adversarial-resilience-score-a-new-metric-for-ai-generated-code-4gej).\n\n**Does GAUNTLEX test code before or after it's generated?**\nAt 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.\n\n**Which compliance frameworks does GAUNTLEX support?**\nOWASP 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](docs/DOMAIN_INTELLIGENCE.md) for exactly what's covered per domain.\n\n**Can GAUNTLEX run without sending code to an external API?**\nYes — the full engine runs on local Ollama with zero outbound calls, for air-gapped or compliance-restricted environments.\n\nMore questions, including gating thresholds and contributing a new policy domain: [full FAQ in the Deep Dive](docs/DEEP_DIVE.md#faq).\n\n---\n\n## Learn more\n\n- **[Deep Dive](docs/DEEP_DIVE.md)** — the full story: why concurrent execution matters, how GAUNTLEX compares to SAST/DAST/pentest, the complete CLI and configuration reference, architecture, FAQ, and roadmap.\n- **[Domain Intelligence](docs/DOMAIN_INTELLIGENCE.md)** — exactly what's covered per regulated domain, what's live vs. static, and how to extend it.\n- **[Contributing](docs/DEEP_DIVE.md#contributing)** — how to add a policy domain, a language profile, or a feature.\n\n---\n\n## Where to find GAUNTLEX\n\n**Package & registries**\n- [PyPI](https://pypi.org/project/gauntlex-ai/) — `pip install gauntlex-ai`\n- [Official MCP Registry](https://registry.modelcontextprotocol.io) — listed as `io.github.sanjoy1234/gauntlex`\n\n**Writing**\n- [dev.to — \"Why I Built an Adversarial Co-Generation Engine\"](https://dev.to/sanjoy1234/why-i-built-an-adversarial-co-generation-engine-2038)\n- [dev.to — \"The Adversarial Resilience Score: A New Metric for AI-Generated Code\"](https://dev.to/sanjoy1234/the-adversarial-resilience-score-a-new-metric-for-ai-generated-code-4gej)\n- [dev.to — \"How GAUNTLEX Gates HIPAA/FINRA Compliance in CI\"](https://dev.to/sanjoy1234/how-gauntlex-gates-hipaafinra-compliance-in-ci-29hj)\n- [LinkedIn Article — \"The Math That Breaks When AI Writes a Million Lines of Code\"](https://www.linkedin.com/feed/update/urn:li:activity:7482279870576611328/)\n\n**Community**\n- [GitHub Discussions](https://github.com/sanjoy1234/gauntlex/discussions) — questions, feedback, and \"I built X with this\" show-and-tell\n\n---\n\n## Acknowledgments\n\n- [Deven Samant](https://www.linkedin.com/in/devensamant/) — early feedback and validation\n\n---\n\n<div align=\"center\">\n\nMIT License · Built by **[Sanjoy Ghosh](https://github.com/sanjoy1234)**\n\n</div>\n",
  "bytes": 18394,
  "sha": "578cbae7d4350d91b20ab2d61e5e6b99b85f3d2eae40a44e60dada6b9ef0bc2f",
  "repo_slug": "sanjoy1234/gauntlex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sanjoy1234_gauntlex_3d19705d/readme"
}