hackrf - Moses Yebei

The Problem

Software-defined radio (SDR) platforms require tight integration between firmware, FPGA gateware, host drivers, and hardware designs. Most SDR repos scatter these layers across separate projects with inconsistent build systems, making it difficult to reproduce a working radio from source or contribute changes that span the stack.

What This Does

This repository is the official HackRF source tree—a low-cost, open-source SDR platform. It contains five self-contained projects: firmware/ (278 files, C and Python for the LPC43xx MCU and FPGA), host/ (27 files, C libraries and CLI tools like hackrf_transfer.c), hardware/ (121 files, KiCad schematics and board layouts), ci-scripts/ (10 files, Jenkins and test harnesses), and tools/ (6 files, utilities). The docs/ folder (89 files) holds Sphinx-based documentation covering both hardware and software.

The firmware is the largest component—126 code files spanning MCU firmware, FPGA gateware (Python-generated Verilog), and a CPLD debug interface. The host stack provides a userspace library (libhackrf) and command-line tools for streaming IQ samples.

How It Is Wired

Execution starts in one of three places depending on the target: firmware/ builds via CMake (firmware/CMakeLists.txt), the host tools compile from host/hackrf-tools/src/hackrf_transfer.c, and CI orchestration begins at Jenkinsfile or .github/workflows/build.yml. The firmware's USB command interface routes through firmware/common/usb.c, which carries 11 unresolved TODO markers and is a central hub for device control. The FPGA gateware in firmware/fpga/ uses Python scripts to generate Verilog, with interface/ modules (spi, sgpio, max586x) handling chip-level communication.

The import graph shows 41 internal Python modules with only 5 edges—the firmware's FPGA tooling is largely self-contained. The most connected modules (firmware/fpga/interface/__init__ and firmware/fpga/util/__init__) are pure aggregators with no inbound dependencies, so changing them is low-risk. The hardware design files in hardware/ are not code and have no runtime wiring.

How To Use It

Setup: Build the host tools from source. The repo uses CMake for firmware and a Makefile-based flow for host tools. A Dockerfile (based on ubuntu:22.04) provides a build environment.

git clone https://github.com/moses-y/hackrf
cd hackrf/host
mkdir build && cd build
cmake .. && make

Configuration: No runtime configuration files are required. Firmware flashing uses hackrf_spiflash from the host tools.

Running it: The primary CLI is hackrf_transfer, which streams IQ samples to/from the device:

hackrf_transfer -r capture.iq -f 915 -s 8000000

This captures 8 MS/s at 915 MHz to capture.iq.

Real-World Use

A typical application: spectrum monitoring. Capture a wideband sweep, process it offline, and detect signals of interest.

hackrf_transfer -r sweep.iq -f 2400 -s 20000000 -n 50000000
# Process sweep.iq with GNU Radio or numpy

Code Health & Issues

Static analysis (not manual review) found 52 issues: 23 high, 26 medium, 3 low. Key findings:

High – Deep nesting (29 occurrences) in firmware/fpga/interface/spi.py and firmware/common/clock_gen.c, with max indentation depth of 8.
High – Duplicated 6-line blocks (1,424 repetitions across 200 files), notably in ci-scripts/hackrf_pro_test.py and firmware/common/adc.c.
High – Oversized files: firmware/common/rad1o/ubuntu18.c at 3,300 lines; host/hackrf-tools/src/hackrf_transfer.c similarly large.
Med – Files opened without context managers in firmware/tools/dump_cgu.py and firmware/tools/edit-font.py; broad exception handling in CI scripts; high branching density in firmware/common/picoprintf.c.
Low – TODO/FIXME markers: 3 in CI scripts, 11 in firmware/common/usb.c.

SDLC observations: CI exists (Jenkins + GitHub Actions), tests are present (15 files), and a license is included. However, the Docker base image (ubuntu:22.04) is unpinned, GitHub Actions use mutable tags (lukka/get-cmake@latest), no dependency update bot is configured, and no vulnerability scanning gates PRs.

The Bottom Line

This is the reference implementation of a widely-used SDR platform—the hardware and firmware are battle-tested across thousands of deployed units. The codebase shows its age in file size and nesting, but the architecture is sound and well-documented. Use it if you need to extend HackRF firmware, build custom FPGA gateware, or integrate the host API into your own tooling.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

551 files

C105
C/C++ Header101
Python41
reStructuredText38
YAML11
Shell10

Docker

Module dependencies

The 10 most depended-upon modules of 41, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_mware_fpga_interface_max586x["max586x"] n1_irmware_fpga_interface_sgpio["sgpio"] n2_firmware_fpga_interface_spi["spi"] n3_firmware_fpga_util__stream["_stream"] n4_firmware_fpga_util_lfsr["lfsr"] n5_ware_fpga_interface___init__["__init__"] n6_firmware_fpga_util___init__["__init__"] n7_ci_scripts_hackrf_pro_test["hackrf_pro_test"] n8_ci_scripts_hackrf_test["hackrf_test"] n9_ci_scripts_test_debug["test-debug"] n5_ware_fpga_interface___init__ --> n0_mware_fpga_interface_max586x n5_ware_fpga_interface___init__ --> n2_firmware_fpga_interface_spi n5_ware_fpga_interface___init__ --> n1_irmware_fpga_interface_sgpio n6_firmware_fpga_util___init__ --> n3_firmware_fpga_util__stream n6_firmware_fpga_util___init__ --> n4_firmware_fpga_util_lfsr

Dependencies

2 of 4 declared dependencies are a major version behind. Resolved 4 of 4 against the registry.

Package	Declared	Latest	Behind
`sphinx`	==7.2.6	9.1.0	2 major
`sphinx_rtd_theme`	==2.0.0	3.1.0	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds docs/requirements.txt

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh5 occurrences

.github/workflows

lukka/get-cmake@latest, k3DW/setup-msvc@v1, msys2/setup-msys2@v2, carlosperate/arm-none-eabi-gcc-action@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/build.yml

3 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

ubuntu:22.04

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/build.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/build.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.