Common Questions¶

1. Can it run without configuring subfinder / naabu?¶

Yes. The ToolOrchestrator probes for external tools and falls back to built-in implementations when they are not found (dnsxs.py DNS resolution, port.py TCP scanning, built-in JS extraction). Scans will not be interrupted by missing tools; discovery capability is merely somewhat weaker.

2. The scan is slow / there are too many assets. What should I do?¶

• Lower the depth: --depth 2
• Reduce concurrency: concurrency.max_tasks (default 20)
• Tighten resource limits: resource_limits.max_*
• Filter out static resources with exclusion rules: exclusions.patterns
• Some large enterprise asset inventories have many assets, which naturally takes longer to breed. This is expected behavior.

3. The scan was interrupted. Can I continue?¶

Yes. By default a checkpoint is saved every 50 processed assets; use --resume to restore:

python main.py --resume

Resume only replays assets in the new / failed / scanning states. See Resume for details.

4. The scan reports No seed assets provided¶

You must provide at least one seed (-d or -u), unless you use --resume and the checkpoint contains nodes.

5. Why do some assets show as excluded?¶

It may match any of the following rules:

• Exceeds max_depth / the type's depth_limit
• The type is disabled in the configuration
• Exceeds resource_limits limits
• Matches an exclusions exclusion rule
• No corresponding breeder for that type

6. Why do URLs appear garbled in the report?¶

During URL normalization, the scheme and domain are lowercased, but the path preserves case (paths are case-sensitive). This is intentional.

7. How do I change the language?¶

language:
  default_language: zh_CN   # or en

The setting lives in breeding-config.yaml. Both the reports and the Web console follow this configuration.

8. Requests to self-signed HTTPS sites fail?¶

http:
  verify_ssl: false   # false by default; skips certificate validation to support self-signed sites

9. Want to use a proxy?¶

http:
  proxy: http://127.0.0.1:7890

The proxy is automatically disabled after 3 consecutive failures (to prevent a dead proxy from dragging down the scan).

10. pip install -r requirements.txt reports externally-managed-environment?¶

Systems like Ubuntu enable PEP 668. Use a virtual environment:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Logging & Debugging¶

Viewing Detailed Logs¶

python main.py -d example.com -v

-v sets the log level to DEBUG; both the console and zsans.log output detailed progress.

Log File¶

After the main program starts, it writes to the root-level zsans.log (UTF-8, DEBUG level):

2026-08-13 00:00:14,016 - zsans.i18n - INFO - Successfully set up i18n with language en

Logger Names¶

• zsans.main — CLI / engine main controller
• zsans.engine — engine scheduling
• zsans.i18n — internationalization

If colorlog is installed, console logs are colored by level (DEBUG=cyan, INFO=green, WARNING=yellow, ERROR=red, CRITICAL=bold red).

Web Console Authentication¶

The console asks for a password — why?¶

The environment variable ZSANS_WEB_PASSWORD is set, so all endpoints require authorization. Log in with that password in the browser (you get a 24-hour session cookie), or call the API with Authorization: Bearer <password> / X-API-Key: <password> headers.

How do I disable authentication again?¶

Unset ZSANS_WEB_PASSWORD when starting the console. Only run it unauthenticated on a trusted localhost/LAN.

Port in Use¶

When the default --web port 8050 is occupied:

python main.py --web --port 9000

You can also specify a different port with --port.

Checkpoint Issues¶

Where is the checkpoint file?¶

By default <output_dir>/checkpoint.json; it can be overridden with checkpoint.file.

The checkpoint is corrupted?¶

Checkpoints are written atomically, so they should not be half-corrupted under normal circumstances. If one is truly corrupted, delete or rename the file and run a fresh full scan.