Understanding Z-Sans's asset model, breeding process, and topology is the foundation for mastering tool usage and extension.

1. Asset¶

Everything scanned is an asset. Z-Sans defines a set of asset types:

Core Asset Fields¶

Each asset (Asset object) contains:

• uid: Unique identifier with the format type:value, e.g., domain:example.com
• type: The asset type
• value: The normalized asset value
• source: The source; manually provided seeds are manual
• depth: Discovery depth (seeds are at 0)
• state: The state machine state

Asset State Machine¶

flowchart LR
    new["new (pending)"]
    scanning["scanning (breeding in progress)"]
    scanned["scanned (processing complete)"]
    failed["failed (processing error)"]
    excluded["excluded"]
    eliminated["eliminated (no breeding value)"]

    new --> scanning
    scanning --> scanned
    scanning -->|processing failed| failed
    scanning -->|depth exceeded / type disabled / resource limit / exclusion match| excluded
    scanning -->|breeder judges no value| eliminated

• new: newly created and pending
• scanning: currently being processed by a breeder
• scanned: processing complete
• excluded: excluded (depth exceeded, type disabled, resource limit reached, or exclusion rule matched)
• eliminated: eliminated (the breeder judged the asset to have no breeding value)
• failed: processing error

2. Breeding Engine¶

The engine (BreedingEngine) is the task controller; its lifecycle is:

flowchart LR
    start["start"]
    loop["concurrent breeding loop"]
    completed["completed"]
    stop["stop"]

    start --> loop --> completed --> stop

Main flow:

1. add_seed(type, value): Adds a seed asset to the asset graph and the priority queue
2. run(): start() → start the thread pool → _concurrent_breed()
3. Each round takes one asset from the queue and runs the _process_asset() processing pipeline
4. Queue empty → completed → stop() (save checkpoint, produce report)

The _process_asset() Processing Pipeline¶

For each asset, the following steps run in order (order matters):

1. Depth check: exceeding max_depth → excluded
2. Type switch: type enabled=false → excluded
3. Resource limits: exceeding resource_limits or the type's depth_limit → excluded
4. Exclusion rules: matching exclusions (domain suffix / exact IP / URL keyword / port / regex) → excluded
5. Get breeder: BreederFactory.get_breeder(type); no matching breeder → excluded
6. Execute breeding: breeder.execute(asset, tool_orchestrator) produces a batch of new assets
7. Add new assets to the graph: add_asset one by one → add_edge(discovered) → enqueue → trigger on_asset_discovered event
8. Trigger on_asset_scanned; on exception set state=failed and trigger on_asset_failed

3. Breeder¶

A breeder determines "what related assets a given asset can discover". In core/breeders/breeders.py, the factory BreederFactory dispatches by type.

4. Priority Queue¶

PriorityBreedingQueue determines "who is processed next". The strategy is decided by the config strategy:

The queue supports deduplication: assets already enqueued or in scanned/eliminated/excluded state will not be enqueued again.

5. Asset Graph¶

AssetGraph is a thread-safe topology store made up of nodes (assets) and edges (relations).

Relation Types (3)¶

Graph Export¶

• JSON: export_json(metadata) → complete nodes and edges with metadata (schema_version, version, stats, seeds, config_hash)
• GraphML: export_graphml() → directed graph XML; nodes carry attributes such as type/value/depth/state/fingerprints

Statistics¶

stats() returns: total asset count, total relation count, and asset type distribution. Both the HTML report and the Web console are based on this data.

6. Seed Asset Expansion Logic¶

add_seed() expands seeds:

7. Concurrency Model¶

• The engine uses ThreadPoolExecutor(max_workers=concurrency.max_tasks) (default 20)
• Each tool also has its own concurrency limit (concurrency.tools.subfinder, etc.)
• Asset states and graph data are protected by locks and safe to access concurrently
• Event hooks may be invoked in a concurrent context; handlers must ensure their own thread safety

References¶

• Asset model implementation: core/zsans_engine.py
• Breeder implementation: core/breeders/breeders.py
• Tool orchestration: core/tools/tools.py
• Engine controller: the BreedingEngine class in main.py