v0.2.1

Full Changelog: v0.2.0...v0.2.1

v0.2.0 — Distribution Ready

gspy v0.2.0 — Distribution Ready

gspy is a forensic goroutine-to-syscall inspector for live Go processes using eBPF.

What's new in v0.2.0

Core changes

• Migrated to cilium/ebpf v0.21.0 API (Variables.Set loop, LogSizeStart)
• Added Go 1.24 ABI support for goroutine ID extraction
• Updated bpf2go from v0.14.0 to v0.17.1
• Fixed go.mod module path to match GitHub repository URL

Distribution packaging

• Fixed debian/control, debian/copyright, debian/rules for Kali/Parrot submission
• Fixed PKGBUILD with verified SHA-256, SPDX license, offline build support
• Added CHANGELOG.md and CONTRIBUTING.md
• Added test coverage reporting to CI

CI hardening

• Updated GitHub Actions to Node.js 24-compatible versions
• Upgraded golangci-lint to v1.64.2 for Go 1.24 compatibility

What's included (from v0.1.0)

Core functionality

• Attach to any running Go process by PID with zero process modification
• Real-time goroutine ID → syscall → user-space stack frame mapping via eBPF uprobes and raw_syscalls tracepoints
• Goroutine state tracking: running, syscall, waiting, dead
• Syscall latency measurement and frequency counting

Inspection modes

• --top: sort by syscall frequency
• --latency: sort by highest current syscall latency
• --filter <io|net|sched|all>: filter by syscall category
• --readonly: forensic mode — zero writes to target process memory, SHA-256 binary verification logged
• --json: newline-delimited JSON output for pipeline integration
• --debug: BPF verifier log and map statistics

Technical details

• Uses process_vm_readv(2) for read-only memory access (no ptrace)
• CO-RE BPF programs with BTF support for kernel portability
• 16MB ring buffer, 100ms poll interval, 1Hz TUI refresh
• < 2% CPU overhead at 10K syscalls/sec on a 4-core machine
• ELF symbol table resolution for stack frames (no DWARF required for basic operation)

Supported platforms

• Linux kernel >= 5.8 (BPF ring buffer required)
• Go 1.21–1.24 (amd64 verified)
• arm64: experimental, goroutine ID offsets unverified

Installation

From binary (recommended):
Download gspy-linux-amd64.tar.gz from this release, then:

tar xzf gspy-linux-amd64.tar.gz
sudo install -Dm 0755 gspy /usr/bin/gspy
sudo setcap cap_bpf,cap_perfmon+ep /usr/bin/gspy

From source:

make generate && make build

Known limitations

• arm64 GID offsets unverified — goroutine IDs may be incorrect
• Go generics: inlined generic functions may produce incorrect frame resolution
• Stripped binaries without DWARF: partial frame resolution (hex addresses)
• Kernel < 5.8: not supported
• cgroupv1 namespaces: unsupported

Full changelog: https://github.com/Mutasem-mk4/gspy/blob/master/CHANGELOG.md

v0.1.1

Full Changelog: https://github.com/Mutasem-mk4/gspy/commits/v0.1.1

v0.1.0

Full Changelog: https://github.com/Mutasem-mk4/gspy/commits/v0.1.0