chore: rename import path, fix gid bug, fix license (#4)

Co-authored-by: Kyle Carberry
Co-authored-by: Katie Horne <[email protected]>

.gitattributes

@@ -1,2 +1,6 @@
-bpf/bpf_helper_defs.h linguist-generated=true
-bpf/bpf_helpers.h linguist-generated=true
+bpf/bpf_core_read.h linguist-vendored
+bpf/bpf_helper_defs.h linguist-vendored
+bpf/bpf_helpers.h linguist-vendored
+bpf/handler-bpfeb.o linguist-generated
+bpf/handler-bpfel.o linguist-generated
+bpf/vmlinux.h linguist-vendored

LICENSE.GPL

@@ -1,4 +1,4 @@
-Copyright (C) 2021 Coder Technologies, Inc.
+Copyright (C) 2022 Coder Technologies, Inc.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

LICENSE.MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (C) 2021 Coder Technologies, Inc.
+Copyright (C) 2022 Coder Technologies, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,68 +1,116 @@
-# exectrace [![Go Reference](https://pkg.go.dev/badge/cdr.dev/exectrace.svg)](https://pkg.go.dev/cdr.dev/exectrace)
+# exectrace [![Go Reference](https://pkg.go.dev/badge/github.com/coder/exectrace.svg)](https://pkg.go.dev/github.com/coder/exectrace)
 
-Simple [eBPF](https://ebpf.io/)-based exec snooping on Linux, packaged as a Go
+Simple [eBPF](https://ebpf.io/)-based exec snooping on Linux packaged as a Go
 library.
 
-exectrace loads a precompiled [eBPF program](./bpf/handler.c) into the running
+exectrace loads a pre-compiled [eBPF program](./bpf/handler.c) into the running
 kernel to receive details about the `exec` family of syscalls.
 
-## Installation
+## Requirements
 
-exectrace only support Go 1.16+ and Linux kernel 5.8+ (due to use of
+exectrace only supports Go 1.16+ and Linux kernel 5.8+ (due to the use of
 `BPF_MAP_TYPE_RINGBUF`).
 
-```
-$ go get -u cdr.dev/exectrace
+## Installation
+
+```console
+$ go get -u github.com/coder/exectrace
 ```
 
-## Quick Start
+## Quickstart
 
-You will need root access, `CAP_SYS_ADMIN` or `CAP_BPF` to run eBPF programs on
+You will need root access, `CAP_SYS_ADMIN` or `CAP_BPF`, to run eBPF programs on
 your system.
 
-> tip: you can use `go run -exec sudo ./cmd/program` to compile a program and
+> Use `go run -exec sudo ./cmd/program` to compile a program and
 > start it with `sudo`
 
-```
-$ go install -u cdr.dev/exectrace/cmd/exectrace
+```console
+$ go install -u github.com/coder/exectrace/cmd/exectrace
 $ exectrace --help
 ...
 
 $ sudo exectrace
 2021/12/01 16:42:02 Waiting for events..
-[1188921, comm="node"] /bin/sh -c 'which ps'
-[1188922, comm="sh"] which ps
+[1188921, comm="node", uid=1002, gid=1003] /bin/sh -c 'which ps'
+[1188922, comm="sh", uid=1002, gid=1003] which ps
 ```
 
 ## Usage
 
-You can look at the example program [exectrace](./cmd/exectrace/main.go) for a
-comprehensive program using this library.
+exectrace exposes a minimal API surface. Call `exectrace.New(nil)` and then
+you can start reading events from the returned `Tracer`.
+
+It is important that you close the tracer to avoid leaking kernel resources,
+so we recommend implementing a simple signal handler like the one in this
+example:
+
+```go
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/coder/exectrace"
+)
+
+func main() {
+	tracer, err := exectrace.New(nil)
+	if err != nil {
+		panic(err)
+	}
+	defer tracer.Close()
+
+	go func() {
+		sigs := make(chan os.Signal, 1)
+		signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+		<-sigs
+		tracer.Close()
+	}()
+
+	for {
+		event, err := tracer.Read()
+		if err != nil {
+			panic(err)
+		}
+
+		fmt.Printf("%+v\n", event)
+	}
+}
+```
 
-## Development
+> For a full usage example, refer to this [comprehensive program](./cmd/exectrace/main.go)
+> that uses the library.
 
-Since the eBPF program is packaged as a Go library, the program needs to be
-compiled and included in the repo. If you make changes to files under the `bpf`
-directory, you should run `make` and include the `.o` files in that directory in
-your commit if they changed. CI will ensure that this is done correctly.
+## Development
 
-You will probably need the following tools:
+You will need the following:
 
-- Docker (clang is run within a Docker container for reproducibility)
+- Docker (the Makefile runs clang within a Docker container for reproducibility)
 - `golangci-lint`
 - `prettier`
 - `shellcheck`
 
-## Status: In Development
+Since the eBPF program is packaged as a Go library, you need to compile the
+program and include it in the repo.
+
+If you change the files in the `bpf` directory, run `make` and ensure that you
+include the `.o` files you changed in your commit (CI will verify that you've
+done this correctly).
+
+## Status: beta
 
-The library is currently under heavy development as we develop it out to suit
-the needs of Coder's enterprise [product](https://coder.com).
+This library is ready to use as-is, though it is under active development as we
+modify it to suit the needs of Coder's [enterprise product](https://coder.com).
 
-We plan on changing the API to add more features and fields that can be read
-from, and potentially adding easier methods for filtering events rather than
-implementing filtering yourself.
+We plan on adding more features and fields that can be read from the API, as
+well as easier-to-use methods for filtering events (currently, you must
+implement additional filtering yourself).
 
-## See Also
+## See also
 
 - [`canonical/etrace`](https://github.com/canonical/etrace) - Go binary that
   uses ptrace and tracks the processes that a command launches for debugging and
@@ -72,4 +120,4 @@ implementing filtering yourself.
 
 ---
 
-Dual licensed under the MIT and GPL-2.0 licenses. See [LICENSE](LICENSE).
+Dual licensed under the MIT and GPL 2.0 licenses. See [LICENSE](LICENSE).

bpf/handler.c

@@ -161,7 +161,7 @@ s32 enter_execve(struct exec_info *ctx) {
 	u64 uidgid = bpf_get_current_uid_gid();
 	u64 pidtgid = bpf_get_current_pid_tgid();
 	event->uid = uidgid;       // uid is the first 32 bits
-	event->gid = uidgid << 32; // gid is the last 32 bits NOLINT(readability-magic-numbers)
+	event->gid = uidgid >> 32; // gid is the last 32 bits NOLINT(readability-magic-numbers)
 	event->pid = pidtgid;      // pid is the first 32 bits
 	ret = bpf_get_current_comm(&event->comm, sizeof(event->comm));
 	if (ret) {

cmd/exectrace/main.go

@@ -14,7 +14,7 @@ import (
 	"github.com/spf13/cobra"
 	"golang.org/x/xerrors"
 
-	"cdr.dev/exectrace"
+	"github.com/coder/exectrace"
 )
 
 func main() {
@@ -92,7 +92,11 @@ func run(pidNS uint32, outputFormat string) error {
 				ellipsis = "..."
 			}
 
-			_, _ = fmt.Printf("[%v, comm=%q] %v%v\n", event.PID, event.Comm, shellquote.Join(event.Argv...), ellipsis)
+			_, _ = fmt.Printf(
+				"[%v, comm=%q, uid=%v, gid=%v] %v%v\n",
+				event.PID, event.Comm, event.UID, event.GID,
+				shellquote.Join(event.Argv...), ellipsis,
+			)
 			continue
 		}
 		err = enc.Encode(event)

go.mod

@@ -1,4 +1,4 @@
-module cdr.dev/exectrace
+module github.com/coder/exectrace
 
 go 1.16