# zeo-design/osint-tool architecture

> Architecture diagram of the GitHub repository zeo-design/osint-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zeo-design/osint-tool
- Repository: https://github.com/zeo-design/osint-tool

## Overview

1. This repository is a Python 3.11+ command-line OSINT/recon tool, organized as a small orchestration layer plus a set of independent analysis modules. The architecture is intentionally modular: `main.py` is the entrypoint, and the `modules/` package contains the feature-specific work.

2. The primary boundary is between user interaction and intelligence gathering. `main.py` appears to handle the terminal menu, target selection, and module dispatch. The individual modules encapsulate the actual reconnaissance logic and return results to the CLI for display.

3. The main runtime flow is linear:
   user launches `python main.py` → menu is shown → user chooses a module → user supplies a target such as domain, IP, username, or name → selected module runs → results are printed in terminal. There is also a “run all” path that executes multiple modules sequentially.

4. `modules/domain_recon.py` is the central infrastructure-intelligence module. Per the README, it combines WHOIS, DNS records, SSL certificate inspection, and SPF/DKIM checks. This module likely acts as the heaviest external-data consumer because it aggregates several network lookups for one domain target.

5. `modules/subdomains.py` is a separate attack-surface discovery subsystem. Its job is to enumerate or validate subdomains via DNS resolution, producing hostnames like `api.target.com` or `staging.target.com`. Architecturally, it depends on DNS/network queries but is distinct from the broader domain recon module.

6. `modules/ip_geo.py` is the IP intelligence boundary. It accepts an IP address and returns infrastructure metadata such as geolocation, ISP, ASN, organization, and hosting/provider context. This module is likely backed by an external IP intelligence/geolocation service or public lookup source.

7. `modules/username_search.py` is the digital-footprint discovery module. It searches a username across multiple platforms, which means its architecture is fan-out oriented: one input, many external platform checks, then a consolidated result set.

8. `modules/email_intel.py` is a lightweight generator module rather than a lookup-heavy one. Its role is to synthesize likely corporate email patterns from a name or target identity, producing candidate address formats for later validation or use in other recon workflows.

9. `modules/dorking.py` is another generator-style module. It produces categorized Google dork queries for exposing files, panels, directories, backups, and similar indexed artifacts. Unlike the network-heavy modules, this one primarily transforms user input into search queries.

10. The modules are independent at the feature level, but they all share the same presentation boundary: terminal output. That means the repo is structured more like a toolkit than a pipeline, with each module responsible for its own fetch/compute/report cycle.

11. The “Run All” option is the main cross-module workflow. It ties the otherwise separate capabilities together into a sequential reconnaissance pass, which is useful for broad initial assessment and for showing how the different intelligence sources complement one another.

12. From an architecture-diagram perspective, the important external dependencies are not internal services but remote/public data sources: DNS, WHOIS, SSL certificate endpoints, public IP geolocation/intelligence sources, and third-party web platforms/search surfaces. The project is therefore an API/network-dependent CLI utility rather than an offline analyzer.

13. The repository is intentionally simple in structure: one entrypoint, one package of feature modules, and a requirements file for Python dependencies. There is no evidence of a web server, database, message queue, or persistent storage layer in the current phase.

14. The roadmap in the README shows future architectural expansion, but it is not yet present in the file tree. Planned additions include reporting, batch execution, export formats, a REST API, and a web dashboard, which would introduce new presentation and persistence boundaries later.

15. For diagramming, the most accurate abstraction is: CLI controller at the top, module-level intelligence workers beneath it, and external network/data providers at the bottom. The key design characteristic is modular OSINT capability with shared terminal-based orchestration.

