Vortex MCP in CI

Vortex MCP is a plain MCP server over stdio, so anything that can run the container can run it in CI. Use the organization API token (no interactive login), gate the build on the findings you care about, and upload SARIF so results show up in code scanning.

For the general REST-API build-gate pattern (triggering cloud scans against a deployed site), see CI/CD automation. This page covers the local, container-based pre-commit pentest instead.

Headless configuration

Provide the endpoint and token as environment variables and run the container directly:

{
  "mcpServers": {
    "bestdefense-pentest": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=missing",
        "--cap-add=NET_ADMIN",
        "--add-host=host.docker.internal:host-gateway",
        "-e", "BD_PENTEST_API_URL",
        "-e", "BD_PENTEST_TOKEN",
        "ghcr.io/bestdefense-io/bd-pentest-mcp:0.1.19"
      ],
      "env": {
        "BD_PENTEST_API_URL": "https://pentest.app.bestdefense.io",
        "BD_PENTEST_TOKEN": "${BD_PENTEST_TOKEN}"
      }
    }
  }
}

• Store the token as a masked CI secret (BD_PENTEST_TOKEN), never in the repo.
• The API-token path needs no keychain and no browser, so it works on any runner.
• Keep --cap-add=NET_ADMIN — it lets the container enforce its own outbound-network guardrails during a scan.

Fail the build on severity

The pattern is the same four steps as an interactive scan: start, poll, fetch, decide. Drive the MCP tools from your agent step, request SARIF, then fail on severity. In pseudocode:

1. start_pentest(target_url, mode) → capture session_id.
2. Poll get_pentest_status(session_id) every 20–30s until terminal.
3. get_findings(session_id, output_format="sarif").
4. Count results at or above your threshold (for example critical and high) and exit non-zero if any exist.

Caution

Even in CI, monitor only via get_pentest_status. Never docker logs/exec or restart the scan container — that aborts the scan and loses findings. See Running a pre-commit pentest.

Upload SARIF to code scanning

get_findings with output_format="sarif" returns SARIF 2.1.0, which GitHub Advanced Security code scanning, IDEs, and other CI tools consume directly. Write it to a file and upload it — for example, with GitHub Actions:

- name: Upload Vortex MCP SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: vortex-mcp.sarif

Findings then appear in the repository’s Security → Code scanning tab, annotated on the relevant lines.

Notes for long scans in CI

• A static org token does not expire mid-scan, which is why it’s the recommended CI credential. The device-flow broker (secure mode) is aimed at interactive hosts, not headless runners.
• Set generous step timeouts — provisioning plus a deep pass can take many minutes, and that’s expected.