> ## 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.

# Start an attack surface assessment

> Start a full or targeted assessment of a domain: module flags and their defaults, the seven targeted reports, domain modes, active scope, report options and the reasons a start is refused.

One `POST` starts an assessment. You choose the domain, the modules, how other domains of the organization are handled, which domains may be tested actively, and how the automatic report looks. The call answers at once with the assessment's `uid`. The work runs in the background: follow it with [Follow an assessment](https://wiki.darknetsearch.com/api/guides/attack-surface-progress.md).

**Availability:** Attack Surface Reports for full assessments and Targeted Attack Surface Reports for targeted assessments, both included in every edition.

**Cost:** 1 unit of your monthly Attack Surface Reports allowance per full assessment, or 1 unit of your monthly Targeted Attack Surface Reports allowance per targeted assessment. The unit is taken before the request reaches the assessment engine and refunded on any non-`2xx` response. No refusal in [Refusals at start](#refusals-at-start) costs a unit. An assessment that starts keeps its unit, even if it later ends `Failed`.

### Choose full or targeted

| | Full assessment | Targeted assessment |
| - | - | - |
| Endpoint | [`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/) |
| Required fields | `domain` | `domain` and `report_type` |
| Modules | All 13 [module flags](#module-flags), 7 of them on by default | Only the modules the chosen report reads |
| Report generated | Full Attack Surface Report | The one report named in `report_type` |
| Allowance | Attack Surface Reports | Targeted Attack Surface Reports |

Both endpoints also take the [domain handling](#domain-handling), [active scope](#active-scope) and [report options](#report-options) fields. Send a JSON body. Fields this page does not list are ignored.

### Start a full assessment

Send the domain. Add a module flag only to change its default.

```bash theme={"dark"}
curl https://client-api.leak.center/api/hackerview/scans/full/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.com",
    "active_vuln_scan": true,
    "code_exposure_enabled": true,
    "report_language": "de"
  }'
```

The call returns `200` with the new assessment:

```json theme={"dark"}
{
  "uid": "6b1f0c2e-4d3a-4f5b-9c8d-7e6f5a4b3c2d",
  "status": "Running",
  "queue_reason": "",
  "domain": "acme.com",
  "original_domain": "",
  "scan_domains": [],
  "subdomain_lookups_completed": false,
  "same_ip_lookups_completed": false,
  "ip_range_lookups_completed": false,
  "reverse_whois_lookups_completed": false,
  "created_at": "2026-10-08T09:14:02.481203Z",
  "updated_at": "2026-10-08T09:14:02.481203Z",
  "completed_at": null,
  "elapsed_time_seconds": null
}
```

Keep the `uid`. It is the `scan_id` in the progress and queue paths and the `scan_uid` in reports.

> [!WARNING]
>
> **Don't trust `status` in this response.** It is always `Running`, because the response is written before the assessment is dispatched. The assessment may be `Queued` a moment later. Read the real status from [progress](https://wiki.darknetsearch.com/api/guides/attack-surface-progress.md).

When the assessment completes, the Full Attack Surface Report is generated automatically. If no report appears in the report list, generate one yourself. See [Generate and download assessment reports](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md).

### Module flags

Every assessment discovers the domain's hosts from passive sources, enriches each one, and runs a set of always-on checks, such as email authentication, leaked credentials, open cloud storage, TLS and web application security. These flags switch the remaining modules on or off. The defaults apply to full assessments. The names match the module switches in the dashboard.

| Flag | Dashboard name | Default | What it adds |
| - | - | - | - |
| `perform_port_scan` | Open ports & services | `true` | Connects to discovered hosts in your [active scope](#active-scope) to confirm open ports and identify the services behind them. |
| `active_dns_enumeration` | Subdomain discovery | `true` | Tests 5,000 common subdomain names through public DNS resolvers to find hosts no public source lists. About 7 minutes. |
| `dns_posture_enabled` | DNS & email security | `true` | 37 checks on nameserver health, zone-transfer exposure, open recursion and SPF, DKIM and DMARC policy. Under 30 seconds. |
| `active_vuln_scan` | Active vulnerability check | `false` | A read-only pass with curated templates that confirms exposed panels, misconfigurations and known vulnerabilities on live services in your active scope. Runs after discovery. |
| `dns_typosquatting_enabled` | Look-alike domains | `true` | Finds registered look-alike domains, such as `acme-login.com`, and flags those serving phishing pages. Up to 30 minutes. |
| `social_media_enabled` | Social media exposure | `false` | Searches major social platforms for brand impersonation and fake profiles. 60 to 90 seconds. |
| `social_media_ads_enabled` | Social media ads | `false` | Searches public ad libraries for paid ads that abuse the brand. Needs `social_media_enabled`. |
| `email_enumeration` | Employee emails | `true` | Finds employee email addresses in breach data and public sources, scored by exposure. 30 to 60 seconds. |
| `code_exposure_enabled` | Leaked code & secrets | `false` | Searches public GitHub repositories and Gists for exposed code, secrets and keys that mention the domain. 2 to 5 minutes. |
| `tg_discord_paste_search` | Hacker channels & paste mentions | `true` | Searches Telegram channels, Discord servers and paste sites for mentions of the brand or domain. 30 to 120 seconds. |
| `paste_include_google_search` | Extended paste search | `false` | Adds a live web search across 76 paste sites. 5 to 30 seconds more. Needs `tg_discord_paste_search`. |
| `vip_enumeration` | Executive exposure | `true` | Identifies executives and other high-value people and builds an exposure profile for each. 15 to 30 minutes. |
| `vip_skip_email_guessing` | Identity-confirmed emails only | `false` | Uses only personal email addresses confirmed to the person, instead of guessing them from name patterns. Needs `vip_enumeration`. |

An assessment that turns on `perform_port_scan`, `active_vuln_scan` or `dns_typosquatting_enabled` is a heavy assessment. So is one with `domain_mode` set to `dual_domain` or `all`. A full assessment with the defaults is heavy. Heavy assessments can be refused while the platform is busy: see [Refusals at start](#refusals-at-start).

### Start a targeted assessment

Send the domain and a `report_type`. Add only the optional flags of that report.

```bash theme={"dark"}
curl https://client-api.leak.center/api/hackerview/scans/targeted/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.com",
    "report_type": "vip_executive_risk",
    "vip_skip_email_guessing": true
  }'
