If you’ve just bought a router, smart camera, or any gadget that hums with Linux inside, you’re holding more than hardware. You’re holding a bundle of rights under the GNU General Public License. The GPL says you’re entitled to the complete, buildable source code that makes the device tick. Yet plenty of manufacturers still ship products without it—sometimes because they’re sloppy, sometimes because they’re hoping nobody asks. A careful audit cuts through the fog. Here’s how to go from blinking lights to a clear picture of whether your device respects your software freedom.
Understanding the GPL Compliance Obligations
Both GPLv2 and GPLv3 demand that anyone distributing binary software hand over the “complete corresponding source” when asked. For an embedded box, that’s not just a tarball of the Linux kernel. It means the exact source tree used to compile the kernel, its loadable modules, any GPL-licensed user-space programs, plus the build scripts, toolchain details, and configuration files needed to recompile and install the whole stack. A written offer that’s good for three years can stand in for a direct download, but a dead link or a bare kernel dump with no build instructions doesn’t cut it. In the wild, non-compliance usually looks like missing kernel source, stripped-out build scripts, or proprietary blobs that should have been GPL’d.
Step 1: Initial Reconnaissance and Firmware Extraction
Start by figuring out what’s actually running on the device. If you can get a shell—via serial console, SSH, or ADB—run uname -a to grab the kernel version and build timestamp. Peek at /proc/version to see which compiler was used. On OpenWrt-style systems, opkg list-installed spills the package list; on Debian-based ones, dpkg -l does the same. Jot down every GPL-licensed binary you spot: bash, iptables, wpa_supplicant, and so on.
If the device is locked tight and you can’t get a shell, go after the firmware update file. Download it from the vendor’s site, then let binwalk sniff out the filesystems. Use dd to carve them out and unsquashfs to unpack. Mount the root filesystem and start cataloging: file tells you what’s an ELF binary, readelf gives you the gritty details. This is the raw material for everything that follows.
Step 2: Verifying Kernel Source Availability
The kernel is the heavyweight GPL component in almost every embedded device, so start there. Hunt through the vendor’s support page or documentation for a source download. If you find a tarball, don’t trust it yet—compare it against what’s actually running. First, try to pull the kernel config from the device: look for /proc/config.gz or /boot/config-*. If those are missing, scripts/extract-ikconfig can yank the config out of a raw kernel image. Build the vendor’s source with that config, then compare the resulting System.map or module symbol tables. Mismatches here are a dead giveaway that the source doesn’t match the binary.
Keep a sharp eye on kernel modules. The GPL treats any module that hooks into the kernel as a derivative work, so binary-only modules are a red flag. Check /proc/sys/kernel/tainted—a non-zero value often points to proprietary modules or other license shenanigans. Some vendors try to hide behind “shim” layers, but if the module calls kernel functions, the taint flag usually tells the story.
Step 3: Auditing User-Space GPL Components
The kernel isn’t the only thing under the GPL. User-space tools like bash, tar, or grep are often GPL-licensed, and the vendor must provide source for every one of them. Run strings on a binary to fish out copyright notices and license references. If you find a GPL binary, cross-check its version string or build ID against the source the vendor offers. No source at all? Try to match the binary against public releases by comparing symbol tables or disassembly with objdump or radare2. Modified GPL programs are a special case—if the vendor patched something, they have to give you the patched source, not just a link to the upstream repo. Look for custom strings or odd behavior that hints at local changes.
Step 4: Analyzing Build Scripts and Toolchains
“Complete corresponding source” means you should be able to rebuild the binaries yourself. That takes more than a kernel tree—it takes the right cross-compiler, build scripts, and any third-party libraries that were linked in. When you get a source drop, look for a README or Makefile that spells out the build environment. If it doesn’t compile with standard toolchains, the vendor is likely holding back. Try to reproduce the build. Missing headers, wrong architecture flags, or absent library sources are all signs of a half-hearted compliance effort. The same rules apply to GPL-licensed bootloaders like U-Boot. Pull the bootloader from flash or the firmware image and check if the vendor provides matching source.
Step 5: Documenting and Reporting Findings
Once you’ve done the legwork, write it up. A solid audit report lists every GPL component you found, the binary version, the source version the vendor provided, and any gaps you uncovered. Include file hashes, build logs, and screenshots—anything that makes your case concrete. If the vendor comes up short, send a formal request for the missing source, citing the specific GPL version and the device model. Give them a reasonable window to respond, usually 30 days. If they stonewall, you can escalate to groups like the Software Freedom Conservancy or the Free Software Foundation, both of which run enforcement programs. Publishing your findings can also nudge a vendor toward compliance, but think through your own legal position before you go public.
Common Pitfalls and How to Avoid Them
One easy trap is assuming a source link on the vendor’s website means you’re done. Always verify that the source matches the exact firmware version on your device. Another blind spot: peripheral chips. A Wi-Fi module might run its own tiny Linux instance with proprietary drivers. Check for separate firmware blobs and demand source for those too. Then there’s “tivoization”—a device that uses GPLv3 code but locks the hardware so you can’t run modified software. That’s a direct violation of GPLv3’s anti-tivoization clause. Look for secure boot keys or signed firmware requirements that block user modifications. If the hardware fights back, the vendor has some explaining to do.
Tools of the Trade
A handful of open-source tools make the audit less painful. Binwalk is your first stop for firmware analysis and extraction. Buildroot and Yocto let you recreate build environments for side-by-side comparison. FOSSology scans source trees for license compliance. Diffoscope digs deep into binary and source differences. For kernel work, vmlinux-to-elf turns raw kernel images into ELF files that disassemblers can handle. One practical tip: use the same toolchain version the vendor used when you try to reproduce a build. Compiler optimizations can make identical source produce different binaries, and you don’t want to chase ghosts.
FAQ
What if the vendor provides source code but it doesn’t compile?
That’s a violation, plain and simple. The GPL requires the “complete corresponding source code,” which includes everything needed to build the software. If the source won’t compile, document the errors and ask for the missing pieces. Common culprits: missing Makefile targets, absent third-party libraries, or toolchain paths that point to the vendor’s internal server.
How do I handle devices that use proprietary kernel modules?
Proprietary kernel modules are generally considered derivative works of the Linux kernel, so they should be GPL-licensed. Some vendors argue that modules using only exported kernel symbols aren’t derivatives, but that’s a legal gray area. For your audit, note any proprietary modules and check if the vendor provides source. If not, flag it as a potential violation and look at the kernel’s MODULE_LICENSE macro to see what license the module declares.
Can I audit a device without physical access?
You can, if the vendor distributes firmware images online. Download the firmware, extract it with binwalk, and analyze the contents. But physical access gives you a lot more: you can verify the running system directly, capture live kernel messages, and spot binaries that only load at runtime. For a thorough audit, having the device in hand is better, but it’s not always a requirement.
What is the difference between GPLv2 and GPLv3 compliance?
GPLv3 adds explicit anti-tivoization rules (the hardware must let you run modified software) and patent grant provisions. If a device uses GPLv3 code, check for secure boot restrictions that block custom firmware. Also, the vendor has to provide installation information for modified versions. GPLv2 doesn’t have these requirements, but many devices mix both licenses, so you’ll need to identify which components fall under which version.