mirror of
https://github.com/laramies/theHarvester.git
synced 2026-09-13 05:07:40 +02:00
119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
# Troubleshooting
|
|
|
|
Start with the smallest failing command and one source. Provider availability, authentication, quotas, and response formats can change independently of theHarvester.
|
|
|
|
## Confirm the installation
|
|
|
|
```bash
|
|
uv run theHarvester -h
|
|
uv run python --version
|
|
```
|
|
|
|
For a packaged installation:
|
|
|
|
```bash
|
|
theHarvester -h
|
|
python3 --version
|
|
```
|
|
|
|
theHarvester requires Python 3.14. Source checkouts managed by `uv` select it from `.python-version`.
|
|
|
|
## Configuration file messages
|
|
|
|
On first use, messages saying that `api-keys.yaml` or `proxies.yaml` was created under `~/.theHarvester/` are expected.
|
|
|
|
If the wrong file is read, check the search order:
|
|
|
|
1. `~/.theHarvester/`
|
|
2. `/etc/theHarvester/`
|
|
3. `/usr/local/etc/theHarvester/`
|
|
|
|
The first existing file wins.
|
|
|
|
## Missing API key
|
|
|
|
Check the [README source matrix](https://github.com/laramies/theHarvester/blob/dev/README.md#discovery-sources). Configure credentials for that provider or choose a keyless source. `-q` suppresses missing-key notices; it does not make keyed providers work without credentials.
|
|
|
|
## A provider fails, times out, or returns no results
|
|
|
|
Rerun one source with a small limit and save its summary:
|
|
|
|
Network activity: provider-facing lookup plus local report writes.
|
|
|
|
```bash
|
|
uv run theHarvester -d example.com -b source-name -l 10 -f diagnostic
|
|
jq -c 'select(.type == "summary") | {evidence_status, source_executions}' diagnostic.jsonl
|
|
```
|
|
|
|
Read the source outcome before treating an empty result as a failure. A completed `no-results` outcome means the provider conversation finished normally. A `partial`, `failed`, or `rate-limited` outcome names a separate coverage problem.
|
|
|
|
If the source did not complete normally, check:
|
|
|
|
- provider status and current API documentation;
|
|
- credential validity and subscription access;
|
|
- provider rate limits or temporary blocking of shared CI/cloud addresses;
|
|
- whether the provider documents the target or query type as supported.
|
|
|
|
Do not post credentials, private targets, account details, or raw provider responses in a public issue.
|
|
|
|
## DNS resolution
|
|
|
|
`-r` accepts no value, a resolver IP, comma-separated resolver IPs, or a resolver file you create with one IP per line:
|
|
|
|
```bash
|
|
AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
|
|
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -b crtsh -r resolvers.txt
|
|
```
|
|
|
|
If theHarvester reports invalid resolvers, remove hostnames, comments, blank values, or `host:port` entries; the resolver list accepts IP addresses only. Check local firewall and DNS policy before substituting public resolvers.
|
|
|
|
The input is accepted when the invalid-resolver message is gone. A valid resolver list does not guarantee that a name has DNS records.
|
|
|
|
## Screenshots and Chromium
|
|
|
|
Install the browser used by Playwright:
|
|
|
|
```bash
|
|
uv run playwright install chromium
|
|
```
|
|
|
|
If Chromium reports missing Linux libraries, install the host dependencies recommended by Playwright. Confirm the target is authorized before retrying; screenshots open discovered web services directly.
|
|
|
|
## REST API
|
|
|
|
Start with:
|
|
|
|
```bash
|
|
uv run harvestview --log-level debug
|
|
```
|
|
|
|
Then open [http://127.0.0.1:5000/docs](http://127.0.0.1:5000/docs).
|
|
|
|
- `401` on `/api/v1/*`: the `X-API-Key` header or HarvestView browser session does not match.
|
|
- `503` on `/api/v1/*`: `THEHARVESTER_API_KEY` was not configured before startup.
|
|
- `429`: a reverse proxy or remote provider applied its own rate limit. `harvestview` has no built-in request limiter.
|
|
- `503` when creating a run: the execution worker is disabled or unavailable.
|
|
|
|
After correcting the cause, retry `GET /api/v1/sources`. A successful authenticated response returns the source catalog.
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
docker compose ps
|
|
docker compose logs theharvester.svc.local
|
|
```
|
|
|
|
The container runs HarvestView and the REST API on container port `8000`, published only as `127.0.0.1:5000` by the supplied Compose file. If startup reports a missing secret, create `.secrets/operator-api-key` as shown in the installation guide.
|
|
|
|
## File an actionable issue
|
|
|
|
Include:
|
|
|
|
- the smallest sanitized reproduction;
|
|
- expected and actual behavior;
|
|
- operating system, installation method, Python version, and theHarvester version or commit;
|
|
- the exact source and options used;
|
|
- only the output needed to diagnose the problem.
|
|
|
|
Use the repository [issue forms](https://github.com/laramies/theHarvester/issues/new/choose). Follow [SECURITY.md](https://github.com/laramies/theHarvester/blob/dev/SECURITY.md) for suspected vulnerabilities.
|