theHarvester/docs/wiki/Operator-Workflows.md

# Operator workflows

Start with the smallest source set and least active behavior that can answer the engagement question. Replace `example.com` only with an authorized target.

Sources and explicit actions contribute different result routes and different levels of network activity. This map shows how they meet in one normalized evidence model:

![theHarvester discovery routes and enrichment](https://raw.githubusercontent.com/laramies/theHarvester/dev/docs/images/run-evidence-architecture.svg)

## Passive subdomain discovery

Network activity: provider-facing passive lookups.

```bash
uv run theHarvester -d example.com -b crtsh,certspotter,commoncrawl
```

Use the [README source matrix](https://github.com/laramies/theHarvester/blob/dev/README.md#discovery-sources) to choose complementary sources. Adding every source usually increases noise, rate-limit failures, and runtime more than it improves a focused run.

Pass `--limit 0` to remove the shared per-source result cap and local page ceilings. Each adapter continues until its provider is exhausted. Provider quotas, protocol maxima, response-size guards, and runtime limits still apply. If one stops collection after the source retained evidence, the run keeps that evidence and records the source as partial with the stop reason.

## Save results for automation

Network activity: provider-facing discovery plus local report writes.

```bash
uv run theHarvester -d example.com -b crtsh,certspotter -f report
```

Use `report.jsonl` for automation, provenance, and run interchange. The same command also writes `report.json` and `report.xml` compatibility files. See [Results and Local Data](Results-and-Local-Data).

## DNS resolution

Network activity: provider-facing discovery followed by resolver-facing DNS queries.

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -b crtsh,certspotter -r
```

To control the resolvers used, create a resolver file with one IP address per line and pass its path:

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -b crtsh -r resolvers.txt
```

DNS requests disclose candidate names to each selected resolver. Candidates from all selected sources are normalized and deduplicated before one run-wide phase queries A, AAAA, and CNAME at most once per hostname and record type. The phase runs at most 20 hostname jobs concurrently with per-query resolver timeouts and no default query-count or phase-runtime ceiling.

## Reverse DNS

Network activity: provider-facing discovery followed by resolver-facing PTR queries.

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester \
  -d "$AUTHORIZED_DOMAIN" \
  -b rapiddns \
  --dns-lookup \
  -f report
```

Reverse DNS uses the `/24` network containing each discovered IPv4 address. It deduplicates addresses across overlapping ranges and runs at most 20 PTR jobs concurrently with per-query resolver timeouts. It has no default request-count or phase-runtime ceiling.

## Shodan enrichment

Configure the Shodan key, then enrich resolved hosts:

Network activity: provider-facing discovery, resolver-facing DNS, and Shodan API requests.

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -b crtsh -r -s
```

Shodan host enrichment runs after discovery and is separate from the `shodan` source's subdomain results.

## DNS brute force

Use only an owned or explicitly authorized target:

Network activity: resolver-facing DNS queries for generated candidate names.

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -c
```

DNS brute force actively tests candidate names. Do not run it against `example.com` or an unrelated third-party domain.

## Recursive DNS

Network activity: provider-facing discovery followed by resolver-facing DNS queries for descendant names.

Create `resolvers.txt` with exactly three distinct resolver IP addresses. Then set a depth and save the structured evidence:

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester \
  -d "$AUTHORIZED_DOMAIN" \
  -b crtsh \
  --dns-resolvers resolvers.txt \
  --dns-recursive-depth 1 \
  -f report
```

Recursive DNS uses source results as seed names. Set the depth explicitly; query and runtime caps still apply. JSONL keeps the discovered hostnames and addresses along with recursive finding, classification, and summary records.

## Takeover checks

Network activity: provider-facing discovery followed by target-facing checks.

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -b crtsh,certspotter -t
```

Treat matches as leads requiring manual confirmation. Do not claim a takeover from a fingerprint match alone.

## RouteViews pivots

Network activity: provider-facing RouteViews requests.

Set an ASN that is part of the authorized assessment scope:

```bash
AUTHORIZED_ASN='replace-with-an-authorized-asn'
uv run theHarvester -d "$AUTHORIZED_ASN" --routeviews -f report
```

The target may also be an authorized IP or CIDR. The action writes external routing relationships and RPKI observations to `report.jsonl`. These records can guide analysis, but they do not establish ownership, authorization, or reachability. RouteViews is never enabled by `-b all`; see [Responsible Use and Scope](Responsible-Use-and-Scope#routeviews) for its fixed limits.

## Virtual host discovery

Network activity: provider-facing discovery followed by target-facing requests to harvested IP endpoints.

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -b rapiddns --vhost -f report
```

The action keeps only confirmed hostnames and records endpoint observations in JSONL. Read [Virtual Host Discovery](Virtual-Host-Discovery) before changing its endpoint, candidate, request, runtime, or TLS controls.

## Screenshots

Install Chromium first, then choose an output directory:

Network activity: provider-facing discovery, resolver-facing DNS, and target-facing browser requests.

```bash
uv run playwright install chromium
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -b crtsh -r --screenshot screenshots
```

Screenshots actively open discovered web services and may retain sensitive page content.

## API-path scanning

Network activity: target-facing HTTP requests.

```bash
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -a
```

Provide a custom path wordlist with `-w FILE`. This sends requests directly to the target and must be explicitly in scope.

## Diagnose one provider

When a combined run fails, rerun only the affected source with a conservative result limit:

Network activity: provider-facing lookup to the named source.

```bash
uv run theHarvester -d example.com -b source-name -l 10
```

Check the provider's current status, authentication requirements, rate limits, and terms before reporting a tool defect.