Trigger a pentest

1 min

, , , , ,

Starts a pentest of the repositories attached to a completed or partial cost estimation. Pentests run asynchronously: the endpoint returns straight away with a scan id to poll.

Prerequisites

Create a cost estimation with POST /cost-estimations.
Wait until the estimation reaches completed or partial status and has a positive total_credits value.
Submit the same repositories, branches, and path scope that the estimation included, and keep each repository’s include_paths and exclude_paths the same. Hacktron rejects a pentest whose repository, archive, branch, or path scope doesn’t match the estimate.
Make sure your organisation has enough Whitebox credits. The dashboard shows them, as Credits and billing describes. Insufficient credits return 402 Payment Required.

Warning

Only one started pentest can claim a cost estimation. To change repositories, archives, branches, or path scope, create a new estimate first.

Request

POST /scans

Send an API key with the write scope in the X-Api-Key header.

curl -X POST "https://api.hacktron.ai/v1/scans" \
  -H "X-Api-Key: $HACKTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cost_estimation_id": "string",
  "repos": [
    {
      "url": "string",
      "branch": "string"
    }
  ]
}'

{
  "id": "string",
  "task_id": "string",
  "status": "string",
  "message": "string"
}

Body

A required application/json body.

Field	Description
`cost_estimation_id` string, required	Completed cost estimation UUID.
`repos` array of object, required	Repositories to scan.
`repos[].url` string, required	Repository URL.
`repos[].branch` string, required	Branch name.
`repos[].source` string	Repository source. One of `connected`, `public`, or `upload`. Default `connected`.
`target_urls` array of string	Target URLs for pentest.
`auth_instructions` string	Target websites and browser login instructions, including URLs and credentials. At most 2000 characters.
`custom_context` string	Custom context for the pentest. At most 2000 characters.
`context_document_ids` array of string	Context document UUIDs to include.

Responses

201 Created

Field	Description
`id` string, required
`task_id` string, required
`status` string, required
`message` string, required

402 Payment Required

Insufficient credits.

Next steps

Poll GET /scans/{id}/status until the status is completed. Then fetch the findings with GET /scans/{id}/findings or export them with GET /scans/{id}/findings/export.

Get scan status List scan findings Export scan findings