Scanning Runbook

This runbook describes how operators should launch and schedule scans in the current hxEASM product. It documents the implemented behavior, not future scan orchestration ideas.

For lower-level reference, see Scan Profiles, Asset Observed State, and Plugin Development.

Scanning Model

The normal scanning flow is:

approved Scope
-> Scan Profile
-> ordered plugins
-> discovered Assets
-> scanner-owned observed state in metadata.asset_info
-> Asset Scan History
-> Threats where vulnerability plugins emit findings

Scope is the customer-approved starting input. A Scan Profile is an ordered pipeline of independently runnable plugins. Plugins do not call each other directly and must remain usable in arbitrary valid profiles.

During profile execution, the worker runs plugins in profile order. When a plugin succeeds, normalized Assets from that plugin are added to the running scan scope, so later plugins in the same scan may consume them. This is why profiles such as recon_expanded can start from root domains and later probe discovered subdomains, WebApps, and certificates.

Most profiles start from the selected Scope IDs plus Assets discovered earlier in that same scan. They do not automatically scan every previously discovered Asset in the organization.

vuln_scan is the current exception. Before running httpx -> nuclei, the worker augments its initial scope with existing WebApp, Subdomain, Domain, and IP Assets for the organization. This makes vuln_scan the preferred recurring vulnerability profile.

Threats are created when vulnerability plugins such as Nuclei emit vulnerability entities. Scanner-observed Asset state is stored separately in metadata.asset_info and produces Asset Scan History.

Scope Types

Common scan starting Scope types are:

Scope type	Operational meaning
domain	Root domain discovery input, for example example.com.
ip	Single IP target.
ip_range	IPv4 range stored as one Scope entry, expanded at scan runtime.
cidr	CIDR scope passed separately to plugins that accept CIDR.

IP Range Expansion

ip_range remains stored as one Scope record:

type = ip_range
value = 10.0.0.1-10.0.0.3

At scan runtime, the worker expands the range into normal ip ScopeItems:

ip:10.0.0.1
ip:10.0.0.2
ip:10.0.0.3

This expansion is runtime-only:

• plugins receive ordinary ip targets;
• plugins do not need to understand ip_range syntax;
• no IP Assets are created merely because an IP is a member of the range;
• overlapping ranges and explicit IP scopes are deduplicated;
• malformed ranges fail the scan clearly;
• oversized ranges fail instead of being truncated.

Current limits are:

• 65,536 IPs per individual ip_range Scope;
• 65,536 unique expanded IP range targets per scan.

CIDR behavior is separate and unchanged. CIDR scopes are not expanded by this mechanism.

Built-In Scan Profiles

The built-in profiles are configured in backend/configs/config.yaml.

Profile	Plugin chain	Purpose	Recommended starting target	Relative load	Typical use
quick	subfinder -> dnsx -> httpx	Fast discovery and freshness check.	Root domains.	Low to moderate.	Daily domain/DNS/Web freshness.
default	subfinder -> dnsx -> httpx -> naabu -> nuclei	Balanced scan with discovery, port discovery, and Nuclei.	Domains or IPs.	Moderate to high.	One-off baseline, but overlaps other profiles.
deep	subfinder -> amass -> dnsx -> naabu -> nmap -> httpx -> tlsx -> katana -> nuclei	Maximum visibility.	Explicitly approved domains/ranges.	High.	Manual investigation or off-hours broad assessment.
stealth	subfinder -> amass -> httpx	Low-noise reconnaissance.	Root domains.	Moderate; Amass can run long.	Optional domain reconnaissance.
recon_nmap	subfinder -> dnsx -> nmap	Reconnaissance with Nmap service validation.	Domains or IPs.	Moderate to high.	Usually superseded by port_discovery for network discovery.
tls_audit	subfinder -> dnsx -> httpx -> tlsx	Certificate and TLS inventory.	Root domains.	Moderate.	Weekly certificate/TLS refresh.
web_discovery	subfinder -> dnsx -> httpx -> katana -> nuclei	Web discovery, crawling, and initial web vulnerability scan.	Domains and appropriate IP scopes.	High.	Initial web/vulnerability baseline or periodic crawl.
port_discovery	subfinder -> dnsx -> naabu -> nmap	Network service mapping.	IP ranges, IPs, domains.	Moderate to high.	Initial and recurring IP range service discovery.
vuln_scan	httpx -> nuclei	Recurring vulnerability validation.	Approved scope; also uses existing discovered assets.	Moderate to high.	Weekly vulnerability refresh.
recon_expanded	subfinder -> amass -> dnsx -> httpx -> tlsx	Strong non-vulnerability discovery.	Root domains.	Moderate to high.	Initial domain baseline and periodic expanded recon.
screenshot	subfinder -> dnsx -> httpx -> httpx_screenshot	Web screenshot collection.	Domains or known Web targets.	Moderate.	Optional visual inventory and demo evidence.

