Trigger Savant Pathseeker Tests

Use the Bugcrowd API to start a Savant Pathseeker test from your own tools and pipelines. The API starts a new run of an existing Pathseeker test configuration, using the targets, credentials, and settings already saved for it. You configure the test once in the platform, and the API controls when it runs.

Common uses include retesting a staging environment after each release, starting a test from a CI/CD pipeline such as GitHub Actions, and running tests on your own schedule.

This endpoint is available in API version 1.2.0. For general API setup, see Getting Started with the API.

Before you begin

You need:

  • The Organization Owner or Test Operator role. It is required to allow API-triggered runs and to start tests with the API.
  • A configured Pathseeker test. See Savant Pathseeker Overview.
  • An API credential pinned to major version V1. Tokens pinned to V1 receive minor releases, including 1.2.0, automatically.
  • Available Pathseeker test quota. Each accepted request uses one test from your quota.

Active testing: Pathseeker performs active testing against your targets. Allow API-triggered runs only for tests whose scope you have reviewed. Avoid business-critical production systems unless they are explicitly in scope.

Step 1: Allow API-triggered runs

  1. Go to your program and click the Autonomous Tests tab.
  2. Start a new test or rescan an existing one.
  3. Turn on Allow API-triggered runs.
  4. Review the scope, confirm authorization, and launch the test.

After launch, the platform displays the API Triggering Setup instructions. To view them again, open the test’s Test Overview page and click View setup instructions.

Step 2: Copy the Configuration ID

Copy the Configuration ID from the API Triggering Setup instructions. You use it in the request URL.

Configuration ID is not the Test ID: The Test ID in the platform URL identifies a single run. The Configuration ID identifies the reusable test setup. Requests that use a Test ID return 404 Not Found.

Step 3: Create an API credential

  1. Go to the API Credentials page.
  2. Enter a descriptive name, such as pathseeker-pipeline, and click Create credentials.
  3. Copy the token. It is not viewable after you leave or refresh the page.
  4. Confirm the credential is pinned to major version V1.
  5. Optional: under Current credentials, click Edit IP Allowlist and add the IPv4 addresses of your CI/CD runners. Requests from other IP addresses are rejected.

Tip: Store the token in your CI/CD secret store. Never commit it to source control or print it in build logs. To rotate a token, create a new credential, update your secret, then delete the old credential.

Step 4: Start a test

Send a POST request to:

https://api.bugcrowd.com/scan_configurations/{configuration_id}/scan_executions

Headers

Authorization: Token TOKEN_USERNAME:TOKEN_PASSWORD
Accept: application/vnd.bugcrowd+json
Content-Type: application/json

Request body

Attribute Type Required Description
trigger_source string Yes A label for what started the run, such as github-actions, jenkins, or nightly-cron. Maximum 255 characters. Recorded with the run.

Example request

curl -X POST \
     --header "Accept: application/vnd.bugcrowd+json" \
     --header "Content-Type: application/json" \
     --header "Authorization: Token TOKEN_USERNAME:TOKEN_PASSWORD" \
     --data '{
       "data": {
         "type": "scan_execution",
         "attributes": {
           "trigger_source": "github-actions"
         }
       }
     }' \
     'https://api.bugcrowd.com/scan_configurations/CONFIGURATION_UUID/scan_executions'

Example response

201 Created

{
  "data": {
    "type": "scan_execution",
    "id": "4f6b1c2e-8d3a-4b7e-9c1f-2a5d7e9b0c3d",
    "attributes": {
      "status": "accepted"
    }
  }
}

A status of accepted means the test is queued. It usually starts within minutes. The id identifies the new run.

Step 5: Monitor the test

API-triggered tests appear on the program’s Autonomous Tests tab with other tests.

  • Use the Activity tab to follow progress.
  • Click Stop Test to stop a run.
  • Use the Results tab to review findings.

Note: The API supports starting tests only. Run status and findings are available in the platform.

Example: GitHub Actions

