# pwnsat/flatsat architecture

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

- Interactive diagram: https://gitdiagram.com/pwnsat/flatsat
- Repository: https://github.com/pwnsat/flatsat

## Overview

FlatSat is a vulnerable-by-design satellite security training platform: users run RF or USB attack exercises against its RP2040 firmware and observe responses. The attack set covers reconnaissance, eavesdropping, fuzzing, command injection, GPS and ground-station spoofing, replay, and reset. The firmware simulates spacecraft communications, telemetry, sensors, and payload control. The README documents these capabilities and dual RF links; source-index references support the shown module dependencies, but unsampled firmware internals limit confidence about their runtime call paths.

Main entry points: [`Firmware/worker.cpp`](https://github.com/pwnsat/flatsat/blob/main/Firmware/worker.cpp) (Command and mission worker), [`Attacks/lib/pwnsat_packets.py`](https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_packets.py) (Packet toolkit), [`Attacks/lib/pwnsat_lora_tx.py`](https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_lora_tx.py) (LoRa transmitter), [`Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py`](https://github.com/pwnsat/flatsat/blob/main/Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py) (APID reconnaissance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_attacks["Attack exercises"]
  node_recon["APID reconnaissance"]
  node_eavesdrop["Eavesdropping<br/>[pwnsat_lora_rx.py]"]
  node_fuzz["Crash fuzzing"]
  node_injection["Command injection"]
  node_gps["GPS spoofing"]
  node_gs_auth["Ground auth spoofing"]
  node_replay["Packet replay<br/>[06_replay_rf.py]"]
  node_reset["Reset attack<br/>[07_resetc_rf.py]"]
end

subgraph group_host["Attack tooling"]
  node_packet_tools["Packet toolkit<br/>[pwnsat_packets.py]"]
  node_usb_link["USB transport<br/>[flatsat_usb.py]"]
  node_radio_tx["LoRa transmitter<br/>[pwnsat_lora_tx.py]"]
  node_radio_rx["RTL-SDR receiver"]
  node_cat_rx["CatSniffer receiver"]
end

subgraph group_comms["Firmware communications"]
  node_firmware["Command and mission worker<br/>[worker.cpp]"]
  node_spp["Space packet protocol<br/>[spp.cpp]"]
  node_secure["Secure link<br/>[secure_link.cpp]"]
  node_uplink["RF uplink<br/>[ruplink.cpp]"]
  node_downlink["RF downlink<br/>[rdownlink.cpp]"]
  node_usb_cdc["USB CDC link<br/>[usbCDC.cpp]"]
end

subgraph group_services["Firmware services"]
  node_sensors["Sensor telemetry<br/>[sensors.cpp]"]
  node_spacecan["SpaceCAN payload<br/>[spacecan.cpp]"]
  node_thruster["Thruster control<br/>[thruster.cpp]"]
  node_mission["Mission configuration<br/>[mission.h]"]
  node_led["Status LEDs<br/>[led.cpp]"]
end

node_user(("Engineer / learner"))

node_user -->|"runs"| node_recon
node_user -->|"runs"| node_eavesdrop
node_user -->|"runs"| node_fuzz
node_user -->|"runs"| node_injection
node_user -->|"runs"| node_gps
node_user -->|"runs"| node_gs_auth
node_user -->|"runs"| node_replay
node_user -->|"runs"| node_reset
node_recon -->|"imports"| node_packet_tools
node_recon -->|"imports"| node_radio_tx
node_recon -->|"imports"| node_cat_rx
node_recon -->|"imports"| node_radio_rx
node_fuzz -->|"imports"| node_packet_tools
node_fuzz -->|"imports"| node_radio_tx
node_injection -->|"imports"| node_packet_tools
node_injection -->|"imports"| node_radio_tx
node_gps -->|"imports"| node_packet_tools
node_gps -->|"imports"| node_radio_tx
node_gs_auth -->|"imports"| node_packet_tools
node_gs_auth -->|"imports"| node_radio_tx
node_gs_auth -->|"imports"| node_cat_rx
node_gs_auth -->|"imports"| node_radio_rx
node_replay -->|"imports"| node_packet_tools
node_replay -->|"imports"| node_radio_tx
node_replay -->|"imports"| node_cat_rx
node_replay -->|"imports"| node_radio_rx
node_reset -->|"imports"| node_packet_tools
node_reset -->|"imports"| node_radio_tx
node_radio_rx -->|"uses flowgraph"| node_eavesdrop
node_usb_link -->|"imports"| node_packet_tools
node_firmware -->|"imports"| node_spp
node_firmware -->|"imports"| node_secure
node_firmware -->|"imports"| node_uplink
node_firmware -->|"imports"| node_downlink
node_firmware -->|"imports"| node_usb_cdc
node_firmware -->|"imports"| node_sensors
node_firmware -->|"imports"| node_spacecan
node_firmware -->|"imports"| node_thruster
node_firmware -->|"imports"| node_mission
node_firmware -->|"imports"| node_led

click node_recon "https://github.com/pwnsat/flatsat/blob/main/Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py"
click node_eavesdrop "https://github.com/pwnsat/flatsat/blob/main/Attacks/01_eavesdropping/pwnsat_lora_rx.py"
click node_fuzz "https://github.com/pwnsat/flatsat/blob/main/Attacks/02_fuzzing_crash/02_fuzzing_crash_rf.py"
click node_injection "https://github.com/pwnsat/flatsat/blob/main/Attacks/03_command_injection/03_command_injection_rf.py"
click node_gps "https://github.com/pwnsat/flatsat/blob/main/Attacks/04_gps_spoofing/04_gps_spoofing_rf.py"
click node_gs_auth "https://github.com/pwnsat/flatsat/blob/main/Attacks/05_gs_auth_spoofing/05_gs_auth_spoofing_rf.py"
click node_replay "https://github.com/pwnsat/flatsat/blob/main/Attacks/06_replay/06_replay_rf.py"
click node_reset "https://github.com/pwnsat/flatsat/blob/main/Attacks/07_resetc/07_resetc_rf.py"
click node_packet_tools "https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_packets.py"
click node_usb_link "https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/flatsat_usb.py"
click node_radio_tx "https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_lora_tx.py"
click node_radio_rx "https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_rtlsdr_rx.py"
click node_cat_rx "https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_catsniffer_rx.py"
click node_firmware "https://github.com/pwnsat/flatsat/blob/main/Firmware/worker.cpp"
click node_spp "https://github.com/pwnsat/flatsat/blob/main/Firmware/spp.cpp"
click node_secure "https://github.com/pwnsat/flatsat/blob/main/Firmware/secure_link.cpp"
click node_uplink "https://github.com/pwnsat/flatsat/blob/main/Firmware/ruplink.cpp"
click node_downlink "https://github.com/pwnsat/flatsat/blob/main/Firmware/rdownlink.cpp"
click node_usb_cdc "https://github.com/pwnsat/flatsat/blob/main/Firmware/usbCDC.cpp"
click node_sensors "https://github.com/pwnsat/flatsat/blob/main/Firmware/sensors.cpp"
click node_spacecan "https://github.com/pwnsat/flatsat/blob/main/Firmware/spacecan.cpp"
click node_thruster "https://github.com/pwnsat/flatsat/blob/main/Firmware/thruster.cpp"
click node_mission "https://github.com/pwnsat/flatsat/blob/main/Firmware/mission.h"
click node_led "https://github.com/pwnsat/flatsat/blob/main/Firmware/led.cpp"

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_recon,node_eavesdrop,node_fuzz,node_injection,node_gps,node_gs_auth,node_replay,node_reset toneBlue
class node_packet_tools,node_usb_link,node_radio_tx,node_radio_rx,node_cat_rx toneAmber
class node_firmware,node_spp,node_secure,node_uplink,node_downlink,node_usb_cdc toneMint
class node_sensors,node_spacecan,node_thruster,node_mission,node_led toneRose
class node_user toneIndigo
```

## Components

### Attack exercises

- [APID reconnaissance](https://github.com/pwnsat/flatsat/blob/main/Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py): `Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py`
- [Eavesdropping](https://github.com/pwnsat/flatsat/blob/main/Attacks/01_eavesdropping/pwnsat_lora_rx.py): `Attacks/01_eavesdropping/pwnsat_lora_rx.py`
- [Crash fuzzing](https://github.com/pwnsat/flatsat/blob/main/Attacks/02_fuzzing_crash/02_fuzzing_crash_rf.py): `Attacks/02_fuzzing_crash/02_fuzzing_crash_rf.py`
- [Command injection](https://github.com/pwnsat/flatsat/blob/main/Attacks/03_command_injection/03_command_injection_rf.py): `Attacks/03_command_injection/03_command_injection_rf.py`
- [GPS spoofing](https://github.com/pwnsat/flatsat/blob/main/Attacks/04_gps_spoofing/04_gps_spoofing_rf.py): `Attacks/04_gps_spoofing/04_gps_spoofing_rf.py`
- [Ground auth spoofing](https://github.com/pwnsat/flatsat/blob/main/Attacks/05_gs_auth_spoofing/05_gs_auth_spoofing_rf.py): `Attacks/05_gs_auth_spoofing/05_gs_auth_spoofing_rf.py`
- [Packet replay](https://github.com/pwnsat/flatsat/blob/main/Attacks/06_replay/06_replay_rf.py): `Attacks/06_replay/06_replay_rf.py`
- [Reset attack](https://github.com/pwnsat/flatsat/blob/main/Attacks/07_resetc/07_resetc_rf.py): `Attacks/07_resetc/07_resetc_rf.py`

### Attack tooling

- [Packet toolkit](https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_packets.py): `Attacks/lib/pwnsat_packets.py`
- [USB transport](https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/flatsat_usb.py): `Attacks/lib/flatsat_usb.py`
- [LoRa transmitter](https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_lora_tx.py): `Attacks/lib/pwnsat_lora_tx.py`
- [RTL-SDR receiver](https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_rtlsdr_rx.py): `Attacks/lib/pwnsat_rtlsdr_rx.py`
- [CatSniffer receiver](https://github.com/pwnsat/flatsat/blob/main/Attacks/lib/pwnsat_catsniffer_rx.py): `Attacks/lib/pwnsat_catsniffer_rx.py`

### Firmware communications

- [Command and mission worker](https://github.com/pwnsat/flatsat/blob/main/Firmware/worker.cpp): `Firmware/worker.cpp`
- [Space packet protocol](https://github.com/pwnsat/flatsat/blob/main/Firmware/spp.cpp): `Firmware/spp.cpp`
- [Secure link](https://github.com/pwnsat/flatsat/blob/main/Firmware/secure_link.cpp): `Firmware/secure_link.cpp`
- [RF uplink](https://github.com/pwnsat/flatsat/blob/main/Firmware/ruplink.cpp): `Firmware/ruplink.cpp`
- [RF downlink](https://github.com/pwnsat/flatsat/blob/main/Firmware/rdownlink.cpp): `Firmware/rdownlink.cpp`
- [USB CDC link](https://github.com/pwnsat/flatsat/blob/main/Firmware/usbCDC.cpp): `Firmware/usbCDC.cpp`

### Firmware services

- [Sensor telemetry](https://github.com/pwnsat/flatsat/blob/main/Firmware/sensors.cpp): `Firmware/sensors.cpp`
- [SpaceCAN payload](https://github.com/pwnsat/flatsat/blob/main/Firmware/spacecan.cpp): `Firmware/spacecan.cpp`
- [Thruster control](https://github.com/pwnsat/flatsat/blob/main/Firmware/thruster.cpp): `Firmware/thruster.cpp`
- [Mission configuration](https://github.com/pwnsat/flatsat/blob/main/Firmware/mission.h): `Firmware/mission.h`
- [Status LEDs](https://github.com/pwnsat/flatsat/blob/main/Firmware/led.cpp): `Firmware/led.cpp`

### Other components

- **Engineer / learner**

## Connections

- Engineer / learner → APID reconnaissance: runs (evidence: `README.md`)
- Engineer / learner → Eavesdropping: runs (evidence: `README.md`)
- Engineer / learner → Crash fuzzing: runs (evidence: `README.md`)
- Engineer / learner → Command injection: runs (evidence: `README.md`)
- Engineer / learner → GPS spoofing: runs (evidence: `README.md`)
- Engineer / learner → Ground auth spoofing: runs (evidence: `README.md`)
- Engineer / learner → Packet replay: runs (evidence: `README.md`)
- Engineer / learner → Reset attack: runs (evidence: `README.md`)
- APID reconnaissance → Packet toolkit: imports (evidence: `Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py`)
- APID reconnaissance → LoRa transmitter: imports (evidence: `Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py`)
- APID reconnaissance → CatSniffer receiver: imports (evidence: `Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py`)
- APID reconnaissance → RTL-SDR receiver: imports (evidence: `Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py`)
- Crash fuzzing → Packet toolkit: imports (evidence: `Attacks/02_fuzzing_crash/02_fuzzing_crash_rf.py`)
- Crash fuzzing → LoRa transmitter: imports (evidence: `Attacks/02_fuzzing_crash/02_fuzzing_crash_rf.py`)
- Command injection → Packet toolkit: imports (evidence: `Attacks/03_command_injection/03_command_injection_rf.py`)
- Command injection → LoRa transmitter: imports (evidence: `Attacks/03_command_injection/03_command_injection_rf.py`)
- GPS spoofing → Packet toolkit: imports (evidence: `Attacks/04_gps_spoofing/04_gps_spoofing_rf.py`)
- GPS spoofing → LoRa transmitter: imports (evidence: `Attacks/04_gps_spoofing/04_gps_spoofing_rf.py`)
- Ground auth spoofing → Packet toolkit: imports (evidence: `Attacks/05_gs_auth_spoofing/05_gs_auth_spoofing_rf.py`)
- Ground auth spoofing → LoRa transmitter: imports (evidence: `Attacks/05_gs_auth_spoofing/05_gs_auth_spoofing_rf.py`)
- Ground auth spoofing → CatSniffer receiver: imports (evidence: `Attacks/05_gs_auth_spoofing/05_gs_auth_spoofing_rf.py`)
- Ground auth spoofing → RTL-SDR receiver: imports (evidence: `Attacks/05_gs_auth_spoofing/05_gs_auth_spoofing_rf.py`)
- Packet replay → Packet toolkit: imports (evidence: `Attacks/06_replay/06_replay_rf.py`)
- Packet replay → LoRa transmitter: imports (evidence: `Attacks/06_replay/06_replay_rf.py`)
- Packet replay → CatSniffer receiver: imports (evidence: `Attacks/06_replay/06_replay_rf.py`)
- Packet replay → RTL-SDR receiver: imports (evidence: `Attacks/06_replay/06_replay_rf.py`)
- Reset attack → Packet toolkit: imports (evidence: `Attacks/07_resetc/07_resetc_rf.py`)
- Reset attack → LoRa transmitter: imports (evidence: `Attacks/07_resetc/07_resetc_rf.py`)
- RTL-SDR receiver → Eavesdropping: uses flowgraph (evidence: `Attacks/lib/pwnsat_rtlsdr_rx.py`)
- USB transport → Packet toolkit: imports (evidence: `Attacks/lib/flatsat_usb.py`)
- Command and mission worker → Space packet protocol: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → Secure link: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → RF uplink: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → RF downlink: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → USB CDC link: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → Sensor telemetry: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → SpaceCAN payload: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → Thruster control: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → Mission configuration: imports (evidence: `Firmware/worker.cpp`)
- Command and mission worker → Status LEDs: imports (evidence: `Firmware/worker.cpp`)