Domain Scanning Flow

Recommended domain baseline:

root domains
-> recon_expanded

Current recon_expanded chain:

subfinder
-> amass
-> dnsx
-> httpx
-> tlsx

This establishes a broad non-vulnerability baseline:

• Subfinder and Amass discover subdomains from root domains.
• DNSX resolves domains/subdomains and records DNS state.
• HTTPX probes HTTP services and creates/enriches WebApp Assets.
• TLSX observes certificates and TLS endpoint state.

This can populate:

• Domain/Subdomain DNS records: A, AAAA, CNAME, NS, MX;
• resolved IP Assets from A/AAAA records;
• WebApp Assets;
• HTTP status, server, selected security headers, CSP, safe cookie flags, technologies, favicon hash, and page fuzzy hash where HTTPX reports them;
• Certificate Assets and certificate observed state;
• Service TLS observed version when TLSX reports an IP and port.

Do not expect WHOIS/RDAP or ASN enrichment from this profile. Those are not production-backed in the current implementation.

IP Range Scanning Flow

Recommended IP range baseline:

ip_range
-> runtime IP expansion
-> port_discovery

Current port_discovery chain:

subfinder
-> dnsx
-> naabu
-> nmap

For IP range targets, the practical flow is:

stored ip_range
-> expanded ip ScopeItems
-> DNSX PTR where available
-> Naabu open service discovery
-> Nmap service and OS fingerprinting

This is the preferred existing profile for initial network/service discovery from approved IPv4 ranges. It can populate:

• IP PTR state where DNSX returns PTR records;
• Service Assets from Naabu and Nmap;
• service state and transport from Naabu;
• IP OS fields from Nmap where available;
• service name, product, version, state, and transport from Nmap.

Range expansion does not create IP Assets by itself. IP Assets are created only when scanner output observes them.

Web and Vulnerability Baseline

Use web_discovery as the initial Web/vulnerability pass after basic domain and network baselines.

Current chain:

subfinder
-> dnsx
-> httpx
-> katana
-> nuclei

This profile is useful because it adds:

• WebApp discovery and enrichment through HTTPX;
• Web paths through Katana;
• initial standard Nuclei findings.

It overlaps with lighter discovery and vulnerability profiles. Do not schedule it very frequently by default unless the customer expects regular crawling and vulnerability load.

Recurring Vulnerability Scanning

Use vuln_scan for recurring vulnerability refresh.

Current chain:

httpx
-> nuclei

vuln_scan has special current behavior: before plugin execution, the worker augments the selected scope with existing WebApp, Subdomain, Domain, and IP Assets for the organization. This lets Nuclei cover previously discovered assets without requiring an operator to manually select every discovered Asset.

Nuclei is allowed to be long-running. hxEASM no longer applies the old 600-second whole-process wall-clock timeout to Nuclei. Scanner-native request-level timeouts, retries, rate limits, and concurrency remain separate and should not be confused with total process duration.

Do not treat that as permission to run Nuclei aggressively by default. For a pilot, weekly vulnerability scanning is a more conservative starting point than daily scanning.

First Customer Baseline

For a first pilot customer with several approved root domains and one or more approved IPv4 ranges:

Step 1

Target: : Root domain scopes

Profile: : recon_expanded

Purpose: : Establish the domain, DNS, WebApp, and TLS/certificate baseline.

Step 2

Target: : IP range scopes

Profile: : port_discovery

Purpose: : Establish the IP, service, and OS baseline from approved network ranges.

Step 3

Target: : Approved domain and IP range scopes

Profile: : web_discovery

Purpose: : Establish Web paths and initial Nuclei vulnerability baseline.

Step 4 - Optional

Target: : Approved domain and Web-relevant scopes

Profile: : screenshot

Purpose: : Collect visual inventory and demo evidence.

Do not automatically run deep across the entire customer perimeter during onboarding by default. Use it only with explicit operator/customer approval and preferably off-hours.

Recommended Pilot Schedule

