# Orbyx AI SPM - AI 安全态势管理 本项目致力于实现企业级 AI-SPM。通过这样做，组织可以主动保护其 AI 系统免受威胁，最小化数据暴露，并保持其 AI 应用程序（智能体、MPC 服务器、模型等）的可信度。 您的组织正在全力以赴投入 AI 应用程序——您准备好保护它们了吗？
在回答之前，请思考以下具体问题：
您能识别出环境中所有的影子 AI（包括 AI 模型、智能体及相关资源）吗？
您是否有效地保护 AI 数据以防止数据投毒、偏见和合规违规？
您知道如何根据上下文优先处理关键 AI 风险吗？
您是否有信心能够检测并快速响应 AI 管道中的可疑活动？
如果对上述问题中的任何一个回答“不确定”或“否”，那么您应该更深入地了解这个项目。这是了解您 AI 生态系统安全现状的方式。 发现您的 AI 智能体、模型及相关资源的安全性。 识别 AI 应用程序供应链/流水线中的风险——这些风险可能导致数据外泄和资源滥用。 实施针对 AI 使用的适当治理控制。 [](https://opensource.org/licenses/Apache-2.0)   [](https://github.com/dshapi/AI-SPM/) 

## 📋 目录 - [项目信息](#ℹ️-project-information) - [平台概览](#platform-at-a-glance) - [功能特性](#features) - [安全与访问控制](#security--access-control) - [LLM 集成与网关](#llm-integration--gateway) - [会话记忆](#conversation-memory) - [可观测性与合规性](#observability--compliance) - [基础设施与事件流水线](#infrastructure--event-pipeline) - [UI 与开发者体验](#ui--developer-experience) - [路线图](#roadmap) - [安装](#installation) - [先决条件](#prerequisites) - [克隆与配置](#clone--configure) - [API 密钥](#api-keys) - [首次启动](#first-boot) - [验证平台](#verify-the-platform) - [访问 UI 与仪表板](#access-the-ui--dashboards) - [运行烟雾测试](#run-the-smoke-test) - [停止与清理](#stopping--cleaning-up) - [使用 Keycloak + Traefik 进行本地 SSO](#local-sso-with-keycloak--traefik) - [故障排除](#troubleshooting) - [环境参考](#environment-reference) - [用法](#usage) - [技术栈](#tech-stack) - [架构概述](#architecture-overview) - [贡献](#contributing) ## ℹ️ 项目信息 - **👤 作者:** Dany Shapiro - [](https://linkedin.com/in/danyshapiro) https://www.linkedin.com/in/danyshapiro/ - **📦 版本:** 1.0.0 - **📄 许可证:** Apache-2.0 - **📂 仓库:** [https://github.com/dshapi/AI-SPM](https://github.com/dshapi/AI-SPM) ## 功能特性 ## 平台概览 | | | |--------------------------|------------------------------------------------------------------| | **微服务** | 16 | | **OPA 策略** | 6 | | **Kafka 主题** | 12+ | | **管理用户界面** | 1（管理员门户） | | **支持模型** | Anthropic / OpenAI 兼容端点 / 第三方模型导入 | | **合规框架** | NIST AI RMF（GOVERN / MAP / MEASURE / MANAGE） |

## 安全与访问控制 ### 认证与授权 | 功能 | 描述 | 组件 | |---|---|---| | **RS256 JWT 认证** | 每个 API 请求均针对平台生成的 RSA 密钥对进行验证。令牌具有短有效期且作用域受限于受众。 | CPM API | | **基于角色的访问控制** | 角色（`spm:admin`、`spm:auditor`、`user`）在所有 SPM 端点上通过 OPA 策略评估强制执行。 | OPA / CPM API | | **开发令牌端点** | `/dev-token` 生成由平台自身私钥签名的 24 小时演示 JWT —— 无需外部身份提供者即可用于开发。 | CPM API | | **每用户速率限制** | Redis 中的滑动窗口：60 请求/分钟，允许突发 10 次。返回 `429` 并附带重试标头。 | CPM API / Redis | | **租户隔离** | 所有事件、主题和审计记录均按 `tenant_id` 作用域划分。从第一天起即支持多租户。 | 所有服务 | ### 提示安全 | 功能 | 描述 | 组件 | |---|---|---| | **防护模型筛选** | 每个提示在到达 LLM 前均通过 Llama Guard 3（8B）进行筛查。拦截有害内容并附带类别标签。 | 防护模型 | | **提示注入检测** | 内存服务会扫描写入内容中的注入模式：`忽略之前的指令`、`表现得像`、`覆盖指令` 等。 | 内存服务 | | **OPA 提示策略** | Rego 策略评估姿态分数、意图漂移、防护判定和认证上下文。决策：`允许` / `升级` / `拦截`。 | OPA | | **基于姿态的拦截** | 风险分数 ≥ 0.70 的请求会被自动拦截。0.30–0.70 的请求会被升级。低于 0.30 的请求允许通过。 | 策略决策器 | | **意图漂移检测** | 使用 Jaccard 相似度跟踪与会话基线的偏差。高漂移会触发升级。 | Flink CEP | ### 输出安全 | 功能 | 描述 | 组件 | |---|---|---| | **秘密扫描** | 正则表达式检测 API 密钥（`sk-`、`ghp_`、`AKIA*`）、Bearer 令牌、密码等 LLM 响应中的敏感信息。 | CPM API | | **PII 检测** | 检测电子邮件地址、美国 SSN 和电话号码等响应中的 PII。触发脱敏或通过 OPA 输出策略进行拦截。 | CPM API | | **输出脱敏** | 匹配到的秘密和 PII 被替换为 `[REDACTED-SECRET]` / `[REDACTED-PII]`，再返回给用户。 | CPM API | | **OPA 输出策略** | 对 LLM 输出进行二次策略评估。考虑 `contains_secret`、`contains_pii` 以及 LLM 判定。 | OPA | | **输出防护 LLM** | 对响应进行二次语义扫描，以捕捉正则表达式未能识别的细微策略违规。 | 输出防护 | ## LLM 集成与网关 ### 模型管理 | 功能 | 描述 | 组件 | |---|---|---| | **模型注册表** | 完整生命周期：注册 → 批准 → 冻结 → 退役。跟踪提供者、版本、风险等级和审批人。 | SPM API / 数据库 | | **模型网关** | CPM API 在每次调用 LLM 前检查 SPM 批准状态。未批准的模型返回 `403`。设计上默认拒绝。 | CPM API / OPA | | **等级分类** | 模型分为 `低` / `中` / `高` 风险等级。影响 OPA 策略阈值和合规证据要求。 | SPM API | | **多模型支持** | 通过 `ANTHROPIC_MODEL` 环境变量在 Claude Haiku、Sonnet、Opus 之间切换。架构支持任何 OpenAI 兼容端点。 | CPM API | | **模型冻结** | 冻结控制器通过 Kafka `freeze_control` 主题实时暂停模型服务流量。 | 冻结控制器 | ### 智能体工具 | 功能 | 描述 | 组件 | |---|---|---| | **网络搜索** | Claude 可通过 Tavily API 在提示涉及时事或实时数据时自主搜索网络。 | CPM API / Tavily | | **网页获取** | Claude 获取用户提供的 URL。HTML 使用 BeautifulSoup 清理后注入上下文。 | CPM API | | **工具授权** | OPA 的 `tool_policy.rego` 在执行前根据姿态分数、意图和认证上下文评估每个工具调用。 | OPA / 执行器 | | **工具执行流水线** | 工具请求流程：`tool_request` → OPA 授权 → 执行器 → `tool_result`。副作用工具需要审批。 | 执行器 / 智能体 | | **审批工作流** | 写入/发送/删除工具操作会发布到 `approval_request` 主题并等待 `approval_result`。 | 执行器 | ## 会话记忆 | 功能 | 描述 | 组件 | |---|---|---| | **跨会话记忆** | 会话历史存储在 Redis 中，TTL 为 30 天。Claude 在每次请求中接收最近 20 轮对话作为上下文。 | CPM API / Redis | | **完整性验证** | 每次记忆写入都会生成 SHA-256 哈希。读取时验证哈希值；`integrity_ok=False` 会触发安全告警。 | 内存服务 | | **命名空间作用域** | 三个命名空间：`session`（1 小时 TTL）、`longterm`（30 天 TTL）、`system`（24 小时 TTL）。OPA 策略按命名空间控制访问。 | 内存服务 | | **注入防护** | 内存写入前会扫描提示注入模式。恶意写入会被拒绝并记录审计。 | 内存服务 | | **软删除** | 内存删除会创建墓碑而非物理删除。审计追踪得以保留用于取证。 | 内存服务 | ## 可观测性与合规性 ### Prometheus 指标 | 指标 | 描述 | |---|---| | `spm_model_risk_score` | 每个模型的风险评分量规。标签：`model_id`、`tenant_id`。 | | `spm_enforcement_actions_total` | 跟踪 `拦截` / `升级` / `允许` 决策的计数器。标签：`action`、`tenant_id`。 | | `spm_snapshot_lag_seconds` | 自上次姿态快照写入以来的秒数。每 15 秒由后台线程更新。 | | `spm_compliance_coverage_pct` | 每个功能（NIST AI RMF）的合规覆盖率百分比。标签：`function`（GOVERN、MAP、MEASURE、MANAGE、OVERALL）。 | ### Grafana 仪表板 **工程仪表板** - 随时间变化的模型风险评分（时间序列） - 强制执行操作总数（统计值） - 快照延迟（带阈值的仪表） - 模型生命周期状态（表格：名称、版本、状态、风险等级、审批人） - Web 工具调用——每次搜索/获取操作的用户、会话、精确查询（表格） - 工具类型分布——搜索与获取分离（饼图） - 被拦截的请求——防护拦截、输出拦截、模型网关拦截及原因（表格） **合规仪表板** - 每个功能的 NIST AI RMF 覆盖率（仪表盘面板） - 总体覆盖率百分比（统计值） - 合规差距表（表格：控制项、状态、证据） ### 审计与合规 | 功能 | 描述 | 组件 | |---|---|---| | **防篡改审计日志** | 所有事件写入 Kafka 审计主题并镜像到 PostgreSQL 的 `audit_export` 表。`ON CONFLICT DO NOTHING` 确保幂等性。 | SPM 聚合器 / 数据库 | | **NIST AI RMF 对齐** | 合规证据映射到 GOVERN、MAP、MEASURE、MANAGE 功能。覆盖率百分比按功能计算。 | SPM API / 数据库 | | **MITRE ATLAS TTP 映射** | CEP 将行为模式映射到 ATLAS TTP（例如 `AML.T0048`、`AML.T0051.000`）。关联至安全告警。 | Flink CEP | | **合规证据** | 将评估结果、测试报告和审批备注作为结构化证据记录关联至每个模型。 | SPM API | | **启动审计记录** | 平台启动时为每个租户写入审计记录。基准时间戳用于取证调查。 | 启动编排器 | ### 行为分析 | 功能 | 描述 | 组件 | |---|---|---| | **突发检测** | 跟踪 2 分钟窗口内的请求量。>5 次事件触发突发告警并附带 ATLAS TTP 编码。 | Flink CEP | | **持续流量检测** | 1 小时滚动窗口检测持续高流量使用（>15 次事件）。 | Flink CEP | | **关键组合检测** | 特定信号组合（例如外泄 + 高姿态 + PII）触发即时关键升级。 | Flink CEP | | **会话信号累积** | 信号在会话内累积。重复可疑信号会使风险分数复合增长。 | Flink CEP | | **姿态快照历史** | 风险评分每 5 分钟对每个模型的每个租户进行快照。对配置的 N 个快照计算滚动平均值。 | SPM 聚合器 | ## 基础设施与事件流水线 ### Kafka 事件总线 | 主题 | 发布者 | 消费者 | |---|---|---| | `{tenant}.raw_events` | API 网关 | 处理器 | | `{tenant}.posture_enriched` | 处理器 | 策略决策器、Flink CEP、SPM 聚合器 | | `{tenant}.decision` | 策略决策器 | 智能体 | | `{tenant}.tool_request` | 智能体 / 工具解析器 | 执行器 | | `{tenant}.tool_result` | 执行器 | 智能体 | | `{tenant}.audit` | 所有服务 | SPM 聚合器 → `audit_export` | | `{tenant}.memory_request` | 智能体 | 内存服务 | | `{tenant}.memory_result` | 内存服务 | 智能体 | | `{tenant}.approval_request` | 执行器 | （人工审核员） | | `{tenant}.freeze_control` | 冻结控制器 | 所有消费者 | ### 平台服务 | 服务 | 角色 | |---|---| | **启动编排器** | 验证 OPA 策略、等待 Kafka、创建主题、注册模型、运行启动自检。 | | **处理器** | 为原始事件添加姿态评分、意图分析、CEP 信号。发布 `PostureEnrichedEvent`。 | | **策略决策器** | 在增强事件上评估 OPA 提示策略。发布 `DecisionEvent`。 | | **智能体编排器** | 基于 OPA 意图清单规划工具执行和内存访问。 | | **执行器** | 执行已授权工具。实现带审批流程的工具注册表，用于副作用操作。 | | **工具解析器** | 从 LLM 输出中提取并验证结构化工具调用，再转发给执行器。 | | **内存服务** | Redis 中的作用域键值存储，包含完整性哈希、注入防护和软删除。 | | **输出防护** | 对响应进行二次 LLM 语义扫描。 | | **检索网关** | 支持 RAG 的检索服务。在注入 LLM 上下文前对文档块进行可信度评分。 | | **冻结控制器** | 通过 Kafka 实时暂停模型。冻结传播至所有消费者，延迟毫秒级。 | | **策略模拟器** | 在部署对策略变更进行干运行。返回允许/升级/拦截结果，不影响线上流量。 | | **SPM 聚合器** | 消费姿态与审计事件，写入 PostgreSQL 并更新 Prometheus 指标。 | | **SPM API** | 用于模型注册、合规证据、审批工作流和审计导出的 REST API。 | | **防护模型** | Llama Guard 3（8B）推理服务。对每个提示筛查有害内容类别。 | ## UI 与开发者体验 | 功能 | 描述 | |-----------------------------|---| | **Orbyx 管理门户** | 提供实时可见性、风险检测和跨智能体、模型、上下文流程的策略执行控制平面。 | | **Orbyx 聊天 UI** | 基于 React + Vite 的聊天界面，包含启动状态、模拟流式传输、模型选择器和新建聊天按钮。 | | **工具使用标识** | 在响应文本上方以蓝色药丸标签形式展示网络搜索和获取工具调用。 | | **安全页脚** | 固定页脚：*“所有消息均经过 Orbyx 安全层筛查”* —— 在每条消息中可见。 | | **模拟降级** | 当 API 不可用时，UI 会回退到模拟响应，实现演示场景的优雅降级。 | | **跨会话记忆 UI** | Claude 在不同会话间记住之前的对话 —— 无需用户干预。 | | **模型选择器** | 从聊天页眉或启动页切换 Claude Haiku / Sonnet / Opus。 | ## #TODO：添加更多管理门户屏幕截图 ## 路线图 尚未实现的功能 —— 下次冲刺的候选： - [ ] **人机协同升级** —— 中风险请求（0.30–0.70）路由至人工审核队列 - [ ] **自动合规报告** —— 一键导出 NIST AI RMF 姿态的 PDF/DOCX 报告 - [ ] **模型漂移检测** —— 在提供者更新后监控模型风险评分分布变化告警 - [ ] **影子模式** —— 并行运行候选模型而不提供其响应，用于对比指标 - [ ] **成本追踪** —— 按租户/用户/模型统计 Token 消耗，集成至 Prometheus 和 Grafana - [ ] **告警机制** —— 当被拦截请求数超过可配置阈值时通过 Slack/Email 通知 - [ ] **幻觉评分** —— 使用轻量验证模型对响应置信度进行后评估 - [ ] **本地模型支持** —— 集成 Ollama/vLLM 以支持在 Apple Silicon 或 GPU 上运行的 HuggingFace 模型 - [ ] **A/B 模型路由** —— 将流量切分到两个已批准模型并比较质量/风险指标 - [ ] **细粒度工具 RBAC** —— 不同用户角色可访问不同工具 - [ ] **会话回放** —— 在审计 UI 中回放任意对话以进行事件调查 *Orbyx AI SPM v3.0 · 2026 年 4 月* ## 安装 ## 目录 1. [先决条件](#prerequisites) 2. [克隆与配置](#clone--configure) 3. [API 密钥](#api-keys) 4. [首次启动](#first-boot) 5. [验证平台](#verify-the-platform) 6. [访问 UI 与仪表板](#access-the-ui--dashboards) 7. [运行烟雾测试](#run-the-smoke-test) 8. [停止与清理](#stopping--cleaning-up) 9. [故障排除](#troubleshooting) 10. [环境参考](#environment-reference) ## 先决条件 | 工具 | 最低版本 | 说明 | |---|---|---| | **Docker Desktop** | 4.25+ | 启用“使用 containerd 拉取和存储镜像”以获得最佳性能 | | **Docker Compose** | v2.20+ | 随 Docker Desktop 捆绑提供 | | **Git** | 任意 | 用于克隆仓库 | | **Make** | 任意 | `brew install make`（macOS）/ `apt install make`（Linux） | | **4 GB 可用内存** | — | Kafka + 所有服务 | | **2 GB 可用磁盘** | — | 镜像与卷 | ## 克隆与配置 ``` git clone https://github.com/your-org/orbyx-aispm.git cd orbyx-aispm ``` 复制示例环境文件： ``` cp .env.example .env ``` ## API 密钥 在任意编辑器中打开 `.env` 并填写两个必需的秘密： ### Anthropic（必需，用于 Claude 响应） ``` ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx ANTHROPIC_MODEL=claude-sonnet-4-6 # or claude-haiku-4-5-20251001 / claude-opus-4-6 ``` 在 [console.anthropic.com](https://console.anthropic.com) 获取密钥。 ### Tavily（必需，用于网页搜索工具） ``` TAVILY_API_KEY=tvly-xxxxxxxxxxxx ``` 在 [app.tavily.com](https://app.tavily.com) 获取免费密钥。若无此密钥，网页搜索工具将静默跳过搜索调用，Claude 仅能依靠训练数据作答。 ### Groq（必需用于威胁狩猎智能体 + 可选的防护模型加速） ``` GROQ_API_KEY=gsk_xxxxxxxxxxxx HUNT_MODEL=llama-3.3-70b-versatile # model used by the threat-hunting agent ``` 在 [console.groq.com](https://console.groq.com) 获取免费密钥。 Groq 在两处使用： - **威胁狩猎智能体** — `GROQ_API_KEY` 为必需。缺少该密钥时，`threat-hunting-agent` 服务将拒绝启动。 - **防护模型（LLama Guard）** — 可选。无密钥时防护降级为内置正则分类器（仍可用，但精度较低）。 ## 首次启动 ``` make up ``` 该命令将： 1. 构建所有 Docker 镜像 2. 启动完整基础设施栈（Kafka、Redis、PostgreSQL、OPA、Prometheus、Grafana） 3. 运行 **启动编排器**，其会自动： - 在 `./keys/` 生成 RSA 密钥对（用于 JWT 签名） - 创建 Kafka 主题与每个租户的 ACL - 种子化 OPA 的默认策略包 - 在 SPM 注册表中注册默认 AI 模型 4. 启动所有平台服务（API、防护模型、CEP、SPM、UI 等） 编排器在配置完成后退出。预计首次构建需 **3–5 分钟**（取决于网速）。后续启动近乎瞬时。 你将看到如下提示表示就绪： ``` ✓ Platform started. API: http://localhost:8080 Guard Model: http://localhost:8200 Freeze Controller: http://localhost:8090 Policy Simulator: http://localhost:8091 OPA: http://localhost:8181 ``` ## 验证平台 检查所有服务是否健康： ``` make status ``` 预期输出显示所有容器状态为 `Up` 或 `healthy`。API 与防护模型的健康端点将返回 JSON `{"status": "ok"}`。 或执行： ``` docker compose ps ``` ## 访问 UI 与仪表板 | 服务 | URL | 凭证 | |---|---|---| | **Orbyx 聊天 UI** | http://localhost:3000 | 自动登录（点击“Sign In”即可） | | **Grafana** | http://localhost:3001 | `admin` / `admin`（首次登录后建议修改） | | **Prometheus** | http://localhost:9090 | 无需认证 | | **OPA** | http://localhost:8181 | 无需认证 | | **SPM API** | http://localhost:8092 | 需要 JWT Bearer 令牌 | | **策略模拟器** | http://localhost:8091 | 需要 JWT Bearer 令牌 | ### Grafana 仪表板 三个仪表板已预置并自动加载： - **AI SPM 概览** — 姿态评分、强制执行操作、风险趋势 - **工程** — 工具调用、拦截请求、模型性能、CEP 事件 - **合规** — NIST AI RMF 控制覆盖率、审计追踪 ## 运行烟雾测试 通过完整流水线发送真实请求并验证端到端： ``` make smoke-test ``` 该操作将： 1. 铸造演示 JWT 2. 发送 `"What meetings do I have today?"` → 期望收到 Claude 响应 3. 发送一次提示注入尝试 → 期望返回 `HTTP 400`（被拦截） 通过的运行结果以如下内容结尾： ``` git clone https://github.com/your-org/orbyx-aispm.git cd orbyx-aispm ``` ## 停止与清理 **停止所有服务（保留数据）：** ``` ./stop.sh # or docker-compose -f docker-compose.yml -f docker-compose.auth.yml down ``` **重新启动所有服务：** ``` ./start.sh ``` **停止但不包含认证覆盖层：** ``` docker compose down ``` **停止并清除所有数据（卷与生成的密钥）：** ``` make clean ``` ## 故障排除 ### 服务无法启动 / `make up` 提前退出 检查编排器日志： ``` docker compose logs startup-orchestrator ``` 常见原因：Kafka 未及时就绪。可重试 `make up` —— 该命令具有幂等性。 ### `cpm-startup-orchestrator` 未找到 使用 **服务名称**（而非容器名称）与 `docker compose`： ``` docker compose restart startup-orchestrator # ✓ correct docker compose restart cpm-startup-orchestrator # ✗ wrong ``` ### 聊天 UI 显示 `[object Object]` 错误 这表示模型网关拒绝了请求。检查 `.env` 中的 `LLM_MODEL_ID` 是否为空： ``` LLM_MODEL_ID= ``` 然后重启 API： ``` docker compose up -d --build api ``` ### 来自 Anthropic 的 `404 模型未找到` 你的 `.env` 中的模型名称已过期。请更新为当前有效模型： ``` ANTHROPIC_MODEL=claude-sonnet-4-6 ``` 当前有效模型 ID： | 标签 | 模型 ID | |---|---| | Claude Haiku | `claude-haiku-4-5-20251001` | | Claude Sonnet | `claude-sonnet-4-6` | | Claude Opus | `claude-opus-4-6` | ### Grafana 面板显示“无数据” 面板在处理首个真实请求后才会填充数据。运行 `make smoke-test` 生成事件，然后刷新仪表板。 ### 端口冲突 若任意端口（3000、3001、8080 等）已被占用，请编辑 `docker-compose.yml` 并修改主机侧端口映射： ``` ports: - "3100:3000" # change 3000 → 3100 (host:container) ``` ### 威胁狩猎采集器报告 `column "session_id" does not exist` `audit_export` 表缺少迁移 `002` 添加的 `session_id` 列。在栈运行期间执行一次迁移： ``` # Option A — via Alembic docker compose exec spm-api alembic upgrade head # Option B — direct SQL docker compose exec spm-db psql -U spm_rw -d spm -c " ALTER TABLE audit_export ADD COLUMN IF NOT EXISTS session_id VARCHAR(64); CREATE INDEX IF NOT EXISTS idx_audit_export_session_id ON audit_export (session_id); " ``` ### `threat-hunting-agent` 启动失败 — 缺少 `GROQ_API_KEY` 威胁狩猎智能体需要 Groq API 密钥。在 `.env` 中设置： ``` GROQ_API_KEY=gsk_xxxxxxxxxxxx ``` 在 [console.groq.com](https://console.groq.com) 获取免费密钥，然后重建服务： ``` docker compose up -d --build threat-hunting-agent ``` ### 重建单个服务（代码变更后） ``` docker compose up -d --build api # rebuild API only docker compose up -d --build ui # rebuild UI only docker compose up -d --build spm-aggregator # rebuild SPM aggregator docker compose up -d --build threat-hunting-agent # rebuild threat hunting agent ``` ## 环境参考 可在 `.env` 中调整以下变量。所有项均有合理默认值，仅 API 密钥需要设置以使安装生效。 | 变量 | 默认值 | 描述 | |---|---|---| | `ANTHROPIC_API_KEY` | *(必需)* | Anthropic API 密钥 | | `ANTHROPIC_MODEL` | `claude-sonnet-4-6` | 使用的 Claude 模型 | | `TAVILY_API_KEY` | *(可选)* | Tavily 密钥（用于网页搜索工具） | | `GROQ_API_KEY` | *(威胁狩猎必需)* | Groq 密钥 —— 为威胁狩猎智能体 LLM 提供支持，并可选地加速 Llama Guard 3 | | `HUNT_MODEL` | `llama-3.3-70b-versatile` | 威胁狩猎智能体使用的 Groq 模型 | | `HUNT_BATCH_WINDOW_SEC` | `30` | 威胁狩猎智能体的 Kafka 批处理窗口（秒） | | `THREATHUNTING_AI_INTERVAL_SEC` | `300` | 主动威胁扫描间隔（秒） | | `TENANTS` | `t1` | 逗号分隔的租户 ID 列表 | | `RATE_LIMIT_RPM` | `60` | 每分钟每用户的最大请求数 | | `GUARD_MODEL_ENABLED` | `true` | 启用/禁用内容防护 | | `POSTURE_BLOCK_THRESHOLD` | `0.70` | 请求风险评分达到此值时将被拦截 | | `CEP_SHORT_WINDOW_SEC` | `120` | 突发检测窗口（秒） | | `CEP_LONG_WINDOW_SEC` | `3600` | 持续流量检测窗口（秒） | | `MEMORY_LONGTERM_TTL_SEC` | `2592000` | 跨会话内存 TTL（30 天） | | `SPM_SNAPSHOT_INTERVAL_SEC` | `300` | 姿态快照间隔（5 分钟） | | `GRAFANA_ADMIN_PASSWORD` | `admin` | Grafana 管理员密码 | | `REDIS_PASSWORD` | *(空)* | Redis 密码（空表示无认证） | | `SPM_DB_PASSWORD` | `spmpass` | SPM 数据库的 PostgreSQL 密码 | | `LLM_MODEL_ID` | *(空)* | SPM 模型注册表 ID（留空以绕过网关） | ## 快速参考命令 ``` make up # Start everything make down # Stop everything make status # Health check make logs # Tail all logs make logs-api # Tail API logs only make smoke-test # End-to-end test make token # Mint a demo user JWT make admin-token # Mint an admin JWT make freeze # Freeze demo user (requires admin token) make unfreeze # Unfreeze demo user make clean # Wipe all data and keys ``` ## 用法 ## 目录 1. [先决条件](#prerequisites) 2. [克隆与配置](#clone--configure) 3. [API 密钥](#api-keys) 4. [首次启动](#first-boot) 5. [验证平台](#verify-the-platform) 6. [访问 UI 与仪表板](#access-the-ui--dashboards) 7. [运行烟雾测试](#run-the-smoke-test) 8. [停止与清理](#stopping--cleaning-up) 9. [故障排除](#troubleshooting) 10. [环境参考](#environment-reference) ## 先决条件 | 工具 | 最低版本 | 说明 | |---|---|---| | **Docker Desktop** | 4.25+ | 启用“使用 containerd 拉取和存储镜像”以获得最佳性能 | | **Docker Compose** | v2.20+ | 随 Docker Desktop 捆绑提供 | | **Git** | 任意 | 用于克隆仓库 | | **Make** | 任意 | `brew install make`（macOS）/ `apt install make`（Linux） | | **4 GB 可用内存** | — | Kafka + 所有服务 | | **2 GB 可用磁盘** | — | 镜像与卷 | ## 克隆与配置 ``` git clone https://github.com/your-org/orbyx-aispm.git cd orbyx-aispm ``` 复制示例环境文件： ``` cp .env.example .env ``` ## API 密钥 在任意编辑器中打开 `.env` 并填写两个必需的秘密： ### Anthropic（必需，用于 Claude 响应） ``` ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx ANTHROPIC_MODEL=claude-sonnet-4-6 # or claude-haiku-4-5-20251001 / claude-opus-4-6 ``` 在 [console.anthropic.com](https://console.anthropic.com) 获取密钥。 ### Tavily（必需，用于网页搜索工具） ``` TAVILY_API_KEY=tvly-xxxxxxxxxxxx ``` 在 [app.tavily.com](https://app.tavily.com) 获取免费密钥。若无此密钥，网页搜索工具将静默跳过搜索调用，Claude 仅能依靠训练数据作答。 ### Groq（必需用于威胁狩猎智能体 + 可选的防护模型加速） ``` GROQ_API_KEY=gsk_xxxxxxxxxxxx HUNT_MODEL=llama-3.3-70b-versatile # model used by the threat-hunting agent ``` 在 [console.groq.com](https://console.groq.com) 获取免费密钥。 Groq 在两处使用： - **威胁狩猎智能体** — `GROQ_API_KEY` 为必需。缺少该密钥时，`threat-hunting-agent` 服务将拒绝启动。 - **防护模型（LLama Guard）** — 可选。无密钥时防护降级为内置正则分类器（仍可用，但精度较低）。 ## 首次启动 ``` make up ``` 该命令将： 1. 构建所有 Docker 镜像 2. 启动完整基础设施栈（Kafka、Redis、PostgreSQL、OPA、Prometheus、Grafana） 3. 运行 **启动编排器**，其会自动： 在 `./keys/` 生成 RSA 密钥对（用于 JWT 签名） - 创建 Kafka 主题与每个租户的 ACL - 种子化 OPA 的默认策略包 - 在 SPM 注册表中注册默认 AI 模型 4. 启动所有平台服务（API、防护模型、CEP、SPM、UI 等） 编排器在配置完成后退出。预计首次构建需 **3–5 分钟**（取决于网速）。后续启动近乎瞬时。 你将看到如下提示表示就绪： ``` ✓ Platform started. API: http://localhost:8080 Guard Model: http://localhost:8200 Freeze Controller: http://localhost:8090 Policy Simulator: http://localhost:8091 OPA: http://localhost:8181 ``` ## 验证平台 检查所有服务是否健康： ``` make status ``` 预期输出显示所有容器状态为 `Up` 或 `healthy`。API 与防护模型的健康端点将返回 JSON `{"status": "ok"}`。 或执行： ``` docker compose ps ``` ## 访问 UI 与仪表板 | 服务 | URL | 凭证 | |---|---|---| | **Orbyx 聊天 UI** | http://localhost:3000 | 自动登录（点击“Sign In”即可） | | **Grafana** | http://localhost:3001 | `admin` / `admin`（首次登录后建议修改） | | **Prometheus** | http://localhost:9090 | 无需认证 | | **OPA** | http://localhost:8181 | 无需认证 | | **SPM API** | http://localhost:8092 | 需要 JWT Bearer 令牌 | | **策略模拟器** | http://localhost:8091 | 需要 JWT Bearer 令牌 | ### Grafana 仪表板 三个仪表板已预置并自动加载： - **AI SPM 概览** — 姿态评分、强制执行操作、风险趋势 - **工程** — 工具调用、拦截请求、模型性能、CEP 事件 - **合规** — NIST AI RMF 控制覆盖率、审计追踪 ## 运行烟雾测试 通过完整流水线发送真实请求并验证端到端： ``` make smoke-test ``` 该操作将： 1. 铸造演示 JWT 2. 发送 `"What meetings do I have today?"` → 期望收到 Claude 响应 3. 发送一次提示注入尝试 → 期望返回 `HTTP 400`（被拦截） 通过的运行结果以如下内容结尾： ``` ✓ Smoke test PASSED ``` ## 停止与清理 **停止所有服务（保留数据）：** ``` ./stop.sh # or docker-compose -f docker-compose.yml -f docker-compose.auth.yml down ``` **重新启动所有服务：** ``` ./start.sh ``` **停止但不包含认证覆盖层：** ``` docker compose down ``` **停止并清除所有数据（卷与生成的密钥）：** ``` make clean ``` ## 故障排除 ### 服务无法启动 / `make up` 提前退出 检查编排器日志： ``` docker compose logs startup-orchestrator ``` 常见原因：Kafka 未及时就绪。可重试 `make up` —— 该命令具有幂等性。 ### `cpm-startup-orchestrator` 未找到 使用 **服务名称**（而非容器名称）与 `docker compose`： ``` docker compose restart startup-orchestrator # ✓ correct docker compose restart cpm-startup-orchestrator # ✗ wrong ``` ### 聊天 UI 显示 `[object Object]` 错误 这表示模型网关拒绝了请求。检查 `.env` 中的 `LLM_MODEL_ID` 是否为空： ``` LLM_MODEL_ID= ``` 然后重启 API： ``` docker compose up -d --build api ``` ### 来自 Anthropic 的 `404 模型未找到` 你的 `.env` 中的模型名称已过期。请更新为当前有效模型： ``` ANTHROPIC_MODEL=claude-sonnet-4-6 ``` 当前有效模型 ID： | 标签 | 模型 ID | |---|---| | Claude Haiku | `claude-haiku-4-5-20251001` | | Claude Sonnet | `claude-sonnet-4-6` | | Claude Opus | `claude-opus-4-6` | ### Grafana 面板显示“无数据” 面板在处理首个真实请求后才会填充数据。运行 `make smoke-test` 生成事件，然后刷新仪表板。 ### 端口冲突 若任意端口（3000、3001、8080 等）已被占用，请编辑 `docker-compose.yml` 并修改主机侧端口映射： ``` ports: - "3100:3000" # change 3000 → 3100 (host:container) ``` ### 威胁狩猎采集器报告 `column "session_id" does not exist` `audit_export` 表缺少迁移 `002` 添加的 `session_id` 列。在栈运行期间执行一次迁移： ``` # Option A — via Alembic docker compose exec spm-api alembic upgrade head # Option B — direct SQL docker compose exec spm-db psql -U spm_rw -d spm -c " ALTER TABLE audit_export ADD COLUMN IF NOT EXISTS session_id VARCHAR(64); CREATE INDEX IF NOT EXISTS idx_audit_export_session_id ON audit_export (session_id); " ``` ### `threat-hunting-agent` 启动失败 — 缺少 `GROQ_API_KEY` 威胁狩猎智能体需要 Groq API 密钥。在 `.env` 中设置： ``` GROQ_API_KEY=gsk_xxxxxxxxxxxx ``` 在 [console.groq.com](https://console.groq.com) 获取免费密钥，然后重建服务： ``` docker compose up -d --build threat-hunting-agent ``` ### 重建单个服务（代码变更后） ``` docker compose up -d --build api # rebuild API only docker compose up -d --build ui # rebuild UI only docker compose up -d --build spm-aggregator # rebuild SPM aggregator docker compose up -d --build threat-hunting-agent # rebuild threat hunting agent ``` ## 环境参考 可在 `.env` 中调整以下变量。所有项均有合理默认值，仅 API 密钥需要设置以使安装生效。 | 变量 | 默认值 | 描述 | |---|---|---| | `ANTHROPIC_API_KEY` | *(必需)* | Anthropic API 密钥 | | `ANTHROPIC_MODEL` | `claude-sonnet-4-6` | 使用的 Claude 模型 | | `TAVILY_API_KEY` | *(可选)* | Tavily 密钥（用于网页搜索工具） | | `GROQ_API_KEY` | *(威胁狩猎必需)* | Groq 密钥 —— 为威胁狩猎智能体 LLM 提供支持，并可选地加速 Llama Guard 3 | | `HUNT_MODEL` | `llama-3.3-70b-versatile` | 威胁狩猎智能体使用的 Groq 模型 | | `HUNT_BATCH_WINDOW_SEC` | `30` | 威胁狩猎智能体的 Kafka 批处理窗口（秒） | | `THREATHUNTING_AI_INTERVAL_SEC` | `300` | 主动威胁扫描间隔（秒） | | `TENANTS` | `t1` | 逗号分隔的租户 ID 列表 | | `RATE_LIMIT_RPM` | `60` | 每分钟每用户的最大请求数 | | `GUARD_MODEL_ENABLED` | `true` | 启用/禁用内容防护 | | `POSTURE_BLOCK_THRESHOLD` | `0.70` | 请求风险评分达到此值时将被拦截 | | `CEP_SHORT_WINDOW_SEC` | `120` | 突发检测窗口（秒） | | `CEP_LONG_WINDOW_SEC` | `3600` | 持续流量检测窗口（秒） | | `MEMORY_LONGTERM_TTL_SEC` | `2592000` | 跨会话内存 TTL（30 天） | | `SPM_SNAPSHOT_INTERVAL_SEC` | `300` | 姿态快照间隔（5 分钟） | | `GRAFANA_ADMIN_PASSWORD` | `admin` | Grafana 管理员密码 | | `REDIS_PASSWORD` | *(空)* | Redis 密码（空表示无认证） | | `SPM_DB_PASSWORD` | `spmpass` | SPM 数据库的 PostgreSQL 密码 | | `LLM_MODEL_ID` | *(空)* | SPM 模型注册表 ID（留空以绕过网关） | ## 快速参考命令 ``` make up # Start everything make down # Stop everything make status # Health check make logs # Tail all logs make logs-api # Tail API logs only make smoke-test # End-to-end test make token # Mint a demo user JWT make admin-token # Mint an admin JWT make freeze # Freeze demo user (requires admin token) make unfreeze # Unfreeze demo user make clean # Wipe all data and keys ``` ## 聊天界面 打开 **http://localhost:3000** 并在浏览器中操作。 1. 点击 **Sign In** —— 系统会自动铸造一个演示 JWT。 2. 在输入框中输入消息并按 **Enter** 或点击 **Send**。 3. Claude 将作出响应。如果使用了网络搜索或网页获取工具，你会在回复上方看到蓝色药丸标签。 4. 使用页眉中的 **模型选择器** 切换 Claude Haiku / Sonnet / Opus。 ### 会话记忆 Claude 会在不同会话记住之前的对话（最长 30 天）—— 无需用户重复提供上下文。 ## 拦截的请求 部分提示会被平台自动拦截： | 拦截类型 | 示例触发 | HTTP 状态码 | |---|---|---| | 提示注入 | `忽略之前的指令…` | `400` | | 高姿态评分 | 重复的可疑模式 | `400` | | 模型网关 | 未批准的模型 ID | `403` | | 输出防护 | 响应中包含敏感数据 | `400` | 当请求被拦截时，UI 会显示红色错误消息说明原因。 ## 管理操作 通过终端铸造令牌并管理用户： ``` # Mint a regular user token make token # Mint an admin token make admin-token # Freeze a user (blocks all their requests) make freeze # Unfreeze a user make unfreeze ``` ## Grafana 仪表板 打开 **http://localhost:3001** → 使用 `admin` / `admin` 登录。 | 仪表板 | 查看内容 | |---|---| | **AI SPM 概览** | 实时姿态评分、强制执行操作、风险趋势（按租户） | | **工程** | 工具调用次数、拦截请求及原因、CEP 事件、模型延迟 | | **合规** | NIST AI RMF 控制覆盖率、30 天审计追踪 | 仪表板会自动刷新每 30 秒。使用右上角的时间范围选择器可缩放查看。 ## SPM API（REST） 基础 URL：**http://localhost:8092** 所有端点均需要 Bearer 令牌。使用 `make admin-token` 或 `make spm-token-auditor` 获取令牌。 ``` # List registered AI models TOKEN=$(make admin-token -s) curl -H "Authorization: Bearer $TOKEN" http://localhost:8092/models # Register a new model curl -X POST http://localhost:8092/models \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"my-model","version":"1.0","provider":"openai","risk_tier":"limited"}' # NIST AI RMF compliance report curl -H "Authorization: Bearer $TOKEN" \ http://localhost:8092/compliance/nist-airm/report ``` ## 策略模拟器 在部署前对策略变更进行干运行测试： ``` make simulate ``` 或直接调用 **http://localhost:8091/simulate** 接口，传入候选策略与样本事件。响应将展示在新策略下事件会被允许、升级还是拦截。 ## 日志 ``` make logs # all services make logs-api # API only make logs-spm-api # SPM API only docker compose logs -f guard-model # any service by name ``` ## 常见工作流 ### 调查被拦截的请求 1. 打开 Grafana → **工程** 仪表板 → **拦截请求** 表 2. 记录 `reason` 与 `session_id` 3. 查询日志：`make logs-api | grep ` ### 检查用户姿态评分 ``` TOKEN=$(make admin-token -s) curl -H "Authorization: Bearer $TOKEN" \ "http://localhost:8092/posture?tenant_id=t1&user_id=user-demo-1" ``` ### 模拟合规报告 ``` make spm-compliance ``` 返回一个 JSON 报告，将 NIST AI RMF 控制项映射为通过/部分/失败状态，依据当前平台配置。 ## 技术栈 # Orbyx AI SPM — 技术栈 完整的技术清单。 ## 架构概述  ### 控制平面与数据路径 

ASCII 图

``` ┌─────────────────────────────────────────────────────────┐ │ Browser (React) │ └───────────────────────────┬─────────────────────────────┘ │ HTTP ┌───────────────────────────▼─────────────────────────────┐ │ API Gateway (FastAPI / Python) │ │ Auth · Rate limit · Guard · CEP · Memory · LLM tools │ └──────┬────────────┬────────────┬───────────┬────────────┘ │ Kafka │ Redis │ OPA │ Anthropic ┌──────▼──────┐ ┌───▼───┐ ┌────▼────┐ ┌─────▼──────────┐ │ Kafka │ │ Redis │ │ OPA │ │ Claude (LLM) │ │ (events) │ │(cache)│ │(policy) │ │ + Tavily │ └──────┬──────┘ └───────┘ └─────────┘ └────────────────┘ │ ├─────────────────────────────────────────────────┐ │ │ ┌──────▼──────────────────────────────────────────────┐ │ │ SPM Aggregator (Python) │ │ │ Consumes events → writes to Postgres │ │ └──────────────────────────┬──────────────────────────┘ │ │ SQL │ Kafka ┌──────────────────────────▼──────────────────────────┐ │ │ SPM API (FastAPI / Python) │ │ │ Model registry · Posture · Compliance · Enforce │ │ └──────────────────────────┬──────────────────────────┘ │ │ │ ┌──────────────────────────▼──────────────────────────┐ │ │ Observability (Prometheus + Grafana) │ │ └─────────────────────────────────────────────────────┘ │ │ ┌────────────────────────────────────────────────────────▼┐ │ Threat Hunting Agent (LangChain + Groq) │ │ 9 proactive scans · Redis · Postgres · /proc · OPA │ └──────────────────────────┬──────────────────────────────┘ │ HTTP POST /api/v1/threat-findings ┌──────────────────────────▼──────────────────────────────┐ │ Agent Orchestrator (FastAPI / Python) │ │ Session lifecycle · Risk scoring · Findings · Cases │ └─────────────────────────────────────────────────────────┘ ```

## 基础设施 | 组件 | 技术 | 版本 | 角色 | |---|---|---|---| | **容器运行时** | Docker + Docker Compose | Compose v2 | 在本地运行所有服务 | | **消息代理** | Apache Kafka（Confluent） | 7.6.1 | 事件流 backbone —— 审计、姿态、CEP 事件 | | **缓存 / 内存** | Redis | 7（Alpine） | 会话内存、长期对话历史、速率限制 | | **数据库** | PostgreSQL | 16（Alpine） | SPM 审计日志、姿态快照、模型注册表 | | **策略引擎** | Open Policy Agent（OPA） | 0.70.0 | 基于 Rego 的请求策略评估 | | **指标** | Prometheus | v2.55.1 | 从所有服务抓取 `/metrics` | | **仪表板** | Grafana | 11.4.0 | 预置的 AI SPM、工程与合规仪表板 | ## 后端服务 所有后端服务均使用 **Python 3.11** 编写，通过 **FastAPI + Uvicorn** 提供服务。 | 服务 | 端口 | 描述 | |---|---|---| | `api` | 8080 | 主网关 —— 认证、防护、LLM 代理、速率限制 | | `guard-model` | 8200 | 内容审核（通过 Groq 的 Llama Guard 3 或内置正则降级） | | `freeze-controller` | 8090 | 管理员冻结/解冻用户与租户 | | `policy-simulator` | 8091 | 在样本事件上干运行策略变更 | | `spm-api` | 8092 | 模型注册表、姿态 API、合规报告 | | `spm-aggregator` | — | Kafka 消费者 → PostgreSQL 写入器、Prometheus 指标 | | `processor` | — | Kafka 消费者 —— 为原始事件添加姿态评分 | | `memory-service` | — | 在 Redis 中管理会话、长期与系统内存，含完整性哈希与注入防护 | | `output-guard` | — | 对 Claude 响应进行二次 LLM 语义扫描 | | `policy-decider` | — | 评估 OPA 决策并发布强制执行事件 | | `retrieval-gateway` | — | 支持 RAG 的检索服务，对文档块进行可信度评分 | | `tool-parser` | — | 解析并验证 LLM 输出的结构化工具调用 | | `executor` | — | 执行已授权工具调用，附带审批流程用于副作用操作 | | `agent-orchestrator` | 8094 | 会话生命周期、风险评分、威胁数据存储与案例管理 | | `threat-hunting-agent` | — | 自主 AI 安全威胁狩猎 —— 9 个检测器 + LangChain/Groq LLM | | `startup-orchestrator` | — | 一次性初始化容器：生成密钥、创建 Kafka 主题、种子 OPA、注册默认模型 | ### 核心 Python 库 | 库 | 版本 | 用途 | |---|---|---| | **FastAPI** | 0.115.x | REST API 框架 | | **Uvicorn** | 0.30–0.32 | ASGI 服务器 | | **Pydantic** | 2.9 | 请求/响应校验 | | **anthropic** | 0.40.0 | Claude API 客户端（工具使用、流式传输） | | **kafka-python-ng** | 2.2.3 | Kafka 生产者/消费者 | | **redis** | 5.1–5.2 | Redis 客户端 | | **PyJWT + cryptography** | 2.9–2.10 / 43.0 | RS256 JWT 签名与验证 | | **httpx** | 0.27.2 | 异步 HTTP 客户端（工具获取、跨服务调用） | | **requests** | 2.32 | 同步 HTTP 客户端 | | **SQLAlchemy (asyncio)** | 2.0.36 | 异步 ORM，用于 SPM 数据库 | | **asyncpg** | 0.30.0 | 异步 PostgreSQL 驱动 | | **psycopg2-binary** | 2.9.9 | 同步 PostgreSQL 驱动 | | **groq** | 0.11.0 | Groq 客户端（用于 Llama Guard 3 推理） | | **tavily-python** | 0.5.0 | 网页搜索工具（Tavily API） | | **beautifulsoup4 + lxml** | 4.12.3 / 5.3.0 | HTML 解析（用于网页获取工具） | | **prometheus-client** | 0.21.1 | 暴露 `/metrics` 端点 | | **prometheus-fastapi-instrumentator** | 7.0.0 | 自动为 FastAPI 集成 Prometheus | | **weasyprint** | 62.3 | PDF 报告生成（合规导出） | ## 前端 技术 | 版本 | 角色 | |---|---|---| | **React** | 18.3 | UI 框架 | | **Vite** | 5.4 | 构建工具与开发服务器 | | **react-markdown** | 9.0 | 渲染 Claude 的 Markdown 响应 | | **remark-gfm** | 4.0 | GitHub 风格 Markdown（表格、删除线等） | 前端是单页应用，由 Nginx 容器（端口 3000）提供服务。无外部 CSS 框架 —— 完全自定义设计，使用 CSS 变量实现主题。 ## 外部 API | 服务 | 用途 | 是否必需 | |---|---|---| | **Anthropic Claude** | LLM 后端（Haiku / Sonnet / Opus） | ✅ 必需 | | **Tavily** | 实时网页搜索工具 | ⚠️ 可选 | | **Groq** | 威胁狩猎智能体 LLM（LLaMA 3.3 70B） + Llama Guard 3 内容审核 | ✅ 必需（威胁狩猎） / ⚠️ 可选（防护） | ## 安全与认证 | 组件 | 技术 | 说明 | |---|---|---| | **认证** | RS256 JWT | 密钥对在启动时自动生成到 `./keys/` | | **授权** | OPA + Rego | 策略即代码，按请求评估 | | **内容审核** | Llama Guard 3（Groq）或正则降级 | 过滤有害内容类别 | | **输出扫描** | 二次 LLM 语义检查 | 防止敏感数据泄露 | | **速率限制** | Redis 计数器 | 每分钟每用户限制，可配置 | | **提示注入检测** | 防护模型 + CEP 模式匹配 | 模式匹配与 ML 评分结合 | ## 可观测性 | 层级 | 技术 | 细节 | |---|---|---| | **指标** | Prometheus | 每 15 秒从所有服务抓取 `/metrics` | | **仪表板** | Grafana | 3 个预置仪表板，自动加载 | | **审计日志** | PostgreSQL (`audit_export` 表) | 每条请求以 JSONB 形式写入，支持 `ON CONFLICT DO NOTHING` 保证幂等 | | **结构化日志** | Python `logging` → stdout | 通过 Docker 查看，`make logs` 可收集 | | **姿态快照** | PostgreSQL + Prometheus | 每 5 分钟对每个模型/租户记录滚动平均值 | ## 数据流 ``` User prompt │ ▼ JWT Auth → Rate Limit → Guard Model (content check) │ ▼ OPA Policy Evaluation │ ▼ Memory Load (Redis — last 20 turns, 30-day TTL) │ ▼ Claude API (tool loop — up to 3 rounds) │ ├── web_search → Tavily │ └── web_fetch → httpx + BeautifulSoup ▼ Output Guard (second-pass LLM scan) │ ▼ Audit Event → Kafka → SPM Aggregator → PostgreSQL + Prometheus │ ▼ Response → User ``` ## 威胁狩猎智能体 **威胁狩猎智能体** 是一个自主 AI 安全服务，持续扫描平台以发现威胁 —— 与用户触发的请求无关。它运行一个 LangChain 代理，依赖 **Groq + Llama 3.3 70B Versatile** 并基于以下两种机制触发： - **Kafka 消费者** — 近乎实时地响应会话事件 - **调度器** — 每 5 分钟（可配置）执行一次全平台主动扫描 ### 主动扫描 每次扫描周期并行运行全部 9 个检测器。所有检测器查询实时数据（PostgreSQL、Redis、`/proc`）并生成结构化发现，由智能体通过 LLM 分析后提交至编排器。 | 扫描器 | 检测内容 | |---|---| | `exposed_credentials` | Redis 中意外命名空间下的 API 密钥、令牌、密码 | | `sensitive_data_exposure` | PII 模式、数据库连接字符串等更广泛的数据泄露 | | `unused_open_ports` | 内部服务端口处于开放但不应开放的状态 | | `unexpected_listen_ports` | `/proc/net/tcp` 中处于 LISTEN 状态但不在允许服务列表的端口 | | `overprivileged_tools` | 注册表中风险等级过高但仍为活跃状态的模型 | | `runtime_anomaly_detection` | 高频操作者、每会话阻断簇（≥3/小时）、会话风暴（5+/10分钟） | | `prompt_secret_exfiltration` | 提示或响应中的 API 密钥、Bearer 令牌 | | `data_leakage_detection` | 响应中的 SSN、信用卡号、电子邮件地址 | | `tool_misuse_detection` | 单会话工具调用频率过高（>20/小时）、快速链（>5/分钟）、高阻断比例 | ### 发现与案例 当扫描发现异常时，智能体会生成结构化的 **威胁发现**（严重等级、假设、证据、建议操作），并执行以下流程： 1. 通过 `POST /api/v1/threat-findings` 发送至编排器 2. 按批次哈希去重，避免重复告警 3. 按风险分数、时效性、发生次数自动优先级排序 4. 当 `should_open_case=true` 且优先级 ≥ 0.40 时自动升级为 **案例** ### 配置 ``` GROQ_API_KEY=gsk_xxxxxxxxxxxx # required — service won't start without it HUNT_MODEL=llama-3.3-70b-versatile # LLM model (any Groq-hosted model) HUNT_BATCH_WINDOW_SEC=30 # Kafka batch window THREATHUNTING_AI_INTERVAL_SEC=300 # Proactive scan interval (seconds) ``` ### 数据库迁移 威胁狩猎采集器查询 `audit_export` 表的 `session_id` 列。若为现有安装，在启动智能体前需执行迁移： ``` # Option A — via Alembic (recommended) docker compose exec spm-api alembic upgrade head # Option B — direct SQL (if Alembic is unavailable) docker compose exec spm-db psql -U spm_rw -d spm -c " ALTER TABLE audit_export ADD COLUMN IF NOT EXISTS session_id VARCHAR(64); CREATE INDEX IF NOT EXISTS idx_audit_export_session_id ON audit_export (session_id); " ``` ## Kafka 主题 | 主题 | 发布者 | 消费者 | |---|---|---| | `{tenant}.raw_events` | API 网关 | 处理器、CEP | | `{tenant}.posture_enriched` | 处理器 | SPM 聚合器、策略决策器、Flink CEP | | `{tenant}.enforcement_actions` | 策略决策器、冻结控制器 | SPM 聚合器 | | `{tenant}.audit_export` | 所有服务 | SPM 聚合器 → PostgreSQL | | `{tenant}.memory_request` | 智能体 | 内存服务 | | `{tenant}.memory_result` | 内存服务 | 智能体 | | `{tenant}.approval_request` | 执行器 | （人工审核员） | | `{tenant}.freeze_control` | 冻结控制器 | 所有消费者 | ## 语言与运行时总结 | 层级 | 语言 | 运行时 | |---|---|---| | 所有后端服务 | Python 3.11 | CPython | | 前端 | JavaScript（ESM） | Node 20（仅构建），Nginx（服务） | | 策略 | Rego | OPA 0.70 | | 基础设施配置 | YAML / Dockerfile | Docker Compose v2 | | 数据库迁移 | SQL | PostgreSQL 16 | | 构建自动化 | Make | GNU Make | ## 贡献 # 为 Orbyx AI SPM 贡献力量 感谢您的参与！以下是快速入门指南。 ## 开始之前 1. Fork 本仓库并克隆您的 Fork 2. 按照 [INSTALL.md](./INSTALL.md) 在本地运行平台 3. 创建功能分支：`git checkout -b feat/your-feature-name` ## 开发流程 ### 修改代码 大多数服务支持热重载。修改 Python 文件后，仅需重建受影响的服务： ``` docker compose up -d --build api # API changes docker compose up -d --build spm-api # SPM API changes docker compose up -d --build ui # Frontend changes ``` ### 运行测试 ``` make test # unit tests (no Docker needed) make smoke-test # end-to-end test against running platform ``` 测试位于 `tests/` 目录。为新功能或修复添加测试用例。 ### 查看日志 ``` make logs # all services make logs-api # single service ``` ## 拉取请求规范 - **单一关注点** — 每个 PR 聚焦一个变更点，便于审查 - **清晰的描述** — 说明修改了什么以及原因 - **包含测试** — 新功能与修复必须附带测试覆盖 - **通过 CI** — 所有测试必须为绿色再提交评审 - **更新文档** — 若修改行为，请更新相关 `.md` 文件 分支命名约定： | 类型 | 模式 | |---|---| | 功能 | `feat/短描述` | | 修复 | `fix/短描述` | | 文档 | `docs/短描述` | | 重构 | `refactor/短描述` | ## 本地 SSO（Keycloak + Traefik） 认证覆盖层在本地添加完整的 OIDC 登录流程，无需真实域名或 TLS 证书即可运行。 ### 新增组件 | 组件 角色 | |---|---| | **Traefik v3** | 反向代理。路由 `aispm.local` → 管理界面，通过 ForwardAuth 中间件实现 SSO。无需 Docker 套接字即可使用静态文件配置。 | | **Keycloak 24** | OIDC 身份提供者，开发模式下持久化领域配置至命名卷。 | | **traefik-forward-auth** | 位于所有受保护路由之前。处理 OIDC 重定向流程，并在 `aispm.local` 上设置签名会话 Cookie。 | ### 一次性主机设置 在 `/etc/hosts` 添加以下条目（Mac 示例）： ``` sudo sh -c 'echo "127.0.0.1 keycloak.local auth.local aispm.local" >> /etc/hosts' ``` ### 启动 / 停止 ``` ./start.sh # full stack including auth ./stop.sh # tear everything down (volumes preserved) ``` ### 首次 Keycloak 设置 仅需执行一次 —— Keycloak 领域配置会持久化至 `keycloak-data` Docker 卷。 1. 运行 `./start.sh` 并打开 **http://keycloak.local:8180/admin/**（账号：`admin` / 密码：`admin`） 2. 顶部下拉菜单 → **Create realm** → 命名 `aispm` → **Create** 3. **Clients** → **Create client** - Client ID: `traefik-forward-auth` - 开启 **Client authentication** → **Next** - 有效重定向 URI: `http://aispm.local/_oauth` - Web 源: `http://aispm.local` → **Save** 4. **Credentials** 标签页 → 复制 **Client secret** → 填入 `.env.auth`： `PROVIDERS_OIDC_CLIENT_SECRET=<粘贴此处>` 5. **Users** → **Create user** → 设置用户名 → **Create** 6. **Credentials** 标签页 → 设置密码 → **关闭 Temporary** → **Save password** 7. 重启 forward-auth：`docker-compose -f docker-compose.yml -f docker-compose.auth.yml up -d traefik-forward-auth` ### 访问地址 | URL | 说明 | |---|---| | **http://aispm.local/admin** | 管理界面（SSO 保护 —— 重定向至 Keycloak 登录） | | **http://keycloak.local:8180/admin/** | Keycloak 管理控制台 | | **http://localhost:9091/dashboard/** | Traefik 路由仪表板 | ### 配置文件 | 文件 | 用途 | |---|---| | `docker-compose.auth.yml` | 覆盖层 —— 添加 Traefik、Keycloak 与 traefik-forward-auth | | `auth/traefik.yml` | Traefik 静态配置（文件提供者、入口点、仪表板端口 `:9091`） | | `auth/traefik-dynamic.yml` | 路由与中间件定义（aispm 路由器 + SSO ForwardAuth） | | `.env.auth` | OIDC 客户端 ID、客户端密钥与 Cookie 签名密钥 |

标签：AI-SPM, AI代理安全, AI安全, AI模型安全, AMSI绕过, Chat Copilot, GitHub开源, Python, 人工智能安全, 企业级安全, 偏差检测, 关键词SEO, 合规性, 合规治理, 响应处置, 威胁检测, 安全态势管理, 安全治理, 审计监控, 搜索引擎查询, 数据中毒, 数据泄露防护, 无后门, 测试用例, 网络探测, 自定义请求头, 请求拦截, 逆向工具, 零日漏洞检测, 风险控制