Update a pentest draft

1 min

, , , , ,

Updates a pentest draft. Fields in the request replace their saved values, and fields you leave out keep their current values. You can’t change a pentest after it starts. You need the member role or above.

repos replaces the saved repository list and must contain at least one entry. Changing it clears the estimate.
login_targets replaces the full list. Send [] to remove all login targets. Sending the same site and login instructions keeps a successful login check. Changing either resets login_check to unverified until you check again.
To fix a login that failed its check, send the site again with new login_instructions, then call POST /pentests/{id}/login-checks.
To switch a draft from signed-in testing to testing without a login, or back, clear the other list in the same request, for example "login_targets": [] with your target_urls.

After changing the draft, estimate it again with POST /pentests/{id}/estimate. POST /pentests/{id}/start rejects a credit total that doesn’t match the current estimate.

Request

PATCH /pentests/{id}

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

curl -X PATCH "https://api.hacktron.ai/v1/pentests/<id>" \
  -H "X-Api-Key: $HACKTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "login_targets": [],
  "target_urls": ["https://staging.acme.dev"]
}'

{
  "scan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "repos": [
    {
      "include_paths": [
        "services/gateway/**"
      ],
      "exclude_paths": [
        "**/tests/**",
        "vendor/",
        "*.md"
      ],
      "source": "connected",
      "provider": "github",
      "url": "https://github.com/owner/repo",
      "branch": "string",
      "ref_type": "branch",
      "archive_id": "string",
      "github_installation_id": 0
    }
  ],
  "target_urls": [
    "string"
  ],
  "login_targets": [
    {
      "site": "string",
      "login_check": "unverified",
      "failure_reason": "string"
    }
  ],
  "custom_context": "string",
  "application_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cost_estimation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "triage_enabled": true,
  "credits_used": 0
}

Path parameters

Parameter	Description
`id` string, required

Body

A required application/json body.

Field	Description
`target_urls` array of string	Target URLs (pentest only).
`custom_context` string	Custom context (pentest only).
`application_id` string	iva application this scan targets (group of repos).
`login_targets` array of object	Deployed sites to test signed in, each with how to sign in. On update the list replaces the saved one, and [] removes them. A pentest tests live sites either all signed in or all without a login (target_urls). Check each login with POST /pentests/{id}/login-checks before starting. At most 10 items.
`login_targets[].site` string, required	A deployed copy of the app to test signed in, e.g. https://staging.acme.dev. At most 2048 characters.
`login_targets[].login_instructions` string, required	How to sign in: the login page, username, password and any steps. Stored encrypted and never returned. At most 2000 characters.
`repos` array of object	Repositories or uploaded archives to test, replacing the saved ones. Changing them clears the estimate, so estimate again before starting. At least 1 item.
When `source` is `connected`
`repos[].include_paths` array of string	Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.
`repos[].exclude_paths` array of string	Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.
`repos[].source` string, required	Always `connected`.
`repos[].url` string, required	Repository URL.
`repos[].branch` string, required	Branch name, tag name, or commit SHA.
`repos[].ref_type` string	How `branch` was selected (UI hint for draft re-use). One of `branch`, `tag`, or `sha`.
`repos[].github_installation_id` number	GitHub App installation id. Omitted for PAT-based connections (e.g. GitHub Enterprise), where the installation is resolved from the repository URL and the organization instead.
When `source` is `public`
`repos[].include_paths` array of string	Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.
`repos[].exclude_paths` array of string	Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.
`repos[].source` string, required	Always `public`.
`repos[].url` string, required	Repository URL.
`repos[].branch` string, required	Branch name, tag name, or commit SHA.
`repos[].ref_type` string	How `branch` was selected (UI hint for draft re-use). One of `branch`, `tag`, or `sha`.
When `source` is `upload`
`repos[].include_paths` array of string	Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.
`repos[].exclude_paths` array of string	Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.
`repos[].source` string, required	Always `upload`.
`repos[].archive_id` string, required	Scan archive ID.

Responses

200 OK

Field	Description
`scan_id` string (uuid), required	Stable pentest id; task_id changes when it starts.
`status` string, required	One of `pending`, `running`, `completed`, `failed`, `stopped`, `cancelled`, `skipped`, `pending_verification`, `pending_triage`, `draft`, `estimating`, or `estimated`.
`repos` array of object, required
`repos[].include_paths` array of string	Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.
`repos[].exclude_paths` array of string	Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.
`repos[].source` string	One of `connected`, `public`, or `upload`.
`repos[].provider` string, read-only	Resolved by the server at scan start; ignored on input. One of `github`, `gitlab`, `bitbucket`, or `azure`.
`repos[].url` string	Repository URL.
`repos[].branch` string	Branch name, tag name, or commit SHA.
`repos[].ref_type` string	How `branch` was selected (UI hint for draft re-use). One of `branch`, `tag`, or `sha`.
`repos[].archive_id` string	Scan archive ID.
`repos[].github_installation_id` number	GitHub App installation ID (connected repos only).
`target_urls` array of string, required
`login_targets` array of object, required
`login_targets[].site` string, required
`login_targets[].login_check` string, required	Whether Hacktron could sign in with the login the site has now. A pass lasts an hour, and changing the site or login makes it unverified. One of `unverified`, `pending`, `running`, `succeeded`, `failed`, `cancelled`, or `expired`.
`login_targets[].failure_reason` string, required, nullable	Why the check failed, without credentials.
`custom_context` string, required, nullable
`application_id` string (uuid), required, nullable
`cost_estimation_id` string (uuid), required, nullable
`triage_enabled` boolean, required, nullable
`credits_used` number, required, nullable