Assess an organization's attack surface

An attack surface assessment maps and tests what one domain exposes to the internet. You send acme.com. The assessment discovers the hosts under it, enriches each one, runs the checks you switch on, scores what it finds and builds a branded report from the results. In the dashboard, assessments live under Exposure → Risk Assessments. The API calls an assessment a scan: the paths are /api/hackerview/scans/, and an assessment’s uid appears as scan_id in paths and as scan_uid in reports. hackerview is the name of the assessment engine. It also appears in download filenames.

Full and targeted assessments

Pick the kind of assessment by the report you want back.

	Full assessment	Targeted assessment
Start it with	`POST /api/hackerview/scans/full/`	`POST /api/hackerview/scans/targeted/` with a `report_type`
What runs	Discovery, the always-on checks, and every module flag you leave on. 7 of the 13 flags are on by default.	Discovery, the always-on checks, and only the modules the chosen report reads
Report you get	The Full Attack Surface Report	One of 7 focused reports, such as the Domain Spoofing Risk Report or the Breach Risk Report
Allowance it uses	1 unit of Attack Surface Reports	1 unit of Targeted Attack Surface Reports

Every assessment, full or targeted, discovers the domain’s hosts from passive sources and enriches each one. It also runs a set of always-on checks, including email authentication, leaked credentials, open cloud storage, shortened URLs, known phishing sites, TLS and web application security. The module flags add the rest, such as port verification, look-alike domains and executive exposure. Start an assessment lists every flag and every targeted report.

How an assessment runs

Start the assessment

Send the domain and the modules you want. The call returns 200 with the assessment’s uid. See Start an assessment.

Follow it to completion

Poll its progress until status is Completed. Your organization runs one assessment at a time, and further starts wait in a queue. An assessment takes from minutes to several hours. See Follow an assessment.

Get the report

When the assessment completes with data for its report, the platform generates the report automatically: the Full Attack Surface Report for a full assessment, or the chosen report for a targeted one. It starts building about 3 minutes after completion. You do not need to request it. If no report appears in the report list, generate one yourself. Track it and download it as a PDF bundle or JSON. See Generate and download assessment reports.

Use the findings

Read the report’s sections and datasets as JSON to feed your own tooling. See Read assessment report data.

Refine and regenerate

Exclude hosts, people or findings that are out of scope, or brand the report with your logo. Then generate the report again. No new assessment is needed. See Exclude assets from assessments and Brand assessment reports.

Availability and cost

Availability: Attack Surface Reports for full assessments and Targeted Attack Surface Reports for targeted assessments, both included in every edition. Either one opens the assessment list, progress, queue, reports, report data, branding templates and exclusion rules. Cost: 1 unit of your monthly Attack Surface Reports allowance for each full assessment you start, and 1 unit of your monthly Targeted Attack Surface Reports allowance for each targeted one. The unit is taken before the request reaches the assessment engine and refunded on any non-2xx response. An assessment that starts keeps its unit, even if it ends Failed. Every other Attack Surface call has no metered allowance: listing, progress, reports, report data, downloads, templates and exclusions use no units. Without either plan feature, or when your license is not in force, every Attack Surface endpoint returns 403:

{
  "detail": "This feature is not included in your plan."
}

These endpoints never answer "Your license is not active.". A lapsed license returns the message above. Starting a full assessment needs Attack Surface Reports, and starting a targeted one needs Targeted Attack Surface Reports. A plan with only one of the two gets 403 on the other start. When the month’s allowance is spent, the start returns 429 and no assessment is created:

{
  "detail": "You have reached your Attack Surface Report limit for this month.",
  "resource": "attack_surface_report",
  "period": "month",
  "limit": 3
}

A targeted start reads "Targeted Attack Surface Report" in detail and targeted_attack_surface_report in resource. Branch on resource. limit is your organization’s monthly units for that allowance, packs included. Allowances reset on the 1st of each month at 00:00 UTC. Attack Surface uses no capacity slots, so no endpoint here returns the 409 capacity body. Every call also counts toward your per-second rate limit and, with an API key, toward your monthly API Calls allowance when it returns 2xx. Plans and quotas explains all of these limits.

Errors from the assessment engine

The API forwards each request to the assessment engine and passes its 4xx answers back unchanged, with the same status code. Their bodies come in these shapes:

