A realistic CubeSat hacking platform. Build a FlatSat from breadboards and Pi Picos, or run it in a software-only simulator on your laptop. Learn satellite communications security by attacking your own spacecraft.
Try it now → View on GitHub READMESemaeopus models the TT&C link (telemetry, tracking and command) of a real CubeSat closely enough that lessons transfer to flight hardware — yet builds from through-hole modules on a solderless breadboard. The on-air protocol is a deliberately simplified version of CCSDS Space Packet, carried over 2-GFSK on the CC1101 — the same shape of stack flown today.
Build both the satellite and the ground station. Then build a second ground station — the attacker — and watch the same protocol from the wrong end.
Ships at L0 (cleartext, no auth) so attacks are trivial. Bump SECURITY_LEVEL through L1 (HMAC), L2 (HMAC + counter), L3 (AES-CTR + HMAC) as the curriculum progresses.
A UDP-multicast "ether" runs the same firmware as the flight build. Plus a synthetic GFSK IQ recording for the SDR lessons. Start before parts arrive.
433.92 MHz EU ISM or 915 MHz US Part 15.247, with a 17 cm whip and 0 dBm. Reaches across the bench, not your neighbour.
Three independent paths. Pick whichever matches the gear you already have.
Virtual satellite + virtual ground stations over UDP. Replay and inject work end-to-end.
$ git clone https://github.com/haxorthematrix/semaeopus
$ cd semaeopus
$ pip install pyserial pytest
$ python -m sim.virtual_satellite &
$ python -m groundstation.operator.gs --sim
op> ping
op> safe
# in another terminal — forge a FORCE_SAFE
$ python -m groundstation.attacker.inject \
--sim --apid 0xFF
A 2.7-second .cu8 recording of a 2-GFSK Semaeopus session, ready for GNU Radio / inspectrum / gqrx.
$ python -m tools.generate_iq
# writes captures/baseline.iq + .jsonl
$ gqrx # File → I/Q file…
# or follow lessons/L02_demod_gnuradio.md
#
# The JSONL oracle has the decoded
# frames — compare against your demod.
~ $35 of through-hole parts. No PCBs, no SMD soldering — breadboard + Dupont wires only. Seven bring-up scripts verify each subsystem before you flash the full firmware.
# BOM: Pi Pico + CC1101 + BME280
# + MPU6050 + INA219 + DS3231
# + SSD1306 OLED + breadboard
$ mpremote connect /dev/ttyACM0 \
run bringup/02_i2c_scan.py
$ mpremote cp -r firmware/satellite/. :/
$ python -m groundstation.operator.gs \
--port /dev/ttyACM1
Three sub-builds. All through-hole or pre-soldered breakouts — no PCB fab, no SMD soldering. Specific Amazon links → · hardware/ folder.
Tier 1 (~ $45) — sufficient for L00–L09:
Tier 2 (~ $360 total) — unlocks L10 jamming + GPS spoofing:
Python 3.11+ is the only hard requirement. Everything else is by path.
pyserial, pytest. pip install pyserial pytest.
textual, rich. Adds the live operator UI with link status + telemetry panes.
gnuradio ≥ 3.10, gr-satellites, rtl-sdr, optionally hackrf, gqrx, inspectrum.
pycryptodome for AES-128-CTR on the host (MicroPython has it built in).
mpremote to push code to the Pi Pico, plus a MicroPython UF2 (1.22+).
macOS 14+, Ubuntu 22.04+. Windows works via WSL2 for the GNU Radio path; native PowerShell for everything else.
Same protocol on every path. The simulator swaps the CC1101 PHY for a UDP socket; everything above that is bit-identical.
┌─────────────────┐ ┌─────────────────────┐
│ "SATELLITE" │ │ OPERATOR GROUND │
│ (FlatSat) │ <── 433/915 MHz ──> │ STATION │
│ │ ISM downlink │ │
│ Pi Pico + CC1101│ ISM uplink │ Pi Pico + CC1101 │
│ + housekeeping │ │ ↕ USB-serial │
│ sensors & disp │ │ Laptop: gs-operator │
└─────────────────┘ └─────────────────────┘
▲
│ ┌─────────────────────┐
│ │ ATTACKER STATION │
└──── eavesdrop / inject ─────────►│ │
│ RTL-SDR v3 (RX) │
│ + Pi Pico + CC1101 │
│ or HackRF (TX/RX) │
│ Laptop: gs-attacker │
│ + GNU Radio │
└─────────────────────┘
A 12-step path from "see the signal" to "take over an authenticated link". All 13 lessons (L00–L12) are written and runnable today.
| # | Title | Sim only? |
|---|---|---|
| L00 | Build & first beacon | partial |
| L01 | Spectrum survey | use IQ |
| L02 | Demod in GNU Radio | use IQ |
| L03 | Frame sync & CRC | use IQ |
| L04 | Telemetry decode | yes |
| L05 | Replay attack | yes |
| L06 | Command injection | yes |
| L07 | HMAC bypass via replay (L1) | yes |
| L08 | Counter-bound HMAC (L2) | yes |
| L09 | Timing side-channel — recovers full HMAC tag | yes |
| L10 | Encryption + jam & replay | partial |
| L11 | Beacon spoofing | yes |
| L12 | Capstone | yes |
Defaults are 0 dBm on 433.920 MHz with a 17 cm whip — within EU/R1 ISM limits and an order of magnitude below US Part 15. Switch to 915 MHz for US compliance.
No external power amplifiers. No transmissions on amateur satellite frequencies (435–438 MHz UHF).
Practice attacks only on systems you own, or with explicit written permission. The point of Semaeopus is to make you better at defending real spacecraft — not to provide tooling for harming them.