# mikebanks/abuseipdbscan architecture

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

- Interactive diagram: https://gitdiagram.com/mikebanks/abuseipdbscan
- Repository: https://github.com/mikebanks/abuseipdbscan

## Overview

AbuseIPDB Scanner is a command-line threat-intelligence lookup tool. Its principal workflow accepts an IP, CIDR, file of IPv4 addresses, or country code; queries AbuseIPDB; and prints or exports normalized results. The sampled implementation is concentrated in one Python file, so nodes represent its distinct runtime responsibilities rather than separate packages. Country-allocation scanning and NirSoft are documented in the README, but the sampled excerpts do not show the full allocation-fetch path.

Main entry points: [`AbuseIPDB.py`](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py) (CLI orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Input workflows"]
  node_cli["CLI orchestration<br/>[AbuseIPDB.py]"]
  node_file_parser["File parser<br/>[AbuseIPDB.py]"]
  node_country_scan["Country scanner<br/>[AbuseIPDB.py]"]
end

subgraph group_lookup["Lookup and enrichment"]
  node_ip_lookup["IP lookup<br/>[AbuseIPDB.py]"]
  node_block_lookup["Block lookup<br/>[AbuseIPDB.py]"]
  node_category_translation["Category translation<br/>[AbuseIPDB.py]"]
end

subgraph group_results["Results and export"]
  node_result_normalization["Result normalization<br/>[AbuseIPDB.py]"]
  node_export["Output writers<br/>[AbuseIPDB.py]"]
end

node_user(("CLI user"))
node_nirsoft["NirSoft allocations"]
node_abuseipdb{{"AbuseIPDB API"}}
node_result_files["Result files"]

node_user -->|"provides arguments"| node_cli
node_cli -->|"dispatches file"| node_file_parser
node_cli -->|"dispatches country"| node_country_scan
node_cli -->|"dispatches IP"| node_ip_lookup
node_cli -->|"dispatches block"| node_block_lookup
node_file_parser -->|"checks addresses"| node_ip_lookup
node_country_scan -->|"uses allocations"| node_nirsoft
node_country_scan -->|"checks subnets"| node_block_lookup
node_ip_lookup -->|"queries API"| node_abuseipdb
node_block_lookup -->|"queries API"| node_abuseipdb
node_ip_lookup -->|"translates categories"| node_category_translation
node_cli -->|"passes results"| node_result_normalization
node_result_normalization -->|"normalizes for"| node_export
node_export -->|"writes formats"| node_result_files
node_export -->|"prints JSON"| node_user

click node_cli "https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py"
click node_file_parser "https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py"
click node_country_scan "https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py"
click node_ip_lookup "https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py"
click node_block_lookup "https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py"
click node_category_translation "https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py"
click node_result_normalization "https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py"
click node_export "https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.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_cli,node_file_parser,node_country_scan,node_user toneBlue
class node_ip_lookup,node_block_lookup,node_category_translation toneAmber
class node_result_normalization,node_export,node_abuseipdb toneMint
class node_nirsoft,node_result_files toneIndigo
```

## Components

### Input workflows

- [CLI orchestration](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py): `AbuseIPDB.py`
- [File parser](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py): `AbuseIPDB.py`
- [Country scanner](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py): `AbuseIPDB.py`

### Lookup and enrichment

- [IP lookup](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py): `AbuseIPDB.py`
- [Block lookup](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py): `AbuseIPDB.py`
- [Category translation](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py): `AbuseIPDB.py`

### Results and export

- [Result normalization](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py): `AbuseIPDB.py`
- [Output writers](https://github.com/mikebanks/abuseipdbscan/blob/master/AbuseIPDB.py): `AbuseIPDB.py`

### Other components

- **CLI user**
- **NirSoft allocations**
- **AbuseIPDB API**
- **Result files**

## Connections

- CLI user → CLI orchestration: provides arguments (evidence: `README.md`)
- CLI orchestration → File parser: dispatches file (evidence: `AbuseIPDB.py`)
- CLI orchestration → Country scanner: dispatches country (evidence: `AbuseIPDB.py`)
- CLI orchestration → IP lookup: dispatches IP (evidence: `AbuseIPDB.py`)
- CLI orchestration → Block lookup: dispatches block (evidence: `AbuseIPDB.py`)
- File parser → IP lookup: checks addresses (evidence: `AbuseIPDB.py`)
- Country scanner → NirSoft allocations: uses allocations (evidence: `README.md`)
- Country scanner → Block lookup: checks subnets (evidence: `AbuseIPDB.py`)
- IP lookup → AbuseIPDB API: queries API (evidence: `AbuseIPDB.py`)
- Block lookup → AbuseIPDB API: queries API (evidence: `AbuseIPDB.py`)
- IP lookup → Category translation: translates categories (evidence: `AbuseIPDB.py`)
- CLI orchestration → Result normalization: passes results (evidence: `AbuseIPDB.py`)
- Result normalization → Output writers: normalizes for (evidence: `AbuseIPDB.py`)
- Output writers → Result files: writes formats (evidence: `AbuseIPDB.py`)
- Output writers → CLI user: prints JSON (evidence: `AbuseIPDB.py`)
