hi-heisenbug/goodman
GitHub: hi-heisenbug/goodman
Goodman 利用 eBPF 将 Linux 系统调用精确归因到具体 npm 包，通过学习依赖行为基线来检测并告警运行时依赖漂移。
Stars: 0 | Forks: 0
# Goodman
[](https://github.com/hi-heisenbug/goodman/actions/workflows/ci.yml)
[](LICENSE)
[](go.mod)
[](deploy/helm/goodman)
Goodman 是一个运行时依赖安全传感器。它将与安全相关的 Linux syscalls 归因于引发它们的准确 npm package，学习每个 `(service, package, version)` 的行为基线，并在依赖项版本开始执行新操作时发出警报。
简短版本：内核可以告诉你某个进程打开了文件或连接到了某个 IP。Goodman 会告诉你该进程中的哪个依赖项执行了此操作。
由 Heisenbug 嵌入的 Goodman dashboard 是一个生产级 React/Vite UI，具有实时警报审查、指纹探索、SSE 更新和响应式移动布局。
## 演示
观看 54 秒的产品演示：
[打开演示视频](demo_build/goodman_demo.mp4)
## 检测内容
Goodman 专为依赖项行为漂移而构建：
- 某个 package 版本开始读取 secrets、tokens、SSH keys、`.npmrc` 或云凭证
- 某个依赖项开始连接到云元数据或新的出站主机
- 某个 package 更新在原有基线没有的情况下增加了 process execution
- 与该 package 学习到的基线相比，任何新的规范行为
在 v1.0 中它是检测优先的。Goodman 负责观察、归因、指纹识别和警报；它不进行拦截或沙盒隔离。
## 工作原理
```
kernel tracepoints
open/openat/openat2/connect/execve
|
v
eBPF sensor captures syscall + user stack
|
v
userspace attribution maps stack frame -> package@version
|
v
collector learns fingerprints and diffs new behavior
|
v
REST API, SSE stream, Prometheus metrics, dashboard
```
1. **捕获：** CO-RE eBPF 挂钩被监视的 Node/Python 进程的 `open`、`openat`、`openat2`、`connect` 和 `execve`，并记录用户空间堆栈。
2. **归因：** 用户空间通过 V8 perf maps 和 `/proc//maps` 解析堆栈地址，然后将最深层的 `node_modules//` 帧映射到其 `package.json` 版本。
3. **指纹识别：** 事件被规范化为稳定的行为，例如 `READ /app/node_modules/pkg/**` 和 `CONNECT 169.254.169.254:80`。
4. **比对：** 收集器将实时行为与学习到的基线进行比较，并应用可配置的高风险规则。
Goodman 宁愿选择 `` 也不愿猜测 package 名称。错误的归因比没有归因更糟糕。
## 快速开始
你需要一台具备内核 5.8+ 和 BTF 的 x86-64 Linux 主机，如果你还想重新构建 dashboard，则需要 Go、clang/LLVM、bpftool 和 Node。
完整的设置和使用指南位于 [docs/setup-and-usage.md](docs/setup-and-usage.md) 中。最简短的本地路径是：
```
make doctor
make build
make test
make smoke
```
`make smoke` 是无需 root 权限的演示。它会启动收集器，输入合成的基线和漂移事件，并准确断言一个 CRITICAL 警报。
要使用真实数据探索产品 UI：
```
make demo
```
然后打开 `http://127.0.0.1:8844`。这条无需 root 权限的路径会使用本地 SQLite 数据库启动收集器，植入基线指纹和依赖漂移警报，并保持 dashboard 运行，直到你按下 `Ctrl-C`。
对于真实的 eBPF 路径：
```
sudo make e2e
```
这会针对包含的 Node 工作负载运行良性漂移重放：
`good-pkg@1.0.0` 作为基线被学习，随后 `good-pkg@1.0.1` 会读取一个虚假的凭证文件并连接到一个 localhost sink。预期结果是针对新行为产生一个 CRITICAL 警报。
## 本地 Dashboard
```
GOODMAN_DSN=goodman.db GOODMAN_LEARN_OBS=50 GOODMAN_LEARN_MIN_AGE=1s \
./bin/collector -listen :8844
```
打开 `http://localhost:8844`。dashboard 内嵌在 collector 二进制文件中，因此新构建的 Go 版本可以直接提供 UI 服务，而无需单独的 Node 服务器。
## Kubernetes
```
scripts/install-k8s.sh --cluster prod
```
在你想让 Goodman 监视的 Node 工作负载上启用 package 归因：
```
scripts/enable-node-attribution.sh --namespace checkout --selector app=api
```
或者给某个命名空间内的每个 Deployment 打补丁：
```
scripts/enable-node-attribution.sh --namespace checkout --all
```
打开 dashboard：
```
kubectl -n goodman-system port-forward svc/goodman-collector 8844:8844
```
对于被监视工作负载，Tier-1 Node 归因仅需设置一个环境变量：
```
env:
- name: NODE_OPTIONS
value: "--perf-basic-prof --interpreted-frames-native-stack"
```
有关生产环境的详细信息、Postgres 配置、镜像发布和 chart 资源，请参阅 [docs/deployment.md](docs/deployment.md)。
## 仓库地图
| Path | Purpose |
|---|---|
| `bpf/` | eBPF C 程序、共享网络结构、生成的 `vmlinux.h` |
| `cmd/sensor` | 特权 sensor：加载 eBPF、归因事件、发布批次 |
| `cmd/collector` | 摄取、指纹识别、比对、API、dashboard |
| `cmd/goodmanctl` | 用于查看事件、警报、确认/解决、指纹的 CLI |
| `internal/attribute` | 堆栈到 package 的归因 |
| `internal/fingerprint` | 行为聚合和基线提升 |
| `internal/diff` | 基线比较和高风险规则评估 |
| `dashboard/` | React/Vite dashboard 源码 |
| `deploy/` | Dockerfiles、Helm chart、示例规则 |
| `test/` | 合成的冒烟测试驱动程序、工作负载 fixtures、e2e 测试工具 |
## 文档
- [入门指南](docs/getting-started.md)
- [设置和使用](docs/setup-and-usage.md)
- [架构](docs/architecture.md)
- [归因](docs/attribution.md)
- [配置](docs/configuration.md)
- [部署](docs/deployment.md)
- [API 参考](docs/api.md)
- [开发](docs/development.md)
- [故障排除](docs/troubleshooting.md)
- [Agent 指令](AGENTS.md)
## 开发
```
make doctor
make build
make vet
make test
make smoke
```
关于完整的本地、dashboard、CLI 和 Kubernetes 工作流，请使用 [docs/setup-and-usage.md](docs/setup-and-usage.md)。
在将更改合并到 `bpf/`、`internal/loader/` 或 `internal/attribute/` 之前，请运行 `sudo make e2e`。
最高严重性的不变条件是共享的事件布局：
`bpf/goodman.h` 中的 `struct event` 和 `internal/model/types.go` 中的 `RawEvent` 必须保持逐字节一致。这由 `internal/model/types_test.go` 强制执行。
## 状态
Goodman v0.1.0 包括：
- 针对 file open、network connect 和 process exec 的 eBPF 捕获
- 通过 V8 perf maps 进行的 Tier-1 npm 归因
- SQLite 和 Postgres 存储
- 基线学习和行为漂移检测
- 可配置的高风险规则
- REST API、SSE 流、Prometheus 指标和内嵌的 dashboard
- Docker 镜像和 Helm chart
后续跟进项记录在 [plan.md](plan.md) 中：mutating-webhook 自动注入、Python/PyPI 归因以及 Tier-2 原生 V8 堆栈展开。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
标签：Docker镜像, Go, Ruby工具, StruQ, 依赖安全, 子域名突变, 客户端加密, 异常检测, 插件系统, 日志审计, 时间线生成, 测试用例, 自定义请求头, 行为基线, 请求拦截