> For the complete documentation index, see [llms.txt](https://copilot-docs.bugbase.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/agentic-testing-with-mcp.md).

# Agentic Testing with MCP

Let your own AI agent explore an application, then prove its findings through the Pentest Copilot tester so they land in the exploit graph and reports.

Agentic testing lets an agent you run, with its own browser, proxy, or scripts, explore a web application and then hand a concrete hypothesis to Pentest Copilot. The platform replays the request with the agent's payload, checks the indicators, and validates the finding. A proven finding is written to the exploit graph as a `TestCase`, `Vulnerability`, and attack path, exactly like one found by a platform scan, and appears in results and [Reports](https://copilot-docs.bugbase.ai/enterprise/reports.md).

You keep the creativity of your own agent. The platform supplies scope enforcement, reproducible evidence, and validation.

## Who Can Use It

| Tools                                                                                                                                     | Roles                       |
| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| Read: `get_browser_sessions`, `list_trajectories`, `get_trajectory`, `get_submodule_status`, `get_job_status`                             | Admin, Operator, Trial user |
| Test: `create_trajectory`, `run_test`, `get_test_case_schema`, `create_oob_url`, `get_oob_hits`, `path_to_root`, `list_nodes_by_property` | Admin, Trial user           |

See [MCP Tool Reference](https://copilot-docs.bugbase.ai/enterprise/settings/api-keys-and-mcp-server/mcp-tool-reference.md#agentic-testing).

## Before You Start

* The target must be a **Domain root in your workspace with verified ownership**. Subnet and APKFile roots are not supported for agentic web testing. See [Domain Verification](https://copilot-docs.bugbase.ai/enterprise/settings/domain-verification.md).
* For authenticated testing, use a **validated browser session** under the same Domain. See [Validating Browser Sessions](https://copilot-docs.bugbase.ai/enterprise/how-to-trigger-a-web-assessment/validating-browser-sessions.md).
* Running Web Discovery first is optional but helpful: it captures user journeys (trajectories) your agent can test directly.
* On shared-trial workspaces, the workspace must be paid and have attack runtime remaining.

Every test sends real traffic to the target. Test only what you are authorized to test.

## Workflow

{% stepper %}
{% step %}

### Pick the session and flow

* `get_browser_sessions` with the Domain's ID lists its sessions. Add `browser_session_id` and `include: ["full"]` to read one session in detail.
* `list_trajectories` with `root_entity_id` lists captured flows. It returns identity only by default; filter with `search_term` or `browser_session_id`.
* `get_trajectory` with `include: ["actions"]` returns a flow's ordered browser and API actions, each API with its `api_id`. Add `"headers"` or `"bodies"` when you need them, or use `"full"`.
  {% endstep %}

{% step %}

### Or register a flow your agent found

If your agent found an endpoint the platform has not captured, register it with `create_trajectory`. Pass a **focused** action list: the navigation needed to reach the page and the target API call, not a whole crawl.

```json
{
  "root_entity_id": "<verified-domain-id>",
  "browser_session_id": "<validated-session-id>",
  "trajectory_summary": "View order by ID",
  "reason": "Order IDs are sequential; testing for IDOR",
  "tags": ["idor", "agent"],
  "actions": [
    {"type": "BROWSER", "action": "GOTO", "url": "https://app.example.com/orders"},
    {
      "type": "API",
      "original_request": {
        "scheme": "https", "host": "app.example.com", "path": "/api/orders/1001",
        "method": "GET", "headers": {}, "query": {}, "body": {}
      },
      "original_response": {"status": 200, "headers": {}, "body": {}}
    }
  ]
}
```

Every action URL and host must stay under the verified Domain. Anything outside it is rejected before anything is written. Omit `browser_session_id` to place the flow under the Domain's unauthenticated session. The tool creates the parent `WebPage` from the first URL-bearing action, or you can pass an existing `webpage_id`.
{% endstep %}

{% step %}

### Write the test case

`get_test_case_schema` returns the exact `TestCaseData` schema `run_test` validates against. A test case has:

* `testcase_name`, `reason`, and `description` (required);
* `modifications`: steps that `add`, `update`, `delete`, or `drop` a part of a request or response. A step's `destination` targets an API by its `api_id` from `get_trajectory`, a `direction`, and a `component` such as `path`, `query_param`, `header`, or `body`;
* `indicators`: what proves the finding, for example a response status code, body content, headers, timing, or for browser tests a DOM alert, content, cookie, or storage value;
* optional `cwe_ids`, `severity`, and `cvss_score`.

Example:

```json
{
  "testcase_name": "IDOR on order lookup",
  "reason": "The order ID is sequential and the API does not check that the order belongs to the caller",
  "description": "Replace the caller's order ID with another customer's order ID and confirm that order is returned",
  "modifications": [
    {"steps": [{
      "action": "update",
      "source": {"value": "1002"},
      "destination": {"api_id": 1, "direction": "request", "component": "path", "match_regex": "1001"}
    }]}
  ],
  "indicators": [
    {"locator": {"api_id": 1, "component": "response_status_code"}, "condition": {"value": "200"},
     "description": "The foreign order is served"},
    {"locator": {"api_id": 1, "component": "response_body"}, "condition": {"regex": "other-customer@example\\.com"},
     "description": "The response contains the other customer's email"}
  ],
  "cwe_ids": ["CWE-639"],
  "severity": "high"
}
```

{% endstep %}

{% step %}

### Run the test

Call `run_test` with:

* `trajectory_id`;
* `category`: a `name` such as `Broken Authorization` or `SQL Injection`, with optional `category_reasons`;
* `test_case`;
* `browser_session_id`: optional, required when indicators read the DOM;
* `force_request_mode`: optional, for API-only findings where browser replay is unnecessary;
* `custom_headers`: optional, applied to every request. Use it only for values such as program attribution, never to swap the identity under test.

`run_test` re-checks the trajectory's scope and session ownership before it runs. It returns immediately with `module_refid`, `submodule_refid`, and `test_case_set_id`. If an input is invalid, it returns a structured error so your agent can correct it and retry.
{% endstep %}

{% step %}

### Read the verdict

Poll `get_submodule_status` with the `submodule_refid` and `test_case_set_id` until the run finishes. Add `include: ["vulnerabilities"]` for full finding details.

If a run finishes without a finding, take a job's `task_id` and call `get_job_status` with `include: ["indicator_results", "request_response"]`. It shows which indicator failed and why, and the exact modified request that was sent, which helps spot a modification that did not apply.
{% endstep %}
{% endstepper %}

## Blind and Out-of-Band Findings

For blind SSRF, out-of-band command injection, XXE, and similar issues:

1. `create_oob_url` returns a unique `hit_url` and `hit_id`. Add a `note` to remember where you used it.
2. Inject `hit_url` into the payload.
3. `get_oob_hits` with the `hit_id` returns any callbacks the target made, with time, source IP, and headers. A non-empty result is strong evidence of a blind vulnerability.

Callback URLs are scoped to your workspace. Other workspaces cannot read their hits.

## Helpers

* `path_to_root` walks from any entity up to its Domain root, for example to confirm where a finding sits.
* `list_nodes_by_property` searches entities of one type by property values, with `exact` or `contains` matching. Use it to locate pages or API actions.

## Scope and Safety

* Flows and tests are confined to the verified Domain. Off-scope URLs are refused, and your workspace's [Trajectories](https://copilot-docs.bugbase.ai/enterprise/settings/trajectories.md) rules still apply.
* Each workspace only sees and tests its own targets, sessions, flows, and callbacks.
* The tester replays real requests. Prefer read-only payloads, avoid destructive actions, and keep test accounts separate from production users.
* Findings created this way carry the same evidence as scan findings. Review them in [Analysing Scan Results](https://copilot-docs.bugbase.ai/enterprise/analysing-scan-results.md) before reporting.