Stagger weekly jobs instead of launching all of them at the same time.

Frequency	Profile	Target	Purpose
Daily	quick	Root domains	Domain, DNS, and Web freshness.
Weekly	port_discovery	IP ranges	Network/service refresh.
Weekly	vuln_scan	Approved scope plus existing discovered assets according to current implementation	Vulnerability refresh.
Weekly	tls_audit	Root domains	Certificate/TLS refresh.
Initial or on-demand	web_discovery	Domains and appropriate IP scope	Crawl/path discovery and Nuclei baseline.
Manual/on-demand	deep	Explicitly selected approved scope	Deeper investigation.

Do not schedule daily Nuclei by default during a first pilot.

Why Domains and IP Ranges Use Different Flows

Domains are discovery roots. They are best for:

domain
-> subdomains
-> DNS
-> IPs
-> WebApps
-> certificates

IP ranges are network discovery roots. They are best for:

range
-> IP targets
-> ports
-> Services
-> service fingerprints
-> OS where available

Because the starting intent is different, domains and IP ranges should not automatically use identical profiles or schedules.

Asset Scan History

Recurring scans are important not only for discovering new Assets, but also for detecting changes in already known Assets. Scanner-owned observed state is written to metadata.asset_info; scan snapshots and field-level scan changes are generated from those observations.

Current production-backed sources include:

Plugin	Asset Scan History fields
DNSX	A, AAAA, CNAME, NS, MX on Domain/Subdomain assets; PTR on IP assets.
Nmap	IP OS fields; service name, product, version, state, transport.
Naabu	Service state and transport.
HTTPX	HTTP status, server, selected security headers, CSP, safe cookie flags, technologies, favicon hash, page fuzzy hash.
Katana	WebApp paths.
TLSX	Certificate fingerprint, serial, subject/issuer fields, SANs, validity, expired flag, and observed TLS version on Service assets where available.

Asset Scan History is separate from System Changes and Exposure Changes. See Asset Observed State for the storage model.

Profile Overlap

Avoid blindly scheduling every profile.

• quick overlaps with many larger profiles.
• default overlaps with quick, network discovery, and Nuclei.
• deep overlaps with most other profiles.
• web_discovery overlaps lighter discovery and vulnerability scanning.
• recon_expanded overlaps tls_audit.

For a pilot, prefer the smallest useful set:

• quick daily on domains;
• port_discovery weekly on IP ranges;
• vuln_scan weekly;
• tls_audit weekly if certificate/TLS history matters;
• web_discovery initially or on demand.

Expensive or Active Scans

Schedule these conservatively and only within customer-approved scope:

• Nuclei;
• Nmap;
• Naabu;
• Katana;
• Amass;
• Nmap vulnerability scripts if manually used in a custom profile.

Broad IP range scans, crawling, vulnerability scanning, and deep scans can generate significant traffic or run for a long time.

Deep Profile

deep currently runs:

subfinder
-> amass
-> dnsx
-> naabu
-> nmap
-> httpx
-> tlsx
-> katana
-> nuclei

Treat it as a broad/heavy profile. Recommended operational use:

• manual investigation;
• explicitly approved broad assessment;
• optionally monthly/off-hours after the pilot team understands normal runtime and customer tolerance.

Do not make deep part of the default daily or weekly first-pilot schedule.

Current Limitations

Current relevant limitations:

• WHOIS/RDAP is not production-backed.
• ASN enrichment is not production-backed.
• TLS supported-version enumeration is not production-backed.
• Nmap vulnerability scripts are registered as nmap_vulns, but they are not included in built-in profiles.
• Custom Nuclei templates are registered as nuclei_custom_templates, but they are not included in built-in profiles.
• Most profiles start from selected Scope IDs and same-scan discoveries.
• vuln_scan has special existing-Asset augmentation behavior.

Do not describe unsupported enrichment or custom profile behavior to customers as if it were part of the default scanning lifecycle.

Operational Quick Reference

First Run

Target	Profile
Domains	recon_expanded
IP ranges	port_discovery
Domains/IP ranges	web_discovery once

Continuous

Target	Profile	Frequency
Domains	quick	Daily
IP ranges	port_discovery	Weekly
Vulnerabilities	vuln_scan	Weekly
TLS/certificates	tls_audit	Weekly

On Demand

Profile	Use
deep	Deeper approved investigation.
screenshot	Visual inventory or demo evidence.
web_discovery	Crawl/path discovery and Web vulnerability refresh.