Running a pre-commit pentest

Once Vortex MCP is installed and authenticated, a pentest is five steps: check readiness, start the scan, poll its status, fetch the findings, and (optionally) cancel. You can drive each step conversationally, through the MCP tools directly, or with the plugin’s slash commands.

Before you start

Make sure your app is running locally and reachable at http://host.docker.internal:PORT (not localhost — see Configuration).

The flow

1. Health-check first

Call health_check(target_url) (or /bestdefense-pentest:doctor [url]) before anything else. It confirms your token authenticates, your org is entitled for pre-commit dispatch, and the target is reachable — and starts no scan. Fix any failing check before continuing.

2. Start the pentest

Call start_pentest(target_url, mode, test_profile, workdir) (or /bestdefense-pentest:scan <url> [smoke|standard|deep]). It returns a session_id you use for every later call.

start_pentest(
  target_url="http://host.docker.internal:3000",
  mode="standard",        # smoke | standard | deep
  test_profile="blackbox" # or greybox, deriving context from workdir
)

Traffic originates on your machine and only findings leave it. See Configuration for modes and profiles.

3. Poll the status

Call get_pentest_status(session_id) about once every 20–30 seconds until the status is terminal. Long scans are normal — provisioning and deep passes can take many minutes. Keep polling; don’t assume a slow scan has failed.

Monitor only through get_pentest_status

get_pentest_status is the only safe way to watch a scan. The scan’s executor runs inside the MCP server’s container, so do not:

• run docker logs / docker exec against the container,
• restart or relaunch the container, or
• tail files or poll in a tight loop.

Any of these can kill the in-container executor and abort the scan, losing its findings.

4. Fetch the findings

When the status is terminal, call get_findings(session_id, output_format) (or /bestdefense-pentest:findings <session-id>). Choose the format:

• output_format="json" (default) — structured findings for humans and tooling.
• output_format="sarif" — SARIF 2.1.0 for GitHub code scanning, IDEs, and CI.

Each finding carries severity, CWE, CVSS, the affected URL and parameter, and evidence.

5. Cancel if needed

To stop a running scan early, call cancel_pentest(session_id). It cancels the scan and tears down the local executor cleanly.

Slash-command equivalents

Step	MCP tool	Slash command
Readiness	health_check	/bestdefense-pentest:doctor [url]
Start	start_pentest	/bestdefense-pentest:scan <url> [mode]
Poll	get_pentest_status	(driven automatically by the agent)
Findings	get_findings	/bestdefense-pentest:findings <session-id>
Cancel	cancel_pentest	(call the tool)

Billing

smoke and standard are seat-covered — run them as often as you like. deep reserves a pre-commit credit per scan. Check remaining deep-scan credits with /bestdefense-pentest:status (secure mode) or in the app.