Scanning

Scans execute tool pipelines against your targets. Each scan is queued, processed by a worker, and tracked from creation to completion.

Creating a Scan

Start a scan by selecting a target and a scan engine. The target must exist and belong to your account.

POST /api/v1/scans

curl -X POST https://api.xnolex.com/api/v1/scans \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "550e8400-e29b-41d4-a716-446655440000",
    "engine": "full"
  }'

Valid engines: full, subdomain, nuclei. Defaults to "full" if not specified.

Engine Pipelines

full

Complete security assessment pipeline. Discovers subdomains, maps HTTP services, and validates vulnerabilities.

Full engine pipeline

subfinder -d <domain> -silent -timeout 60          (5-25%)
  → Passive subdomain enumeration from multiple sources

nmap -sn --open -T4 --max-retries 1 <domain>      (25-40%)
  → Host discovery and open port detection

merge subdomains from both tools, deduplicate     (40%)

httpx-pd -silent -status-code -title \
  -tech-detect -follow-redirects \
  -timeout 15 -retries 1                          (40-65%)
  → HTTP probing with status codes, page titles, tech fingerprints

nuclei -silent -json \
  -severity critical,high,medium,low,info \
  -timeout 10 -retries 1 -rate-limit 50           (65-92%)
  → Vulnerability template scanning on all endpoints

100%                                              Scan complete

subdomain

Attack surface mapping without vulnerability scanning. Discovers subdomains and HTTP services.

Subdomain engine pipeline

subfinder -d <domain> -silent -timeout 60          (5-50%)
  → Passive subdomain enumeration

nmap -sn --open -T4 --max-retries 1 <domain>      (50-70%)
  → Host discovery and open port detection

merge subdomains from both tools, deduplicate     (70%)

httpx-pd -silent -status-code -title \
  -tech-detect -follow-redirects \
  -timeout 15 -retries 1                          (70-90%)
  → HTTP probing with status codes and tech detection

100%                                              Scan complete

nuclei

Direct vulnerability scanning on the root domain. Probes the domain with httpx first, then runs nuclei against discovered endpoints.

Nuclei engine pipeline

httpx-pd -silent -status-code -title \
  -tech-detect -follow-redirects \
  -timeout 15 -retries 1                          (10-35%)
  → Probe root domain for HTTP services

nuclei -silent -json \
  -severity critical,high,medium,low,info \
  -timeout 10 -retries 1 -rate-limit 50           (35-90%)
  → Vulnerability template scanning

100%                                              Scan complete

Scan Lifecycle

Scans progress through the following statuses:

pending — Scan created and queued. Waiting for a worker to pick it up.

running — Worker is executing the tool pipeline. Progress updates are delivered via WebSocket.

completed — Pipeline finished successfully. All findings are stored and the report is available.

failed — An error occurred during execution. Check the scan detail for the error message.

cancelled — You stopped the scan manually before completion.

Real-Time Progress

Connect to the WebSocket endpoint to receive live progress updates. Each message includes the current progress percentage, status, and findings counts as they are discovered.

WebSocket connection

ws://api.xnolex.com/ws/scans/{scan_id}?token=<access_token>

Message format:

WebSocket message

{
  "scan_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress": 45,
  "message": "discovered:subdomain:api.example.com:192.168.1.1"
}

Note

The WebSocket automatically sends a status ping every 5 seconds if no progress events are emitted. The connection closes when the scan reaches a terminal status (completed, failed, or cancelled).

Stopping a Scan

Cancel a running or pending scan. The worker process is terminated and the scan status is set to "cancelled".

POST /api/v1/scans/{id}/stop

curl -X POST https://api.xnolex.com/api/v1/scans/{scan_id}/stop \
  -H "Authorization: Bearer <token>"

Warning

Stopping a scan is irreversible. Any findings discovered before the stop request are preserved, but the scan cannot be resumed.

Scan History

List your scans with optional filters for target ID and status. Results are ordered by creation date (newest first) with a limit of 50.

GET /api/v1/scans

curl "https://api.xnolex.com/api/v1/scans?status=completed" \
  -H "Authorization: Bearer <token>"

Limits & Rate Limits

Concurrent Scan Limits

Tier

Concurrent Scans

Total Scan Limit

Demo

Monthly Pro

Yearly Pro

120

System-Wide Limits

Global concurrent limit: 10 scans across all users. Exceeding this returns a 429 status code.

Scan queue: Maximum 100 pending scans. The queue is processed by 3 workers.

Stuck scan recovery: Scans running for more than 2 hours are automatically marked as failed.

API Rate Limits

Tier

Requests Per Minute

Demo

Monthly Pro

Yearly Pro

120

Info

Rate limits are enforced per user via a sliding window counter in Redis. Exceeding the limit returns a 429 status code. Webhook and health check endpoints are exempt.

Getting Scan Detail

Retrieve a scan's full details including all discovered subdomains, endpoints, and vulnerabilities.

GET /api/v1/scans/{id}

curl https://api.xnolex.com/api/v1/scans/{scan_id} \
  -H "Authorization: Bearer <token>"

Response (abbreviated)

{
  "id": "550e8400-...",
  "target_domain": "example.com",
  "engine": "full",
  "status": "completed",
  "progress": 100,
  "findings_count": 12,
  "critical_count": 2,
  "high_count": 3,
  "medium_count": 4,
  "low_count": 3,
  "subdomains": [...],
  "endpoints": [...],
  "vulnerabilities": [...]
}