# clayhax/shodanscope architecture

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

- Interactive diagram: https://gitdiagram.com/clayhax/shodanscope
- Repository: https://github.com/clayhax/shodanscope

## Overview

ShodanScope is a single-script passive inventory tool: a user supplies a scope file, the program parses and normalizes IPs, CIDRs, and FQDNs, prepares unique queries (resolving domains), searches Shodan’s existing index, deduplicates and attributes observations, then writes inventory reports. It does not scan hosts. The main routine’s calls and report output are visible in the excerpt; DNS and Shodan behavior are also documented in the README. Internal responsibilities share one source file, so the graph separates them by function rather than module.

Main entry points: [`shodanscope.py`](https://github.com/clayhax/shodanscope/blob/main/shodanscope.py) (CLI orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Inventory workflow"]
  node_main["CLI orchestrator<br/>[shodanscope.py]"]
  node_parse["Scope parsing<br/>[shodanscope.py]"]
  node_prepare["Query preparation<br/>[shodanscope.py]"]
  node_search["Shodan search<br/>[shodanscope.py]"]
  node_results["Result processing<br/>[shodanscope.py]"]
  node_reports["Inventory exports<br/>[shodanscope.py]"]
end

subgraph group_external["External services"]
  node_dns["DNS resolver"]
  node_shodan["Shodan API"]
end

node_user(("Operator"))
node_scope["Scope file"]
node_output["Report files"]

node_user -->|"provides scope"| node_scope
node_user -->|"runs"| node_main
node_main -->|"loads scope"| node_parse
node_scope -->|"supplies entries"| node_parse
node_main -->|"prepares queries"| node_prepare
node_prepare -->|"resolves FQDNs"| node_dns
node_main -->|"searches queries"| node_search
node_search -->|"queries index"| node_shodan
node_main -->|"deduplicates, annotates"| node_results
node_main -->|"saves results"| node_reports
node_reports -->|"writes reports"| node_output

click node_main "https://github.com/clayhax/shodanscope/blob/main/shodanscope.py"
click node_parse "https://github.com/clayhax/shodanscope/blob/main/shodanscope.py"
click node_prepare "https://github.com/clayhax/shodanscope/blob/main/shodanscope.py"
click node_search "https://github.com/clayhax/shodanscope/blob/main/shodanscope.py"
click node_results "https://github.com/clayhax/shodanscope/blob/main/shodanscope.py"
click node_reports "https://github.com/clayhax/shodanscope/blob/main/shodanscope.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_parse,node_prepare,node_search,node_results,node_reports toneBlue
class node_dns,node_shodan toneAmber
class node_user,node_scope,node_output toneIndigo
```

## Components

### Inventory workflow

- [CLI orchestrator](https://github.com/clayhax/shodanscope/blob/main/shodanscope.py): `shodanscope.py`
- [Scope parsing](https://github.com/clayhax/shodanscope/blob/main/shodanscope.py): `shodanscope.py`
- [Query preparation](https://github.com/clayhax/shodanscope/blob/main/shodanscope.py): `shodanscope.py`
- [Shodan search](https://github.com/clayhax/shodanscope/blob/main/shodanscope.py): `shodanscope.py`
- [Result processing](https://github.com/clayhax/shodanscope/blob/main/shodanscope.py): `shodanscope.py`
- [Inventory exports](https://github.com/clayhax/shodanscope/blob/main/shodanscope.py): `shodanscope.py`

### External services

- **DNS resolver**
- **Shodan API**

### Other components

- **Operator**
- **Scope file**
- **Report files**

## Connections

- Operator → Scope file: provides scope (evidence: `README.md`)
- Operator → CLI orchestrator: runs (evidence: `README.md`)
- CLI orchestrator → Scope parsing: loads scope (evidence: `shodanscope.py`)
- Scope file → Scope parsing: supplies entries (evidence: `README.md`)
- CLI orchestrator → Query preparation: prepares queries (evidence: `shodanscope.py`)
- Query preparation → DNS resolver: resolves FQDNs (evidence: `README.md`)
- CLI orchestrator → Shodan search: searches queries (evidence: `shodanscope.py`)
- Shodan search → Shodan API: queries index (evidence: `README.md`)
- CLI orchestrator → Result processing: deduplicates, annotates (evidence: `shodanscope.py`)
- CLI orchestrator → Inventory exports: saves results (evidence: `shodanscope.py`)
- Inventory exports → Report files: writes reports (evidence: `README.md`)