GitHub - boratanrikulu/gobee: Write your BPF programs in Go, not C. gobee transpiles a Go subset to BPF C and generates typed cilium/ebpf bindings. · GitHub

Skip to content

Navigation Menu

Toggle navigation

Sign in

Appearance settings

PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

boratanrikulu

/

gobee

Public

Notifications
You must be signed in to change notification settings

Fork
1

Star
214

Code

Issues
0

Pull requests
0

Actions

Projects

Security and quality
0

Insights

Additional navigation options

Code

Issues

Pull requests

Actions

Projects

Security and quality

Insights

boratanrikulu/gobee

 mainBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History24 Commits24 Commits.github/workflows.github/workflows  bpfbpf  cmd/gobeecmd/gobee  diagnosediagnose  docsdocs  e2ee2e  exampleexample  internal/transpileinternal/transpile  testdatatestdata  tools/genhelperstools/genhelpers  .gitattributes.gitattributes  .gitignore.gitignore  LICENSELICENSE  MakefileMakefile  README.mdREADME.md  go.modgo.mod  go.sumgo.sum  View all filesRepository files navigationREADMEMIT licensegobee
Write your BPF programs in Go, not C. gobee transpiles a strict subset of Go into BPF C, generates typed Go bindings for the userspace side, and gates loads against the running kernel.
The Go ecosystem has solid userspace tooling for BPF. The kernel side has always ended with "now write your program in C." Aya brought eBPF to Rust by writing a new BPF backend in rustc. gobee gets there a different way: by transpiling to C and reusing clang's mature backend.
A Go file in, a BPF program out
A tracepoint that streams every execve to userspace via a ringbuf:

Your input (Go)
What gobee emits (BPF C)

//go:build ignore

package main

import "github.com/boratanrikulu/gobee/bpf"

//bpf:license GPL

type Event struct {
Pid uint32
Comm [16]byte
}

var Events = bpf.RingBuf[Event]{
MaxEntries: 4096,
}

//bpf:section tracepoint/syscalls/sys_enter_execve
func OnExec(ctx *bpf.ExecveEnterCtx) bpf.TpReturn {
e, ok := Events.Reserve()
if !ok {
return bpf.TpOk
}
e.Pid = bpf.GetCurrentPid()
bpf.GetTaskComm(&e.Comm)
Events.Submit(e)
return bpf.TpOk
}

func main() {}

// Code generated by gobee. DO NOT EDIT.

#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_core_read.h>

char _license[] SEC("license") = "GPL";

struct Event {
__u32 Pid;
__u8 Comm[16];
};

struct {
__uint(type, BPF_MAP_TYPE_RINGBUF);
__uint(max_entries, 4096);
} Events SEC(".maps");

SEC("tracepoint/syscalls/sys_enter_execve")
int OnExec(struct trace_event_raw_sys_enter *ctx) {
struct Event *e = bpf_ringbuf_reserve(
&Events, sizeof(struct Event), 0);
if (!e) {
return 0;
}
e->Pid = (__u32)(
bpf_get_current_pid_tgid() >> 32);
bpf_get_current_comm(&e->Comm, 16);
bpf_ringbuf_submit(e, 0);
return 0;
}

gobee translate --bindings-dir ./bpf ./bpf/src produces both files, plus a sourcemap (events.bpf.c.map) so verifier errors map back to Go lines and a typed bindings file (bpf/events_bindings.go) so the userspace driver writes objs.Events, objs.AttachOnExec(), and decodes ringbuf payloads straight into bpf.Event (the same struct you see above, re-published in Go) instead of stringly-typed coll.Programs["..."] lookups.
The C is readable on purpose. If gobee emits something weird, you can see it. For tracepoints + kprobes + XDP combined into one binary, see example/sysmon/.
How it compares

gobee
C + clang + bpf2go
Aya (Rust)
bpftrace
BCC

Kernel-side language
Go subset
C
Rust
DSL
C

Userspace integration
typed Go bindings + cilium/ebpf
bpf2go
aya-runtime
none
python

CO-RE
✅ via clang
✅
✅ via LLVM
✅
✅

Helper coverage
200 typed Go wrappers
full (write C)
full
limited
full (write C)

Verifier error → source
✅ Go file:line:col
❌ raw C
✅ Rust file:line
❌
partial

Kernel-version gate at load
✅ via bpfvet
manual
manual
n/a
runtime

Toolchain deps
Go + clang
clang + bpf2go
rustc + LLVM
bpftrace
python + bcc

Generated artifact
.bpf.o + Go binary
.bpf.o + Go binary
.bpf.o + Rust binary
JIT
JIT

