> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.darknetsearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assess an organization's attack surface

> Run an external assessment of a domain's internet-facing estate and get a branded report: full and targeted assessments, what they use from your plan, and how they differ from Infra search.

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/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/scans/full/) | [`POST /api/hackerview/scans/targeted/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/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](https://wiki.darknetsearch.com/api/guides/attack-surface-assessments.md) lists every flag and every targeted report.

### How an assessment runs

**1. Start the assessment**

Send the domain and the modules you want. The call returns `200` with the assessment's `uid`. See [Start an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-assessments.md).

**2. 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](https://wiki.darknetsearch.com/api/guides/attack-surface-progress.md).

**3. 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](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md).

**4. Use the findings**

Read the report's sections and datasets as JSON to feed your own tooling. See [Read assessment report data](https://wiki.darknetsearch.com/api/guides/attack-surface-report-data.md).

**5. 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](https://wiki.darknetsearch.com/api/guides/attack-surface-exclusions.md) and [Brand assessment reports](https://wiki.darknetsearch.com/api/guides/attack-surface-branding.md).

### 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`:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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](https://wiki.darknetsearch.com/api/guides/rate-limits.md) and, with an API key, toward your monthly API Calls allowance when it returns `2xx`. [Plans and quotas](https://wiki.darknetsearch.com/api/guides/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](https://wiki.darknetsearch.com/api/guides/errors.md) explains how to branch on each status.

### Infra search is a different feature

The dashboard's **Exposure → Attack Surface Discovery** is [Infra search](https://wiki.darknetsearch.com/api/guides/infra-search.md), 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](https://wiki.darknetsearch.com/api/guides/infra-search.md) |
| 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](https://wiki.darknetsearch.com/api/guides/domain-monitoring.md) |
| Search public code platforms for exposed code and secrets by keyword | [Code exposure](https://wiki.darknetsearch.com/api/guides/code-exposure.md) |

### Guides in this section

> [card] [Start an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-assessments.md)
>
> Full and targeted starts, module flags, domain modes, active scope, report options and refusals.

> [card] [Follow an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-progress.md)
>
> Statuses, progress phases, the queue, the assessment list and how long it takes.

> [card] [Generate and download reports](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md)
>
> Report types, on-demand reports, tracking and downloads.

> [card] [Read report data](https://wiki.darknetsearch.com/api/guides/attack-surface-report-data.md)
>
> A report's sections and datasets as JSON.

> [card] [Brand reports](https://wiki.darknetsearch.com/api/guides/attack-surface-branding.md)
>
> Report templates with your logo, colors and footer.

> [card] [Exclude assets](https://wiki.darknetsearch.com/api/guides/attack-surface-exclusions.md)
>
> Exclusion and include rules for hosts, people, CVEs, findings and more.

### Endpoints

| Action | Endpoint | Guide |
| - | - | - |
| Start a full assessment | [`POST /api/hackerview/scans/full/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/scans/full/) | [Start an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-assessments.md) |
| Start a targeted assessment | [`POST /api/hackerview/scans/targeted/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/scans/targeted/) | [Start an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-assessments.md) |
| List assessments | [`GET /api/hackerview/scans/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/scans/) | [Follow an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-progress.md) |
| Get an assessment's progress | [`GET /api/hackerview/scans/{scan_id}/progress/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/scans/\{scan_id}/progress/) | [Follow an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-progress.md) |
| Get an assessment's queue position | [`GET /api/hackerview/scans/{scan_id}/queue/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/scans/\{scan_id}/queue/) | [Follow an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-progress.md) |
| List reports | [`GET /api/hackerview/reports/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/) | [Reports](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md) |
| Generate a report | [`POST /api/hackerview/reports/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/reports/) | [Reports](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md) |
| Download a report | [`GET /api/hackerview/reports/{report_uid}/download/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/download/) | [Reports](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md) |
| List a report's data | [`GET /api/hackerview/reports/{report_uid}/data/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/) | [Report data](https://wiki.darknetsearch.com/api/guides/attack-surface-report-data.md) |
| Read a report section | [`GET /api/hackerview/reports/{report_uid}/data/{section}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/\{section}/) | [Report data](https://wiki.darknetsearch.com/api/guides/attack-surface-report-data.md) |
| Read a report dataset | [`GET /api/hackerview/reports/{report_uid}/data/datasets/{name}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/reports/\{report_uid}/data/datasets/\{name}/) | [Report data](https://wiki.darknetsearch.com/api/guides/attack-surface-report-data.md) |
| List report templates | [`GET /api/hackerview/report_templates/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/report_templates/) | [Branding](https://wiki.darknetsearch.com/api/guides/attack-surface-branding.md) |
| Create a report template | [`POST /api/hackerview/report_templates/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/report_templates/) | [Branding](https://wiki.darknetsearch.com/api/guides/attack-surface-branding.md) |
| Update a report template | [`PATCH /api/hackerview/report_templates/{template_uid}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/PATCH/api/hackerview/report_templates/\{template_uid}/) | [Branding](https://wiki.darknetsearch.com/api/guides/attack-surface-branding.md) |
| Delete a report template | [`DELETE /api/hackerview/report_templates/{template_uid}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/DELETE/api/hackerview/report_templates/\{template_uid}/) | [Branding](https://wiki.darknetsearch.com/api/guides/attack-surface-branding.md) |
| List exclusion rules | [`GET /api/hackerview/exclusions/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/exclusions/) | [Exclusions](https://wiki.darknetsearch.com/api/guides/attack-surface-exclusions.md) |
| Create an exclusion rule | [`POST /api/hackerview/exclusions/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/exclusions/) | [Exclusions](https://wiki.darknetsearch.com/api/guides/attack-surface-exclusions.md) |
| Delete an exclusion rule | [`DELETE /api/hackerview/exclusions/{entry_id}/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/DELETE/api/hackerview/exclusions/\{entry_id}/) | [Exclusions](https://wiki.darknetsearch.com/api/guides/attack-surface-exclusions.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.