The Problem

The repository contains 137 files and 38 source files with no test suite, no CI/CD pipeline, and no licence file, meaning any change ships without signal that existing behaviour holds and the code’s redistribution rights are undefined.

What This Does

FlatSat is a hardware‑based aerospace cybersecurity research platform. The Attacks/ directory holds eight attack modules (00‑07), each provided in both RF (HackRF/RTL‑SDR) and USB variants; e.g. Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py and 00_recon_apid_enum_usb.py. Entry‑point main in Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py:134 reaches 30 functions and drives the recon flow. The Firmware/ folder contains the vulnerable‑by‑design RP2040 firmware (Firmware/firmware.ino, worker.cpp with 1470 lines) and headers (led.cpp, rdownlink.cpp). Eight attack scripts exercise firmware flaws such as command injection, fuzzing, and reset sequences. Python modules import from Attacks/lib/ (e.g. pwnsat_lora_rx.py, pwnsat_rtlsdr_rx.py) and call shared helpers like _try_soapy_call (4 call sites) and _cmd (4 call sites).

How It Is Wired

Execution starts at four entry points: main (Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py:134), run (Attacks/01_eavesdropping/pwnsat_rx_bridge.py:193), start (pwnsat_rx_bridge.py:152), and setup (pwnsat_rx_bridge.py:133). The internal call graph resolves 87 edges; key hubs are _try_soapy_call (4 callers), _cmd (4), transmit_packet (3), and build_command_packet (3). Paths that leave the process: main → transmit triggers subprocess.run and deletes hackrf_iq_path; start → file_open creates output‑file directories via Path(...).parent.mkdir. The most connected modules have zero incoming/outgoing import edges, indicating a flat dependency graph with no circular modules.

How To Use It

  • Firmware build: use PlatformIO as defined in Firmware/platformio.ini; run platformio run to compile and platformio run -t upload to flash the RP2040.
  • Python attacks: scripts are ready to run with a Python 3 interpreter; no setup.py or requirements.txt is present, but Attacks/lib/require_gnuradio.py lists GNU Radio dependencies. Install any missing packages from that file or the wiki.
  • Running an attack: invoke the desired entry point directly, e.g. python Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py. Consult the FlatSat Wiki for step‑by‑step hardware setup, RF hardware configuration, and environment variables (e.g., hackrf device paths).

Real‑World Use

A researcher can plug a HackRF One into a workstation, flash the FlatSat firmware, and run Attacks/02_fuzzing_crash/02_fuzzing_crash_rf.py to send malformed LoRa packets and observe firmware crashes—all within the ISM bands (433 MHz/915 MHz) the platform documents. The same workflow applies to USB‑based attacks by switching the variant suffix (_usb.py). This provides a safe, reproducible sandbox for testing exploit primitives that mirror real satellite‑subsystem failures.

Code Health & Issues

  • Measured findings (static analysis, 37 total): 16 high, 21 medium, 0 low, 5 distinct kinds.
  • Deep nesting x32 – max indentation depth 12 in Firmware/led.cpp, Firmware/rdownlink.cpp, Firmware/rdownlink.h.
  • Duplicated code blocks – 201 repeated 6‑line blocks across 22 files including Attacks/00_recon_apid_enum/00_recon_apid_enum_rf.py and 00_recon_apid_enum_usb.py.
  • Oversized file – Firmware/worker.cpp at 1470 lines.
  • File opened without context manager – Attacks/01_eavesdropping/pwnsat_rx_bridge.py uses bare open(...).
  • Broad exception handling x2 – Attacks/07_resetc/07_resetc_rf.py and 07_resetc_usb.py have bare except clauses.
  • SDLC observations (from repository hygiene):
  • High – No licence file at repository root; redistribution rights undefined.
  • High – No test files; 38 source files have zero test coverage.
  • High – No CI/CD configuration; every merge runs untested.

The Bottom Line

FlatSat offers a concrete, hardware‑level sandbox for aerospace cybersecurity experimentation, with a clear set of documented attacks and a well‑structured firmware base. However, the lack of a licence, test suite, and CI pipeline means production‑grade changes carry significant risk, and the codebase suffers from deep nesting, duplicated logic, and oversized files that hinder maintenance. It is well‑suited for learning and prototyping, but any deployment or integration effort should first address the identified health findings.