Check pentest logins

1 min

, , , , ,

Checks whether Hacktron can sign in to each of the draft’s login_targets with the saved login instructions. Every login check must pass before the pentest can start. You need the member role or above.

A successful check is valid for one hour. Start the pentest within that time or run the check again.
Hacktron skips checks that are already running or that passed within the last hour, unless the site or login instructions have changed.
Set wait_seconds to wait up to 50 seconds for the checks. Without it, the endpoint returns while checks are pending. You can call again with wait_seconds to wait for the results. Each call retries failed logins, so correct wrong instructions before calling again.

Each entry in login_targets has a login_check status: pending or running while the check is in progress, succeeded after a successful sign-in, or failed if Hacktron couldn’t sign in.

A failed check includes a failure_reason without login details. Correct the instructions with PATCH /pentests/{id}, then run the check again.

Request

POST /pentests/{id}/login-checks

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

curl -X POST "https://api.hacktron.ai/v1/pentests/<id>/login-checks" \
  -H "X-Api-Key: $HACKTRON_API_KEY"

{
  "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

Query parameters

Parameter	Description
`wait_seconds` integer	Wait up to this many seconds for the work to finish before answering. Default `0`. At least 0. At most 50.

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

400 Bad Request

The pentest has no login targets.