# @turbopentest/mcp-server

MCP server for [TurboPentest](https://turbopentest.com) — launch AI-powered penetration tests, review vulnerability findings, and generate security reports, all without leaving your coding assistant.

## What it does

Ask your AI assistant to run a pentest, check progress, and walk you through remediation — the server handles all the API calls. Every completed scan is anchored to the blockchain, giving you a tamper-proof attestation you can share with customers or auditors.

## Quick start

### 1. Get your API key

Sign up and create an API key at [turbopentest.com/settings/api-keys](https://turbopentest.com/settings/api-keys).

### 2. Verify a domain

Before scanning, verify that you own the target domain at [turbopentest.com/domains](https://turbopentest.com/domains).

### 3. Add the server to your MCP client

**Claude Code** (`.mcp.json` in your project root):

```json
{
  "mcpServers": {
    "turbopentest": {
      "command": "npx",
      "args": ["@turbopentest/mcp-server"],
      "env": {
        "TURBOPENTEST_API_KEY": "tp_live_..."
      }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "turbopentest": {
      "command": "npx",
      "args": ["@turbopentest/mcp-server"],
      "env": {
        "TURBOPENTEST_API_KEY": "tp_live_..."
      }
    }
  }
}
```

**Cursor** (Settings > MCP Servers > Add):

```json
{
  "command": "npx",
  "args": ["@turbopentest/mcp-server"],
  "env": {
    "TURBOPENTEST_API_KEY": "tp_live_..."
  }
}
```

**OpenAI Codex CLI** (`~/.codex/config.toml`, or run `codex mcp add turbopentest -- npx @turbopentest/mcp-server` and set the env var when prompted):

```toml
[mcp_servers.turbopentest]
command = "npx"
args = ["@turbopentest/mcp-server"]

[mcp_servers.turbopentest.env]
TURBOPENTEST_API_KEY = "tp_live_..."
```

Then run `/mcp` inside Codex to confirm `turbopentest` is listed. Codex's MCP
client doesn't support the "prompts" primitive, so the four guided workflows
are also exposed as plain tools (`turbopentest_workflow_*`, see below) and
described in this repo's `AGENTS.md`, which Codex reads automatically.

## Example session

```
You:    "Run a standard pentest on staging.example.com"
Claude: Checks domain is verified, confirms credit balance,
        calls start_pentest → "Started tp_abc123, 4 agents, ~1 hour"

You:    "Any findings yet?"
Claude: Calls get_pentest → "62% complete — 3 findings (1 high, 2 medium)"

You:    "Show me the high severity ones"
Claude: Calls get_findings(severity: "high") →
        [1] HIGH: SQL Injection in /api/search
            CVSS: 8.6 (AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N)
            CWE: CWE-89
            PoC: POST /api/search?q=' OR 1=1--
            Remediation: Use parameterized queries...
            Retest: sqlmap -u "https://staging.example.com/api/search" ...

You:    "Give me a prioritized remediation plan"
Claude: Uses the analyze_findings prompt → produces a full markdown
        remediation plan grouped by severity and effort
```

## White-box scanning

Pass a GitHub repository URL to `start_pentest` to enable white-box mode. In addition to black-box testing, the scan will include:

- **SAST** — static code analysis for common vulnerability patterns
- **Secret detection** — leaked API keys, credentials, and tokens in source
- **SCA** — dependency audit for known CVEs

```
You:  "Pentest staging.example.com, the repo is github.com/myorg/myapp"
```

## Tools

| Tool | Description |
|------|-------------|
| `turbopentest_start_pentest` | Launch a pentest against a verified domain. Supports four tiers and optional GitHub repo for white-box scanning. |
| `turbopentest_get_pentest` | Get scan status, progress, findings summary, executive summary, attack surface map, and STRIDE threat model. |
| `turbopentest_list_pentests` | List all pentests with status and finding counts. Filterable by status. |
| `turbopentest_get_findings` | Retrieve structured findings with severity, CVSS, CWE, OWASP category, PoC, remediation steps, and retest commands. Filterable by severity. |
| `turbopentest_download_report` | Download a report in markdown (best for AI), JSON, or PDF format. |
| `turbopentest_get_credits` | Check your credit balance and available scan tiers with pricing. |
| `turbopentest_verify_attestation` | Verify a blockchain-anchored attestation by SHA-256 hash. No API key required — public endpoint. |
| `turbopentest_list_domains` | List your verified domains and their verification status. |
| `turbopentest_workflow_run_pentest` | Returns the `run_pentest` workflow instructions as tool output (for clients without prompts support, e.g. Codex). |
| `turbopentest_workflow_analyze_findings` | Returns the `analyze_findings` workflow instructions as tool output. |
| `turbopentest_workflow_compare_pentests` | Returns the `compare_pentests` workflow instructions as tool output. |
| `turbopentest_workflow_security_posture` | Returns the `security_posture` workflow instructions as tool output. |

**Security note:** `turbopentest_start_pentest` checks domain verification
itself before calling the API — it will refuse (`isError: true`) to launch
against a target whose domain isn't verified on your account, rather than
relying solely on the agent to check first.

## Prompts

Built-in prompts guide your AI assistant through multi-step workflows. Invoke them by name in any MCP client that supports prompts (Claude Code, Claude Desktop, Cursor). In clients that only support tools (Codex), use the matching `turbopentest_workflow_*` tool above instead — the text is identical.

| Prompt | Equivalent tool | Description |
|--------|------------------|-------------|
| `run_pentest` | `turbopentest_workflow_run_pentest` | Full-lifecycle pentest: domain check → credit verification → launch → progress monitoring → findings summary → report download |
| `analyze_findings` | `turbopentest_workflow_analyze_findings` | Deep-dive analysis of a single pentest's findings, producing a prioritized remediation plan with effort estimates and retest commands |
| `compare_pentests` | `turbopentest_workflow_compare_pentests` | Diff two pentests on the same target — shows what's new, what's been fixed, and what's still unresolved |
| `security_posture` | `turbopentest_workflow_security_posture` | Executive briefing across your 5 most recent pentests: risk trends, highest-risk targets, and top 3 recommended actions |

## Scan tiers

| Tier | Agents | Duration | Price |
|------|--------|----------|-------|
| Recon | 1 | ~30 min | $49 |
| Standard | 4 | ~1 hour | $99 |
| Deep | 10 | ~2 hours | $299 |
| Blitz | 20 | ~4 hours | $699 |

Default tier is `standard`. Use `recon` for a quick surface sweep or `blitz` for maximum coverage on critical assets.

## Blockchain attestation

Every completed pentest is anchored on-chain as a tamper-proof attestation. The SHA-256 hash is included in the report and can be independently verified — by you, your customers, or auditors — with no API key required:

```
You:  "Verify attestation abc123def456..."
```

`turbopentest_verify_attestation` returns the scan metadata (tier, agents, duration, risk score, findings summary) alongside the blockchain proof (chain ID, transaction hash, block number, merkle root).

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `TURBOPENTEST_API_KEY` | Yes | — | API key from turbopentest.com/settings/api-keys |
| `TURBOPENTEST_API_URL` | No | `https://turbopentest.com/api` | Override the API base URL (for testing) |

## Requirements

- Node.js 18+
- A [TurboPentest](https://turbopentest.com) account with at least one verified domain

## Using with OpenAI Codex

See [docs/CODEX.md](docs/CODEX.md) for the full Codex guide — configuration,
the tool list, the authorization model, and why the guided workflows are
exposed as `turbopentest_workflow_*` tools instead of MCP prompts.

## Privacy & support

- **Privacy policy:** https://turbopentest.com/privacy
- **Subprocessors:** https://turbopentest.com/subprocessors
- **Support:** open a case at https://turbopentest.com/support (typically
  answered within a few hours on business days) or join the
  [Discord](https://discord.gg/6eRf5UMvf2)
- **Bugs in this MCP server:** https://github.com/integsec/turbopentest-mcp/issues

Your API key is sent only to `turbopentest.com/api` as a bearer token over
HTTPS. It is never logged and never transmitted anywhere else. Customer pentest
content is not used to train public AI models.

## License

MIT