Scans - Efflux

What a scan is

A scan job targets hosts, ports, domains, URLs, or specific CVEs. Host and port combinations are scanned together. Domains get DNS and HTTP collection. URLs get HTTP collection.

Create returns the scan. data.job_id is the id you poll. data.status starts as pending, moves through in progress, and finishes as complete. A rejected request comes back as rejected with errors and rejected_* arrays. canceled means the scan was stopped.

POST/v3/scans

Create a scan job

API reference

Request fields

Field	Type	Notes
`hosts`	string[]	IPs, CIDRs, or a saved host list name
`ports`	string[]	Ports, ranges (`80-88`), `top_1000`, or a saved port list name
`proto`	string	`tcp` (default) or `udp`
`domains`	string[]	Domain names to collect
`urls`	string[]	Exact URLs to collect
`paths`	string[]	Paths appended to hosts and domains
`paths_https`	boolean	Use `https` for path collection
`cves`	string[]	CVE ids to check. Cannot be combined with `urls` or `paths`
`fingerprint`	boolean	Identify the service on open ports. Doubles `request_count`
`checks`	boolean	Run vulnerability checks on open services
`checks_options`	object	`cves_only`, `min_severity`, `max_severity`
`collect`	object	Service name to the ports to collect
`callback`	object	See Callbacks. Empty phases can be filled from preferences
`tags`	string[]	At most 10 tags, 40 characters each
`description`	string	At most 300 characters

Severity values are info, low, medium, high, and critical. min_severity cannot be above max_severity.

cves cannot be combined with urls or paths. With cves set, hosts and domains are targets for those checks only. With urls or paths set, hosts and domains are HTTP collection targets, and normal port scanning is not run.

curl -sS -X POST "https://api.efflux.io/v3/scans" \
  -H "Authorization: Bearer $EFFLUX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hosts": ["1.2.3.4", "10.0.0.0/24", "my_internal_servers"],
    "ports": ["22", "80-88", "top_1000", "my_common_ports"],
    "proto": "tcp",
    "fingerprint": false,
    "checks": true,
    "checks_options": { "cves_only": false, "min_severity": "high" },
    "collect": { "ssh": ["22", "2222"], "rdp": ["3389"] },
    "tags": ["web", "security"],
    "description": "External web tier",
    "callback": {
      "success": { "url": "https://example.com/hook/$job_id", "method": "POST" }
    }
  }'

Names inside hosts and ports refer to lists you already saved. Unknown names land in rejected_hosts or rejected_ports.

Dry run

POST /scans/eval checks the same body and returns the counts for that scan without creating it. status is acceptable when the scan can be created.

POST/v3/scans/eval

Evaluate a scan without creating it

API reference

Read results

Poll GET /scans/{job_id} until status is complete.

GET/v3/scans/{job_id}

Get a scan job

API reference

GET/v3/scans/{job_id}/results

Full result report

API reference

GET/v3/scans/{job_id}/summary

Summary counts

API reference

Results and summary are the report. They are not wrapped in data. Pass details on the results route for the full report.

links on the job includes self, results, and summary.

GET/v3/scans

List your scan jobs

API reference

POST/v3/scans/{job_id}/repeat

Run the same request again

API reference

Repeat returns 201 and a new job id.

Checks found by the scan are queried separately. See Checks.

Errors and limits

Status	When
400	Body failed validation
401	Missing key, or a plan limit was reached
409	An equivalent job is already pending
429	Rate limit. Read `retry_after_seconds`

Pending and concurrent scan caps, and the monthly request budget, come from GET /limits. The create response includes request_count, the requests this scan uses from that budget. Fingerprinting doubles that count.