# saltx5/farsight architecture

> Architecture diagram of the GitHub repository saltx5/farsight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saltx5/farsight
- Repository: https://github.com/saltx5/farsight

## Overview

##### Project type and purpose
- This is a Python‐based, CLI‐first reconnaissance and threat intelligence framework (“FARSIGHT”).
- It is an open‐source security tool that performs domain discovery, DNS and port enumeration, threat intelligence gathering, typosquatting detection, news monitoring, and report generation.

##### File structure
- Top level:
- README, LICENSE, .gitignore, docs/, pyproject.toml, requirements*.txt
- farsight/ (main package)
- cli/ – CLI interface built with Typer (scan command)
- modules/ – core scanning and analysis modules (org_discovery, recon, threat_intel, typosquat, news, report_writer)
- utils/ – shared utilities (api_handler, common helpers, dns, subdomain enumeration)
- config.py – configuration loader and environment variable handling
- main.py – entry point for `python -m farsight`

##### README for additional insights
- Async‐first, modular design with fallback for API outages
- Pure Python, no external binary dependencies (optional integrations)
- Core dependencies: aiohttp, dnspython, python‐whois, BeautifulSoup, Typer, optional dnstwist, markdown/weasyprint for PDF, gnews

##### Elements
- Clear labels for each layer and component (CLI, Orchestrator, Modules, Utilities, External Services, Outputs)
- CLI → Orchestrator → Modules → Utils/API → External Services
- Modules → Report Writer → Output file
- use a consistent palette (e.g., blue for code, green for utils, gray for external, yellow for outputs)

##### Detailed capture of essential architectural elements
- Config loader feeding into CLI and modules
- Fallback behavior in API handler (primary vs fallback service)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI["CLI (scan)"]:::code
    end
    subgraph "Configuration Layer"
        CFG["Config Loader"]:::code
    end
    subgraph "Orchestrator Layer"
        ORCH["Workflow Orchestrator<br/>(async parallel)"]:::code
    end
    subgraph "Core Modules"
        OD["Org Discovery"]:::code
        RE["Recon / Asset Discovery"]:::code
        TI["Threat Intelligence"]:::code
        TY["Typosquatting Detection"]:::code
        NM["News Monitoring"]:::code
        RP["Report Generation"]:::code
    end
    subgraph "Utility Layer"
        API["API Handler"]:::utils
        DNS["DNS Operations"]:::utils
        COM["Common Helpers"]:::utils
        SUB["Subdomain Enumeration"]:::utils
    end
    subgraph "External Services"
        WHOIS[(WHOIS Services)]:::external
        CT[(Certificate Transparency Logs)]:::external
        DNSR[(DNS Resolvers)]:::external
        SHODAN[(Shodan / Censys / SecurityTrails / VirusTotal / LeakPeek)]:::external
        NEWSAPI[(News APIs)]:::external
        PASSIVE[(Passive DNS Sources)]:::external
    end
    subgraph "Outputs"
        MD["Markdown Reports"]:::output
        PDF["PDF Reports"]:::output
        LOG["Logs"]:::output
    end

    CLI --> CFG
    CLI --> ORCH
    CFG --> ORCH

    ORCH --> OD
    ORCH --> RE
    ORCH --> TI
    ORCH --> TY
    ORCH --> NM
    ORCH --> RP

    OD --> API
    RE --> API
    TI --> API
    NM --> API
    TY --> DNS
    OD --> SUB
    RE --> SUB
    SUB --> DNS

    API --> WHOIS
    API --> SHODAN
    API --> NEWSAPI
    API --> PASSIVE
    DNS --> DNSR
    API --> CT

    RP --> MD
    RP --> PDF
    RP --> LOG

    %% Click Events
    click CLI "https://github.com/saltx5/farsight/blob/main/farsight/cli/scan.py"
    click ORCH "https://github.com/saltx5/farsight/blob/main/farsight/main.py"
    click CFG "https://github.com/saltx5/farsight/blob/main/farsight/config.py"
    click OD "https://github.com/saltx5/farsight/blob/main/farsight/modules/org_discovery.py"
    click RE "https://github.com/saltx5/farsight/blob/main/farsight/modules/recon.py"
    click TI "https://github.com/saltx5/farsight/blob/main/farsight/modules/threat_intel.py"
    click TY "https://github.com/saltx5/farsight/blob/main/farsight/modules/typosquat.py"
    click NM "https://github.com/saltx5/farsight/blob/main/farsight/modules/news.py"
    click RP "https://github.com/saltx5/farsight/blob/main/farsight/modules/report_writer.py"
    click API "https://github.com/saltx5/farsight/blob/main/farsight/utils/api_handler.py"
    click DNS "https://github.com/saltx5/farsight/blob/main/farsight/utils/dns.py"
    click COM "https://github.com/saltx5/farsight/blob/main/farsight/utils/common.py"
    click SUB "https://github.com/saltx5/farsight/blob/main/farsight/utils/subdomain_enum.py"
    click ANSI1 "https://github.com/saltx5/farsight/blob/main/farsight/__init__.py"
    click ANSI2 "https://github.com/saltx5/farsight/blob/main/farsight/modules/__init__.py"
    click ANSI3 "https://github.com/saltx5/farsight/blob/main/farsight/utils/__init__.py"
    click ANSI4 "https://github.com/saltx5/farsight/blob/main/farsight/cli/__init__.py"

    classDef code fill:#E3F2FD,stroke:#2196F3,color:#0D47A1,stroke-width:2px;
    classDef utils fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20,stroke-width:2px;
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#455A64,stroke-width:2px,stroke-dasharray: 5 5;
    classDef output fill:#FFF8E1,stroke:#FFB300,color:#FF6F00,stroke-width:2px,stroke-dasharray: 2 2;
```
