Install FANGS: Build from Source on Linux

FANGS has no pre-built releases — the eBPF sensor must be compiled against kernel type information extracted from the machine it will run on. This means every build is host-specific: the vmlinux.h header generated during make vmlinux encodes the exact struct layouts of your running kernel, and the compiled BPF object files are linked to those layouts. The good news is that the build is fully automated by a single make all invocation once prerequisites are satisfied.

Prerequisites

Linux Kernel

FANGS requires a kernel with BTF (BPF Type Format) enabled. BTF ships in most distribution kernels since 5.8 and is how bpftool extracts the vmlinux.h type definitions that the eBPF C code includes.

The build will fail with /sys/kernel/btf/vmlinux not readable — kernel may lack BTF if your kernel was compiled without CONFIG_DEBUG_INFO_BTF=y. Verify with test -r /sys/kernel/btf/vmlinux && echo OK.

Check your kernel version and BTF availability:

uname -r                          # need 5.8+
test -r /sys/kernel/btf/vmlinux && echo "BTF OK" || echo "BTF missing"

Required Tools

Tool	Minimum version	Purpose
`clang`	14+	Compiles the eBPF C programs to BPF bytecode
`bpftool`	5.13+	Dumps `vmlinux.h` from the host BTF at `/sys/kernel/btf/vmlinux`
`go`	1.26.3+	Builds the four Go binaries (go.mod declares `go 1.26.3`)
`docker`	20.10+	Runner launches package sandboxes via the Docker daemon
`git`	any	Clone the repository

sudo apt-get install -y clang bpftool golang-go docker.io

The Go module path is github.com/irchaosclub/FANGS and the module file requires go 1.26.3. If your distribution ships an older Go toolchain, download a recent release from go.dev/dl.

Clone the Repository

git clone https://github.com/irchaosclub/FANGS.git
cd FANGS

Install Git Hooks (Recommended)

The repository ships a gofmt pre-commit hook. Install it once per clone so every commit is automatically format-checked before it leaves your workstation:

make install-hooks

✓ git hooks now sourced from ./githooks/
  pre-commit

This runs git config core.hooksPath githooks — it doesn’t modify your global git config.

Build Steps

The Makefile has four primary build targets that must run in order. make all chains them automatically.

Step 1 — Generate `vmlinux.h`

make vmlinux

Runs bpftool btf dump file /sys/kernel/btf/vmlinux format c and writes the result to internal/runner/sensor/bpf/vmlinux.h. This file is not checked into the repository — it is generated fresh on each build host to match the local kernel’s struct layouts exactly.

vmlinux.h is host-specific. Never copy it between machines with different kernel versions. Re-run make vmlinux after any kernel upgrade.

Step 2 — Compile eBPF Programs and Emit Go Bindings

make generate

Uses clang to compile the eBPF C source files into BPF bytecode, then runs bpf2go (via go generate) to emit Go binding files (*_bpfel.go for little-endian architectures). These generated .go files are also excluded from the repository by .gitignore.

Step 3 — Build Go Binaries

make build

Compiles four binaries into ./bin/ using go build -trimpath:

Binary	Path	Description
`fangs-orchestrator`	`bin/fangs-orchestrator`	Control-plane: API, watcher, differ, notifier, UI
`fangs-runner`	`bin/fangs-runner`	Execution-plane: eBPF sensor + Docker sandboxes
`fangs`	`bin/fangs`	Operator CLI
`sensor-smoketest`	`bin/sensor-smoketest`	Development tool for probe verification

One-Shot Build

In practice, run everything together:

Install prerequisites

Install clang, bpftool, go, and docker for your distribution (see the table above).

Clone and enter the repository

git clone https://github.com/irchaosclub/FANGS.git
cd FANGS

Install git hooks

make install-hooks

Build everything

make all

This runs generate → build → test in sequence. A successful run ends with all tests passing and four binaries in ./bin/.

Verify the binaries

ls -lh bin/

bin/fangs
bin/fangs-orchestrator
bin/fangs-runner
bin/sensor-smoketest

