Quick Start

上一页 下一页

This guide walks you through using Z-Sans from scratch: setting up the environment, running your first scan, and understanding the output.

Requirements

  • Python 3.9+
  • Supported operating systems: Windows, Linux, macOS

Optional Dependencies

Some tools are optional external binaries; when they are missing, the engine falls back to its built-in implementations:

Tool Purpose When missing
subfinder Subdomain discovery Falls back to built-in DNS resolution + free passive sources
naabu Port scanning Falls back to the built-in port.py TCP scanner
EHole Web fingerprinting Uses the built-in multi-architecture binary, or title-only extraction
WhatWeb Web fingerprinting Falls back to EHole or title-only extraction
JSfinder JS / link extraction Falls back to the built-in requests + BeautifulSoup extractor
What does 'fallback' mean?

Z-Sans's ToolOrchestrator probes tools in order: configured path → tools directory → system PATH. When a tool cannot be found, it uses a pure PHP or pure Python internal implementation, ensuring scans are never interrupted by a missing binary.

Installation

git clone https://github.com/sansjtw1/Z-Sans.git
cd Z-Sans

# A virtual environment is recommended
python -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate

pip install -r requirements.txt

Verify the installation:

python main.py --version
External Tools

requirements.txt only contains Python dependencies. To use tools such as subfinder and naabu, you need to install / configure their paths separately. It works out of the box on the first run without any configuration (using built-in implementations).

First Scan

Domain Seed

python main.py -d example.com

URL Seed

python main.py -u https://example.com

Specify an Output Directory

python main.py -d example.com -o my-output

Increase Scan Depth

The default is 4 levels; a greater depth discovers more assets but takes longer:

python main.py -d example.com --depth 6

Recommendations for Resource-Constrained Environments

python main.py -d example.com --depth 2   # quick verification

Understanding the Output

After a run finishes, a timestamped directory is created under output/:

flowchart TD
    out["output/"]
    ts["20260812_231800/<br/>Scan timestamp (YYYYMMDD_HHMMSS)"]
    json["zsans_20260812_231800.json<br/>Full asset graph JSON"]
    csv1["zsans_20260812_231800_assets.csv<br/>Asset table"]
    csv2["zsans_20260812_231800_relations.csv<br/>Relations table"]
    graphml["zsans_20260812_231800.graphml<br/>GraphML topology"]
    html["zsans_20260812_231800_report.html<br/>Interactive HTML report (recommended)"]

    out --> ts
    ts --> json & csv1 & csv2 & graphml & html

Open the HTML report to see tabs for overview statistics, a force-directed topology graph, active assets, excluded assets, and execution metrics.

See Output & Reports for detailed documentation.

Next Steps

Home Core Concepts