# pirxthepilot/wtfis architecture

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

- Interactive diagram: https://gitdiagram.com/pirxthepilot/wtfis
- Repository: https://github.com/pirxthepilot/wtfis

## Overview

wtfis is a command-line OSINT lookup tool for domains, hostnames, and IP addresses. The main flow parses configuration, selects an entity handler, fetches VirusTotal and optional provider enrichments, then formats the collected results as terminal panels. IP and domain lookups have distinct handler stages; provider-specific clients and normalized response models support enrichment, while the UI presents the results. The README documents the provider capabilities. Some handler and client implementations were not excerpted, so those documented relationships use README evidence rather than assumed call chains.

Main entry points: [`wtfis/main.py`](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/main.py) (CLI workflow), [`wtfis/ui/base.py`](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/ui/base.py) (Panel rendering), [`wtfis/handlers/base.py`](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/handlers/base.py) (Shared handler), [`wtfis/config.py`](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/config.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Lookup flow"]
  node_main["CLI workflow<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_base_handler["Shared handler<br/>[base.py]"]
  node_domain_handler["Domain lookup<br/>[domain.py]"]
  node_ip_handler["IP lookup<br/>[ip.py]"]
end

subgraph group_providers["Enrichment providers"]
  node_vt_client["VirusTotal client<br/>[virustotal.py]"]
  node_abuse_client["AbuseIPDB client<br/>[abuseipdb.py]"]
  node_greynoise_client["GreyNoise client<br/>[greynoise.py]"]
  node_ip2location_client["IP2Location client<br/>[ip2location.py]"]
  node_ip2whois_client["IP2Whois client<br/>[ip2whois.py]"]
  node_ipinfo_client["IPinfo client<br/>[ipinfo.py]"]
  node_ipwhois_client["IPWhois client<br/>[ipwhois.py]"]
  node_shodan_client["Shodan client<br/>[shodan.py]"]
  node_urlhaus_client["URLhaus client<br/>[urlhaus.py]"]
end

subgraph group_schemas["Data models"]
  node_vt_models["VirusTotal models<br/>[virustotal.py]"]
  node_ipwhois_model["IPWhois model<br/>[ipwhois.py]"]
  node_abuse_model["AbuseIPDB model<br/>[abuseipdb.py]"]
  node_greynoise_model["GreyNoise model<br/>[greynoise.py]"]
  node_shodan_model["Shodan model<br/>[shodan.py]"]
  node_urlhaus_model["URLhaus model<br/>[urlhaus.py]"]
  node_common_models["Shared models<br/>[base.py]"]
end

subgraph group_presentation["Terminal output"]
  node_base_view["Panel rendering<br/>[base.py]"]
  node_entity_view["Lookup views<br/>[view.py]"]
  node_progress["Progress display<br/>[progress.py]"]
end

node_user(("User"))
node_external_osint["OSINT services"]

node_user -->|"submits lookup"| node_main
node_main -->|"loads options"| node_config
node_main -->|"selects domain"| node_domain_handler
node_main -->|"selects IP"| node_ip_handler
node_main -->|"fetches data"| node_base_handler
node_main -->|"shows progress"| node_progress
node_main -->|"creates view"| node_entity_view
node_main -->|"prints results"| node_base_view
node_domain_handler -->|"inherits behavior"| node_base_handler
node_ip_handler -->|"inherits behavior"| node_base_handler
node_config -->|"selects provider"| node_ip2location_client
node_config -->|"selects provider"| node_ipinfo_client
node_config -->|"selects provider"| node_ipwhois_client
node_config -->|"selects WHOIS"| node_ip2whois_client
node_base_handler -->|"requests enrichment"| node_abuse_client
node_base_handler -->|"requests enrichment"| node_greynoise_client
node_base_handler -->|"requests enrichment"| node_shodan_client
node_base_handler -->|"requests enrichment"| node_urlhaus_client
node_base_handler -.->|"uses primary source"| node_vt_client
node_vt_client -->|"validates responses"| node_vt_models
node_vt_client -->|"queries VirusTotal"| node_external_osint
node_abuse_client -->|"queries AbuseIPDB"| node_external_osint
node_greynoise_client -->|"queries GreyNoise"| node_external_osint
node_ip2location_client -->|"queries IP2Location"| node_external_osint
node_ip2whois_client -->|"queries IP2Whois"| node_external_osint
node_ipinfo_client -->|"queries IPinfo"| node_external_osint
node_ipwhois_client -->|"queries IPWhois"| node_external_osint
node_shodan_client -->|"queries Shodan"| node_external_osint
node_urlhaus_client -->|"queries URLhaus"| node_external_osint
node_base_view -->|"renders analysis"| node_vt_models
node_base_view -->|"renders reports"| node_abuse_model
node_base_view -->|"renders classification"| node_greynoise_model
node_base_view -->|"renders host data"| node_shodan_model
node_base_view -->|"renders URL data"| node_urlhaus_model
node_base_view -->|"renders normalized data"| node_common_models
node_entity_view -->|"builds panels"| node_base_view
node_ipwhois_model -->|"extends shared fields"| node_common_models

click node_main "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/main.py"
click node_config "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/config.py"
click node_base_handler "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/handlers/base.py"
click node_domain_handler "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/handlers/domain.py"
click node_ip_handler "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/handlers/ip.py"
click node_vt_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/virustotal.py"
click node_abuse_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/abuseipdb.py"
click node_greynoise_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/greynoise.py"
click node_ip2location_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/ip2location.py"
click node_ip2whois_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/ip2whois.py"
click node_ipinfo_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/ipinfo.py"
click node_ipwhois_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/ipwhois.py"
click node_shodan_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/shodan.py"
click node_urlhaus_client "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/urlhaus.py"
click node_vt_models "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/virustotal.py"
click node_ipwhois_model "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/ipwhois.py"
click node_abuse_model "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/abuseipdb.py"
click node_greynoise_model "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/greynoise.py"
click node_shodan_model "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/shodan.py"
click node_urlhaus_model "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/urlhaus.py"
click node_common_models "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/base.py"
click node_base_view "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/ui/base.py"
click node_entity_view "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/ui/view.py"
click node_progress "https://github.com/pirxthepilot/wtfis/blob/main/wtfis/ui/progress.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_config,node_base_handler,node_domain_handler,node_ip_handler,node_user toneBlue
class node_vt_client,node_abuse_client,node_greynoise_client,node_ip2location_client,node_ip2whois_client,node_ipinfo_client,node_ipwhois_client,node_shodan_client,node_urlhaus_client toneAmber
class node_vt_models,node_ipwhois_model,node_abuse_model,node_greynoise_model,node_shodan_model,node_urlhaus_model,node_common_models toneMint
class node_base_view,node_entity_view,node_progress toneRose
class node_external_osint toneIndigo
```

## Components

### Lookup flow

- [CLI workflow](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/main.py): `wtfis/main.py`
- [Configuration](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/config.py): `wtfis/config.py`
- [Shared handler](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/handlers/base.py): `wtfis/handlers/base.py`
- [Domain lookup](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/handlers/domain.py): `wtfis/handlers/domain.py`
- [IP lookup](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/handlers/ip.py): `wtfis/handlers/ip.py`

### Enrichment providers

- [VirusTotal client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/virustotal.py): `wtfis/clients/virustotal.py`
- [AbuseIPDB client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/abuseipdb.py): `wtfis/clients/abuseipdb.py`
- [GreyNoise client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/greynoise.py): `wtfis/clients/greynoise.py`
- [IP2Location client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/ip2location.py): `wtfis/clients/ip2location.py`
- [IP2Whois client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/ip2whois.py): `wtfis/clients/ip2whois.py`
- [IPinfo client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/ipinfo.py): `wtfis/clients/ipinfo.py`
- [IPWhois client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/ipwhois.py): `wtfis/clients/ipwhois.py`
- [Shodan client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/shodan.py): `wtfis/clients/shodan.py`
- [URLhaus client](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/clients/urlhaus.py): `wtfis/clients/urlhaus.py`

### Data models

- [VirusTotal models](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/virustotal.py): `wtfis/models/virustotal.py`
- [IPWhois model](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/ipwhois.py): `wtfis/models/ipwhois.py`
- [AbuseIPDB model](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/abuseipdb.py): `wtfis/models/abuseipdb.py`
- [GreyNoise model](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/greynoise.py): `wtfis/models/greynoise.py`
- [Shodan model](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/shodan.py): `wtfis/models/shodan.py`
- [URLhaus model](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/urlhaus.py): `wtfis/models/urlhaus.py`
- [Shared models](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/models/base.py): `wtfis/models/base.py`

### Terminal output

- [Panel rendering](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/ui/base.py): `wtfis/ui/base.py`
- [Lookup views](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/ui/view.py): `wtfis/ui/view.py`
- [Progress display](https://github.com/pirxthepilot/wtfis/blob/main/wtfis/ui/progress.py): `wtfis/ui/progress.py`

### Other components

- **User**
- **OSINT services**

## Connections

- User → CLI workflow: submits lookup
- CLI workflow → Configuration: loads options (evidence: `wtfis/main.py`)
- CLI workflow → Domain lookup: selects domain (evidence: `wtfis/main.py`)
- CLI workflow → IP lookup: selects IP (evidence: `wtfis/main.py`)
- CLI workflow → Shared handler: fetches data (evidence: `wtfis/main.py`)
- CLI workflow → Progress display: shows progress (evidence: `wtfis/main.py`)
- CLI workflow → Lookup views: creates view (evidence: `wtfis/main.py`)
- CLI workflow → Panel rendering: prints results (evidence: `wtfis/main.py`)
- Domain lookup → Shared handler: inherits behavior (evidence: `wtfis/handlers/domain.py`)
- IP lookup → Shared handler: inherits behavior (evidence: `wtfis/handlers/ip.py`)
- Configuration → IP2Location client: selects provider (evidence: `wtfis/config.py`)
- Configuration → IPinfo client: selects provider (evidence: `wtfis/config.py`)
- Configuration → IPWhois client: selects provider (evidence: `wtfis/config.py`)
- Configuration → IP2Whois client: selects WHOIS (evidence: `wtfis/config.py`)
- Shared handler → AbuseIPDB client: requests enrichment (evidence: `wtfis/handlers/base.py`)
- Shared handler → GreyNoise client: requests enrichment (evidence: `wtfis/handlers/base.py`)
- Shared handler → Shodan client: requests enrichment (evidence: `wtfis/handlers/base.py`)
- Shared handler → URLhaus client: requests enrichment (evidence: `wtfis/handlers/base.py`)
- Shared handler → VirusTotal client: uses primary source (evidence: `wtfis/handlers/base.py`)
- VirusTotal client → VirusTotal models: validates responses (evidence: `wtfis/clients/virustotal.py`)
- VirusTotal client → OSINT services: queries VirusTotal
- AbuseIPDB client → OSINT services: queries AbuseIPDB
- GreyNoise client → OSINT services: queries GreyNoise
- IP2Location client → OSINT services: queries IP2Location
- IP2Whois client → OSINT services: queries IP2Whois
- IPinfo client → OSINT services: queries IPinfo
- IPWhois client → OSINT services: queries IPWhois
- Shodan client → OSINT services: queries Shodan
- URLhaus client → OSINT services: queries URLhaus
- Panel rendering → VirusTotal models: renders analysis (evidence: `wtfis/ui/base.py`)
- Panel rendering → AbuseIPDB model: renders reports (evidence: `wtfis/ui/base.py`)
- Panel rendering → GreyNoise model: renders classification (evidence: `wtfis/ui/base.py`)
- Panel rendering → Shodan model: renders host data (evidence: `wtfis/ui/base.py`)
- Panel rendering → URLhaus model: renders URL data (evidence: `wtfis/ui/base.py`)
- Panel rendering → Shared models: renders normalized data (evidence: `wtfis/ui/base.py`)
- Lookup views → Panel rendering: builds panels (evidence: `wtfis/ui/view.py`)
- IPWhois model → Shared models: extends shared fields (evidence: `wtfis/models/ipwhois.py`)
