Pentestas / help

Operator hints

While a scan is running or pending, the scan detail page shows an Operator hints panel. Hints are a live steering channel: you drop guidance, the engine picks it up within about 15 seconds, and the UI shows status (pending → acknowledged → acted_on).

Hints are not fire-and-forget chat. Structured directives change engine behaviour. Free-text guidance still reaches the AI analyst, but free-text alone does not auto-promote a hint to acted_on.

Where to send them

  1. Open the scan detail page for a live scan.
  2. Find Operator hints (above the tabs).
  3. Enter control syntax and/or free text in the textarea.
  4. Optionally add tags (comma-separated) in the tags field.
  5. Click Send hint.

On completed / failed / cancelled scans the panel is read-only (history for audit).

Control syntax

Use one directive per line (or inline key: value tokens). Directives are case-insensitive.

Directive Effect
focus: /admin/ Prioritise URL paths under this prefix
skip: /static/ Deprioritise / ignore matching paths
retest: SQLI Re-queue a vulnerability module (aliases supported)
retest: SQLI @ /api/users Module retest scoped to a path
retest: https://target/api/v1/orders?id=1 Hot URL for retest
param: user_token Note an auth/CSRF field name for workbench + logs
workbench: true Force a workbench-agent investigation turn

Example

focus: /admin/
skip: /static/
skip: /assets/
retest: XSS @ /vulnerabilities/xss_r/
param: user_token
workbench: true

Also: login is admin/password — form posts to /login.php

The free-text paragraph steers the AI analyst; the directive lines drive concrete engine actions.

Tags (UI field)

Tags are alnum + dash. Useful shortcuts:

Tag Meaning
workbench Same as workbench: true
retest-sqli Retest SQL injection module
retest-xss Retest XSS
focus-admin Focus /admin
skip-staging Skip /staging
param-csrf Param hint csrf

Bare vuln aliases as tags (sqli, ssrf, idor, …) also queue retests.

Vulnerability aliases for retest

Common aliases map to engine module names:

sqli / sql → SQLI · xss → XSS · rce / cmd → RCE · lfi / path → PATH_TRAVERSAL · ssrf → SSRF · idor → IDOR · ssti → SSTI · csrf → CSRF · auth → AUTH_BYPASS · jwt → JWT · xxe → XXE · upload → FILE_UPLOAD · nosql → NOSQL_INJECTION · redirect → OPEN_REDIRECT · mass-assignment → MASS_ASSIGNMENT

Lifecycle

Status Meaning
pending Accepted; not yet consumed by the engine
acknowledged Engine saw the hint (control directives applied or free-text fed to analyst)
acted_on A concrete control action ran (focus/skip/retest/workbench). Free-text-only hints stay acknowledged, not acted_on

This avoids the false “acted on” badge when the model only read your note.

What hints can and cannot do

Can

  • Narrow crawl/attack attention to a path prefix.
  • Skip noisy or out-of-interest trees (static assets, staging mirrors).
  • Re-queue a module or URL after you noticed something mid-scan.
  • Force a workbench investigation turn.
  • Steer AI narrative/analyst context with free text.

Cannot

  • Expand scope beyond the scan’s allowed hosts / verified domains.
  • Inject new credentials (use authenticated scans or re-run with auth).
  • Guarantee a finding — retest still has to prove the issue.
  • Change destructive-safety policy mid-flight.

API

http 
GET  /api/scans/{id}/hints
POST /api/scans/{id}/hints
     { "text": "focus: /admin/\nretest: SQLI", "tags": ["workbench"] }
PATCH /api/scans/{id}/hints/{hint_id}

Requires the same auth as other scan endpoints (session or API key).

See also