Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alegrey91/harpoon
🔍 Trace syscalls of user-space defined functions, using eBPF
https://github.com/alegrey91/harpoon
ebpf ebpf-programs golang seccomp security-audit security-tools syscalls system-calls
Last synced: 28 days ago
JSON representation
🔍 Trace syscalls of user-space defined functions, using eBPF
- Host: GitHub
- URL: https://github.com/alegrey91/harpoon
- Owner: alegrey91
- License: apache-2.0
- Created: 2023-09-20T19:42:52.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-22T10:36:28.000Z (8 months ago)
- Last Synced: 2024-04-22T11:43:27.976Z (8 months ago)
- Topics: ebpf, ebpf-programs, golang, seccomp, security-audit, security-tools, syscalls, system-calls
- Language: C
- Homepage:
- Size: 852 KB
- Stars: 45
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- trackawesomelist - harpoon (⭐87) - Trace syscalls from user-space functions, by using eBPF. (Recently Updated / [Oct 03, 2024](/content/2024/10/03/README.md))
README
# Harpoon
**Harpoon** aims to capture the syscalls (as if they were fishes) from the execution flow (the river) of a single user-defined function.
## Introduction
This tool is designed to provide fine-grained visibility into the syscalls made by specific functions within a program. Unlike traditional system call tracing tools like `strace`, which capture all syscalls made during the entire program's execution, this project leverages the power of **eBPF** to pinpoint and monitor system calls exclusively within targeted functions.
## Getting Started
First of all, let's identify the symbol of the function you want to trace from the binary. Suppose you want to trace the function `doSomething()` present in the example program `./binary`. In order to get the symbol from the binary itself, you need to use the following command:
```sh
objdump --syms ./binary | grep doSomething
0000000000480720 g F .text 0000000000000067 main.doSomething
```
So, `main.doSomething` is the symbol of the function we want to trace using `harpoon`.
Then, let's run `harpoon` to extract the syscalls from the function `main.doSomething`:
```shell
harpoon capture -f main.doSomething ./binary
read
sigaltstack
gettid
close
mmap
fcntl
write
futex
openat
clone
getrlimit
```
These are the syscalls that have been executed by the traced function!
**N.B.** For a complete list of available commands, take a look [here](docs/commands.md).
## Installation
To install `harpoon` you currently have 2 options:
### Download
You can easily download the latest release using the installation script:
```sh
curl -s https://raw.githubusercontent.com/alegrey91/harpoon/main/install | sudo sh
```
### Build
Or you can build `harpoon` manually by using the following steps:
Install dependencies (for Ubuntu):
* `clang`
* `libbpf-dev`
* `libseccomp-dev`
Build the application:
```sh
make build
```
After the build is completed, you can find the executable under the `bin/` directory.
## Debugging
In case you want to run the application locally, I've provided the [`.vscode/launch.json`](.vscode/launch.json) file to easily debug the application with `root` privileges in `vscode`. Just replace the parameters marked with `<>`.
## Talks
I had the pleasure of speaking about `harpoon` at the following conferences:
* [**FOSDEM**](https://fosdem.org/2024/schedule/event/fosdem-2024-1884-how-we-almost-secured-our-projects-by-writing-more-tests/)
* [**Conf42**](https://www.youtube.com/watch?v=Z8IHOTlG3pM)
## References
I would like to point out that without the references mentioned below this project would never have come to life.
As a result, the code draws significant inspiration from the references listed here:
* https://www.grant.pizza/blog/tracing-go-functions-with-ebpf-part-1/
* https://itnext.io/seccomp-in-kubernetes-part-2-crafting-custom-seccomp-profiles-for-your-applications-c28c658f676e
* https://github.com/containers/oci-seccomp-bpf-hook
* https://sysdig.com/blog/ebpf-offensive-capabilities/
* *Liz Rice. Learning eBPF, 173-176. O'Reilly, 2023*