```

The response is the same as for a full assessment.

| `report_type` | Report | What it covers | Forced on | Optional flags and their defaults |
| - | - | - | - | - |
| `domain_spoofing_risk` | Domain Spoofing Risk Report | Look-alike and typosquatting domains that could impersonate the organization for phishing | `dns_typosquatting_enabled` | None |
| `vip_executive_risk` | VIP Executive Risk Report | Exposure of executives and other high-value people: emails, breaches and personal data | `vip_enumeration` | `email_enumeration` (`true`), `vip_skip_email_guessing` (`false`) |
| `social_media_risk` | Social Media Risk Report | Fake profiles, brand impersonation, and fraudulent ads on social platforms | `social_media_enabled` | `social_media_ads_enabled` (`false`) |
| `application_security` | Application Security Report | Exposed admin panels, misconfigurations and confirmed vulnerabilities on live web services | `active_vuln_scan` | `perform_port_scan` (`true`) |
| `breach_risk` | Breach Risk Report | Breach likelihood and impact from employee emails and credentials in known leaks | `email_enumeration` | None |
| `infrastructure_risk` | Infrastructure Risk Report | Internet-facing hosts, open ports and the services an attacker can reach | None | `perform_port_scan` (`true`), `active_dns_enumeration` (`true`), `dns_posture_enabled` (`true`) |
| `exposed_assets_risk` | Exposed Assets Report | Code and secrets in public repositories, plus mentions on paste sites, open cloud storage and shortened URLs | `code_exposure_enabled`, `tg_discord_paste_search` | `paste_include_google_search` (`false`) |

Five rules apply:

* **Forced modules always run.** Sending `false` for one changes nothing.
* **Only the report's optional flags count.** The API drops every other flag you send, and every module outside the row stays off.
* **One report, no more.** The assessment generates the report in `report_type` and nothing else. It never generates the Full Attack Surface Report.
* **No data, no report.** The report is generated only when the assessment found data for it. A VIP Executive Risk Report needs executive or employee-email results, for example. Without them, no report is generated and the assessment keeps its unit. [Generating the report yourself](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md#generate-a-report) is then refused with `400`.
* **`asm_full` is not a targeted report.** Sending it returns `400` with `{"report_type": ["\"asm_full\" is not a valid choice."]}`. Use the full endpoint.

The Domain Spoofing Risk Report and the Application Security Report always make a heavy assessment. So does the Infrastructure Risk Report unless you send `"perform_port_scan": false`.

### Domain handling

Send the organization's registrable domain, such as `acme.com`. The engine reduces any host name to its registrable domain, so `www.acme.com` and `vpn.acme.com` both start an assessment of `acme.com`. You cannot assess a single subdomain. A value that is not a domain name, such as a URL or an IP address, returns `400` with `{"details": "Please enter a valid domain."}`.

At the start, the assessment checks whether the organization's email or infrastructure lives on other domains. `domain_mode` decides what it does with them:

| `domain_mode` | What the assessment covers |
| - | - |
| `default` | The submitted domain only. This is the default, and the dashboard's **Primary domain only**. |
| `swap_to_primary` | The detected domain instead of the submitted one, when the detected domain has a larger infrastructure footprint. `domain` then holds the new domain and `original_domain` the one you sent. |
| `dual_domain` | The submitted domain and one detected email domain, merged into one assessment. With several email domains, it picks the one with the highest estimated subdomain count. Discovery takes about twice as long. |
| `all` | Every organization domain the assessment can find and verify, such as email domains, related brands and service portals, largest first, up to a budget of 500 IP addresses. The dashboard's **All — discover all org domains**. Time grows with the number of domains. |

When no other domain is detected, `swap_to_primary` and `dual_domain` assess the submitted domain only, like `default`. A `dual_domain` start still counts as heavy. An `all` assessment that verifies no other domain still searches for domains on the same IP addresses, and still counts as heavy.

Even in `default` mode, the leaked-credential and employee-email checks also search the organization's detected email domains. Send `"breach_primary_domain_only": true` to limit them to the submitted domain, plus any domain `dual_domain` or `all` added. The Breach Risk Report always covers the submitted domain only.

### Active scope

Active checks connect to hosts: port and service detection, the active vulnerability check, and the TLS and web application checks. They reach only hosts in the active scope:

* **The submitted domain and its subdomains**, plus each domain in `active_scope_domains` and its subdomains.
* **Hosts and IP addresses named in an include rule.** See [Add a host the assessment missed](https://wiki.darknetsearch.com/api/guides/attack-surface-exclusions.md#add-a-host-the-assessment-missed).
* **Hosts in the organization's IP ranges** whose certificate or reverse DNS name proves they belong to one of the assessment's verified domains.

Two rules override the scope. An exclusion rule that matches a host, by host name, domain, IP address or IP range, blocks active checks on it, even under the submitted domain. A host on a private or other non-public IP address is never checked actively.

Hosts under any other domain, including the domains that `swap_to_primary`, `dual_domain` or `all` added, are assessed passively unless one of the rules above covers them.

To test other domains the organization owns, list them in `active_scope_domains`:

```json theme={"dark"}
{
  "domain": "acme.com",
  "domain_mode": "all",
  "active_scope_domains": ["acme-login.com"]
}
```

* Up to 5 domains. A sixth returns `400` with `{"active_scope_domains": ["At most 5 additional active-scope domains are accepted."]}`.
* Each entry is a domain name: it needs a dot and cannot contain `/`, `:`, a space or a leading `*`. A URL returns `400` naming the entry.
* Entries are lowercased, and duplicates count once. Each domain also covers its subdomains.

List only domains your organization owns or is authorized to have tested.

### Report options

These fields shape the report the assessment generates automatically. Set them at the start: they cannot be changed later. To get a different version, [generate another report](https://wiki.darknetsearch.com/api/guides/attack-surface-reports.md) from the completed assessment.

| Field | Default | What it does |
| - | - | - |
| `report_language` | `en` | Language of the report: `en`, `de`, `fr`, `it` or `es`. |
| `report_template_uid` | None: built-in branding | A report template from [Brand assessment reports](https://wiki.darknetsearch.com/api/guides/attack-surface-branding.md). |
| `report_baseline_scan_uid` | None: no comparison | The `uid` of a `Completed` assessment of the same domain to compare against, or `"auto"` for your most recently completed other assessment of that domain. With `"auto"` and no such assessment, the report has no comparison. |
| `report_privacy_gate` | Off | `true` checks the report's JSON, CSV and rendered pages for leftover secrets before they are stored. If a check finds one, the report fails instead of being stored. Off, the checks run but never block a report. Evidence is masked when it is collected either way. |

> [!WARNING]
>
> **The template and baseline are checked only when the report is built.** The start checks only that each value is a UUID, or `"auto"` for the baseline. If the template does not belong to your organization, or the baseline is not a `Completed` assessment of the same domain, no report is generated automatically. Generate one yourself once the assessment completes.

Translated reports cover the narrative, the finding explanations, chapter titles and table headers. Host names, IP addresses, URLs, CVE IDs, ports, product names, code and email addresses stay as found. A string that cannot be translated stays in English, and the report is still delivered.

#### Narrow breach and CVE findings

| Field | What it does |
| - | - |
| `breach_date_from`, `breach_date_to` | Dates in `YYYY-MM-DD`. They limit the list of breaches to those added to the leak database in that window. The leaked-credential rows are still collected for all time. `breach_date_to` must be on or after `breach_date_from`. |
| `known_service_versions` | Up to 200 entries for hosts you control, each `target:port:version` or `target:port:product:version`, for example `vpn.acme.com:443:2.4.57`. `target` is the IP address or host name as the assessment reports it, and `port` is 1 to 65535. CVEs found at that port are marked `verified` when the version confirms them, or `likely_false_positive` when it rules them out. Nothing is hidden. |

### Refusals at start

The API checks your plan and the rate limit first, then takes the allowance unit, then validates the body. The assessment engine runs its own checks last. A refusal never costs a unit: the first two checks run before the unit is taken, and every later refusal refunds it.

| Status | When | Body |
| - | - | - |
| `400` | A field is missing or invalid, such as no `domain`, an unknown `domain_mode`, `asm_full` as `report_type`, or a bad `known_service_versions` entry | Field errors, for example `{"domain": ["This field is required."]}` |
| `400` | `domain` is not a domain name | `{"details": "Please enter a valid domain."}` |
| `400` | Your organization already has 10 assessments `Running` or `Queued` | `details`, shown below |
| `400` | An assessment of the same domain started in the last 30 minutes already covers every module this request turns on | `details`, shown below |
| `403` | Your plan lacks the feature for this start, or your license is not in force | `{"detail": "This feature is not included in your plan."}` |
| `429` | The month's allowance is spent | `detail`, `resource`, `period` and `limit`. See [Availability and cost](https://wiki.darknetsearch.com/api/guides/attack-surface-overview#availability-and-cost). |
| `429` | The request is heavy, and other organizations already have the platform's maximum of heavy assessments running or queued (2) | `details` and `"code": "heavy_scan_capacity_full"`, shown below |
| `429` | The per-second rate limit or the monthly API Calls allowance is hit | `message` reads `Rate limit exceeded`, with `retry_after_seconds`. See [Rate limits](https://wiki.darknetsearch.com/api/guides/rate-limits.md). |
| `502` | The assessment engine is unavailable | `{"detail": "The requested service is temporarily unavailable."}` |
| `504` | The assessment engine did not answer in time | `{"detail": "The requested service timed out."}` |

The engine's three business refusals read:

```json theme={"dark"}
{"details": "This organisation already has 10 running/queued scan(s), which is the maximum allowed (10). Please wait for one to complete or check GET .../scans/{uid}/queue/ for position."}
```

```json theme={"dark"}
{"details": "An equivalent scan for this domain (same opt-in modules) was started within the last 30 minutes. Please wait before starting another, or request additional modules not already covered by the recent scan."}
```

```json theme={"dark"}
{"details": "Deep scan capacity is full (2 heavy scans running). Please try again shortly or use a lighter scan profile (quick/standard).", "code": "heavy_scan_capacity_full"}
```

How to clear each one:

* **10 open assessments.** Wait for one to finish. Your organization runs one assessment at a time and queues the rest. See [Read the queue](https://wiki.darknetsearch.com/api/guides/attack-surface-progress.md#read-the-queue).
* **Duplicate within 30 minutes.** The window counts from the earlier assessment's start, whatever its status. Only module flags and `domain_mode` count, so the same modules with another report language are refused too. A request that turns on at least one module the earlier assessment did not run is accepted. A full assessment with the defaults already covers the modules of the Domain Spoofing, VIP Executive, Breach and Infrastructure reports, so a targeted assessment of those types for the same domain, with its default flags, is refused for 30 minutes after it.
* **Heavy capacity.** Retry in a few minutes, or start a lighter assessment: turn off `perform_port_scan`, `active_vuln_scan` and `dns_typosquatting_enabled`, and use `default` or `swap_to_primary` as `domain_mode`. The API has no scan profiles. Switch the flags off instead.
* **Three kinds of `429`.** Branch on the body: `resource` means the allowance, `code` means heavy capacity, `message` means the rate limit.

> [!NOTE]
>
> **After a `504`, list your assessments before you retry.** The engine may have started the assessment after the API stopped waiting. The unit was refunded either way.

[Handle API errors](https://wiki.darknetsearch.com/api/guides/errors.md) covers every status in more detail.

### Endpoints

| Action | Endpoint |
| - | - |
| 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 a targeted assessment | [`POST /api/hackerview/scans/targeted/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/POST/api/hackerview/scans/targeted/) |
| Follow its 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/) |
| List assessments | [`GET /api/hackerview/scans/`](https://client-api.leak.center/scalar-docs/#tag/attack-surface/GET/api/hackerview/scans/) |


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