If you're already in a C / libbpf workflow, gobee is not trying to replace it wholesale. It's for cases where you want the kernel side, the userspace side, and the build pipeline all in one Go module.
What's supported today
See docs/status.md for the full matrix (Go subset, statements, expressions, every helper, every map type, every directive). Quick view:

Surface
Coverage

Program types (8)
XDP, tracepoint, kprobe / kretprobe, uprobe / uretprobe, sock_ops, TC, cgroup_skb, LSM

Map types (19)
array, hash, lru_hash, per-CPU variants, bloom_filter, lpm_trie, ringbuf, perf_event_array, prog_array, queue, stack, sk/task/inode storage, devmap/cpumap/xskmap

BPF helpers
~200 typed Go stubs auto-generated from libbpf v1.5.0 headers. The ones exercised by example/helloworld/ and example/sysmon/ are tested in real-kernel CI; the rest are unverified. File an issue if a stub doesn't match the kernel signature

CO-RE
✅ auto-detected. BPF_CORE_READ for kernel-internal struct fields (task_struct, sock, inode); direct ctx->field for UAPI BPF context structs (xdp_md, __sk_buff, bpf_sock_ops). Exercised on Linux 6.x (Ubuntu 24.04 CI); older kernels not yet in the CI matrix

BTF-ready output
✅ emitted C includes vmlinux.h and uses BPF_CORE_READ for kernel-internal field reads, so the BTF clang generates from clang -g carries the right relocations. clang itself stays your responsibility (the example Makefiles show the canonical invocation)

User-defined helpers
✅ top-level Go funcs without //bpf:section are emitted as static __always_inline C functions

Typed Go bindings
✅ Load<Stem>, Close, per-program Attach<Name>, AttachAll, plus your kernel-side struct types and constants re-published in Go

Kernel-version gate
✅ bpfvet runs at load time. Fails fast with bpf program needs kernel >= 5.8, host is 5.4 instead of opaque EINVAL

Verifier error → Go source
✅ auto-annotated inside Load<Stem>. No manual pipe to gobee diagnose; *ebpf.VerifierError comes back with → counter.go:18:5 markers

Sourcemap sidecar
✅ <stem>.bpf.c.map written next to every .bpf.c for offline gobee diagnose use too

Cross-arch
✅ Linux arm64 + amd64

What gobee does

Transpiles a Go subset to BPF C (and runs go/types over your input first, so misuses surface at file:line:col).
Generates a typed <Stem>_bindings.go next to the .bpf.c: bpf.LoadCounter(spec), objs.PerIface.Lookup(...), objs.AttachAll(ifindex), plus your kernel-side struct types and constants re-published in Go.
Auto-annotates *ebpf.VerifierError from LoadAndAssign with Go source positions, no manual gobee diagnose pipe needed.
Runs bpfvet inside Load<Stem> so old kernels fail fast with bpf program needs kernel >= 5.8, host is 5.4.
Surfaces ~200 typed Go stubs for the libbpf v1.5.0 helper set, plus user-defined helper functions emitted as static __always_inline.

What gobee won't do

Replace clang. clang's BPF backend gives us CO-RE, BTF, and verifier-friendly codegen for free. Reimplementing that costs years and gains nothing.
Replace cilium/ebpf. The generated bindings sit on top of it.
Hide BPF. The Go subset maps 1:1 to BPF C idioms. If you know BPF, gobee is thin sugar. If you don't, the manual is still required reading.
Run clang for you. Compile, embed, and load remain user-owned. Same pattern as bpf2go.

Why transpile, not generate BPF directly
gc, the Go compiler, has no LLVM-based BPF backend. Adding one is a multi-year compiler project. rustc is built on LLVM and that's why Aya works. So gobee emits C and reuses clang's BPF backend, which gives us mature codegen, BTF, and CO-RE relocations for free.
Quickstart
go install github.com/boratanrikulu/gobee/cmd/gobee@latest

cd example/helloworld
make build # gobee translate, clang, go build
sudo ./helloworld eth0
You'll need clang with the BPF target. On Linux that's the distro package; on macOS, brew install llvm. The transpiler itself is pure Go and runs anywhere.
Project layout (typical)
yourproject/
├── bpf/ # Go package, importable from anywhere in your project
│ ├── embed_amd64.go # //go:embed bin/x86/your.bpf.o
│ ├── embed_arm64.go
│ ├── your_bindings.go # generated by gobee
│ ├── bin/{x86,arm64}/your.bpf.o
│ └── src/ # not a Go package; clang lives here
│ ├── your.go # //go:build ignore: BPF source
│ ├── your.bpf.c # generated
│ ├── Makefile # clang per arch
│ └── vmlinux.h # vendored BTF dump
├── main.go # imports yourproject/bpf
└── Makefile

