How zeo-design/osint-tool works
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 Menu · domain_recon.py Domain recon · subdomains.py Subdomains · ip_geo.py IP geo
Components 16
CLI orchestration
Terminal entrypoint and user-driven dispatch.
- Main CLI · Starts the tool, shows the menu, collects targets, and dispatches modules.
main.py - Menu · Terminal menu and run-all selection flow.
main.py - Dispatcher · Routes user choices to the selected analysis module.
main.py - Terminal output · Shared console reporting surface for all module results.
main.py
OSINT modules
Feature modules that perform reconnaissance and generation.
- Domain recon · Aggregates domain intelligence such as WHOIS, DNS, SSL, and email policy checks.
modules/domain_recon.py - Subdomains · Enumerates or validates subdomains through DNS resolution.
modules/subdomains.py - IP geo · Resolves IP metadata including geolocation, ASN, ISP, and hosting context.
modules/ip_geo.py - Username search · Fans out a username across multiple platforms and consolidates hits.
modules/username_search.py - Email intel · Builds likely corporate email patterns from identity clues.
modules/email_intel.py - Dorking · 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 · Domain registration and ownership records.
- DNS · Record lookup and hostname resolution.
- SSL certs · Certificate inspection and TLS metadata.
- IP intel · Public IP geolocation and provider intelligence.
- Web platforms · Third-party sites checked during username discovery.
- Search engine · Indexed search surface used by generated dork queries.
Connections 28
- 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.