AI Pentest
Autonomous AI penetration testing scans and reports.
ποΈ Create Pentest Assessment
Create a new AI pentest assessment in draft status with the given name, target, authentication, context, and scan configuration, and return the created record.
ποΈ List Pentest Assessments
Return a paginated list of the client's pentest assessments sorted by creation date, controlled by the `page` and `page_size` query parameters. Optionally filter server-side with `q` (case-insensitive substring on the name or the target URL), `status`, and a `created_from`/`created_to` day window on `created_at`; all are applied before pagination.
ποΈ Bulk Delete Pentest Assessments
Cascade-delete up to 100 pentest assessments in one request. Returns 200 with {succeeded, failed} when every cascade succeeds, 207 Multi-Status when at least one id fails (per-id status in `failed`), and 409 for the WHOLE request when any pentest doc lacks a client_id β nothing is deleted in that case (fail-closed, same semantics as the single delete).
ποΈ Record scope wizard acceptance
Store the single scope wizard screen 1 (SC-1) acceptance for this tenant: the typed target name, the verified main domain and the terms version exactly as sent. Returns 404 while NEXUS_SCOPE_WIZARD is off (flag-gated surface), 422 on a missing field. With the flag on, `POST /pentests/{pentest_id}/run` refuses without this record.
ποΈ Get Pentest Assessment
Return a single pentest assessment by ID for the authenticated client. Returns 404 when the pentest does not exist.
ποΈ Update Pentest Assessment
Update the name, target, authentication, context, or scan configuration of a draft pentest. Returns 404 when the pentest does not exist and 409 when it is no longer in draft status.
ποΈ Delete Pentest Assessment
Permanently delete a pentest assessment together with all of its findings (findings first, pentest doc last). Returns 404 when the pentest does not exist, 409 when it is currently running, and 409 when the pentest doc lacks a client_id (legacy doc β the cascade is refused so its findings stay repairable).
ποΈ Trigger Pentest Scan
Start the pentest scan workflow after validating that a target URL is set, the tenant's plan includes the AI Pentest feature (403 otherwise), and the target URL's host is covered by a verified domain or an app-scoped verification (422 otherwise; the ownership check is skipped when OWNERSHIP_VERIFICATION_ENABLED is false). A mobile target (target_kind android-apk or ios-repo) has no host: it needs at least one verified domain or app and every declared allowed domain verified, and that check is NEVER skipped, whatever OWNERSHIP_VERIFICATION_ENABLED says. Returns 404 when not found and 409 when the pentest is already pending or running.
ποΈ Cancel Running Pentest Scan
Mark a pending or running pentest as cancelled. Returns 404 when the pentest does not exist and 409 when it is not in a cancellable state.
ποΈ Stop Running Pentest Early (Keep Report)
Ask the engine to finish a running pentest now with what it has found. The run stays running while the engine wraps up; its findings and report then arrive as on a normal completion and the pentest ends completed with `stopped_early: true`. Returns 404 when the pentest does not exist, 409 when it is not running or a stop is already pending, 409 `engine_cannot_stop` when the engine does not support finishing early (nothing is changed), and 502 when the engine cannot be reached. Cancel stays the hard abort.
ποΈ Can This Running Pentest Be Stopped Early
`can_stop` is true only when the pentest is running on a nexus engine that declares `finish_early` on its capabilities. Unknown (no pod, engine silent) reads as false, so the UI hides Stop. Returns 404 when the pentest does not exist.
ποΈ Retest A Completed Pentest
Re-run the confirmed findings of a completed pentest against the same target and report one verdict per finding (fixed, fixed_by_removal, not_fixed, env_changed, not_retestable). One retest is included with each pentest, within 90 days of its completion; it creates no findings and uses no AI credits. The target ownership check runs again on every launch. `mutating_replays_acknowledged` (administrators only) lets replays that change target state run. Refusals are problem+json with a stable `data.code`: pentest_not_found (404); pentest_not_completed, retest_window_closed, retest_in_progress (409); retest_not_included, mutating_ack_requires_admin (403); target_ownership_unverified, target_scope_unrecorded, no_retestable_findings, manifest_too_large (422); artifact_store_unavailable (503); retest_launch_failed (500).
ποΈ Cancel A Pending Or Running Retest
Cancel a pending or running retest. The included retest is given back only when the cancel lands before the engine pod was reached: a cancel after warm-up has begun is not refunded. A retest already past warm-up stops at its next check, which can take up to about twenty minutes. Refusals are problem+json with a stable `data.code`: retest_not_found (404); retest_not_cancellable (409).
ποΈ List The Retests Of A Pentest
Return the retests of a pentest, newest first (at most 20): `retest_id`, `seq`, `status` (pending, running, completed, failed, refused, cancelled), `phase` (queued, starting, verifying, or the terminal status), `target_url`, `coverage`, the `created_at`/`started_at`/`finished_at` times, `entitlement_refunded`, and for a failed retest `failure` with a closed `code` (target_unreachable, engine_unavailable, login_not_applied, request_rejected, timed_out, engine_error, cancelled) and a `message`. Refusal is problem+json with `data.code`: pentest_not_found (404).
ποΈ Get One Retest
Return one retest of a pentest: everything the list returns plus `verdict_summary` (counts by verdict), `verdicts` (`finding_id`, `verdict`, `reason`, `row`, `fixed_subclass`), `not_run` (finding ids), `refused` and `control` when the engine could not log in fresh, and `cap_remaining_seconds` (seconds before an active retest is stopped; null when it is not running). Evidence is never returned. Refusal is problem+json with `data.code`: retest_not_found (404), also for a retest of another pentest or tenant.
ποΈ Get Pentest Summary
Return a pentest's status, severity counts over its live findings, and the optionally linked source repository β the compact lookup the finding detail and War Room fallback surfaces use (no full doc, no credentials echo). Returns 404 when the pentest does not exist.
ποΈ Download Pentest Report
Stream the markdown report generated by the pentest engine for this pentest as an attachment. Returns 404 when the pentest or its report is not available.
ποΈ Stream Pentest Recording
Stream the browser session recording (.webm) captured by the pentest engine for this pentest, for inline playback. Returns 404 when the pentest or its recording is not available.
ποΈ Get Pentest Logs
Return the accumulated pentest pod logs, pod name, and current status for a pentest. Returns 404 when the pentest does not exist.
ποΈ Stream Pentest Logs
Stream new pentest pod log lines as Server-Sent Events while the pentest is pending or running, ending with a [SCAN_DONE] event. Returns 404 when the pentest does not exist.
ποΈ Get Pentest Findings
Return all findings produced by a pentest together with the total count. Returns 404 when the pentest does not exist.
ποΈ Download Pentest Finding Replay Artifact
Stream the deterministic proof-of-concept artifact for a nexus pentest finding (cURL command, shell script or HAR capture) from object storage. Post-mortem-safe: artifacts persist after the scan pod is gone. Returns 404 when the pentest or finding does not exist, or when the finding carries no replay artifact (legacy inline PoC text).
ποΈ Get Pentest Chain Of Proof
Return the chain of proof of a pentest as one linear ribbon (entry, steps, objective) with the proofs no path links in `aside`, read from the engine's `chain.json`. A step is `linked` or `blocked`; its connector to the previous step is `solid` (replay-verified), `dashed` or `none`. After a retest, a step is `fixed` only when EVERY finding on it has the retest verdict `fixed` (`fixed_by_removal` never marks a step). A pentest with no published chain answers 200 with `available: false` and a `reason` (`not_published`, `unsupported_schema`, `invalid`), never an invented chain. Replays are read through the existing finding replay download; nothing here runs them. Returns 404 when the pentest does not exist and 503 when object storage is unreachable.
ποΈ Download Pentest Chain Of Proof PDF
The static PDF page of the pentest's chain of proof: the same ribbon, encoding and retest overlay as `GET /pentests/{pentest_id}/chain`. Returns 404 when the pentest does not exist or has no published chain, and 503 when object storage is unreachable.
ποΈ Get Live Browser Frame
Fetch a current JPEG browser screenshot from the running pentest pod HTTP API. Returns 409 when the pentest is not running, and 204 when no frame is available right now (pod still starting, already gone, or pentest has not captured a frame yet).
ποΈ Download Pentest Screenshot
Return the stored pentest screenshot at the given zero-based index as a JPEG image. Returns 404 when the pentest or the requested screenshot does not exist.
ποΈ Resume the scope wizard draft
Returns the half-finished scope-wizard draft for the authenticated member (discovered domains, recorded exclusions, computed run scope). 404 when there is no draft or when NEXUS_SCOPE_WIZARD is off.
ποΈ Save the scope wizard draft
Upserts the screen-2 draft (discovered domains + recorded exclusions) for the authenticated member and returns the stored, normalised draft together with the run scope it yields. 404 while NEXUS_SCOPE_WIZARD is off.