# jessebowling/ipgrep architecture

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

- Interactive diagram: https://gitdiagram.com/jessebowling/ipgrep
- Repository: https://github.com/jessebowling/ipgrep

## Overview

ipgrep is a command-line IP extraction and enrichment utility. Users provide text via stdin or a file and choose extraction options, chained enrichments, and an output format; the CLI constructs the pipeline, which extracts and normalizes IP data, applies enrichment plugins, and formats results. The README also documents local IP classification, IPInfo database enrichment, and three Shadowserver ASN lookups. Their advertised capabilities are represented below; unsampled modules are not described beyond those documented behaviors.

Main entry points: [`src/ipgrep/core.py`](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/core.py) (Processing pipeline), [`src/ipgrep/plugins/enrichment/asn_base.py`](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_base.py) (ASN API and batching), [`src/ipgrep/cli.py`](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/cli.py) (CLI options and input), [`src/ipgrep/plugins/enrichment/asn_prefix.py`](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_prefix.py) (ASN prefix lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_cli["CLI options and input<br/>[cli.py]"]
  node_pipeline["Processing pipeline<br/>[core.py]"]
end

subgraph group_extract["Extraction"]
  node_extractor["IP and CIDR extractor<br/>[extractor.py]"]
end

subgraph group_enrich["Enrichment plugins"]
  node_plugin_api["Plugin interfaces and discovery<br/>[base.py]"]
  node_ipclass["IP classification"]
  node_ipinfo["IPInfo database lookup<br/>[ipinfo.py]"]
  node_asn_base["ASN API and batching<br/>[asn_base.py]"]
  node_origin["Origin ASN lookup<br/>[asn_origin.py]"]
  node_peer["Peer ASN lookup<br/>[asn_peer.py]"]
  node_prefix["ASN prefix lookup<br/>[asn_prefix.py]"]
end

subgraph group_output["Output formatting"]
  node_plain["Plain output<br/>[plain.py]"]
  node_csv["CSV output<br/>[csv.py]"]
  node_json["JSON output<br/>[json.py]"]
  node_space["Space output<br/>[space_delimited.py]"]
  node_pipe["Pipe output<br/>[pipe_delimited.py]"]
end

node_user(("CLI user"))
node_shadowserver{{"Shadowserver API"}}
node_ipinfo_db{{"IPInfo database service"}}

node_user -->|"provides input"| node_cli
node_cli -->|"constructs and runs"| node_pipeline
node_cli -->|"loads plugins"| node_plugin_api
node_pipeline -->|"extracts addresses"| node_extractor
node_pipeline -->|"uses plugin interfaces"| node_plugin_api
node_pipeline -.->|"formats by default"| node_plain
node_pipeline -.->|"formats enriched data"| node_csv
node_pipeline -.->|"formats selected data"| node_json
node_pipeline -.->|"formats selected data"| node_space
node_pipeline -.->|"formats selected data"| node_pipe
node_pipeline -.->|"applies enrichment"| node_ipclass
node_pipeline -.->|"applies enrichment"| node_ipinfo
node_pipeline -.->|"applies enrichment"| node_origin
node_pipeline -.->|"applies enrichment"| node_peer
node_pipeline -.->|"applies enrichment"| node_prefix
node_origin -->|"inherits API support"| node_asn_base
node_peer -->|"inherits API support"| node_asn_base
node_prefix -->|"inherits API support"| node_asn_base
node_prefix -->|"looks up origin ASN"| node_origin
node_asn_base -->|"requests ASN data"| node_shadowserver
node_ipinfo -.->|"queries database"| node_ipinfo_db

click node_cli "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/cli.py"
click node_pipeline "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/core.py"
click node_extractor "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/extractor.py"
click node_plugin_api "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/base.py"
click node_ipclass "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/ipaddress_enrichment.py"
click node_ipinfo "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/ipinfo.py"
click node_asn_base "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_base.py"
click node_origin "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_origin.py"
click node_peer "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_peer.py"
click node_prefix "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_prefix.py"
click node_plain "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/plain.py"
click node_csv "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/csv.py"
click node_json "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/json.py"
click node_space "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/space_delimited.py"
click node_pipe "https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/pipe_delimited.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_pipeline,node_user toneBlue
class node_extractor,node_ipinfo_db toneAmber
class node_plugin_api,node_ipclass,node_ipinfo,node_asn_base,node_origin,node_peer,node_prefix,node_shadowserver toneMint
class node_plain,node_csv,node_json,node_space,node_pipe toneRose
```

## Components

### CLI and orchestration

- [CLI options and input](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/cli.py): `src/ipgrep/cli.py`
- [Processing pipeline](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/core.py): `src/ipgrep/core.py`

### Extraction

- [IP and CIDR extractor](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/extractor.py): `src/ipgrep/extractor.py`

### Enrichment plugins

- [Plugin interfaces and discovery](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/base.py): `src/ipgrep/plugins/base.py`
- [IP classification](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/ipaddress_enrichment.py): `src/ipgrep/plugins/enrichment/ipaddress_enrichment.py`
- [IPInfo database lookup](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/ipinfo.py): `src/ipgrep/plugins/enrichment/ipinfo.py`
- [ASN API and batching](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_base.py): `src/ipgrep/plugins/enrichment/asn_base.py`
- [Origin ASN lookup](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_origin.py): `src/ipgrep/plugins/enrichment/asn_origin.py`
- [Peer ASN lookup](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_peer.py): `src/ipgrep/plugins/enrichment/asn_peer.py`
- [ASN prefix lookup](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/enrichment/asn_prefix.py): `src/ipgrep/plugins/enrichment/asn_prefix.py`

### Output formatting

- [Plain output](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/plain.py): `src/ipgrep/plugins/output/plain.py`
- [CSV output](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/csv.py): `src/ipgrep/plugins/output/csv.py`
- [JSON output](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/json.py): `src/ipgrep/plugins/output/json.py`
- [Space output](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/space_delimited.py): `src/ipgrep/plugins/output/space_delimited.py`
- [Pipe output](https://github.com/jessebowling/ipgrep/blob/main/src/ipgrep/plugins/output/pipe_delimited.py): `src/ipgrep/plugins/output/pipe_delimited.py`

### Other components

- **CLI user**
- **Shadowserver API**
- **IPInfo database service**

## Connections

- CLI user → CLI options and input: provides input (evidence: `README.md`)
- CLI options and input → Processing pipeline: constructs and runs (evidence: `src/ipgrep/cli.py`)
- CLI options and input → Plugin interfaces and discovery: loads plugins (evidence: `src/ipgrep/cli.py`)
- Processing pipeline → IP and CIDR extractor: extracts addresses (evidence: `src/ipgrep/core.py`)
- Processing pipeline → Plugin interfaces and discovery: uses plugin interfaces (evidence: `src/ipgrep/core.py`)
- Processing pipeline → Plain output: formats by default
- Processing pipeline → CSV output: formats enriched data
- Processing pipeline → JSON output: formats selected data
- Processing pipeline → Space output: formats selected data
- Processing pipeline → Pipe output: formats selected data
- Processing pipeline → IP classification: applies enrichment
- Processing pipeline → IPInfo database lookup: applies enrichment
- Processing pipeline → Origin ASN lookup: applies enrichment
- Processing pipeline → Peer ASN lookup: applies enrichment
- Processing pipeline → ASN prefix lookup: applies enrichment
- Origin ASN lookup → ASN API and batching: inherits API support (evidence: `src/ipgrep/plugins/enrichment/asn_origin.py`)
- Peer ASN lookup → ASN API and batching: inherits API support (evidence: `src/ipgrep/plugins/enrichment/asn_peer.py`)
- ASN prefix lookup → ASN API and batching: inherits API support (evidence: `src/ipgrep/plugins/enrichment/asn_prefix.py`)
- ASN prefix lookup → Origin ASN lookup: looks up origin ASN (evidence: `src/ipgrep/plugins/enrichment/asn_prefix.py`)
- ASN API and batching → Shadowserver API: requests ASN data (evidence: `src/ipgrep/plugins/enrichment/asn_base.py`)
- IPInfo database lookup → IPInfo database service: queries database