This workflow starts a Pathseeker test after a successful deployment to staging, or on demand.

  1. In your repository, add two secrets: BUGCROWD_API_TOKEN (the full TOKEN_USERNAME:TOKEN_PASSWORD value) and PATHSEEKER_CONFIGURATION_ID.
  2. Add the following file at .github/workflows/pathseeker.yml.
name: Start Pathseeker test

on:
  workflow_dispatch:
  deployment_status:

jobs:
  pathseeker:
    if: github.event_name == 'workflow_dispatch' || (github.event.deployment_status.state == 'success' && github.event.deployment.environment == 'staging')
    runs-on: ubuntu-latest
    steps:
      - name: Start test
        env:
          BUGCROWD_API_TOKEN: $
          CONFIG_ID: $
        run: |
          status=$(curl -s -o response.json -w "%{http_code}" -X POST \
            --header "Accept: application/vnd.bugcrowd+json" \
            --header "Content-Type: application/json" \
            --header "Authorization: Token ${BUGCROWD_API_TOKEN}" \
            --data '{"data":{"type":"scan_execution","attributes":{"trigger_source":"github-actions"}}}' \
            "https://api.bugcrowd.com/scan_configurations/${CONFIG_ID}/scan_executions")
          if [ "$status" = "201" ]; then
            echo "Pathseeker test started."
          elif [ "$status" = "409" ]; then
            echo "::warning::A Pathseeker run is already queued or running for this configuration. Skipping."
          else
            echo "::error::Request failed with HTTP $status"
            cat response.json
            exit 1
          fi

IP Allowlist and GitHub-hosted runners: Standard GitHub-hosted runners do not use fixed IP addresses. If your token has an IP Allowlist, use self-hosted runners or GitHub larger runners with static IP ranges. Static IP ranges for larger runners require GitHub Enterprise Cloud and are not available on macOS larger runners.

Responses

Status Meaning What to do
201 Created The run is queued. None. Monitor the run in the platform.
400 Bad Request The body is malformed or trigger_source is missing. Check the request body.
401 Unauthorized The token is missing, invalid, expired, or deleted. Check the Authorization header and the credential.
403 Forbidden The request came from an IP address that is not on the token’s IP Allowlist. Add the runner’s IPv4 address or use a runner with a static IP.
404 Not Found The Configuration ID was not found, or the token owner cannot access it. Confirm you used the Configuration ID, not the Test ID, and that the token owner has the Organization Owner or Test Operator role.
409 Conflict A run for this configuration is already queued or running. Wait for the current run to finish. Retrying a request that timed out returns 409 if the first request was accepted.
422 Unprocessable Entity The configuration cannot run in its current state, for example because Allow API-triggered runs is turned off. Check the test setup in the platform.
429 Too Many Requests The rate limit was exceeded. Wait for the time in the Retry-After header, then retry.

Errors use the JSON API error format:

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "A scan is already running for this scan configuration."
    }
  ]
}

Behavior and limits

  • Same scope and settings: each run uses the targets, credentials, and settings saved for the configuration. Changes you make in the platform apply to future runs.
  • One run at a time: each configuration can have one queued or running run.
  • Quota: each accepted request uses one test from your Pathseeker quota. Trigger on deployments to specific environments rather than on every commit.
  • Run time: tests take from under an hour to several hours. Do not make your pipeline wait for a test to finish.
  • Traceability: each run records the token owner, the time of the request, and the trigger_source.
  • Rate limits: Bugcrowd limits API requests to 60 requests per minute per IP address.

FAQ

Can I change targets or scope through the API?

No. Update the test in the platform. Changes apply to the next run.

Can I get results through the API?

Not yet. Review findings on the test’s Results tab.

Do I need to allow API-triggered runs for each test?

Yes. Turn on Allow API-triggered runs for each test you want to start with the API.

What is the difference between the Test ID and the Configuration ID?

The Test ID identifies a single run. The Configuration ID identifies the reusable test setup. The API uses the Configuration ID.

Visit bugcrowd.com