The split keeps bpf/ a clean importable Go package (Go rejects .c files in non-cgo packages). Kernel sources and clang artifacts live one level down in bpf/src/.
Examples

example/helloworld/: the canonical XDP packet counter, ~40 lines BPF, ~80 lines userspace.
example/sysmon/: XDP, two tracepoints, and a kprobe in one binary, sharing a ringbuf for events. Demonstrates per-syscall typed contexts, user-defined helper functions, and the AttachAll shortcut.

CI
GitHub Actions runs four layers on every push:

go test, go vet, transpiler golden tests
Coverage matrix: every map type and //bpf:section kind has at least one example
clang compile of every curated example, then bpfvet portability report
Real-kernel verifier acceptance: ebpf.NewCollectionWithOptions on each .bpf.o (Ubuntu 24.04 runner, kernel 6.x)

Docs

docs/design.md: architecture and rationale
docs/go-subset.md: accepted Go syntax in BPF source files
docs/directives.md: //bpf:* reference
docs/status.md: support matrix (single source of truth)

Toolchain

The gobee binary builds anywhere (pure Go, no CGO).
Compiling .bpf.o needs clang with the BPF target. Apple's bundled clang doesn't ship with it; on macOS use brew install llvm or build inside a Linux VM.
Running the artifact needs Linux on arm64 or amd64.

Inspirations

Solod: the Go-to-C transpiler that proved this pattern works.
Aya: the Rust eBPF framework whose ergonomics gobee chases.

License
MIT. See LICENSE.
Copyright (c) 2026 Bora Tanrikulu <me@bora.sh>

About

Write your BPF programs in Go, not C. gobee transpiles a Go subset to BPF C and generates typed cilium/ebpf bindings.

Topics

linux

golang

kernel

transpiler

ebpf

bpf

cilium-ebpf

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity
Stars

214
stars
Watchers

1
watching
Forks

1
fork

Report repository

Releases
No releases published

Packages
0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Go
96.6%

Makefile
3.4%

Footer

© 2026 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Community

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

gobee is a tool designed to allow developers to write BPF programs in Go rather than the traditional C language, aiming to bridge the gap between the Go ecosystem and the kernel-side BPF development, which has historically relied on C. gobee achieves this by transpiling a strict subset of Go into BPF C code and subsequently generating typed Go bindings for the userspace side, integrated with cilium/ebpf. This approach leverages clang's mature backend to handle the complexities of BPF code generation, allowing users to maintain control over the compilation and loading process while benefiting from the ecosystem built around the LLVM infrastructure.

The core functionality involves translating Go constructs into BPF C and generating associated bindings. For instance, a Go program defining an event structure and a tracepoint function is transpiled into BPF C code, which is then used to generate typed Go bindings that allow userspace drivers to directly interact with the BPF execution environment, such as reading data from ring buffers. This process allows users to define their logic in Go while utilizing the established capabilities of the C/Clang compilation pipeline.

gobee’s design choices are informed by comparisons with existing workflows and frameworks. It seeks a middle ground compared to methods like C plus clang plus bpf2go, Rust’s Aya framework, bpftrace, and BCC. A significant feature of gobee is its adherence to Cross-Repository (CO-RE) principles, which is achieved via clang and LLVM, offering built-in support for better code relocation and verification. Furthermore, gobee automates critical aspects of BPF development, such as error handling, where verifier errors are automatically annotated with the corresponding line and column in the Go source, eliminating the need for manual diagnostic piping.

Technically, gobee supports a rich set of BPF surface features, including eight program types, nineteen map types, and over two hundred typed Go stubs generated from the libbpf v1.5.0 header set for BPF helpers. The system incorporates a kernel-version gate using bpfvet, which ensures that BPF programs fail fast if the required kernel version is not met, thereby improving runtime stability. The generated output includes C source files alongside typed Go bindings, resulting in an artifact that is directly usable for userspace drivers while maintaining a traceable link back to the original Go source code.

gobee focuses on transpilation rather than wholesale replacement of existing tools. It does not attempt to replace the clang backend or the entire cilium/ebpf framework; instead, it sits on top of these established technologies. This distinction means that while gobee handles the translation, the user remains responsible for the external compilation, embedding, and loading steps, maintaining the familiar pattern seen in other BPF toolchains.

The supporting workflow involves a specific project layout where Go packages containing BPF definitions and Go code are separated from the kernel-side artifacts, which include the generated C source files and the relevant BTF dump, all within a structured directory. This setup facilitates automated testing through GitHub Actions, which verifies the transpiler, performs clang compilation, assesses portability through bpfvet reports, and validates execution by running the BPF programs against a real kernel environment. This comprehensive CI strategy ensures that the generated artifacts are robust and verifiable across different architectures.