Makefile Target Reference

Target	What it does
`make vmlinux`	Generates `vmlinux.h` from `/sys/kernel/btf/vmlinux` via `bpftool`
`make generate`	Compiles eBPF C and emits `bpf2go` Go bindings (depends on `vmlinux`)
`make build`	Builds all four Go binaries into `./bin/` (depends on `generate`)
`make test`	Runs all Go tests with `-race -count=1` (depends on `generate`)
`make lint`	Checks `gofmt` formatting and runs `go vet`
`make all`	`generate` + `build` + `test`
`make clean`	Removes `./bin/`, `vmlinux.h`, and all generated BPF object and binding files
`make install-hooks`	Points git at `./githooks/` for the `gofmt` pre-commit hook
`make help`	Prints a one-line description of each target

Key Dependencies

FANGS’s Go module (github.com/irchaosclub/FANGS) has two direct runtime dependencies:

Package	Version	Role
`github.com/cilium/ebpf`	v0.21.0	eBPF program loading, map access, `bpf2go` code generation
`modernc.org/sqlite`	v1.50.1	Pure-Go SQLite driver for the default storage backend

Additional indirect dependencies include github.com/jackc/pgx/v5 (PostgreSQL), github.com/prometheus/client_golang (metrics), and gopkg.in/yaml.v3 (config parsing). All dependencies are pinned in go.sum.

Smoke-Testing the Sensor

After building, verify that the eBPF probes load and fire on your kernel before starting the full stack:

sudo bin/sensor-smoketest

A successful run prints probe attachment confirmations and then exits. If it fails, the error message will indicate whether the issue is a missing kernel feature, an insufficient capability, or a BTF mismatch.

sensor-smoketest requires the same privileges as the runner (CAP_BPF or root). If you get a permission error, run it with sudo or grant the capability with sudo setcap cap_bpf+ep bin/sensor-smoketest.

Runner Privilege Requirements

The runner needs two things that require elevated privileges:

CAP_BPF — to load and attach eBPF programs.
Docker socket access — to launch and tear down sandboxes (/var/run/docker.sock).

The simplest approach is sudo ./bin/fangs-runner. For production deployments, create a dedicated service account with only the required capabilities. A systemd unit example is available on the Installation wiki page.

Rebuilding After a Kernel Upgrade

After any kernel upgrade, the host BTF layout changes. Rebuild from vmlinux to stay consistent:

make clean
make all

Get Started

Architecture

Configuration

Operations

Security

Install FANGS: Build from Source on Linux

Prerequisites

Linux Kernel

Required Tools

Clone the Repository

Install Git Hooks (Recommended)

Build Steps

Step 1 — Generate `vmlinux.h`

Step 2 — Compile eBPF Programs and Emit Go Bindings

Step 3 — Build Go Binaries

One-Shot Build

Makefile Target Reference

Key Dependencies

Smoke-Testing the Sensor

Runner Privilege Requirements

Rebuilding After a Kernel Upgrade

Build docs developers (and LLMs) love

Get Started

Architecture

Configuration

Operations

Security

Documentation Index

​Prerequisites

​Linux Kernel

​Required Tools

​Clone the Repository

​Install Git Hooks (Recommended)

​Build Steps

​Step 1 — Generate vmlinux.h

​Step 2 — Compile eBPF Programs and Emit Go Bindings

​Step 3 — Build Go Binaries

​One-Shot Build

​Makefile Target Reference

​Key Dependencies

​Smoke-Testing the Sensor

​Runner Privilege Requirements

​Rebuilding After a Kernel Upgrade

Build docs developers (and LLMs) love

Prerequisites

Linux Kernel

Required Tools

Clone the Repository

Install Git Hooks (Recommended)

Build Steps

Step 1 — Generate `vmlinux.h`

Step 2 — Compile eBPF Programs and Emit Go Bindings

Step 3 — Build Go Binaries

One-Shot Build

Makefile Target Reference

Key Dependencies

Smoke-Testing the Sensor

Runner Privilege Requirements

Rebuilding After a Kernel Upgrade