# oros42/imsi-catcher architecture

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

- Interactive diagram: https://gitdiagram.com/oros42/imsi-catcher
- Repository: https://github.com/oros42/imsi-catcher

## Overview

IMSI-catcher receives GSMTAP traffic decoded by gr-gsm, extracts cell and mobile identities, enriches IMSIs with country/operator data, and displays or saves observations. Its principal workflow is documented in the README; the sampled source confirms identity parsing, tracking, and SQLite/TXT/MySQL persistence. The same program also offers packet sniffing and an immediate-assignment inspection utility. Some runtime wiring is not shown in the excerpts, so only documented or excerpt-supported relationships are drawn.

Main entry points: [`simple_IMSI-catcher.py`](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py) (IMSI tracker), [`immediate_assignment_catcher.py`](https://github.com/oros42/imsi-catcher/blob/master/immediate_assignment_catcher.py) (Assignment inspector), [`mcc-mnc/mcc_codes.json`](https://github.com/oros42/imsi-catcher/blob/master/mcc-mnc/mcc_codes.json) (MCC/MNC codes), [`mcc-mnc/update_codes.py`](https://github.com/oros42/imsi-catcher/blob/master/mcc-mnc/update_codes.py) (Code updater)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Signal capture"]
  node_listener["GSMTAP receiver"]
  node_sniffer["Interface sniffer"]
end

subgraph group_analysis["GSM analysis"]
  node_assignment["Assignment inspector"]
  node_packet_parser["GSMTAP parser"]
  node_tracker["IMSI tracker"]
end

subgraph group_enrichment["Identity enrichment"]
  node_identity_decode["Identity decoder"]
  node_mcc_data["MCC/MNC codes<br/>[mcc_codes.json]"]
  node_code_updater["Code updater<br/>[update_codes.py]"]
end

subgraph group_outputs["Observation outputs"]
  node_console["Console output"]
  node_sqlite[("SQLite observations")]
  node_text["Text observations"]
  node_mysql[("MySQL observations")]
end

node_operator(("Operator"))
node_sdr["SDR receiver"]
node_grgsm["gr-gsm live decoder"]
node_mysql_service[("MySQL server")]

node_operator -->|"tunes receiver"| node_sdr
node_sdr -->|"supplies radio signals"| node_grgsm
node_grgsm -->|"sends decoded GSMTAP"| node_listener
node_operator -->|"starts capture"| node_listener
node_operator -->|"selects sniff mode"| node_sniffer
node_operator -->|"runs inspector"| node_assignment
node_listener -.->|"passes packets"| node_packet_parser
node_sniffer -.->|"passes packets"| node_packet_parser
node_packet_parser -->|"registers identities"| node_tracker
node_assignment -->|"prints channel details"| node_operator
node_tracker -->|"decodes IMSI"| node_identity_decode
node_identity_decode -.->|"looks up network"| node_mcc_data
node_code_updater -->|"writes code data"| node_mcc_data
node_tracker -.->|"displays observations"| node_console
node_tracker -->|"writes observations"| node_sqlite
node_tracker -.->|"writes observations"| node_text
node_tracker -.->|"writes observations"| node_mysql
node_mysql -.->|"stores records"| node_mysql_service

click node_listener "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py"
click node_sniffer "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py"
click node_assignment "https://github.com/oros42/imsi-catcher/blob/master/immediate_assignment_catcher.py"
click node_packet_parser "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py"
click node_tracker "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py"
click node_identity_decode "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py"
click node_mcc_data "https://github.com/oros42/imsi-catcher/blob/master/mcc-mnc/mcc_codes.json"
click node_code_updater "https://github.com/oros42/imsi-catcher/blob/master/mcc-mnc/update_codes.py"
click node_console "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py"
click node_sqlite "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py"
click node_text "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py"
click node_mysql "https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.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_listener,node_sniffer toneBlue
class node_assignment,node_packet_parser,node_tracker,node_mysql_service toneAmber
class node_identity_decode,node_mcc_data,node_code_updater toneMint
class node_console,node_sqlite,node_text,node_mysql toneRose
class node_operator,node_sdr,node_grgsm toneIndigo
```

## Components

### Signal capture

- [GSMTAP receiver](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`
- [Interface sniffer](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`

### GSM analysis

- [Assignment inspector](https://github.com/oros42/imsi-catcher/blob/master/immediate_assignment_catcher.py): `immediate_assignment_catcher.py`
- [GSMTAP parser](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`
- [IMSI tracker](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`

### Identity enrichment

- [Identity decoder](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`
- [MCC/MNC codes](https://github.com/oros42/imsi-catcher/blob/master/mcc-mnc/mcc_codes.json): `mcc-mnc/mcc_codes.json`
- [Code updater](https://github.com/oros42/imsi-catcher/blob/master/mcc-mnc/update_codes.py): `mcc-mnc/update_codes.py`

### Observation outputs

- [Console output](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`
- [SQLite observations](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`
- [Text observations](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`
- [MySQL observations](https://github.com/oros42/imsi-catcher/blob/master/simple_IMSI-catcher.py): `simple_IMSI-catcher.py`

### Other components

- **Operator**
- **SDR receiver**
- **gr-gsm live decoder**
- **MySQL server**

## Connections

- Operator → SDR receiver: tunes receiver (evidence: `README.md`)
- SDR receiver → gr-gsm live decoder: supplies radio signals (evidence: `README.md`)
- gr-gsm live decoder → GSMTAP receiver: sends decoded GSMTAP (evidence: `README.md`)
- Operator → GSMTAP receiver: starts capture (evidence: `README.md`)
- Operator → Interface sniffer: selects sniff mode (evidence: `README.md`)
- Operator → Assignment inspector: runs inspector (evidence: `README.md`)
- GSMTAP receiver → GSMTAP parser: passes packets (evidence: `simple_IMSI-catcher.py`)
- Interface sniffer → GSMTAP parser: passes packets (evidence: `simple_IMSI-catcher.py`)
- GSMTAP parser → IMSI tracker: registers identities (evidence: `simple_IMSI-catcher.py`)
- Assignment inspector → Operator: prints channel details (evidence: `immediate_assignment_catcher.py`)
- IMSI tracker → Identity decoder: decodes IMSI (evidence: `simple_IMSI-catcher.py`)
- Identity decoder → MCC/MNC codes: looks up network
- Code updater → MCC/MNC codes: writes code data (evidence: `mcc-mnc/update_codes.py`)
- IMSI tracker → Console output: displays observations (evidence: `simple_IMSI-catcher.py`)
- IMSI tracker → SQLite observations: writes observations (evidence: `simple_IMSI-catcher.py`)
- IMSI tracker → Text observations: writes observations (evidence: `simple_IMSI-catcher.py`)
- IMSI tracker → MySQL observations: writes observations (evidence: `simple_IMSI-catcher.py`)
- MySQL observations → MySQL server: stores records