Main entry points: [`main.py`](https://github.com/zeo-design/osint-tool/blob/master/main.py) (Menu), [`modules/domain_recon.py`](https://github.com/zeo-design/osint-tool/blob/master/modules/domain_recon.py) (Domain recon), [`modules/subdomains.py`](https://github.com/zeo-design/osint-tool/blob/master/modules/subdomains.py) (Subdomains), [`modules/ip_geo.py`](https://github.com/zeo-design/osint-tool/blob/master/modules/ip_geo.py) (IP geo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI orchestration"]
  node_main["Main CLI<br/>entrypoint<br/>[main.py]"]
  node_menu["Menu<br/>interaction<br/>[main.py]"]
  node_dispatch["Dispatcher<br/>orchestration<br/>[main.py]"]
  node_output["Terminal output<br/>presentation<br/>[main.py]"]
end

subgraph group_mods["OSINT modules"]
  node_domain["Domain recon<br/>intel module<br/>[domain_recon.py]"]
  node_subs["Subdomains<br/>discovery module<br/>[subdomains.py]"]
  node_ipgeo["IP geo<br/>intel module<br/>[ip_geo.py]"]
  node_usersearch["Username search<br/>discovery module<br/>[username_search.py]"]
  node_email["Email intel<br/>generator<br/>[email_intel.py]"]
  node_dorks["Dorking<br/>generator<br/>[dorking.py]"]
end

subgraph group_ext["External sources"]
  node_whois[("WHOIS<br/>data source")]
  node_dns[("DNS<br/>data source")]
  node_ssl[("SSL certs<br/>data source")]
  node_ipdb[("IP intel<br/>data source")]
  node_web["Web platforms<br/>surface"]
  node_search["Search engine<br/>surface"]
end

node_main -->|"shows"| node_menu
node_menu -->|"choice"| node_dispatch
node_dispatch -->|"run"| node_domain
node_dispatch -->|"run"| node_subs
node_dispatch -->|"run"| node_ipgeo
node_dispatch -->|"run"| node_usersearch
node_dispatch -->|"run"| node_email
node_dispatch -->|"run"| node_dorks
node_domain -->|"queries"| node_whois
node_domain -->|"queries"| node_dns
node_domain -->|"inspects"| node_ssl
node_subs -->|"resolves"| node_dns
node_ipgeo -->|"looks up"| node_ipdb
node_usersearch -->|"fans out"| node_web
node_dorks -->|"targets"| node_search
node_main -->|"prints"| node_output
node_domain -->|"reports"| node_output
node_subs -->|"reports"| node_output
node_ipgeo -->|"reports"| node_output
node_usersearch -->|"reports"| node_output
node_email -->|"reports"| node_output
node_dorks -->|"reports"| node_output
node_menu -.->|"run all"| node_domain
node_menu -.->|"run all"| node_subs
node_menu -.->|"run all"| node_ipgeo
node_menu -.->|"run all"| node_usersearch
node_menu -.->|"run all"| node_email
node_menu -.->|"run all"| node_dorks

click node_main "https://github.com/zeo-design/osint-tool/blob/master/main.py"
click node_menu "https://github.com/zeo-design/osint-tool/blob/master/main.py"
click node_dispatch "https://github.com/zeo-design/osint-tool/blob/master/main.py"
click node_output "https://github.com/zeo-design/osint-tool/blob/master/main.py"
click node_domain "https://github.com/zeo-design/osint-tool/blob/master/modules/domain_recon.py"
click node_subs "https://github.com/zeo-design/osint-tool/blob/master/modules/subdomains.py"
click node_ipgeo "https://github.com/zeo-design/osint-tool/blob/master/modules/ip_geo.py"
click node_usersearch "https://github.com/zeo-design/osint-tool/blob/master/modules/username_search.py"
click node_email "https://github.com/zeo-design/osint-tool/blob/master/modules/email_intel.py"
click node_dorks "https://github.com/zeo-design/osint-tool/blob/master/modules/dorking.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_menu,node_dispatch,node_output toneBlue
class node_domain,node_subs,node_ipgeo,node_usersearch,node_email,node_dorks toneAmber
class node_whois,node_dns,node_ssl,node_ipdb,node_web,node_search toneMint
```

## Components

### CLI orchestration

Terminal entrypoint and user-driven dispatch.

- [Main CLI](https://github.com/zeo-design/osint-tool/blob/master/main.py): entrypoint · Starts the tool, shows the menu, collects targets, and dispatches modules. · `main.py`
- [Menu](https://github.com/zeo-design/osint-tool/blob/master/main.py): interaction · Terminal menu and run-all selection flow. · `main.py`
- [Dispatcher](https://github.com/zeo-design/osint-tool/blob/master/main.py): orchestration · Routes user choices to the selected analysis module. · `main.py`
- [Terminal output](https://github.com/zeo-design/osint-tool/blob/master/main.py): presentation · Shared console reporting surface for all module results. · `main.py`

### OSINT modules

Feature modules that perform reconnaissance and generation.

- [Domain recon](https://github.com/zeo-design/osint-tool/blob/master/modules/domain_recon.py): intel module · Aggregates domain intelligence such as WHOIS, DNS, SSL, and email policy checks. · `modules/domain_recon.py`
- [Subdomains](https://github.com/zeo-design/osint-tool/blob/master/modules/subdomains.py): discovery module · Enumerates or validates subdomains through DNS resolution. · `modules/subdomains.py`
- [IP geo](https://github.com/zeo-design/osint-tool/blob/master/modules/ip_geo.py): intel module · Resolves IP metadata including geolocation, ASN, ISP, and hosting context. · `modules/ip_geo.py`
- [Username search](https://github.com/zeo-design/osint-tool/blob/master/modules/username_search.py): discovery module · Fans out a username across multiple platforms and consolidates hits. · `modules/username_search.py`
- [Email intel](https://github.com/zeo-design/osint-tool/blob/master/modules/email_intel.py): generator · Builds likely corporate email patterns from identity clues. · `modules/email_intel.py`
- [Dorking](https://github.com/zeo-design/osint-tool/blob/master/modules/dorking.py): generator · Generates categorized search queries for exposed artifacts and surfaces. · `modules/dorking.py`

### External sources

Remote data providers and public web surfaces used by modules.

- **WHOIS**: data source · Domain registration and ownership records.
- **DNS**: data source · Record lookup and hostname resolution.
- **SSL certs**: data source · Certificate inspection and TLS metadata.
- **IP intel**: data source · Public IP geolocation and provider intelligence.
- **Web platforms**: surface · Third-party sites checked during username discovery.
- **Search engine**: surface · Indexed search surface used by generated dork queries.

## Connections

- Main CLI → Menu: shows · The entrypoint presents the interactive menu.
- Menu → Dispatcher: choice · User selection is routed to the dispatcher.
- Dispatcher → Domain recon: run · Dispatch executes the domain recon module.
- Dispatcher → Subdomains: run · Dispatch executes the subdomain discovery module.
- Dispatcher → IP geo: run · Dispatch executes the IP intelligence module.
- Dispatcher → Username search: run · Dispatch executes the username search module.
- Dispatcher → Email intel: run · Dispatch executes the email pattern generator.
- Dispatcher → Dorking: run · Dispatch executes the dork query generator.
- Domain recon → WHOIS: queries · Domain recon pulls registration data.
- Domain recon → DNS: queries · Domain recon gathers DNS records.
- Domain recon → SSL certs: inspects · Domain recon checks certificate details.
- Subdomains → DNS: resolves · Subdomain discovery validates hostnames through DNS.
- IP geo → IP intel: looks up · IP intelligence fetches external provider data.
- Username search → Web platforms: fans out · Username search checks multiple public platforms.
- Dorking → Search engine: targets · Generated queries are intended for search-engine use.
- Main CLI → Terminal output: prints · All module results are returned to the terminal.
- Domain recon → Terminal output: reports · Domain intelligence is rendered in the CLI.
- Subdomains → Terminal output: reports · Subdomain results are rendered in the CLI.
- IP geo → Terminal output: reports · IP metadata is rendered in the CLI.
- Username search → Terminal output: reports · Username hits are rendered in the CLI.
- Email intel → Terminal output: reports · Generated email patterns are rendered in the CLI.
- Dorking → Terminal output: reports · Generated dork queries are rendered in the CLI.
- Menu → Domain recon: run all · The run-all path can invoke domain recon as part of a broader pass.
- Menu → Subdomains: run all · The run-all path can invoke subdomain discovery.
- Menu → IP geo: run all · The run-all path can invoke IP intelligence.
- Menu → Username search: run all · The run-all path can invoke username discovery.
- Menu → Email intel: run all · The run-all path can invoke email generation.
- Menu → Dorking: run all · The run-all path can invoke query generation.
