add gspy: forensic goroutine-to-syscall inspector for Go processes

[Mutasem-mk4]

New tool: gspy

URL: https://github.com/Mutasem-mk4/gspy
License: GPL-2.0-only
Language: Go + eBPF C
Version: 0.2.0

Description

gspy attaches to a running Go process by PID using eBPF uprobes (runtime.execute) and raw_syscalls tracepoints. It reads goroutine IDs from thread-local storage via process_vm_readv(2) — zero ptrace, zero binary modification — and displays a live terminal map of goroutine ID → syscall → user-space stack frame.

Capabilities

• Real-time goroutine-to-syscall attribution
• Syscall latency measurement and frequency counting
• Forensic --readonly mode with SHA-256 chain-of-custody verification
• JSON output pipeline (--json) for SIEM integration
• Filter by syscall category: io | net | sched | all

Security use cases

• Live forensic inspection of Go processes without ptrace or binary modification
• Incident response: identify which goroutine is making unexpected network calls, file writes, or privilege escalations
• Malware analysis: goroutine-level behavioral attribution in Go implants and C2 agents
• Red/blue team: zero-footprint inspection that doesn't trigger file integrity monitoring

Technical

• eBPF uprobes on runtime.execute + raw_syscalls/sys_enter + raw_syscalls/sys_exit
• CO-RE BPF programs with BTF support
• BPF ring buffer (16MB), 100ms poll, 1Hz TUI refresh
• < 2% CPU overhead at 10K syscalls/sec
• Kernel >= 5.8, Go 1.21–1.24, amd64

CI

All checks passing: https://github.com/Mutasem-mk4/gspy/actions

Category

blackarch-forensic — this tool provides no capability that can be used for active exploitation. It is read-only inspection only.

Checklist

• PKGBUILD builds with makepkg -si
• Tool is in correct category (blackarch-forensic)
• License is open source (GPL-2.0-only)
• Upstream CI is green
• Man page included (man/gspy.1)
• SHA-256 sum verified for source tarball
• No existing BlackArch tool provides goroutine-level Go process inspection