Documentation

Overview

aisec is an autonomous AI-driven penetration testing agent. It uses large language models to plan and execute security assessments, combining traditional security tools (nmap, sqlmap, nikto, dirsearch, Playwright) with AI reasoning to discover vulnerabilities.

The agent operates in iterative cycles: each iteration it analyzes what it knows, decides which tool to run next, executes it, and interprets the results. This continues until it exhausts its iteration budget or determines the target has been thoroughly tested.

Interact via the web dashboard, the CLI (pip install git+https://github.com/stuseek/aisec-cli.git), or the REST API directly.

2
AI Engines
12+
Security Tools
4
Scan Profiles
Authentication

All API requests require a Bearer token:

Authorization: Bearer ask_xxxxxxxxxxxxxxxx

Generate keys in Developer → API Keys. For the CLI, set AISEC_TOKEN env variable. WebSocket connections pass the token as a query parameter: ?token=ask_xxx.

Keys use the ask_ prefix. Each key can access all scans and data under your account. Revoke compromised keys immediately in the Developer panel.
Scan Profiles
normal
Balanced speed and thoroughness. Standard toolset with moderate rate limiting. Good for most targets.
Tools: nmap, nikto, curl, PlaywrightDefault iters: 30
stealth
Slow and careful. Randomized timing, WAF/IDS evasion, avoids noisy tools like nmap aggressive scans.
Tools: curl, Playwright (headless)Default iters: 20
aggressive
Full power. All tools enabled, brute-force included, no rate limiting. Use only with permission.
Tools: All: nmap, sqlmap, nikto, dirsearch, Playwright, curlDefault iters: 50
full
Maximum coverage. Aggressive profile plus subdomain scope and 50 iterations. Most comprehensive scan.
Tools: All + subdomain enumerationDefault iters: 50
API Endpoints
GET/api/v1/statsDashboard stats, severity breakdown, cost, recent activity
GET/api/v1/scansList scans — query: page, limit, status, search
POST/api/v1/scansCreate and start a new scan
GET/api/v1/scans/{id}Get full scan details
DELETE/api/v1/scans/{id}Delete a scan and all associated data
POST/api/v1/scans/{id}/cancelCancel a running scan
GET/api/v1/scans/{id}/findingsList all findings for a scan
PATCH/api/v1/scans/{id}/findings/{fid}Update finding verification status
GET/api/v1/scans/{id}/logsAgent logs — query: page, limit, log_type
GET/api/v1/scans/{id}/reconInfrastructure and browser recon data
GET/api/v1/scans/{id}/technologiesDetected technologies and versions
GET/api/v1/scans/{id}/endpointsDiscovered endpoints and parameters
GET/api/v1/scans/{id}/report.pdfDownload PDF report
GET/api/v1/billingCurrent plan, usage, billing history
GET/api/v1/keysList API keys
POST/api/v1/keysCreate new API key
DELETE/api/v1/keys/{id}Revoke an API key
WS/ws/scans/{id}?token=...Live scan event stream (WebSocket)
Create Scan
POST /api/v1/scans — all fields except target are optional with sensible defaults.
{
  "target": "https://example.com",
  "engine": "claude",
  "model": "claude-sonnet-4-5-20250929",
  "profile": "normal",
  "max_iterations": 50,
  "scope": "target",
  "timeout_minutes": 0,
  "temperature": 0.4,
  "username": null,
  "password": null,
  "cookies_json": null,
  "proxy": null,
  "custom_headers": null,
  "skip_recon": false,
  "skip_browser": false
}
WebSocket
Connect to /ws/scans/{id}?token=ask_xxx for real-time scan events. Server sends JSON with type, ts, data. Client can send {"type":"cancel"} or {"type":"ping"}.
scan_startedScan has begun executingscan_id
iteration_startNew AI iteration cycle startediteration, max_iterations
consoleConsole output with ANSI formattingtext, ansi
tool_execTool being executed by the agenttool, command
tool_outputTool execution resulttool, command, output, exit_code
thinkingAI reasoning / analysis texttext
findingVulnerability discoveredseverity, title, cwe, url, description
cost_updateToken usage and cost updatecost, tokens_in, tokens_out
errorError occurred during scanmessage, recoverable
recoveryAgent recovered from errormessage, strategy
scan_completeScan finishedfindings_count, cost, duration_seconds
Errors
All errors return JSON with detail field.
400Bad Request — invalid parameters or missing required fields
401Unauthorized — missing or invalid Bearer token
403Forbidden — valid token but insufficient permissions
404Not Found — scan or resource doesn't exist
409Conflict — scan already running or cancelled
422Validation Error — request body failed schema validation
429Rate Limited — too many requests, retry after delay
500Internal Error — unexpected server error
Limits
20Concurrent scans
Additional scans queued automatically
50Max iterations
Per scan, configurable at creation
UnlimitedWebSocket connections
One per scan for live streaming
100 req/minAPI rate limit
Per API key, 429 on exceed
ConfigurableScan timeout
0 = unlimited, set timeout_minutes
UnlimitedMax findings
All findings stored per scan