protet/monitor

# Protet Runtime Monitor — GitHub Action 为 CI/CD 构建会话提供运行时安全防护。只需在任何 job 中添加 **三行代码**；Protet 便会监视该 job 启动的每一个进程，将 execve 数据流发送至云端，并 返回该构建的 **恶意 / 良性** 判定结果。 ``` - uses: protet/monitor@v1 with: token: ${{ secrets.PROTET_TOKEN }} ``` 就是这样。你现有的构建步骤将 **完全保持不变** 地运行 —— 无需进行任何封装。 ## 工作原理 - `uses:` 步骤会开启 **系统级的 execve 捕获** (`auditd`) 并启动 **后台流式传输器**。它会立即返回；你的构建步骤会照常运行。 - 在构建运行期间，流式传输器会将每个 execve **实时** 发送到云端入口 (`/v1/ingest`)，作为 Protet `exec` 事件 (`cmd = " "` —— 与 集群内 Tetragon collector 发出的传输格式相同)。没有任何内容会被批量处理到最后，并且 **绝不会被截断**：如果网关短暂无法连接，事件会转存到磁盘 并进行重试；任何在构建结束时仍未成功投递的事件都会被报告，绝不会 被静默丢弃。（你配置的 token 是一个长期有效的 *refresh* token；流式传输器会 将其换取为短期有效的 access token 并自动进行刷新 —— 你无需管理任何内容。） - 云端会对数据流进行评分（滑动窗口 → StarEncoder → 分类器 → 可解释性），并 输出 OCSF Detection Findings。post 步骤会关闭会话，通过 **同一个 token**（一个持久且按会话过滤的 findings 流）读取判定结果，并将其报告回来 —— 包括精确的 **被标记的命令链**。 没有任何源码、artifact 或构建产物会离开 runner —— 只有命令序列。 **Runner 要求：** Linux、`sudo` 以及 `auditd`（会自动安装）—— 在 GitHub 托管的 `ubuntu-*` runner 上开箱即用。目前尚不支持 macOS/Windows 以及 没有 `auditd` 且被锁定的自托管 runner （该步骤会降级为警告，绝不会导致构建 失败）。与发行版无关的 eBPF 捕获（免安装）已在路线图中 —— [spike](docs/ebpf-spike-results.md) 已经确认 eBPF `execve` 捕获可以在 GitHub 托管的 runner 上加载并运行，因此它将插入到同一个可插拔的捕获接口之后。 **一个 token，双向通用。** 同一个 `token` 既用于验证发送事件，*也*用于读取 判定结果 —— 无需配置其他任何内容。findings 数据流是持久化的（短期保留 + 断点续传），因此判定结果绝不会丢失，并且多个订阅者可以同时读取它（本次运行、 你的仪表板、SIEM）。 ## 输入项 | 输入项 | 必需 | 默认值 | | |---|---|---|---| | `token` | 是 | | Protet token（repo secret）—— **一个 token**：既用于发送事件，也用于读取判定结果 | | `environment` | 否 | `prod` | Protet 云端目标 (prod)；为本地部署设置 `gateway-url` + `app-url` | | `gateway-url` / `app-url` | 否 | | 用于 **on-prem / self-hosted / air-gapped** 部署的覆盖配置 | | `github-token` | 否 | 自动 | PR comment —— 默认使用运行内置的 `GITHUB_TOKEN`，无需传递（只需添加 `permissions: pull-requests: write`） | | `fail-on-malicious` | 否 | `false` | 当检测到恶意行为窗口时使 job 失败 | ### 目标 ``` environment: prod # Protet cloud (prod) # — 或者 — self-hosted / on-prem： gateway-url: https://protet.internal.acme.com app-url: https://protet-app.internal.acme.com ``` ## 报告 **每次运行** 都会生成一份 **job summary** —— 包含判定结果、投递状态，如果判定为恶意，还会包含 告警描述以及精确的 **被标记的命令链**（始终包含顶级命令；在授权计划中包含完整的 经过 beam-search 的链条）。 **只有在判定结果为恶意时，才会发布 PR comment** —— 干净的运行会保持 PR 安静。 如果之前的运行已经发表了评论，而构建在此后已被修复，该评论将 原地更新为干净的判定结果，而不是留下一条过时的 🔴（一旦解决，就绝不会重新创建）。 无需传递任何 token —— 只需在 job 中添加 `permissions: pull-requests: write`。设置 `fail-on-malicious: "true"` 即可对合并进行拦截管控。 ## `compromised-build` 演示 该演示运行两个 job。第二个 job 会注入一条供应链 postinstall 链（curl|bash 下载器、挖矿程序获取、`/dev/tcp` 反向 shell、base64 执行）。每个网络操作都指向 `127.0.0.1:1`（会被拒绝），并且每一行都带有 `|| true`，因此 **实际上不会有任何东西 被执行** —— 但 auditd 仍然会捕获命令字符串，而这正是 Protet 进行评分的对象。检测的关键 在于命令流中的意图，而不是 payload 是否执行成功。

标签：Docker镜像, 自定义脚本