ErenAri/Aegis-BPF
GitHub: ErenAri/Aegis-BPF
基于 eBPF LSM 的 Linux 运行时安全引擎，在内核层面确定性阻断未授权的文件与网络操作，填补了检测类工具到真正预防执行之间的空白。
Stars: 9 | Forks: 0
# AegisBPF
[](https://github.com/ErenAri/Aegis-BPF/actions/workflows/ci.yml)
[]()
[]()
[]()
[]()
**AegisBPF** 是一个基于 eBPF 的运行时安全代理，它利用 Linux Security Modules (LSM) 监控并阻止未授权的文件和网络活动。它为文件拒绝规则以及出站和选定的入站网络拒绝面提供内核级别的强制执行，并在具备强制执行能力的钩子不可用时，提供显式的仅审计回退机制。
` 上传（包含内核 + 发行版 + 测试日志）。
## 项目与社区
| 资源 | 位置 |
|---|---|
| 维护者 | [`MAINTAINERS.md`](MAINTAINERS.md) |
| 治理 | [`GOVERNANCE.md`](GOVERNANCE.md) |
| 行为准则 | [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) |
| 贡献指南 | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
| 安全策略 | [`SECURITY.md`](SECURITY.md) |
| 支持 | [`SUPPORT.md`](SUPPORT.md) · 生命周期见 [`docs/SUPPORT_POLICY.md`](docs/SUPPORT_POLICY.md) |
| 采用者 | [`ADOPTERS.md`](ADOPTERS.md) |
| CNCF 沙盒申请草案 | [`docs/CNCF_SANDBOX_APPLICATION.md`](docs/CNCF_SANDBOX_APPLICATION.md) |
| 路线图 | [`docs/POSITIONING.md` §5](docs/POSITIONING.md#5-roadmap-to-v10-ga) |
| 诚实的局限性 | [`docs/POSITIONING.md` §4](docs/POSITIONING.md#4-honest-limitations) |
| 问题、想法、展示与讲述 | GitHub [讨论区](https://github.com/ErenAri/Aegis-BPF/discussions) |
| 缺陷、功能退化 | GitHub [议题](https://github.com/ErenAri/Aegis-BPF/issues) |
| 漏洞 | 根据 [`SECURITY.md`](SECURITY.md) 进行私密提交 |
AegisBPF 是一个年轻的项目（首次提交于 2026-01-11），正在积极招募贡献者和采用者。如果您正在以任何身份进行试点——哪怕是单个预发布集群——请考虑向 [`ADOPTERS.md`]() 提交 PR，您可以选择匿名列出。
## 架构
```
+----------------------------- User Space -----------------------------+
| |
| +----------------------------------------------------------------+ |
| | aegisbpf daemon | |
| | | |
| | +------+ +-------+ +-------+ +------+ +-----+ +------+ +------+| |
| | | CLI | |Policy | |Event | |Metric| | Log | |Plugin| |Rules || |
| | | Disp | |+ Sign | |Handler| |Health| |(JSON| |System| |Engine|| |
| | +------+ +-------+ +-------+ +------+ +-----+ +------+ +------+| |
| +----------------------------------------------------------------+ |
| | |
| +------+------+ |
| | libbpf | |
| +------+------+ |
| | |
+--------------------------------|-------------------------------------+
bpf() syscall
+--------------------------------|-------------------------------------+
| | Kernel Space |
| +-----------------------------+-----------------------------+ |
| | BPF Subsystem | |
| | | |
| | +------------------------+ +---------------------------+ | |
| | | LSM Hooks | | Tracepoint Fallback | | |
| | | file_open | | openat / exec / fork | | |
| | | inode_permission | | (audit when no BPF LSM) | | |
| | | inode_copy_up | +---------------------------+ | |
| | | bprm_check_security | | |
| | | (+ IMA hash, 6.1+) | | |
| | | socket_connect / bind | | |
| | | socket_listen / accept | | |
| | | socket_sendmsg/recvmsg | | |
| | +------------------------+ | |
| | | |
| | +------------------------------------------------------+ | |
| | | BPF Maps | | |
| | | deny_* / allow_* net_* / survival_* | | |
| | | deny_cgroup_inode/ipv4/port trusted_exec_hash | | |
| | | agent_meta / stats events ring buffer | | |
| | +------------------------------------------------------+ | |
| +-----------------------------------------------------------+ |
| |
| file/network ops: allowed, audited, or blocked |
+----------------------------------------------------------------------+
```
## 标准对齐
| 领域 | 标准 | 状态 |
|---|---|---|
| 内核执行 | BPF LSM (`CONFIG_BPF_LSM`，内核 ≥ 5.7) | ✅ 已附加 15 个钩子 |
| 可移植性 | CO‑RE + BTF | ✅ (最低内核 5.15) |
| 可移植性 | 针对没有 `/sys/kernel/btf/vmlinux` 的内核的 BTFhub 回退 | ✅ 多级解析器 + `AEGIS_BTF_PATH` 覆盖 (`docs/BTF_FALLBACK.md`) |
| 供应链 | SBOM (SPDX 2.3 + CycloneDX 1.6) | ✅ 每次发布均公布 |
| 供应链 | SLSA v1.0 L3 构建来源 | ✅ 发布工作流中的 `actions/attest-build-provenance` + 自验证；详见 `docs/compliance/SLSA_PROVENANCE.md` |
| 供应链 | cosign / Sigstore 签名 | ✅ 在发布工作流中通过 GitHub OIDC 实现无密钥签名 |
| 供应链 | OpenSSF 最佳实践徽章 | ◐ 自评通过 (`docs/compliance/OPENSSF_BEST_PRACTICES.md`)；正式提交待定 |
| 供应链 | OpenSSF 记分卡 | ✅ `.github/workflows/scorecard.yml` 每周发布 |
| 供应链 | 逐比特可重现构建 | ✅ 在 CI 中验证 (`scripts/check_reproducible_build.sh`，`docs/REPRODUCIBLE_BUILDS.md`) |
| Daemon 加固 | seccomp-bpf 白名单 | ✅ |
| Daemon 加固 | Landlock 自沙箱化 | ✅ 通过 `--landlock` 选择启用 (`docs/HARDENING.md`) |
| Daemon 加固 | 分离的能力 (`CAP_BPF` + `CAP_PERFMON`) | ✅ 通过 `--drop-caps` 选择在附加后丢弃能力 (`docs/HARDENING.md`) |
| 合规性 | NIST SP 800‑53 Rev 5 控制项映射 | ✅ `docs/compliance/NIST_800_53_MAPPING.md` |
| 合规性 | NIST SP 800‑190 (容器安全) | 路线图 |
| 合规性 | ISO/IEC 27001:2022 | ✅ `docs/compliance/ISO_27001_CONTROLS.md` |
| 合规性 | SOC 2 Type II 证据包 | ✅ `docs/compliance/SOC2_EVIDENCE_KIT.md` |
| 合规性 | PCI DSS 4.0 | ✅ `docs/compliance/PCI_DSS_4_MAPPING.md` |
| 合规性 | CIS Kubernetes Benchmark v1.8 | ✅ `docs/compliance/CIS_KUBERNETES_BENCHMARK.md` |
| 合规性 | 面向容器 / Linux 的 MITRE ATT&CK | ✅ 标签 schema + CI 门禁 (`docs/rules/MITRE_ATTACK_TAG_SCHEMA.md`) |
| 事件 schema | OCSF 1.1 / ECS / CEF | 路线图 (目前为自定义 JSON + ECS 格式化器) |
| 社区 | CNCF 沙盒 → 孵化 → 毕业 | 准沙盒阶段 |
完整的合规性映射位于 [`docs/compliance/`](docs/compliance/)。
详细的差距分析与专业产品路线图：
[`docs/POSITIONING.md`](docs/POSITIONING.md)。
## 诚实的局限性
专业的安全产品会承认其局限性。以下是 AegisBPF 的局限性，按优先级排列。每一项都在 [`docs/POSITIONING.md`](docs/POSITIONING.md) 中进行跟踪。
1. **基于路径的规则存在 TOCTOU。** 路径名到 inode 的解析可能会在 `inode_permission` 和 `file_open` 之间被替换。路径规则属于**检测级别**；inode 和 IMA 哈希规则属于**预防级别**。参见 [`docs/GUARANTEES.md`](docs/GUARANTEES.md)。
2. **验证器 / 复杂度限制。** 非常庞大的规则集可能会触及 BPF 的 1M 条指令或 4K 栈上限。能够跨尾调用程序划分大型规则集的策略编译器已在路线图中。
3. **`socket_listen` / `socket_recvmsg` 受限于内核版本。** AegisBPF 在启动时会探测匹配的 `bpf_lsm_*` BTF 符号，并在未暴露这些符号的内核上优雅降级。操作人员可以在安装前通过 `aegisbpf probe` 预测结果——除了读取 `/sys/kernel/btf/vmlinux` 之外无需特权——其 `hook_probe.hooks.*` JSON 块会报告 AegisBPF 附加的所有 14 个 LSM 钩子的可附加性。参见 [`docs/HOOK_CAPABILITY_PROBE.md`](docs/HOOK_CAPABILITY_PROBE.md)。
4. **单节点控制平面。** 每个集群一个 operator pod；暂不支持跨集群的全局视图。
5. **策略语言仅限 INI + CRD。** 尚不支持 CEL/Rego 表达式，也不支持在匹配条件中使用父进程/标签选择器。
6. **BTF 回退需要逐内核的数据块。** 缺少 `/sys/kernel/btf/vmlinux` 的内核（RHEL 7，非常老旧的嵌入式设备）需要在 `/lib/modules//btf/vmlinux`、`/var/lib/aegisbpf/btfs/.btf`、`/usr/lib/aegisbpf/btfs/`、`/etc/aegisbpf/btfs/` 下暂存匹配的 BTF 数据块，或通过 `AEGIS_BTF_PATH` 指定。使用 `scripts/btfgen.sh` 可从 BTFhub-archive 中提取。参见 [`docs/BTF_FALLBACK.md`](docs/BTF_FALLBACK.md)。
7. **暂无发行版软件包。** 安装需从源码构建或使用提供的容器镜像；Ubuntu PPA / Fedora COPR 已在路线图中。
8. **Daemon 默认在其整个生命周期内以 root 身份运行。** 选择启用 `--drop-caps` 可在 BPF 附加后移除 `CAP_SYS_ADMIN`/`CAP_BPF`/`CAP_PERFMON`（保留：`CAP_NET_ADMIN`、`CAP_DAC_READ_SEARCH`）；参见 [`docs/HARDENING.md`](docs/HARDENING.md)。
9. **尚无第三方安全审计。** 计划在 v1.0 GA 之前进行。
10. **仅限 Linux。** Windows (`ebpf-for-windows`) 是 v2.0 的考量范围；macOS 被明确列为非目标。
## 快速开始
### 前置条件
- 带有 BTF 支持的 Linux 内核 5.8+
- 启用了 BPF LSM 以支持执行模式（检查方法：`cat /sys/kernel/security/lsm | grep bpf`）
- Cgroup v2 挂载在 `/sys/fs/cgroup`
可选的环境检查：
```
scripts/verify_env.sh --strict
```
### 安装依赖项
```
sudo apt-get update
sudo apt-get install -y clang llvm libbpf-dev libsystemd-dev \
pkg-config cmake ninja-build python3-jsonschema linux-tools-common
sudo apt-get install -y "linux-tools-$(uname -r)" || true
```
### 构建
```
cmake -S . -B build -G Ninja
cmake --build build
```
### 运行
```
# 审计模式 (观察而不阻止)
sudo ./build/aegisbpf run --audit
# 强制模式 (阻止匹配的文件打开)
sudo ./build/aegisbpf run --enforce
# 带有显式信号策略的强制模式 (默认为 SIGTERM)
sudo ./build/aegisbpf run --enforce --enforce-signal=term
# 仅作为紧急应急例外允许未知的 exec 身份
sudo ./build/aegisbpf run --enforce --allow-unknown-binary-identity
# 如果强制模式降级为审计/降级状态，则安全闭环
sudo ./build/aegisbpf run --enforce --strict-degrade
# SIGKILL 模式升级：先发出 TERM，仅在反复拒绝后才发出 KILL
sudo ./build/aegisbpf run --enforce --enforce-signal=kill
# 调整 SIGKILL 升级策略 (仅用于 --enforce-signal=kill)
sudo ./build/aegisbpf run --enforce --enforce-signal=kill \
--kill-escalation-threshold=8 \
--kill-escalation-window-seconds=60
# 使用 JSON 日志记录
sudo ./build/aegisbpf run --log-format=json
# 选择 LSM hook (默认: file_open)
sudo ./build/aegisbpf run --enforce --lsm-hook=both
# 增大 ring buffer 和 sample events 以减少高负载下的丢弃
sudo ./build/aegisbpf run --audit --ringbuf-bytes=67108864 --event-sample-rate=10
```
## 代码布局
最近的维护工作将过去的热点文件拆分成了更细致的模块：
- Daemon 编排保留在 `src/daemon.cpp`，能力报告在 `src/daemon_posture.cpp`，运行时状态与心跳处理在 `src/daemon_runtime.cpp`，执行门控在 `src/daemon_policy_gate.cpp`。
- BPF 生命周期代码保留在 `src/bpf_ops.cpp`，附加编排在 `src/bpf_attach.cpp`，map 与影子辅助函数在 `src/bpf_maps.cpp`，完整性检查在 `src/bpf_integrity.cpp`，config/agent-meta 处理在 `src/bpf_config.cpp`。
- 策略解析与运行时应用现位于 `src/policy_parse.cpp` 和 `src/policy_runtime.cpp`。
- 面向监控的命令被拆分为专门的模块，如 `src/commands_health.cpp`、`src/commands_probe.cpp`、`src/commands_explain.cpp` 和 `src/commands_metrics.cpp`。
- 质量与可观测性模块：`src/selftest.cpp`（启动验证）、`src/map_monitor.cpp`（容量警告）、`src/proc_scan.cpp`（/proc 协调）。
- 安全模块：`src/bpf_signing.cpp`（BPF 对象完整性）、`src/binary_hash.cpp`（白名单哈希验证）。
- 扩展模块：`src/rule_engine.cpp`（可热加载的检测规则）、`src/plugin.cpp`（事件处理插件系统）。
- 内核侧的 BPF 代码拆分为各子系统的头文件：`bpf/aegis_common.h`（共享类型/辅助函数）、`bpf/aegis_file.bpf.h`（文件钩子）、`bpf/aegis_exec.bpf.h`（执行钩子）、`bpf/aegis_net.bpf.h`（网络钩子）、`bpf/aegis_process.bpf.h`（进程生命周期）。
## 工作原理
```
File Access Blocking Flow
User Process Kernel (BPF LSM)
|
| open("/etc/shadow")
|----------------------->|
| |
| allow_cgroup? ----yes----> ALLOW
| |no
| v
| deny_inode? ----yes--+
| |no |
| v v
| survival_allowlist? -> ALLOW
| |no
| v
| audit mode?
| / \
| yes no
| | |
| emit event signal + -EPERM
| ALLOW DENY
| |
|<-----------------------|
| Success / EPERM
```
## 用法
### 运行选项
```
# 选择 LSM hook (默认: file_open)
sudo aegisbpf run --enforce --lsm-hook=file
sudo aegisbpf run --enforce --lsm-hook=inode
sudo aegisbpf run --enforce --lsm-hook=both
# 选择强制信号动作 (默认: term)
sudo aegisbpf run --enforce --enforce-signal=term
sudo aegisbpf run --enforce --enforce-signal=none
# 'kill' 仅在短时间内反复拒绝后升级为 SIGKILL
sudo aegisbpf run --enforce --enforce-signal=kill
# 调整 kill 模式的升级策略
sudo aegisbpf run --enforce --enforce-signal=kill \
--kill-escalation-threshold=8 \
--kill-escalation-window-seconds=60
# 增大 ring buffer 大小 (字节) 以减少 ringbuf 丢弃
sudo aegisbpf run --audit --ringbuf-bytes=67108864
# 对阻止事件进行采样 (1 = 所有事件, 10 = 十分之一)
sudo aegisbpf run --audit --event-sample-rate=10
# 在强制模式下，遇到回退/降级运行时状态时以非零退出
sudo aegisbpf run --enforce --strict-degrade
```
### 性能与浸泡测试 (示例结果)
结果因主机和工作负载而异。最新的自托管基线记录在 `docs/PERF_BASELINE.md` 中。
```
# perf_compare.sh (200,000 次操作, FILE=/etc/hosts, i9-13900H, kernel 6.17)
baseline_us_per_op=1.69
with_agent_us_per_op=1.68
delta_pct=-0.59
# KPI 比率 (p95)
open_p95_ratio=0.787 (target <= 1.05)
connect_p95_ratio=0.994 (target <= 1.05)
# soak 测试 (审计 + 强制模式, 文件 + 网络工作负载)
ringbuf_drops_delta=0
```
有关与 Falco 和 Tetragon 的正面比较，请参见[与其他工具的比较](#comparison-with-other-tools)。
**浸泡测试基础设施：**
- `scripts/soak_reliability.sh` -- 审计 + 执行模式，文件 + 网络工作负载，RSS/丢失率/比例门禁
- `scripts/aws_soak_24h.sh` -- 在 AWS EC2 上自动进行 24 小时浸泡测试（在 t2.micro 上约 $0.28/天，带有 SSH 调试访问权限并可自动终止）
- `.github/workflows/soak.yml` -- 每周 CI：1 小时审计浸泡，15 分钟执行浸泡，5 分钟 ASAN 浸泡
- **首个 24 小时 AWS 浸泡测试：通过 (2026-04-17)** -- `t2.micro`，审计模式，文件 + UDP 工作负载；24 小时内 RSS 增长 88 kB，在 336 万次决策事件中 ringbuf 丢包数为 0。完整报告：[`docs/SOAK_24H.md`](docs/SOAK_24H.md)，原始产物：[`evidence/soak-24h/`](evidence/soak-24h/)。
### 阻断命令
```
# 将文件添加到拒绝列表
sudo aegisbpf block add /usr/bin/malware
# 列出所有被阻止的条目
sudo aegisbpf block list
# 从拒绝列表中移除
sudo aegisbpf block del /usr/bin/malware
# 清除所有规则和统计数据
sudo aegisbpf block clear
```
### 允许命令
```
# 允许 cgroup (进程绕过拒绝规则)
sudo aegisbpf allow add /sys/fs/cgroup/system.slice
# 列出允许的 cgroup
sudo aegisbpf allow list
# 从 allowlist 中移除
sudo aegisbpf allow del /sys/fs/cgroup/system.slice
```
### 策略文件
```
# /etc/aegisbpf/policy.conf
version=5
[deny_path]
/usr/bin/dangerous
/opt/malware/binary
[deny_inode]
259:12345
[allow_cgroup]
/sys/fs/cgroup/system.slice
cgid:123456
[allow_binary_hash]
sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
# 受保护的资源 (需要 VERIFIED_EXEC, 参见 docs/VERIFIED_EXEC_CONTRACT.md)
[protect_connect]
[protect_runtime_deps]
# 可选的硬性关卡：在强制执行时要求主机 IMA appraisal
[require_ima_appraisal]
[protect_path]
/etc/shadow
```
```
# 验证策略
sudo aegisbpf policy lint /etc/aegisbpf/policy.conf
# 应用并带有 SHA256 验证
sudo aegisbpf policy apply /etc/aegisbpf/policy.conf --sha256 abc123...
# 应用签名包 (推荐用于生产环境)
sudo aegisbpf policy apply /etc/aegisbpf/policy.signed --require-signature
# 导出当前规则
sudo aegisbpf policy export /tmp/current.conf
# 回滚到以前的策略
sudo aegisbpf policy rollback
```
### 监控
```
# 查看统计数据
sudo aegisbpf stats
# 查看详细的高基数 debug 细分
sudo aegisbpf stats --detailed
# 导出 Prometheus metrics
sudo aegisbpf metrics --out /var/lib/prometheus/aegisbpf.prom
# 导出用于短期调试的高基数 metrics
sudo aegisbpf metrics --detailed --out /tmp/aegisbpf.debug.prom
# 健康检查
sudo aegisbpf health
# 在日志中启用 OTel 风格的策略 spans (用于故障排查)
AEGIS_OTEL_SPANS=1 sudo aegisbpf policy apply /etc/aegisbpf/policy.conf
```
Daemon 启动时会将能力/附加报告写入
`/var/lib/aegisbpf/capabilities.json`（可通过 `AEGIS_CAPABILITIES_REPORT_PATH` 覆盖）。
在执行模式下，如果应用的策略需要不可用的网络、执行身份或运行时依赖信任钩子（以及配置时要求的缺失 IMA 鉴定姿态），启动将会失败并关闭。
能力报告还包含运行时姿态字段（`runtime_state`、`state_transitions`），以便操作人员区分 `ENFORCE`、`AUDIT_FALLBACK` 和 `DEGRADED` 结果。
对于机器可读的姿态合规性和 Kubernetes 调度标签，请使用：
```
python3 scripts/evaluate_capability_posture.py \
--input /var/lib/aegisbpf/capabilities.json \
--strict \
--out-json /var/lib/aegisbpf/capabilities.posture.json \
--out-labels-json /var/lib/aegisbpf/capabilities.labels.json
```
## 事件格式
事件以换行符分隔的 JSON 格式发出：
```
{
"type": "block",
"pid": 12345,
"ppid": 1000,
"start_time": 123456789,
"exec_id": "12345:123456789",
"trace_id": "12345:123456789",
"parent_start_time": 123400000,
"parent_exec_id": "1000:123400000",
"parent_trace_id": "1000:123400000",
"cgid": 5678,
"cgroup_path": "/sys/fs/cgroup/user.slice",
"comm": "bash",
"path": "/usr/bin/malware",
"ino": 123456,
"dev": 259,
"action": "TERM"
}
```
关键安全阻断会通过优先级环形缓冲区发出丰富的取证事件：
```
{
"type": "forensic_block",
"pid": 12351,
"ppid": 12345,
"start_time": 723456789,
"exec_id": "12351:723456789",
"cgid": 5678,
"cgroup_path": "/sys/fs/cgroup/user.slice",
"ino": 654321,
"dev": 259,
"uid": 1000,
"gid": 1000,
"exec_ino": 111222,
"exec_dev": 259,
"verified_exec": false,
"exec_identity_known": true,
"action": "KILL",
"comm": "malware"
}
```
运行时姿态变更会发出独立的事件类型：
```
{
"type": "state_change",
"event_version": 1,
"state": "AUDIT_FALLBACK",
"reason_code": "CAPABILITY_AUDIT_ONLY",
"detail": "kernel lacks required enforce hooks",
"strict_mode": false,
"transition_id": 2,
"degradation_count": 1
}
```
## 部署
### Docker
```
docker build -t aegisbpf .
docker run --privileged --pid=host \
-v /sys/fs/bpf:/sys/fs/bpf \
-v /sys/fs/cgroup:/sys/fs/cgroup:ro \
-v /sys/kernel/btf:/sys/kernel/btf:ro \
aegisbpf run --audit
```
### Kubernetes (Helm)
```
helm install aegisbpf ./helm/aegisbpf \
--set agent.auditMode=false \
--set agent.logFormat=json
```
### Systemd
```
sudo cmake --install build
sudo systemctl daemon-reload
sudo systemctl enable --now aegisbpf
```
`/etc/default/aegisbpf` 默认配置为：
- `AEGIS_REQUIRE_SIGNATURE=1`
- `AEGIS_POLICY=` (为空，服务启动时不应用启动策略)
在生产环境中，请将 `AEGIS_POLICY` 设置为签名的策略包路径（例如 `/etc/aegisbpf/policy.signed`），并保持启用签名强制执行。
## 数据流图
```
+----------------------------+
| Policy bundle/rules |
| /etc/aegisbpf/policy.signed|
+-------------+--------------+
|
v
+-------+ +------------------+ +------------------+
| CLI |->| aegisbpf |->| journald/stdout |
| Cmds | | daemon | | (structured logs)|
+-------+ +--------+---------+ +------------------+
|
bpf() syscall
|
+---------+---------+
| BPF Maps |
|/sys/fs/bpf/aegisbpf/|
| |
| deny_* allow_* |
| deny_ipv4/ipv6 |
| deny_cidr_v4/v6 |
| deny_port |
| deny_cgroup_* |
| trusted_exec_hash |
| net_*/block_stats |
| survival/meta |
| events (ring buf) |
| priority_events |
| hook_latency |
| event_approver_* |
+---------+---------+
|
+---------+---------+
| BPF hooks (kernel)|
| - file_open |
| - inode_permission|
| - inode_copy_up |
| - bprm_check (IMA)|
| - socket_connect |
| - socket_bind |
| - socket_listen |
| - socket_accept |
| - socket_sendmsg |
| - socket_recvmsg |
| - tracepoints |
+-------------------+
```
## 指标
AegisBPF 导出与 Prometheus 兼容的指标：
| 指标 | 类型 | 描述 |
|--------|------|-------------|
| `aegisbpf_blocks_total` | counter | 阻断的文件打开总数 |
| `aegisbpf_ringbuf_drops_total` | counter | 因缓冲区溢出而丢弃的事件 |
| `aegisbpf_deny_inode_entries` | gauge | inode 拒绝规则的数量 |
| `aegisbpf_deny_path_entries` | gauge | 路径拒绝规则的数量 |
| `aegisbpf_allow_cgroup_entries` | gauge | 允许的 cgroup 数量 |
| `aegisbpf_net_blocks_total` | counter 按类型（`connect`/`bind`/`listen`/`accept`/`sendmsg`/`recvmsg`）阻断的网络操作 |
| `aegisbpf_net_ringbuf_drops_total` | counter | 丢弃的网络事件 |
| `aegisbpf_net_rules_total` | gauge | 按类型（`ip`/`cidr`/`port`/`cgroup_inode`/`cgroup_ipv4`/`cgroup_port`）划分的活动网络拒绝规则 |
使用 `aegisbpf metrics --detailed` 可获取高基数调试指标：
`aegisbpf_blocks_by_cgroup_total`、`aegisbpf_blocks_by_inode_total`、`aegisbpf_blocks_by_path_total`、`aegisbpf_net_blocks_by_ip_total`、`aegisbpf_net_blocks_by_port_total`。
## 安全加固
```
+----------------------------------------------------------+
| Layer 5: Cryptographic |
| Constant-time comparisons, BPF integrity, policy sigs |
+----------------------------------------------------------+
| Layer 4: Code Signing |
| Sigstore/Cosign + SBOM |
+----------------------------------------------------------+
| Layer 3: MAC Policies |
| AppArmor / SELinux |
+----------------------------------------------------------+
| Layer 2: Seccomp |
| Syscall allowlist (--seccomp) |
+----------------------------------------------------------+
| Layer 1: Capabilities |
| CAP_SYS_ADMIN, CAP_BPF, CAP_PERFMON |
+----------------------------------------------------------+
```
**加密保护：**
- 所有哈希比较均采用恒定时间算法以防止时序攻击
- BPF 对象在加载前通过 SHA256 验证完整性
- 使用 Ed25519 签名进行策略签名（建议在生产环境中使用）
启用所有加固层：
```
sudo aegisbpf run --enforce --seccomp
```
有关漏洞报告、环境变量和加固细节，请参见 [SECURITY.md](SECURITY.md)。
安全边界、攻击者模型和已知盲区记录在
[docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) 中。执行保证与 TOCTOU 分析在 [docs/GUARANTEES.md](docs/GUARANTEES.md) 中。
## 文档
### 核心文档
| 文档 | 描述 |
|----------|-------------|
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 系统设计与内部机制 |
| [API_REFERENCE.md](docs/API_REFERENCE.md) | 类型、函数和 BPF map 的 API 参考 |
| [DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) | 开发环境搭建、编码规范与贡献指南 |
| [POLICY.md](docs/POLICY.md) | 策略文件格式与语义 |
| [POLICY_SEMANTICS.md](docs/POLICY_SEMANTICS.md) | 精确的运行时规则语义与边缘情况行为 |
| [NETWORK_LAYER_DESIGN.md](docs/NETWORK_LAYER_DESIGN.md) | 网络阻断架构 |
| [THREAT_MODEL.md](docs/THREAT_MODEL.md) | 威胁模型、覆盖边界与已知绕过面 |
| [GUARANTEES.md](docs/GUARANTEES.md) | 执行保证、TOCTOU 分析与已知绕过类别 |
| [BYPASS_CATALOG.md](docs/BYPASS_CATALOG.md) | 已知绕过、缓解措施与被接受的缺口 |
| [BPF_MAP_SCHEMA.md](docs/BPF_MAP_SCHEMA.md) | BPF map 类型、容量规划、键/值契约与内存预算 |
| [REFERENCE_ENFORCEMENT_SLICE.md](docs/REFERENCE_ENFORCEMENT_SLICE.md) | 决策级执行参考切片 |
### 运维
| 文档 | 描述 |
|----------|-------------|
| [PRODUCTION_READINESS.md](docs/PRODUCTION_READINESS.md) | 生产就绪清单与操作人员指南 |
| [CAPABILITY_POSTURE_CONTRACT.md](docs/CAPABILITY_POSTURE_CONTRACT.md) | 规范化的能力 schema + 运行时姿态门控契约 |
| [HELM_ENFORCE_GATING_CONTRACT.md](docs/HELM_ENFORCE_GATING_CONTRACT.md) | 用于 fail-closed 执行的 Helm 默认值/模板契约 |
| [K8S_ROLLOUT_AUDIT_ENFORCE.md](docs/K8S_ROLLOUT_AUDIT_ENFORCE.md) | 混合能力推出：全面审计，在标记节点上执行 |
| [ENFORCEMENT_GUARANTEES.md](docs/ENFORCEMENT_GUARANTEES.md) | 已保证/尽力而为/不保证的执行行为 |
| [PRODUCTION_DEPLOYMENT_BLUEPRINT.md](docs/PRODUCTION_DEPLOYMENT_BLUEPRINT.md) | 部署加固与推出蓝图 |
| [CANARY_RUNBOOK.md](docs/CANARY_RUNBOOK.md) | 预发布金丝雀与浸泡验证工作流 |
| [RELEASE_DRILL.md](docs/RELEASE_DRILL.md) | 发布前打包与升级演练 |
| [KEY_MANAGEMENT.md](docs/KEY_MANAGEMENT.md) | 策略签名密钥轮换与撤销运维手册 |
| [INCIDENT_RESPONSE.md](docs/INCIDENT_RESPONSE.md) | 事件处理流程 |
| [METRICS_OPERATIONS.md](docs/METRICS_OPERATIONS.md) | 指标解读、阈值与操作人员行动 |
| [EVIDENCE.md](docs/EVIDENCE.md) | 公共 CI 证据与产物图谱 |
| [EXTERNAL_VALIDATION.md](docs/EXTERNAL_VALIDATION.md) | 独立审查与试点案例研究摘要 |
| [runbooks/](docs/runbooks/) | 告警/事件/维护运维手册 |
| [VENDORED_DEPENDENCIES.md](docs/VENDORED_DEPENDENCIES.md) | 供应商依赖库清单与审查周期 |
| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | 常见问题与解决方案 |
| [SIEM_INTEGRATION.md](docs/SIEM_INTEGRATION.md) | Splunk、ELK、QRadar 集成 |
### 参考
| 文档 | 描述 |
|----------|-------------|
| [SUPPORT_POLICY.md](docs/SUPPORT_POLICY.md) | 支持的版本、兼容性与弃用保证 |
| [COMPATIBILITY.md](docs/COMPATIBILITY.md) | 内核与版本兼容性矩阵 |
| [PERF.md](docs/PERF.md) | 性能调优与基准测试 |
| [PERFORMANCE.md](docs/PERFORMANCE.md) | 性能配置文件、内存公式与环形缓冲区大小规划 |
| [BRANCH_PROTECTION.md](docs/BRANCH_PROTECTION.md) | 受保护分支基线与必需检查 |
| [QUALITY_GATES.md](docs/QUALITY_GATES.md) | CI 门禁策略与覆盖率棘轮预期 |
| [CI_EXECUTION_STRATEGY.md](docs/CI_EXECUTION_STRATEGY.md) | 特权 CI 与内核矩阵执行策略 |
| [repo_labels.json](config/repo_labels.json) | 用于分流/发布策略的仓库标签真实来源 |
| [CHANGELOG.md](docs/CHANGELOG.md) | 版本历史 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献者工作流与本地质量检查 |
| [GOVERNANCE.md](GOVERNANCE.md) | 项目决策模型与维护者角色 |
| [SUPPORT.md](SUPPORT.md) | 支持渠道与版本支持范围 |
| [aegisbpf.1.md](docs/man/aegisbpf.1.md) | 手册页 |
## 系统要求
- Linux 内核 5.8+，需包含：
- `CONFIG_BPF=y`
- `CONFIG_BPF_SYSCALL=y`
- `CONFIG_BPF_JIT=y`
- `CONFIG_BPF_LSM=y` (用于执行模式)
- `CONFIG_DEBUG_INFO_BTF=y`
- Cgroup v2 (统一层级)
- Root 权限或 `CAP_SYS_ADMIN`、`CAP_BPF`、`CAP_PERFMON`
### 启用 BPF LSM
如果 `/sys/kernel/security/lsm` 中没有 `bpf`：
```
# 编辑 GRUB 配置
sudo vim /etc/default/grub
GRUB_CMDLINE_LINUX="lsm=lockdown,capability,landlock,yama,bpf"
# 更新并重启
sudo update-grub
sudo reboot
```
## 性能
在参考主机上测量 (Linux 6.17, i9-13900H；参见
`docs/PERF_BASELINE.md` 和 `docs/PERFORMANCE.md`)：
- **open(2) 系统调用增量**：相对裸机基线 -0.59%（在误差范围内）
- **connect(2) 系统调用增量**：相对裸机基线 +6.91%（6 个 socket 钩子）
- **BPF hash-map 拒绝查找**：3.9-4.1 ns，从 100 到 10,000 条记录保持平稳（规则数量不影响单次系统调用延迟）
- **启动时间**：约 130 ms
- **策略重载** (`aegisbpf policy apply`)：中位数约 115 ms，无需进程重启；代理内部的影子 map 切换本身 <5 ms
- **无锁环形缓冲区** 用于事件（丢弃操作会被计数，绝不阻塞执行）
- **用户空间 VmRSS (空闲)**：约 7.4 MB
- **BPF map memlock (空策略)**：约 100 MB（主要由事件 ringbuf 和每 CPU 统计数组构成；容器限制的总预算约 140 MB）
与 Falco 和 Tetragon 的正面对比：参见[与其他工具的比较](#comparison-with-other-tools)
或 [`docs/PERFORMANCE_COMPARISON.md`](docs/PERFORMANCE_COMPARISON.md)。
运行基准测试：
```
# Userspace 热路径基准测试 (无需 root)
./build/aegisbpf_bench
# 附加 BPF 的 Syscall 级别基准测试 (需要 root)
sudo scripts/bench_syscall.sh --json --out results.json
# 快速 A/B 比较
ITERATIONS=200000 FILE=/etc/hosts scripts/perf_open_bench.sh
# 正面比较 (需要安装 Falco + Tetragon)
sudo scripts/install_peer_tools.sh all
sudo scripts/compare_runtime_security.sh \
--agents none,aegisbpf,falco,tetragon \
--workload open_close --iterations 200000 --out results/
# 24小时 AWS soak 测试 (约 $0.25, 自行终止)
./scripts/aws_soak_24h.sh --dry-run # preview first
./scripts/aws_soak_24h.sh --instance-type t3.micro --branch main
```
有关内存公式、环形缓冲区大小规划指南和容量规划，请参见 [docs/PERFORMANCE.md](docs/PERFORMANCE.md)。
## 贡献
1. 阅读 `CONTRIBUTING.md` 了解工作流和质量期望
2. 创建一个重点分支并实现单一的逻辑变更
3. 运行 `scripts/dev_check.sh` 以及 `CONTRIBUTING.md` 中的静态/安全检查
4. 使用模板提交 PR 并包含验证输出
## 状态
状态：积极维护中。欢迎贡献与反馈。
该项目在进入执行模式之前遵循“审计优先”的推出策略。
## 许可证
AegisBPF 采用 [Apache License, Version 2.0](LICENSE) 授权
(SPDX: `Apache-2.0`)。所需的归属声明和第三方组件许可证请参见 [`NOTICE`](NOTICE)。
内核侧的 BPF 程序在加载时按照 BPF 子系统的要求携带双重的 `BSD/GPL`
许可证字符串
(`char LICENSE[] SEC("license") = "Dual BSD/GPL";`)。Apache-2.0
管理着用户空间 Daemon、Operator 以及支持代码。
标签：0day挖掘, ARM64, C++20, cgroup, CIDR, Docker镜像, Falco替代, HIPS, HTTP工具, IMA, IP 地址批量处理, JSONLines, KubeArmor替代, LSM, OverlayFS, Streamlit, Tetragon替代, Tracee替代, Web截图, x86_64, 内核安全, 内核模块, 威胁防护, 子域名枚举, 子域名突变, 安全代理, 安全合规, 安全资源, 审计日志, 容器安全, 文件访问控制, 日志审计, 系统安全, 系统调用拦截, 网络代理, 网络安全, 网络安全审计, 网络防火墙, 自定义请求头, 访问控制, 请求响应过滤, 请求拦截, 防御机制, 阻断攻击, 隐私保护, 零信任