NX1X/Egret

# 🪶 Egret 这个名字巧妙结合了 **egress**（其核心功能）和白鹭（egret bird）。CLI 命令为： `egret run -- ./build.sh`。 [](https://github.com/NX1X/Egret) - **状态：** pre-MVP / 积极开发中（见 [docs/ROADMAP.md](docs/ROADMAP.md)） - **代码库：** [github.com/NX1X/Egret](https://github.com/NX1X/Egret) - **许可证：** [Apache-2.0](LICENSE) - **平台：** Linux 5.8+ (eBPF CO-RE)。非 eBPF 包的构建可以运行在任何 操作系统上；agent 本身则运行在 Linux 上。 ## 功能 Egret 会包装一个命令并通过 eBPF 对其进行监控： - **网络出站** — 记录每一个出站连接 (PID、进程、IP、 端口；当关联 DNS 时包含域名)。 - **出站控制** *(block 模式)* — 结合域名允许列表实行默认拒绝，由 本地 DNS 代理 + nftables 动态允许集提供支持。 - **进程树** — `execve`/`fork` 监控。 - **文件写入** — 标记对受保护路径的写入操作 (`.git/`, `~/.ssh/`, …)。 - **audit 模式** — 观察运行过程，然后生成一份*建议的*允许列表。 报告会以 Markdown + JSON 格式写入，并在检测到时附加到 GitHub Actions 的 job 摘要中。无需服务器，无需账户，不会向外发送任何数据。 ## 快速开始 ``` # 1. 构建 (Linux)。 `generate` 通过 clang + bpf2go 编译 eBPF C。 make generate build # 2. 在 audit 模式下观察构建（记录日志，从不阻断）。 sudo ./bin/egret run --config examples/policy.yaml --mode audit -- ./build.sh # 3. 将观察到的运行转换为建议的 allowlist。 egret audit --from hardened-report/report.json --emit policy.suggested.yaml # 4. 执行它。 sudo ./bin/egret run --config policy.suggested.yaml --mode block -- ./build.sh ``` 生成的报告位于 `./hardened-report/` 目录下 (`report.md`, `report.json`)。 ### 校验策略 ``` egret policy lint --config examples/policy.yaml ``` ## 快速开始 使用 `command` 输入包装你的构建。Egret 会对它进行监控、生成报告， 并 (默认情况下) 将 SARIF 上传至 **Code Scanning**： ``` jobs: build: runs-on: ubuntu-latest permissions: # scope to the job contents: read security-events: write # required to upload SARIF to Code Scanning steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - uses: NX1X/Egret/action@v1 # published with the first release; pin to a SHA meanwhile with: policy: .github/egret-policy.yaml mode: audit # or: block command: make ci # your whole build — monitored end-to-end fail-on-violations: true # optional: fail the job on any violation ``` 然后，结果会显示在代码库的 **Security → Code scanning** 标签页下。省略 `command` 参数将仅安装二进制文件，然后你可以自行在多个步骤前后 调用 `egret run`。 | 输入项 | 默认值 | 用途 | |---|---|---| | `command` | `""` | 在 Egret 下运行的命令 (空 = 仅安装) | | `policy` | `""` | `policy.yaml` 的路径 (未设置则默认为 audit 模式) | | `mode` | `audit` | `audit` 或 `block` | | `sarif` / `upload-sarif` | `true` | 生成 SARIF / 将其上传至 Code Scanning | | `fail-on-violations` | `false` | 如果记录到任何策略违规则让 job 失败 | | `version` | `latest` | 要安装的 Egret 发行版 | | `disable-sudo` | `false` | block 模式：在运行期间撤销构建用户的免密 sudo (`no_new_privs` 的双重保险) | | `ingest-url` | `""` | 可选的自托管 [Egret Nest](docs/ingest-contract.md) URL，用于 POST 运行结果 (空 = 保持本地，不向外发送数据) | | `ingest-token` | `""` | `ingest-url` 的 bearer token (请传入密钥；以 header 形式发送，绝不出现在命令行中) | 输出项：`report-dir`、`sarif-file`、`violations`。详情请参见 [action/](action/)。 要在不使用包装器的情况下对*每一个*步骤进行透明追踪，需要一个 pre-job 守护进程 — 这是一个计划中的增强功能。 ## `policy.yaml` ``` version: 1 mode: audit # audit | block egress: allowed-endpoints: - github.com - api.github.com - "*.actions.githubusercontent.com" # subdomains only - registry.npmjs.org block-raw-ip: true filesystem: protected-paths: - .git/ - ~/.ssh/ - /etc/ process: disallowed: [] # e.g. ["nc", "/tmp/*"] report: format: [markdown, json] output-dir: ./hardened-report github-job-summary: true ``` 完整示例请见 [examples/policy.yaml](examples/policy.yaml)。 ## 架构 ``` GitHub Action wrapper ─┐ ├─ both wrap the same core → AGENT BINARY (eBPF + enforcement) CLI / daemon ─────────┘ ``` Agent 会解码 eBPF ring-buffer 事件 (`internal/collector`)，根据策略对它们进行 评估 (`internal/policy`)，通过 DNS 代理 + nftables 执行出站控制 (`internal/enforcer`)，并生成报告 (`internal/report`)。基于域名的 出站：允许列表中的名称会通过 Egret 的 DNS 代理进行解析，解析出的 IP 会被添加到 nftables 允许集中，其他所有流量默认会被拒绝。 ### 代码库结构 | 路径 | 内容 | |---|---| | `cmd/egret` | CLI 入口 | | `internal/event` | 平台中立的事件类型 | | `internal/policy` | `policy.yaml` 解析 + 评估 | | `internal/bpf` | eBPF C 程序 (`*.bpf.c`, CO-RE) | | `internal/collector` | eBPF 加载器 + ring-buffer 解码 (Linux) | | `internal/enforcer` | DNS 代理 + nftables 防火墙 (Linux) | | `internal/report` | Markdown/JSON/job 摘要生成器 | | `internal/audit` | 观察运行过程 → 生成建议允许列表 | | `action/` | GitHub Action 包装器 | ## 开发 ``` make fmt vet # hygiene (any OS) make test # unit tests (any OS) make generate # eBPF codegen (Linux + clang) make build # build ./bin/egret (Linux) ``` 跨平台包 (`policy`, `report`, `audit`, `event`) 可以在任何 OS 上构建和 测试。任何带有 `//go:build linux` 标签的内容 — 即 collector 和 enforcer — 都需要 Linux 内核；eBPF 集成测试会在内核虚拟机中运行。 ## 路线图 Egret 分为三个**纯粹增量式**的层级发展 — 不会强制进入下一阶段： 1. **CLI + Action** (当前) — 零基础设施。 2. **无服务器 GitHub App** — 组织级策略、触发 CI 的自动 PR、品牌化 检查，以及 Renovate 风格的 [issue dashboard](docs/github-app.md)。无需服务器。 3. **可选的自托管服务器** (延期) — 由你部署在自己的 基础设施上的历史记录/仪表盘；你的数据永远不会离开它。 完整的计划及“永远不需要服务器”的原则请见 [docs/ROADMAP.md](docs/ROADMAP.md)， 设置 App 请参考 [docs/github-app.md](docs/github-app.md)。 ### 文档导航 (各模块分布) | 文档 | 负责内容 | |---|---| | [docs/ROADMAP.md](docs/ROADMAP.md) | Egret 是什么，哪些功能可用，未来的方向 | | [CHANGELOG.md](CHANGELOG.md) | 发布的变更 (agent 尚未打标签 — 将随 v1.0 仪表盘一同发布) | | [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) | 依赖项策略 | | [docs/github-app.md](docs/github-app.md) | GitHub App 设置 | | [docs/ingest-contract.md](docs/ingest-contract.md) | agent→仪表盘的数据信封 (唯一的跨代码库接口) | ## 已知限制 (MVP) 出站控制是基于域名允许列表的，存在一些残留漏洞 (DoH/DoT, 裸 IP, CDN IP 轮换)。**block 模式在裸机/VM 主机上是一个隔离边界； 在 GitHub 托管 / 容器 runner 上仍在验证中 — 目前请在此类环境中使用 `audit` 模式。** enforcer 的每一项更改都会经过专门的 网络安全审查。 ## 联系方式 - **网站：** [nx1xlab.dev](https://nx1xlab.dev) - **联系：** [nx1xlab.dev/contact](https://nx1xlab.dev/contact) - **Bug / 问题：** 请在 [github.com/nx1x/egret/issues](https://github.com/nx1x/egret/issues) 提交 issue - **安全：** 私下披露漏洞请见 [SECURITY.md](SECURITY.md)。 ## 许可证 Egret 采用 [Apache License 2.0](LICENSE) 授权 — © 2026 NX1X ([nx1xlab.dev](https://nx1xlab.dev))。署名信息请参见 [NOTICE](NOTICE)。

标签：CI/CD安全, EVTX分析, IP 地址批量处理, Llama, 审计, 提示词模板, 日志审计, 网络信息收集, 网络访问控制