Shape	Example	Where you see it
`details`	`{"details": "Scan not found."}`	Starting an assessment, progress, queue and exclusion rules, such as `{"details": "Entry not found."}` for an unknown rule
`error`, often with a `code` and more fields	`{"error": "Report not ready for download."}`	Reports and report data. Branch on `code` when it is present.
`detail`	`{"detail": "Invalid page."}`	A list page past the last one, or `{"detail": "Not found."}` for an unknown report template
Field errors	`{"report_type": ["This field is required."]}`	Any request body or query parameter that fails validation

When the engine fails, the API answers itself and hides the engine’s body:

Status	Body
`502`	`{"detail": "The requested service is temporarily unavailable."}`
`504`	`{"detail": "The requested service timed out."}`

Handle API errors explains how to branch on each status.

Infra search is a different feature

The dashboard’s Exposure → Attack Surface Discovery is Infra search, not an assessment. It uses its own allowance, Attack Surface Mapping, and returns a host list rather than a report.

You want to…	Use
Inventory the hosts, IP addresses, open ports and known CVEs under a domain from public datasets, without touching your hosts	Infra search
Get a complete external assessment with active checks on your own domains, scored and delivered as a branded report	A full assessment
Get one focused report, such as look-alike domains or executive exposure	A targeted assessment
Watch look-alike domains continuously	Domain monitoring
Search public code platforms for exposed code and secrets by keyword	Code exposure

Guides in this section

Start an assessment

Full and targeted starts, module flags, domain modes, active scope, report options and refusals.

Follow an assessment

Statuses, progress phases, the queue, the assessment list and how long it takes.

Generate and download reports

Report types, on-demand reports, tracking and downloads.

Read report data

A report’s sections and datasets as JSON.

Brand reports

Report templates with your logo, colors and footer.

Exclude assets

Exclusion and include rules for hosts, people, CVEs, findings and more.

Endpoints

Action	Endpoint	Guide
Start a full assessment	`POST /api/hackerview/scans/full/`	Start an assessment
Start a targeted assessment	`POST /api/hackerview/scans/targeted/`	Start an assessment
List assessments	`GET /api/hackerview/scans/`	Follow an assessment
Get an assessment’s progress	`GET /api/hackerview/scans/{scan_id}/progress/`	Follow an assessment
Get an assessment’s queue position	`GET /api/hackerview/scans/{scan_id}/queue/`	Follow an assessment
List reports	`GET /api/hackerview/reports/`	Reports
Generate a report	`POST /api/hackerview/reports/`	Reports
Download a report	`GET /api/hackerview/reports/{report_uid}/download/`	Reports
List a report’s data	`GET /api/hackerview/reports/{report_uid}/data/`	Report data
Read a report section	`GET /api/hackerview/reports/{report_uid}/data/{section}/`	Report data
Read a report dataset	`GET /api/hackerview/reports/{report_uid}/data/datasets/{name}/`	Report data
List report templates	`GET /api/hackerview/report_templates/`	Branding
Create a report template	`POST /api/hackerview/report_templates/`	Branding
Update a report template	`PATCH /api/hackerview/report_templates/{template_uid}/`	Branding
Delete a report template	`DELETE /api/hackerview/report_templates/{template_uid}/`	Branding
List exclusion rules	`GET /api/hackerview/exclusions/`	Exclusions
Create an exclusion rule	`POST /api/hackerview/exclusions/`	Exclusions
Delete an exclusion rule	`DELETE /api/hackerview/exclusions/{entry_id}/`	Exclusions

Get started

Search

Leaked credentials

Assess & report

Monitors

Domain monitoring

Downloads & exports

Changelog

Assess an organization's attack surface

Full and targeted assessments

How an assessment runs

Availability and cost

Errors from the assessment engine

Infra search is a different feature

Guides in this section

Start an assessment

Follow an assessment

Generate and download reports

Read report data

Brand reports

Exclude assets

Endpoints

​Full and targeted assessments

​How an assessment runs

​Availability and cost

​Errors from the assessment engine

​Infra search is a different feature

​Guides in this section

Start an assessment

Follow an assessment

Generate and download reports

Read report data

Brand reports

Exclude assets

​Endpoints

Full and targeted assessments

How an assessment runs

Availability and cost

Errors from the assessment engine

Infra search is a different feature

Guides in this section

Endpoints