AmanSK5/shadow-ai-guard

# shadow-ai-guard Shadow AI 检测覆盖其出现的所有层面：browser、CLI、IDE、desktop、network 和 cloud。专为在你现有的基础设施上运行而构建，几乎零成本。 ## 为什么会有这个项目 没有任何一款单一的商业工具能够监控到 AI 工具出现的所有位置。CASB 和 DLP 产品只关注 browser。Endpoint 工具只监控已安装的应用程序。Cloud 访问工具只监控 OAuth 授权。它们都不会读取 `~/.claude.json` 来告诉你你的开发者登录了哪个 AI CLI 账户，而账户才是最关键的部分：在个人账户上使用已批准的工具属于不受管束的数据流、隐形的开支，同时也是离职管理上的漏洞。 本项目通过一个统一的发现 schema、一个已知 AI 工具的 registry 以及一个仪表板，实现了跨六个层面的检测。要将新的 AI 工具纳入检测，只需向一个 YAML 文件提交合并请求，而无需在每个 endpoint 上去修改脚本。 ## 五分钟试用 https://github.com/user-attachments/assets/f114e781-7053-4000-ba82-2b2d0fcc3e85 你不需要 Kubernetes cluster、MDM 或任何 cloud 登录就能看到它的作用。这里有一个 demo，它使用模拟数据运行真实的 receiver 和真实的 Grafana 仪表板，所有内容都在 Docker 中运行： ``` git clone https://github.com/AmanSK5/shadow-ai-guard.git cd shadow-ai-guard/demo docker compose up ``` 然后打开 **http://localhost:3000** 并查看 **AI Guard - Shadow AI Visibility** 仪表板。它会启动 Loki、receiver（基于本仓库中真实的 Dockerfile 构建），以及一个小型 seeder，用于发布跨各个层面和 OS 的示例发现结果。这样你看到的就会是一个已经填满数据的仪表板，而不是一个空仪表板：谁在运行什么、个人账户与工作账户的对比、各个工具的明细，以及人们配置好的 MCP 集成。 该 demo 使用 `example.com` / `example.co.uk` 作为工作域名，并使用了虚构的设备和用户名。它只运行 Loki，因此省略了一些 Prometheus 磁贴。这不是真实部署所能呈现的完整画面，但足以让你在不进行任何设置的情况下了解其工作原理。仪表板本身的标题栏说明了不同之处，更多细节请参阅 [`demo/README.md`](demo/README.md)。 当你想要真正运行它时，请从 [docs/getting-started.md](docs/getting-started.md) 开始。 ## 文档 所有内容都位于 `docs/` 和各个组件文件夹中。请从这里开始阅读，不要直接深入子文件夹。 **让它运行起来** - [入门指南](docs/getting-started.md) - 从克隆到在仪表板上看到第一条发现结果，这是最小可行性部署 - [架构](docs/architecture.md) - 心智模型：finding schema，以及各组件为何如此设计 **部署各个层面** - [macOS endpoint collector](endpoint/macos/README.md) - 通过 Jamf - [Windows endpoint collector](endpoint/windows/README.md) - 通过 Intune - [Linux endpoint collector](endpoint/linux/README.md) - 通过任何 RMM、cron 或配置管理工具 - [Browser 扩展](extension/README.md) - browser 层面 - [Cloud 和 network 扫描器](scanner/README.md) - Entra、Exchange、Intune、 Jamf、SentinelOne 以及 MCP 安全扫描器 **扩展与运维** - [编写扫描器](docs/writing-a-scanner.md) - 通过输出 finding schema 来添加新的检测源 - [安全模型](SECURITY.md) - 坦率陈述的信任模型 - [隐私和 DPIA 指南](docs/deployment-privacy.md) - 部署前请阅读； 这属于工作场所监控，通常需要进行 DPIA ## 工作原理 ``` browser extension ─┐ macOS collector ──┤ Windows collector ─┼──► receiver ──► logs (Loki) ──► Grafana dashboard Linux collector ──┤ │ cloud scanners ───┤ └──────► Alertmanager ──► alerts (personal accounts) network scanner ───┘ ▲ registry (YAML, MR-reviewed) ── served to collectors at runtime ``` - **receiver** - FastAPI 服务。接收发现结果，将其记录为结构化的 JSON，针对个人账户触发警报，并向 collector 提供 registry。 - **registry** - 判定何为 AI 工具的真理之源：包括域名、扩展 ID、配置文件路径、批准状态。在 CI 中进行 schema 验证。Collector 会在 runtime 从 receiver 获取它们的标识符列表，因此添加新工具无需更改 endpoint。 - **scanner** - cloud 和 fleet 扫描器：Entra ID 登录记录、Exchange 注册邮件证据、Intune 和 Jamf 软件清单、SentinelOne DNS 遥测数据（用于包括本地进程桥在内的网络级检测）。每个模块都是可选的；请运行你的环境支持的那些。 - **endpoint** - 用于 macOS（Jamf、bash）、Windows（Intune、PowerShell）和 Linux（任何 RMM、cron 或配置管理）的 collector。它们会读取 AI 工具的配置文件，以报告每个工具登录的账户。这是任何基于 API 的产品都不具备的数据。 - **discovery** - 每周任务，从 DNS 遥测数据中对无法识别的疑似 AI 域名进行分类，并以合并请求的形式提出 registry 添加建议。每一项更改都需要由人工批准。 - **dashboards** - 基于 Loki 的 Grafana 仪表板。在仪表板变量中设置你的企业域名，个人账户就会亮起红灯。 discovery 任务目前会开启 GitLab 合并请求；GitHub backend 已在路线图上。 ## Finding schema 每个来源都使用相同的结构。任何输出该结构的新 scanner 或 collector 都能与下游的所有组件协同工作： ``` { "tool": "claude-code", "surface": "cli", "os": "macos", "account_domain": "gmail.com", "device": "SERIAL123", "user": "aman.test", "evidence": "~/.claude.json", "severity": "warn", "reported_at": "2026-01-01T09:00:00Z", "source": "collector-macos" } ``` 当账户域名不属于你的企业域名时，`severity` 为 `warn`，否则为 `info`。`user` 字段包含账户名，以便针对正确的人员跟进发现结果；关于其具体何时填充，请参阅 [隐私](docs/deployment-privacy.md)。 ## 你需要准备什么 - 一个用于运行 receiver 和 scanner CronJob 的 Kubernetes cluster。任何符合规范的都可以；核心部分没有任何特定于 cloud 的内容。 - 一个获取容器 stdout 的日志 pipeline。提供的仪表板默认使用 Loki，但 receiver 的唯一输出格式是 JSON lines。 - 用于显示仪表板的 Grafana，用于报警的 Alertmanager（可选）。 - 你关注的每个层面至少需要一个检测源。目前支持：Microsoft Graph（Entra、Exchange、Intune）、Jamf Pro、SentinelOne、Chrome/Edge 托管扩展策略，以及用于 macOS、Windows 和 Linux 的 endpoint collector。 - 用于你启用的任何来源的 Secrets。本地开发使用 `.env`（参见 `scanner/README.md`）；部署后的 scanner 会从 Kubernetes Secrets 或你的 secret store 中读取数据。 CI 会将预构建的镜像发布到 GHCR。Helm chart 正在开发中；在此之前，receiver 是一个 Deployment，并在 `/etc/ai-guard` 处挂载了 registry ConfigMap，而 scanner 则是 CronJob。有关详细信息，请参阅各组件的 README。 ## 部署顺序 1. 部署 receiver，创建其 bearer token Secret，并将其暴露在 endpoint 可以访问的 ingress 上。 2. 发布 registry：`python registry/build.py`，然后将 `registry/dist/registry.json` 和 `registry/dist/collector.json` 加载到 receiver 挂载的 ConfigMap 中。 3. 启用你的环境支持的 scanner 并对其进行调度。 4. 通过你的 MDM 或 RMM 推出 endpoint collector。首先在一台机器上进行试点；`endpoint/*/README.md` 中的部署说明正是根据这种操作实践编写的。 5. 导入仪表板，设置企业域名变量。 刚接触这里？[docs/getting-started.md](docs/getting-started.md) 逐步讲解了如何进行最小化部署。 ## 状态和已知限制 这是一个 alpha 版本，是特意提前发布的。它目前在一个环境中投入了生产运行，粗糙的地方都被明确标记了出来，而不是被隐藏。目前的已知限制包括： - **Registry 一致性。** 并非每个层面都能检测到所有的 registry 条目。某些工具被 endpoint collector 覆盖，但未被 scanner 覆盖，反之亦然，这取决于各个层面能看到哪些标识符。缩小这一差距是 ongoing 的 registry 工作，而不是代码变更。 - **Scanner 准确性。** Cloud 和 network scanner 会根据登录应用程序名称和 DNS pattern 等标识符进行匹配，其中一些边界仍在调整中。预计偶尔会出现漏报或误报；请将发现结果视为需要跟进的线索，而不是最终定论。 - **交付途径。** Collector 已通过本项目背后实际运行的交付机制（Jamf、Intune 以及用于 Linux 的 RMM）进行了测试。其他已记录的途径（例如 Ansible 或普通的 cron）虽然按预期编写，但在实际场景中的锻炼较少。请先在一台机器上进行试点。 如果你遇到了上述问题或未在此列表中的问题，请提交一个包含发现 JSON 和你期望结果的问题，这将会非常有帮助。 ## 治理说明 Registry 在发布时，将每个工具都设置为 `approved: false`。是否批准是由你的组织决定的，而不是本项目的默认设置。discovery 任务只提出添加建议；它从不执行合并。如果你在 ISO 42001 或类似标准下运营，registry 可以兼作你正在使用的 AI 系统的维护清单，而仪表板则可作为其证据。 在部署之前，请阅读 docs/deployment-privacy.md：在大多数司法管辖区，这属于工作场所监控，通常需要进行 DPIA。 ## 安全模型 请参阅 SECURITY.md。简短版本：报告源共享一个 bearer token，进行速率限制的公开数据获取，由于发现结果包含用户名和设备标识符，因此请将你的日志存储视为敏感数据，并且 endpoint collector 是通过你的 MDM 或 RMM 以 root/SYSTEM 权限运行的，因此请像审查你通过这些途径推送的任何其他内容一样审查它们。 ## 许可证 Apache-2.0。

标签：AI合规, Docker, Grafana, Loki, Shadow AI检测, 子域名突变, 安全可见性, 安全防御评估, 应用安全, 请求拦截, 逆向工具