lumen-argus

<h1 align="center">lumen-argus</h1> <p align="center"> <strong>AI 编码工具 DLP 代理</strong><br/> 在 AI 提供商之前扫描输出请求中的机密信息、个人身份信息和专有数据。 </p> <p align="center"> <img src="https://img.shields.io/badge/python-3.12+-blue?logo=python&logoColor=white" alt="Python 3.12+"> <a href="https://github.com/lumen-argus/lumen-argus/actions/workflows/test.yml"><img src="https://github.com/lumen-argus/lumen-argus/actions/workflows/test.yml/badge.svg" alt="tests"></a> <img src="https://img.shields.io/badge/dependencies-minimal-brightgreen" alt="Minimal dependencies"> <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"> <a href="https://lumen-argus.github.io/lumen-argus/docs/"><img src="https://img.shields.io/badge/docs-mkdocs-blue" alt="Documentation"></a> </p> <p align="center"> <a href="#quick-start">快速开始</a> · <a href="#what-it-detects">检测器</a> · <a href="#dashboard">仪表盘</a> · <a href="#configuration">配置</a> · <a href="#docker">Docker</a> · <a href="https://lumen-argus.github.io/lumen-argus/docs/">文档</a> </p> <p align="center"> <a href="docs/images/finding.jpg"><img src="docs/images/finding.jpg" alt="Finding detail" width="100%"/></a> </p> <table> <tr> <td align="center" width="25%"><a href="docs/images/dashboard.jpg"><img src="docs/images/dashboard.jpg" width="100%"/></a><br/>_{<b>仪表盘</b>}</td> <td align="center" width="25%"><a href="docs/images/rules.jpg"><img src="docs/images/rules.jpg" width="100%"/></a><br/>_{<b>规则</b>}</td> <td align="center" width="25%"><a href="docs/images/allowlist.jpg"><img src="docs/images/allowlist.jpg" width="100%"/></a><br/>_{<b>允许列表</b>}</td> <td align="center" width="25%"><a href="docs/images/pipeline.jpg"><img src="docs/images/pipeline.jpg" width="100%"/></a><br/>_{<b>管道</b>}</td> </tr> </table> <p align="center"> <img src="docs/images/architecture.svg" alt="lumen-argus architecture" width="100%"/> </p> ## 简介 — 30 秒试用 > 暂未发布在 PyPI — 目前从源码安装。需要 Python 3.12+ 和 [uv](https://github.com/astral-sh/uv)。 ```bash git clone https://github.com/lumen-argus/lumen-argus.git cd lumen-argus && uv sync uv run lumen-argus serve & ANTHROPIC_BASE_URL=http://localhost:8080 claude # 将支持的工具指向 :8080 open http://localhost:8081 # 实时仪表盘 ``` 将任何类似机密的字符串粘贴到聊天中。代理捕获它，记录发现，仪表盘实时更新。 ## 问题 AI 编码助手将您的代码发送到外部 API 请求。这会产生数据泄露风险： - **机密信息** — API 密钥、数据库凭证、私钥嵌入代码或配置中 - **个人身份信息** — 客户数据、社会保障号码、信用卡号码在源代码、测试fixtures或日志中 - **专有代码** — 未发布的特性、商业秘密发送到第三方 AI 提供商 lumen-argus 位于您的 AI 工具和提供商之间，扫描每个输出请求并采取行动 — **在任何数据离开您的机器之前**。 ## 主要功能 ### 检测 - **70+ 机密模式**，使用香农熵分析 - **8 个 PII 检测器**，使用验证（Luhn、SSN 范围、IBAN 校验和） - **专有代码** 检测（文件模式 + 关键词匹配） - **编码感知扫描** — 捕获 base64、hex、URL、Unicode 编码的机密信息 - **响应扫描** — 在 API 响应中检测机密信息和提示注入（异步，零延迟） ### 覆盖范围 - **27 个 AI CLI 代理** 支持，自动检测和配置 - **MCP 代理** — 扫描 stdio、HTTP 和 WebSocket 传输中的 MCP 流量（`lumen-argus mcp`） - **MCP 检测** — 从 8 个 AI 工具 + Claude Code 插件中发现 MCP 服务器 - **WebSocket 代理** — 同一端口上的双向帧扫描（可选） - **转发代理** — 用于不支持自定义基本 URL 的工具的 TLS 拦截 mitmproxy（Copilot CLI with GitHub auth） ### 身份识别和重复数据删除 - **会话跟踪** — 确定谁、哪个项目、哪次对话每个发现 - **代理中继** — 操作系统级身份识别丰富（主机名、用户名、工作目录通过 PID 相关性） - **跨请求去重** — 3 层去重消除冗余扫描的对话历史 ### 操作 - **< 50ms 扫描开销**，适用于典型负载 - **最小依赖** — aiohttp、pyyaml、pyahocorasick、phonenumbers — 其他都是标准库 - **中继 + 引擎分离** — 故障隔离的双进程架构；中继在引擎崩溃时转发（故障开启/关闭） - **热重载** — 通过 SIGHUP 更新配置，无需停机 - **保护切换** — `lumen-argus-agent protection enable/disable/status` - **Docker 就绪** — 单个命令，数据在升级过程中持续存在 ### 开发人员体验 - **网页仪表盘** — 实时发现、图表、会话过滤、审计日志 - **通知渠道** — webhook、email、Slack、Teams、PagerDuty、OpsGenie、Jira - **预提交扫描器** — 在会话历史记录之前捕获机密信息 ## 快速开始 **要求：** Python 3.12+，[uv](https://github.com/astral-sh/uv)。 > PyPI 包（`lumen-argus-proxy`、`lumen-argus-agent`、`lumen-argus-core`）尚未发布。目前从源码安装。 ```bash git clone https://github.com/lumen-argus/lumen-argus.git cd lumen-argus && uv sync uv run lumen-argus serve ``` 然后将您的 AI 工具指向代理。**支持 27 个代理** — 自动检测和配置它们： | 代理（环境变量） | 代理（配置/IDE） | 代理（手动） | 仅检测 | |---|---|---|---| | Claude Code | GitHub Copilot (IDE) | GitHub Copilot CLI | Windsurf | | Aider | Cody | Cursor | Amazon Q | | Codex CLI | Continue | Cline | Tabnine | | OpenCode | | Roo Code | Augment Code | | Gemini CLI | | Aide | Gemini Code Assist | | | | Droid | Antigravity | | | | CodeBuddy | Kiro | | | | Kilo Code | Kiro CLI | | | | | Trae | | | | | Qoder | | | | | Warp | ```bash # 自动检测安装的 AI 工具 lumen-argus detect # 从 AI 工具配置中检测 MCP 服务器 lumen-argus detect --mcp # 自动配置所有检测到的工具（环境变量、IDE 设置、转发代理） lumen-argus-agent setup # 将 MCP 服务器包装在扫描代理中（stdio + HTTP/WS） lumen-argus-agent setup --mcp # 设置需要转发代理的工具（Copilot CLI，Warp）由 # 代理 CLI 拥有 - CA 生成需要 mitmproxy 支持的代理包。 lumen-argus-agent setup copilot_cli # 或手动配置： ANTHROPIC_BASE_URL=http://localhost:8080 claude OPENAI_BASE_URL=http://localhost:8080 aider GEMINI_BASE_URL=http://localhost:8080 gemini ``` **后台监控** — 自动检测和配置新工具： ```bash # 以前台监视守护进程运行 lumen-argus-agent watch --auto-configure # 或安装为系统服务（launchd/systemd） lumen-argus-agent watch --install --auto-configure ``` **Shell 钩子** — 在每个新 shell 上警告未配置的工具： ```bash # 添加到您的 .zshrc / .bashrc（在 <100ms 内运行） eval "$(lumen-argus detect --check-quiet 2>/dev/null)" # 或自动安装： lumen-argus-agent setup # 提供安装钩子 ``` **代理中继** — 本地身份识别丰富代理（推荐用于多代理设置）： ```bash # 启动本地中继 - 用工作目录、主机名、用户丰富请求 lumen-argus-agent relay --upstream http://proxy:8080 # AI 工具连接到中继，而不是直接连接到代理 ANTHROPIC_BASE_URL=http://localhost:8070 claude ``` **转发代理** — 用于不支持自定义基本 URL 的工具的 TLS 拦截（例如，带有 GitHub 身份验证的 Copilot CLI）： ```bash # 启动带有转发代理的继电器（组合模式） lumen-argus-agent relay --upstream http://proxy:8080 --forward-proxy-port 9090 # 生成和查看 CA 证书 lumen-argus-agent forward-proxy ca-path sudo lumen-argus-agent forward-proxy install-ca # 全系统信任 # 工具特定别名（仅 Copilot CLI 路由通过转发代理） alias copilot='HTTPS_PROXY=http://localhost:9090 NODE_EXTRA_CA_CERTS=~/.lumen-argus/ca/ca-cert.pem copilot' ``` **故障隔离模式**（中继 + 引擎）： ```bash # 两个独立进程 - 中继在引擎崩溃时存活 lumen-argus engine --port 8090 & lumen-argus relay --port 8080 --engine http://localhost:8090 --fail-mode open # 或在一个进程中组合 lumen-argus serve --engine-port 8090 --fail-mode open # 切换保护开启/关闭 lumen-argus-agent protection enable lumen-argus-agent protection disable lumen-argus-agent protection status ``` **Docker：** ```bash docker compose up -d ANTHROPIC_BASE_URL=http://localhost:8080 claude open http://localhost:8081 # 仪表盘 ``` 如果 `8080`/`8081` 在您的机器上已被占用，请复制 `.env.example` 到 `.env` 并编辑 `LUMEN_ARGUS_PROXY_PORT` / `LUMEN_ARGUS_DASH_PORT` 然后运行 `docker compose up -d`。 多个会话（包括混合提供商）可以共享同一个代理实例。每个会话自动跟踪 - 代理从每个请求中提取帐户、设备、项目和对话标识符。 代理使用异步架构（aiohttp）以高并发性和低内存使用。针对 Python 3.13+ 免费线程模式（无 GIL）线程安全。 ## CLI 输出 ``` lumen-argus — 监听 http://127.0.0.1:8080 #1 POST /v1/messages opus-4-6 88.3k->1.5k 2312ms PASS #2 POST /v1/messages opus-4-6 90.1k->0.8k 1134ms ALERT aws_access_key (messages[4]) #3 POST /v1/messages opus-4-6 91.2k->2.1k 3412ms BLOCK private_key*3 shutdown — 3 requests | 1 blocked | 1 alerts | avg scan 12.3ms findings: aws_access_key, private_key*3 ``` ## 它检测什么 ### 机密（34 个模式 + 熵分析） AWS 密钥、GitHub 令牌、Anthropic/OpenAI/Google API 密钥、Stripe 密钥、Slack 令牌、JWT、数据库 URL、PEM 私钥、通用密码等。通过香农熵分析，高熵字符串接近机密相关关键词也被标记。重复发现自动折叠。 ### PII（8 个模式验证） | 类型 | 验证 | |---|---| | 邮箱 | 域名格式检查 | | SSN（美国） | 范围验证（拒绝 000、666、900+） | | 信用卡 | Luhn 算法 | | 电话（美国/国际） | 格式检查 | | IP 地址 | 排除私有/环回范围 | | IBAN | MOD-97 校验和 | | 美国护照 | 上下文要求 | ### 专有代码 - **文件模式阻止列表** - `.pem`、`.key`、`.env`、`credentials.json` 等。 - **关键词检测** - `CONFIDENTIAL`、`TRADE SECRET`、`INTERNAL ONLY` 等。 ### 编码感知扫描 隐藏在编码后面的机密信息会在扫描前被解码： | 编码 | 示例 | |---|---| | Base64 | `c2tfbGl2ZV8xMjM0...` → `sk_live_1234...` | | Hex | `736b5f6c6976655f...` → `sk_live_...` | | URL | `sk%5Flive%5F1234...` → `sk_live_1234...` | | Unicode | `\u0073\u006b\u005f...` → `sk_...` | 嵌套编码支持（例如，URL 编码中的 base64，配置深度）。每个编码类型可从 Pipeline 仪表盘页面切换。发现位置注释：`messages[0].content[base64]`。 ### 响应扫描 API 响应会异步扫描机密信息和提示注入 - 对请求/响应循环的零延迟影响。 | 检测 | 模式 | 描述 | |---|---|---| | **机密信息** | 重用所有请求检测器 | 捕获从上下文中泄漏的机密信息 | | **注入** | 10 个内置模式 | 检测提示注入（例如，“忽略以前的指令”，`<system>` 标签，渗出尝试） | 注入模式存储为数据库中的规则（检测器=`injection`）- 从规则仪表盘页面可见和可配置。启用 Pipeline 页面：切换 `Response Secrets` 和/或 `Response Injection` 阶段。 ### MCP 服务器扫描 用 DLP 扫描包装任何 MCP 服务器 - 工具调用参数和响应在 4 种传输模式下双向扫描： ```bash # Stdio 子进程 - 包装本地 MCP 服务器 lumen-argus mcp -- npx @modelcontextprotocol/server-filesystem /path # HTTP 桥 - stdio 客户端，HTTP 上游 lumen-argus mcp --upstream http://localhost:3000/mcp # HTTP 反向代理 - 集中式扫描许多客户端 lumen-argus mcp --listen :8089 --upstream http://mcp-server:3000 # WebSocket 桥 - WS 上游 lumen-argus mcp --upstream ws://localhost:9000/mcp ``` ```json { "mcpServers": { "filesystem": { "command": "lumen-argus", "args": ["mcp", "--", "npx", "@modelcontextprotocol/server-filesystem", "/path"] } } ``` **安全层**（所有默认启用）: - **工具描述毒性检测** - 7 个模式类别（注入标签、文件渗出、|文件渗出、跨工具操纵、危险执行、下载+执行、脚本注入、命令注入） - **工具漂移检测** - SHA-256 基线检测会话之间的定义变化（防止 rug-pull） - **混淆委托保护** - 跟踪输出请求 ID，拒绝无请求的响应 - **会话绑定** - 验证 `tools/call` 与第一个 `tools/list` 的工具清单（可选） - **环境限制** - 子进程模式剥夺子进程环境中的机密信息 **允许/阻止列表** 可通过 `mcp:` 配置部分或仪表盘 API 配置。 **传输覆盖范围：** - HTTP 上的 MCP - 自动检测并由主代理扫描（无需配置） - stdio 子进程 - 通过 `lumen-argus mcp --` 包装本地 MCP 服务器 - HTTP 桥接器 - stdio 客户端与远程 HTTP MCP 服务器通信 - HTTP 反向代理 - 为许多客户端集中扫描 - WebSocket 桥接器 - 适用于基于 WebSocket 的 MCP 服务器 **插件钩子** (`set_tool_policy_evaluator`, `set_approval_gate`) 允许外部包添加 ABAC 工具策略（工具名称的 glob 匹配，服务器，参数，上下文），人工干预批准门户和风险分类在社区允许/阻止列表之上。 **MCP 服务器检测** (`lumen-argus detect --mcp`) 从 8 个 AI 工具 + Claude Code 插件中发现服务器。 <details> <summary><b>扫描的配置源</b>（11 个位置）</summary> | 资料来源 | 配置位置 | JSON 键 | |--------|----------------|----------| | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | `mcpServers` | | Claude Code（用户）| `~/.claude.json` | `mcpServers` | | Claude Code（设置）| `~/.claude/settings.json` | `mcpServers` | | Claude Code（项目）| `<cwd>/.mcp.json` | `mcpServers` | | Claude Code（插件）| `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/.mcp.json` | `mcpServers` 或顶级 | | Cursor | `~/.cursor/mcp.json` | `mcpServers` | | Windsurf | `~/.windsurf/mcp.json` | `mcpServers` | | Cline | `~/.cline/mcp_servers.json` | `mcpServers` | | Roo Code | `~/.roo-code/mcp.json` | `mcpServers` | | VS Code（全局）| `~/Library/Application Support/Code/User/mcp.json` | `servers` | | VS Code（工作区）| `<cwd>/.vscode/mcp.json` | `servers` | 插件检测读取 `~/.claude/plugins/installed_plugins.json` 以获取安装路径和 `~/.claude/settings.json` 以获取启用状态。仅扫描已启用的插件。支持两种 `.mcp.json` 格式：顶级服务器名称（serena，greptile）和 `mcpServers` 包装键（playwright）。 </details> ## 规则引擎 检测规则存储在 SQLite 中 - 通过 CLI 或规则仪表盘进行管理。社区规则在第一次运行时自动导入。 ```bash lumen-argus rules import # 导入捆绑的社区规则 lumen-argus rules list # 显示加载的规则 lumen-argus rules export > backup.json # 备份以便迁移 ``` 规则支持三种来源：**导入**（CLI，模式读取，只读），**仪表盘**（完整 CRUD），**yaml**（配置管理，Kubernetes 样式协调）。每个规则都有一个层级标签（`community` / 插件层级 / `custom`），操作覆盖，启用/禁用切换和验证器。 ## 会话跟踪 每个代理请求都会被丰富会话上下文 - 无需配置。安全团队可以根据以下信息过滤发现结果： | 字段 | 来源 | 答案 | |---|---|---| | `account_id` | 提供商元数据 | 谁泄露了？ | | `session_id` | 提供商元数据或派生指纹 | 哪次对话？ | | `device_id` | Claude Code 元数据 | 哪台机器？ | | `working_directory` | 系统提示 | 哪个项目？ | | `git_branch` | 系统提示 | 哪个分支？ | | `client_name` | 客户端注册（用户代理匹配） | 哪个工具？（标准化 ID，例如“cursor”） | | `client_version` | 用户代理头部 | 哪个版本？（例如“0.45.1”） | | `sdk_name` | 从用户代理解析 | 哪个 SDK？（例如“ai-sdk/anthropic”） | | `sdk_version` | 从用户代理解析 | 哪个 SDK 版本？ | | `runtime` | 从用户代理解析 | 哪个运行时？（例如“bun/1.3.11”） | | `api_format` | 从正文自动检测 | 哪种线路格式？（anthropic/openai/gemini） | 27 个 AI CLI 代理通过客户端注册自动检测（`lumen-argus clients` 列出）。仪表盘上的发现结果可按客户端，会话和帐户过滤。 ## 跨请求去重 LLM API 请求包含完整的对话历史记录 — 每个之前的消息都会被重新发送。 如果没有去重功能，同一个密钥会在每次请求中生成重复的发现结果。 一条包含 50 条消息的对话，包含 5 个密钥，将产生约 250 行重复记录；启用去重功能后，结果仅为 5 行。 | 层级 | 功能描述 | 影响 | |---|---|---| | **内容指纹识别** | 跳过已扫描的字段（每个会话的 SHA-256 哈希集） | 减少 80-95% 的扫描 CPU 使用率 | | **发现结果 TTL 缓存** | 在 30 分钟窗口内抑制重复的数据库写入 | 约 0 个重复的 INSERT 操作 | | **存储唯一约束** | `(content_hash, session_id)` 上的 `INSERT OR IGNORE` | 深度防御 | 无需配置 — 当会话跟踪启用时自动生效。 可通过 `dedup:` 配置部分进行调整。 每个发现结果跟踪 `seen_count` — 有多少个请求包含该密钥。 仪表板上显示一个 `×N` 徽章，表示多次发现的密钥。 **值哈希:** 每个匹配密钥的 HMAC-SHA-256 哈希存储为 `value_hash`，用于发现数据库。 实现跨会话跟踪（"此确切密钥出现在 5 个会话中"），而无需保留原始密钥。 默认启用，可通过 `analytics.hash_secrets: false` 禁用。 ## 性能 典型负载的扫描开销保持在 50ms 以下。 连接池消除冗余的 TLS 握手。 | 有效载荷大小 | 中位数扫描时间 | P95 | |---|---|---| | 1 KB | 0.2ms | 0.2ms | | 10 KB | 2.6ms | 2.7ms | | 100 KB | 25.3ms | 26.3ms | | 500 KB | 51.5ms | 53.7ms | | 1 MB | 52.3ms | 54.0ms | ## 仪表板 内置 Web 仪表板，位于 `http://localhost:8081`。 | 页面 | 内容描述 | |---|---| | **仪表板** | 快速统计、严重性分解、7/30/90 天趋势、顶级检测器、顶级提供商、活动提要、最近会话、管道健康状况 | | **发现结果** | 分页表格，包含 8 个过滤器（严重性、检测器、操作、类型、提供商、客户端、时间范围、会话）+ CSV/JSON 导出 | | **规则** | 搜索/过滤、统计芯片、标签芯片、启用切换、操作选择、添加/编辑/克隆/删除。 URL 哈希深度链接来自发现结果；重叠徽章链接到规则分析 | | **规则分析** | 跨火力驱动的重叠检测（重复/子集/重叠），具有禁用/审查/驳回功能。 实时进度 + 日志流。 需要 `rules-analysis` 可选依赖项（`uv sync --extra rules-analysis`） | | **允许列表** | 机密/个人识别信息/路径 — 合并 YAML 配置 + API 条目、内联添加/删除、针对最近发现结果的模式测试面板 | | **审计** | 带有搜索功能的日志查看器 | | **管道** | 切换阶段、检测器、编码设置、默认操作 | | **设置** | 代理配置、许可证激活 | | **通知** | 频道管理 | 插件通过 Python 扩展钩子（`register_dashboard_pages`、`register_dashboard_css`、`register_dashboard_api`）和 JS 注册表（`registerPage`、`registerSettingsSection`、`registerPipelineAction`）扩展仪表板。 它们可以添加新页面、设置部分、操作选项和图表。 ### 仪表板 API <details> <summary><b>30+ REST 端点</b> — 发现结果、统计数据、规则、管道、允许列表、通知</summary> | 端点 | 描述 | |---|---| | `GET /api/v1/status` | 健康状况、正常运行时间、版本 | | `GET /api/v1/build` | 构建身份，用于侧车采用（`build_id` = 运行二进制文件的 SHA256）+ 加载的插件。 代理中继也在 `:8070` 上提供。 | | `GET /api/v1/findings` | 分页发现结果（按严重性、检测器、操作、类型、提供商、客户端、天数、会话、帐户过滤） | | `GET /api/v1/sessions` | 会话，包含发现结果计数和元数据 | | `GET /api/v1/sessions/dashboard` | 活动会话（最近 24 小时），按严重性分解 | | `GET /api/v1/stats` | 聚合统计数据，包括 `today_count`、`last_finding_time`、`by_client`（`?days=N` 表示趋势） | | `GET /api/v1/stats/advanced` | 操作趋势、活动矩阵、顶级帐户/项目、检测覆盖率 | | `GET /api/v1/config` | 当前配置 | | `PUT /api/v1/config` | 保存设置（触发 SIGHUP 重载） | | `GET /api/v1/pipeline` | 管道阶段配置，包含统计数据 | | `PUT /api/v1/pipeline` | 保存阶段切换、检测器操作、编码设置 | | `GET /api/v1/rules` | 分页规则（按层级、检测器、严重性、启用、标签、搜索过滤） | | `POST /api/v1/rules` | 创建自定义规则（操作：日志/警报/编辑/阻止） | | `GET /api/v1/rules/stats` | 按层级、检测器、启用、标签统计规则 | | `GET /api/v1/rules/:name` | 单个规则详细信息 | | `PUT /api/v1/rules/:name` | 更新规则（操作、启用、严重性等） | | `DELETE /api/v1/rules/:name` | 删除仪表板创建的规则 | | `POST /api/v1/rules/:name/clone` | 克隆规则到自定义层级 | | `POST /api/v1/rules/bulk-update` | 批量更新规则（每次最多 500 个请求） | | `GET /api/v1/rules/analysis` | 缓存的重叠分析结果（需要 crossfire） | | `POST /api/v1/rules/analysis` | 触发新的重叠分析（后台，202） | | `GET /api/v1/rules/analysis/status` | 分析进度，增量日志流 | | `POST /api/v1/rules/analysis/dismiss` | 驳回重叠发现结果对 | | `GET /api/v1/allowlists` | 合并的允许列表条目（YAML 配置 + API 管理） | | `POST /api/v1/allowlists` | 添加允许列表条目（类型：机密/个人识别信息/路径） | | `POST /api/v1/allowlists/test` | 测试模式与值和最近发现结果 | | `DELETE /api/v1/allowlists/:id` | 删除 API 管理的条目 | | `GET /api/v1/audit` | 审计日志条目 | | `GET /api/v1/live` | SSE 实时馈送 | | `GET /api/v1/notifications/channels` | 通知频道列表 | | `POST /api/v1/notifications/channels` | 创建频道（强制执行限制） | </details> [完整 API 参考](https://lumen-argus.github.io/lumen-argus/docs/reference/api-endpoints/) ## 通知频道 通过 YAML（IaC 管理）或仪表板配置警报。 社区版自带 **Webhook** 频道类型和即发即弃调度 — 指向任意 URL（Slack incoming webhooks、Discord、自定义 HTTP 端点），具有可配置的事件触发器（`block` / `alert` / `log`）和每个频道的最低严重性。 频道数量无限制。 插件通过 `register_channel_types`、`set_notifier_builder` 和 `set_dispatcher` 钩子添加频道类型和调度后端。 扩展包括重试、熔断器、调度健康监测和原生 Slack/Teams/PagerDuty/OpsGenie/Jira/Email 集成。 ```yaml notifications: - name: production-alerts type: webhook url: "https://hooks.slack.com/services/T00/B00/xxx" events: [block, alert] min_severity: high ``` YAML 频道在启动/SIGHUP（Kubernetes 风格的声明式）时与 SQLite 协调。 ## 预提交扫描器 在机密进入 AI 对话历史记录之前捕获： ```bash $ lumen-argus scan .env config/database.yml lumen-argus: .env — 3 个发现结果 [CRITICAL] 机密: aws_secret_key [CRITICAL] 机密: database_url [HIGH] 机密: generic_password $ echo $? 1 ``` ```bash # Git 预提交钩子 echo 'lumen-argus scan --diff' > .git/hooks/pre-commit chmod +x .git/hooks/pre-commit # 扫描与分支的差异（CI/PR 检查） lumen-argus scan --diff main # 基线管理 lumen-argus scan --create-baseline .lumen-argus-baseline.json src/ lumen-argus scan --baseline .lumen-argus-baseline.json src/ ``` | 退出代码 | 含义 | CI 操作 | |-----------|---------|-----------| | 0 | 无发现结果 | 通过 | | 1 | `block` 发现结果 | 失败构建 | | 2 | `alert`/`redact` 发现结果 | 警告 | | 3 | `log` 发现结果 | 信息 | ## 配置 默认配置在首次运行时创建在 `~/.lumen-argus/config.yaml`： ```yaml proxy: port: 8080 bind: "127.0.0.1" timeout: 120 connect_timeout: 10 max_connections: 50 default_action: alert # log | alert | redact | block detectors: secrets: enabled: true action: alert entropy_threshold: 4.5 pii: enabled: true action: alert proprietary: enabled: true action: alert allowlists: secrets: - "AKIAIOSFODNN7EXAMPLE" pii: - "*@example.com" paths: - "test/**" pipeline: stages: outbound_dlp: enabled: true encoding_decode: enabled: true base64: true hex: true url: true unicode: true max_depth: 2 custom_rules: - name: internal_api_token pattern: "itk_[a-zA-Z0-9]{32}" severity: critical action: block ``` **管道页面：** 从仪表板配置扫描阶段 — 切换阶段开启/关闭，启用/禁用单个检测器，设置每个检测器的操作，配置编码解码设置。 只有更改的设置保存到数据库，并通过热加载应用。 每个渲染后调度一个 `pipeline-rendered` DOM 事件，以便插件可以装饰页面。 **热加载：** `kill -HUP $(pgrep -f lumen_argus)` — 更新允许列表、操作、超时、端口/绑定和最大正文大小。 无需停机。 **项目覆盖：** 将 `.lumen-argus.yaml` 提交到您的仓库根目录。 项目配置只能比全局配置 **更具限制性**。 ## 操作 | 操作 | 行为 | |---|---| | **log** | 记录在审计日志中，允许请求 | | **alert** | 日志 + 打印到终端，允许请求 | | **block** | 拒绝并返回 HTTP 400（`invalid_request_error`）。 如果发现结果仅在对话历史记录中，则会剥离这些消息并转发清理后的请求（记录为 `strip`）。 | | **redact** | 用 `[REDACTED:{type}]` 占位符替换请求正文中的敏感值，然后转发。 不可逆转的替换。 | 最高严重性的操作获胜：`block > redact > alert > log`. ## 监控 | 端点 | 格式 | 描述 | |----------|--------|-------------| | `/health` | JSON | 代理状态、正常运行时间、请求计数 | | `/metrics` | Prometheus | 按操作请求的次数、按类型查找结果、扫描持续时间 | | `--format json` | JSONL | 用于日志聚合的结构化输出 | 两个端点都公开了扩展钩子（`set_health_hook`、`set_metrics_hook`），以便插件可以追加自己的字段/行。 `set_trace_request_hook` 扩展程序将整个请求生命周期连接到 OpenTelemetry 中，当加载跟踪插件时。 ## 软件包 来自一个 monorepo（uv 工作区）的三个软件包： | 软件包 | 功能描述 | 大小 | 依赖项 | |---------|------|------|-------------| | `lumen-argus-core` | 客户端注册、检测引擎、设置向导 | 27KB | 零（仅限标准库） | | `lumen-argus-agent` | 轻量级工作站代理 CLI | 5KB | `lumen-argus-core` | | `lumen-argus-proxy` | 带有仪表板的完整代理服务器 | 245KB | `lumen-argus-core` + aiohttp + pyyaml + pyahocorasick + phonenumbers | > PyPI 版本待定。 目前可以从源码安装。 ```bash git clone https://github.com/lumen-argus/lumen-argus.git cd lumen-argus && uv sync # 完整代理 uv run lumen-argus serve # 轻量级工作站代理（适用于指向远程代理的部署） uv run lumen-argus-agent setup --proxy-url http://proxy.local:8080 ``` 代理命令：`detect`、`setup`、`watch`、`protection`、`clients`、`relay`、`forward-proxy`、`uninstall`. **干净移除（删除检出前或发布后 `pip uninstall`）：** ```bash # 撤销代理对系统所做的所有更改：工具配置、 # MCP 包装器、shell 环境文件、launchctl 环境变量（macOS）， # 以及 ~/.lumen-argus/ 下的代理拥有状态文件。 lumen-argus-agent uninstall # 等效的独立二进制文件 — 相同的标志，相同的输出： lumen-argus-uninstall ``` 始终在 stdout 上发出 JSON，成功时退出 `0`，部分失败时退出 `1` — 安全运行多次（幂等）。 调用者计划删除 `~/.lumen-argus/` 时，请传递 `--keep-data`。 有关完整的输出形状，请参见 `docs/reference/cli.md#uninstall`。 ## Docker ```bash docker compose up -d # 启动 ANTHROPIC_BASE_URL=http://localhost:8080 claude # 连接 open http://localhost:8081 # 仪表板 ``` 数据在容器重建时保存在命名卷中。 通过卷挂载进行自定义配置。 ## 扩展 通过 Python 入口点进行插件系统： ```toml [project.entry-points."lumen_argus.extensions"] my_plugin = "my_package:register" ``` ```python def register(registry): from my_package.detectors import MyDetector registry.add_detector(MyDetector()) ``` ## 安全 - 默认绑定到 `127.0.0.1`（仅使用 `--host 0.0.0.0` 进行 Docker） - 本地 HTTP，localhost HTTPS，无 TLS 拦截 - 所有敏感文件均以 `0600` 权限创建 - 匹配的值仅在内存中保留 — 永远不会写入磁盘、日志或数据库 - 值哈希使用 HMAC-SHA-256 和自动生成的密钥（`~/.lumen-argus/hmac.key`，0600）— 数据库泄露时密钥无效 - 连接池按主机范围限定 — 无身份验证标头在提供者之间泄漏 - 仪表板：会话身份验证（HttpOnly，SameSite=Strict），CSRF 双提交，CRLF 安全重定向 - 插件 HTML 在客户端进行清理；插件 JS 受信任（仅限入口点） 有关漏洞报告，请参阅 [SECURITY.md](SECURITY.md)。 ## 社区 - **贡献** — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发设置、测试和 PR 指南 - **讨论** — [GitHub Discussions](https://github.com/lumen-argus/lumen-argus/discussions) 用于提问和想法 - **错误报告** — [GitHub Issues](https://github.com/lumen-argus/lumen-argus/issues) - **安全** — 通过 [SECURITY.md](SECURITY.md) 进行私人漏洞报告 ## 致谢 社区机密检测规则的子集改编自 [Gitleaks](https://github.com/gitleaks/gitleaks) （MIT）。 有关完整列表的上游项目和许可证归属，请参阅 [NOTICE.md](NOTICE.md)。 ## 许可证 MIT — [Artem Senenko](https://github.com/lumen-argus)