dleeceffp/openimpactcascade

# OpenImpactCascade - AI 驱动的风险评估平台 **版本:** v3.1.0 (文件树 Context，增强的 LEF 分解，结合 TEF × Vulnerability 控制评分，OT 的 cascade archetype 样本以及一个通用的勒索软件 archetype) **端口:** 8080 **Python:** 3.8 - 3.11 (推荐 3.11) 这是一个由 AI 驱动的风险评估问卷生成器，具备增强的 FAIR 方法论 (TEF/LEF 分解)、MITRE ATT&CK 集成、Markdown+Frontmatter 知识库检索、智能网络搜索以及全面的安全防护措施。专为 SaaS 免费增值模式部署而构建。 ## 🔧 技术栈 - **后端:** Flask 3.0+, Python 3.11 - **AI/ML:** Anthropic Claude Sonnet 4.6 (通过 API) - **知识库:** 基于文件的 Markdown + Frontmatter 语料库，带缓存注入 - **网络搜索:** Google Custom Search (用于信息填补) - **模拟:** NumPy, SciPy (使用对数正态分布的蒙特卡洛模拟) - **部署:** Gunicorn, Docker, GCP Cloud Run, Cloud SQL ## 🎯 概述 OpenImpactCascade 是一个基于 Flask 的 Web 应用程序，它生成针对特定行业和地区定制的网络安全风险评估。它结合了： - 基于经过验证的威胁情报的 **AI 生成的问卷** - 用于定量风险分析的 **FAIR 方法论** - 用于风险分布建模的 **蒙特卡洛模拟** - 引导用户完成评估的 **实时聊天助手** - 用于防止滥用和确保合规性的 **API 安全防护** ## ✨ 关键特性 ### 🤖 AI 生成的问卷 - 根据行业和地区定制的风险评估 - 基于权威来源 (MITRE ATT&CK, CISA, Verizon DBIR) - 实时的网络搜索以获取最新威胁情报 - 引用前的来源验证 - 对数据局限性保持透明 ### 🧬 Cascade-Archetype Grounding (路径 A) — 标志位控制 可选的 **AI 生成问卷** 的 grounded-analysis 模式。在选择行业和地区（以及组织规模）后，展示者可以选择一个 **精心策划的 cascade archetype** — 一个经过压缩的、权威的攻击级联 — 作为评估的锚点。 - **选择步骤：** 生成表单上的下拉菜单列出了可用的 archetype 以及 *"Let AI suggest threats"* (现有的仅基于网络的回退机制，保持不变)。 - **完整级联视图：** *"View full cascade ↗"* 链接会在 **新标签页** 中作为渲染后的 HTML 页面 (`/archetype/view/`) 打开完整的卡片，并带有返回按钮 — 这样进行中的选择永远不会丢失。 - **Grounding 流水线 (提升问题质量)：** 当选择一个 archetype 时，生成器会 **在调用 LLM 之前** 组装： 1. **cascade card** (权威的、逐字的 — 基础构建块)， 2. 一次 **cascade-grounded 网络搜索** — 行业 + 地区 + 卡片事实 (`dbir_pattern`、锚定事件、监管驱动因素) 构成查询集，因此 Google Custom Search 丰富了 *频率/幅度* 的框架，而不是重新发现威胁，以及 3. **系统上下文**。 执行优先级规则：网络/行业上下文用于了解发生的频率/成本，并且 **不得** 更改级联的步骤或瓶颈点。 - **元数据：** 生成的问卷会记录 `grounding_mode` (`cascade` | `web_only`)、`selected_archetype_id` 和 `selected_card_ids`。 - **卡片位置：** `app/generated/cascade_archetypes/oic-ca-*.md`。只有这个文件夹会被复制到 Docker 镜像中；详细的源数据流目前仍保留在代码库中。 - **默认关闭。** 如果不设置标志位，应用程序的行为将与以前完全相同（仅基于网络的生成）。请参阅下面的 **配置**。 ### 🎯 自定义风险场景 (路径 B) — 方向性 “自定义风险评估场景”卡片是一个 **快速的、方向性** 选项：用您自己的话定义任何威胁场景，并获得针对该场景的快速问卷。最适合没有合适的 grounded archetype 的情况；如果需要可信的结构化分析，请使用带有 cascade archetype 的路径 A。 ### 📊 增强的 FAIR 风险分析 - **TEF × Vulnerability 分解**：将攻击尝试与成功概率区分开来 - **Threat Event Frequency (TEF)**：攻击者尝试攻击的频率 - **Vulnerability 评估**：控制有效性映射到攻击成功率 - **Loss Event Frequency (LEF)**：根据 TEF × Vulnerability 自动计算 - **Loss Magnitude (LM)**：每次成功入侵造成的财务影响 - 所有组件的 **三点 PERT 估计**（最小值、最可能值、最大值） - 蒙特卡洛模拟（10,000+ 次迭代），使用 PERT 和对数正态分布 - 风险分布可视化，提供百分位报告 - **控制 ROI 分析**：了解安全投资如何降低风险 ### 💬 交互式聊天助手 - 每个问题的上下文感知帮助 - 针对特定行业和地区的指导 - 实用的示例和解释 - 使用 Claude Sonnet 4 的对话式界面 - 记住对话历史 ### 🛡️ 安全与合规 - 使用加密哈希进行用户追踪 - 用于滥用调查的 API 调用日志 - 符合 Anthropic 安全防护要求 - 隐私保护的最小化日志记录 - 详情请参阅 **[SAFEGUARDS_README.md](SAFEGUARDS_README.md)** ### 🎨 响应式设计 - 桌面端：持久的聊天侧边栏 - 移动端：带浮动按钮的可折叠助手 - 专业的风险评估界面 - 实时验证和反馈 ## 📁 项目结构 ``` app/ ├── main.py # Main Flask application with LEF decomposition ├── ai_question_generator.py # AI generator with Corpus grounding, web search, and TEF/Vulnerability ├── simulation.py # Monte Carlo simulation with PERT and lognormal distributions ├── user_tracking.py # User tracking & API safeguards ├── persistence.py # Cloud SQL access (replaces SQLite context_storage) ├── corpus/ # Markdown + Frontmatter Knowledge Base package │ ├── retrieve.py # Deterministic slice retrieval from index │ ├── build_index.py # Scans and validates corpus, builds _index.json │ └── schema.py # Frontmatter schema, vocabularies, and governance ├── cards/ # Cascade-archetype card library (flag-gated) │ └── library.py # Card loader (frontmatter+body parse, archetypes_for) ├── templates/ │ ├── home.html # Landing page │ ├── generate.html # Standard questionnaire form (+ archetype dropdown) │ ├── archetype_view.html # Full cascade archetype rendered as HTML │ ├── generate_custom.html # Custom scenario generator │ ├── questionnaire_chat_rationale.html # Interactive questionnaire with chat │ ├── results.html # Analysis results with chat sidebar │ ├── error.html # Error page │ ├── about_fair.html # FAIR methodology documentation │ ├── about_mitre.html # MITRE ATT&CK integration info │ └── about_probability_weighting.html # Probability weighting explanation ├── static/ # Static assets (CSS, JS, images) ├── generated/ # Generated questionnaires saved here │ └── cascade_archetypes/ # Curated cascade-archetype cards (oic-ca-*.md) ├── logs/ │ └── api_calls/ # API call logs (JSONL format) ├── requirements.txt # Python dependencies └── README.md # This file ``` ## 🚀 快速开始 ### 1. 安装依赖 ``` pip install -r requirements.txt ``` **requirements.txt:** ``` # Web Framework Flask>=3.0.0,<4.0 gunicorn>=21.2.0,<22.0 # AI/ML anthropic>=0.39.0,<0.50 httpx>=0.25.0,<1.0 # GCP Vertex AI (RAG) google-cloud-aiplatform>=1.70.0,<1.80 google-auth>=2.25.0,<3.0 # 科学计算 numpy>=1.26.2,<2.0 scipy>=1.11.4,<1.13 # 实用工具 python-dotenv>=1.0.0,<2.0 typing-extensions>=4.8.0,<5.0 ``` **Python 版本:** 3.8 - 3.11 (推荐 3.11) ### 2. 设置环境变量 **必需项:** - `ANTHROPIC_API_KEY` - 从 https://console.anthropic.com 获取 - `SECRET_KEY` - Flask session 密钥 (使用 `python -c "import secrets; print(secrets.token_hex(32))"` 生成) **GCP 服务 (Cloud Run, Cloud SQL, Secret Manager):** - `GOOGLE_APPLICATION_CREDENTIALS` - 服务账号 JSON 密钥的路径 - `GOOGLE_CLOUD_PROJECT` - 您的 GCP 项目 ID - `GCP_LOCATION` - GCP 区域 (默认: us-central1) ``` # 选项 1：环境变量 export ANTHROPIC_API_KEY='sk-ant-xxxxx' export SECRET_KEY='your-secure-secret-key' export GOOGLE_APPLICATION_CREDENTIALS='/path/to/service-account-key.json' export GOOGLE_CLOUD_PROJECT='your-project-id' # 选项 2：.env file cat > .env << EOF ANTHROPIC_API_KEY=sk-ant-xxxxx SECRET_KEY=your-secure-secret-key GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json GOOGLE_CLOUD_PROJECT=your-project-id EOF ``` **Cascade-Archetype Grounding (可选，默认关闭):** | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `OIC_CARDS_ENABLED` | `0` | 加载 cascade-archetype 卡片库并允许卡片 grounding。设置为 `1` 以启用。 | | `OIC_ARCHETYPE_SELECT` | `0` | 在生成表单上显示 archetype 选择下拉菜单。设置为 `1` 以启用。 | | `OIC_ARCHETYPE_LIMIT` | `3` | 下拉菜单中显示的 archetype 的最大数量。 | | `OIC_CARDS_DIR` | `generated/cascade_archetypes` | 包含 `oic-ca-*.md` 卡片的目录 (相对于应用程序工作目录 / Docker 中的 `/app`)。 | ``` # 为 demo 启用 Path A cascade-archetype grounding export OIC_CARDS_ENABLED=1 export OIC_ARCHETYPE_SELECT=1 ``` ### 3. 创建目录 ``` mkdir -p generated logs/api_calls static ``` ### 4. 运行应用程序 **开发环境:** ``` python main.py ``` **生产环境 (使用 Gunicorn):** ``` gunicorn -w 4 -b 0.0.0.0:8080 --timeout 300 main:app ``` **Docker:** ``` docker build -t openimpactcascade:latest . docker run -p 8080:8080 \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -e SECRET_KEY=$SECRET_KEY \ -e GOOGLE_APPLICATION_CREDENTIALS=/app/service-account-key.json \ -v $(pwd)/service-account-key.json:/app/service-account-key.json \ openimpactcascade:latest ``` 访问地址: **http://localhost:8080** **默认端口:** 8080 (可通过 `PORT` 环境变量配置) ## 📖 用户指南 ### 工作流程 1. **主页** → 选择 "AI 生成的问卷" 2. **生成** → 选择行业和地区 (20-40 秒) 3. **完成** → 在 AI 聊天助手的帮助下回答问题 4. **分析** → 查看蒙特卡洛模拟结果 5. **调整** → 修改控制措施以查看风险降低的影响 ### 示例会话 ``` 1. Select: Healthcare / Canada ↓ 2. AI generates questionnaire based on: - Canadian threat landscape - Healthcare-specific attacks - Verified CISA/ACSC advisories - MITRE ATT&CK techniques ↓ 3. Answer questions with chat help: - "How to estimate ransomware frequency?" - "What costs to include in data breach?" ↓ 4. View results: - Expected Annual Loss: $1,250,000 - 90th percentile: $3,500,000 - Risk reduction scenarios ``` ### 聊天助手使用 **快速帮助按钮** (上下文感知): - 对于频率问题："How to estimate frequency?" - 对于影响幅度问题："What costs to include?" - 对于控制措施："How to improve security?" **聊天示例:** ``` You: "What's a typical ransomware frequency for hospitals?" AI: For Canadian healthcare organizations with moderate security... You: "Should I include reputation damage in the cost?" AI: Yes! Reputation costs for healthcare breaches typically include... You: "How does MFA reduce my risk?" AI: Multi-factor authentication reduces likelihood by preventing... ``` ## 📐 FAIR 方法论：TEF × Vulnerability 方法 ### 理解 LEF 分解 该平台通过将 Loss Event Frequency (LEF) 分解为其基本组件，实现了用于风险量化的 **Open FAIR 标准**： ``` LEF = TEF × Vulnerability ``` **其中:** - **TEF (Threat Event Frequency)**：威胁行为者 **尝试** 攻击的频率 (事件/年) - **Vulnerability**：攻击尝试 **成功** 并造成损失的概率 (0.0 到 1.0) - **LEF (Loss Event Frequency)**：攻击 **成功造成损失** 的频率 (事件/年) ### 为什么这很重要 **问题所在：** 大多数用户很难区分“我们被攻击的频率”和“攻击成功的频率”。这是 **FAIR 认证考试中最容易答错的问题**。 **解决方案：** 为以下内容提供独立的问题： 1. **威胁频率** (尝试) - 基于威胁情报 2. **控制有效性** (vulnerability) - 基于您的安全态势 3. **损失频率** (成功) - 根据 TEF × Vulnerability 自动计算 ### 真实世界示例 **场景：** 针对医疗保健组织的勒索软件 **步骤 1 - Threat Event Frequency:** ``` "How often do ransomware groups attempt attacks?" → Answer: 6 attempts per year (based on CISA data) ``` **步骤 2 - 控制有效性:** ``` "What ransomware defenses do you have?" → Answer: EDR + training + tested backups = 15% vulnerability (Meaning: 15% of attacks succeed, 85% are blocked) ``` **步骤 3 - 计算出的 Loss Event Frequency:** ``` LEF = 6 attempts/year × 0.15 vulnerability = 0.9 successful breaches/year Interpretation: ~1 successful breach every 13 months ``` ### 控制有效性映射 | 控制成熟度 | Vulnerability | 攻击成功率 | |-----------------|---------------|---------------------| | **最低** (仅基本 AV) | 70% | 10 次攻击中有 7 次成功 | | **基础** (AV + 邮件过滤) | 40% | 10 次攻击中有 4 次成功 | | **中级** (EDR + 培训 + 备份) | 15% | 10 次攻击中有 1.5 次成功 | | **高级** (EDR + SIEM + MFA + 不可变备份) | 5% | 10 次攻击中有 0.5 次成功 | ### 优势 **对于用户:** - ✅ 更清晰的心智模型 (将“尝试”与“成功”分开) - ✅ 更好的控制评估 (查看安全投资的直接影响) - ✅ 更准确的估计 (更容易单独考虑各个组成部分) - ✅ 学习正确的 FAIR 方法论 **对于风险分析:** - ✅ 更高保真度的风险量化 - ✅ 独立的敏感性分析 (单独改变 TEF 或 Vulnerability) - ✅ 控制 ROI 计算 (展示投资如何降低 LEF) - ✅ 完整的风险估计审计追踪 ### 文档 有关完整的实现细节，请参阅： - **[FAIR_LEF_DECOMPOSITION_PROPOSAL.md](documentation/FAIR_LEF_DECOMPOSITION_PROPOSAL.md)** - 完整的方法论 - **[about_fair.html](app/templates/about_fair.html)** - 面向用户的 FAIR 解释 - **FAIR Institute:** https://www.fairinstitute.org/blog/fair-terminology-101-risk-threat-event-frequency-and-vulnerability ## 🔧 API Endpoint ### 公共 Endpoint | 方法 | 路径 | 描述 | |--------|------|-------------| | GET | `/` | 主页 | | GET | `/generate` | 问卷生成表单 (启用标志位时显示 archetype 下拉菜单) | | POST | `/generate` | 生成问卷 (需要行业、地区；可选 `selected_archetype_id`) | | GET | `/archetype/view/` | 将完整的 cascade archetype 渲染为 HTML 页面 (受标志位控制) | | GET | `/questionnaire` | 显示生成的问卷 | | POST | `/analyze` | 运行蒙特卡洛模拟 | | POST | `/chat/assist` | AI 聊天助手 (AJAX) | | POST | `/recalculate` | 使用调整后的控制措施重新计算 (AJAX) | | GET | `/download/` | 下载问卷 JSON | | GET | `/health` | 健康检查 | ### 请求示例 **生成问卷:** ``` curl -X POST http://localhost:8080/generate \ -F "industry=Healthcare" \ -F "region=Canada" \ -F "organization_size=500 employees" ``` **聊天助手:** ``` curl -X POST http://localhost:8080/chat/assist \ -H "Content-Type: application/json" \ -d '{ "message": "How to estimate ransomware frequency?", "context": { "question_type": "pert_estimate", "fair_component": "LEF", "industry": "Healthcare", "region": "Canada" }, "history": [] }' ``` ## 🛡️ 安全与防护 ### 用户追踪 (已实现) 该应用程序实现了 Anthropic 推荐防护措施： **追踪内容:** - ✅ 基于 session 的用户 ID (评估模式) - ✅ 加密哈希 ID (SHA-256) - ✅ API 调用日志 (时间戳、类型、模型) - ✅ 最小化元数据 (行业、地区) **不追踪的内容:** - ❌ Prompt 或响应 - ❌ 用户账户信息 - ❌ 个人身份信息 (PII) **优势:** - 响应 Anthropic 的滥用投诉 - 在不存储用户数据的情况下调查违规行为 - 在实现问责的同时维护隐私 **详情:** 请参阅 **[SAFEGUARDS_README.md](SAFEGUARDS_README.md)** ### 当前模式：评估 系统生成基于会话的随机用户 ID： - 格式：`eval-user-{random-12-chars}` - 每次应用启动时生成新 ID - 允许在没有真实用户账户的情况下进行测试 ### 生产就绪 当与用户注册系统集成时： 1. 更新 `flask_app_chat.py` 以使用真实的用户 ID 2. 从您的身份验证系统传递 ID 3. 维护哈希和日志记录 4. 有关迁移指南，请参阅 SAFEGUARDS_README ## 💰 成本分析 ### Anthropic API 成本 (Claude Sonnet 4) **单次请求:** - 输入: $3.00 / 百万个 token - 输出: $15.00 / 百万个 token **典型使用量:** | 操作 | Token | 成本 | |--------|--------|------| | 问卷生成 | ~5,600 | $0.05-0.15 | | 聊天消息 | ~1,200 | $0.01-0.02 | | 分析 (本地) | 0 | $0.00 | **月度估算:** | 规模 | 问卷 | 聊天 | 总计/月 | |--------|---------------|------|-------------| | 小型 | 10 | 100 | $1.50-2.50 | | 中型 | 100 | 1,000 | $15-25 | | 大型 | 1,000 | 10,000 | $150-250 | **注意:** - 蒙特卡洛模拟在本地运行 (无 API 成本) - 用户追踪增加的 API 开销极小 (~0.1%) - 用于验证的网络搜索时间已包含在生成时间内 - 重试 (如果需要) 可能会使成本增加 2-3 倍 ### 成本优化建议 1. **缓存问卷**: 为常见的行业/地区组合存储生成的问题 2. **批量生成**: 在非高峰时段预先生成热门组合 3. **速率限制**: 限制免费用户以防止滥用 4. **会话管理**: 清理旧会话以减少存储 ## 🔐 安全最佳实践 ### API 密钥保护 - ✅ 切勿将 API 密钥提交到版本控制中 - ✅ 使用环境变量或 `.env` 文件 - ✅ 定期轮换密钥 - ✅ 在开发/预发布/生产环境中使用不同的密钥 ### Session 安全 - ✅ 在生产环境中使用强大的随机密钥 - ✅ 仅限 HTTPS (绝不要使用 HTTP) - ✅ 安全的 cookie 标志 (HttpOnly, Secure, SameSite) - ✅ Session 超时 (30-60 分钟) ### 输入验证 - ✅ 验证所有表单输入 - ✅ 行业/地区白名单验证 - ✅ PERT 值范围检查 - ✅ 通过模板转义提供 XSS 保护 ### API 安全防护 - ✅ 启用用户追踪 - ✅ 激活 API 调用日志记录 - ✅ 将哈希 ID 传递给 Anthropic - ✅ 准备好调查工具 ### 日志安全 - ✅ 限制日志文件访问权限 - ✅ 日志中不包含 PII - ✅ 定期进行日志轮转 - ✅ 静态加密 (推荐) ## 📊 监控与运维 ### 健康监控 ``` curl http://localhost:8080/health ``` 响应: ``` { "status": "healthy", "ai_enabled": true } ``` ### 日志位置 | 日志类型 | 位置 | 格式 | |----------|----------|--------| | API 调用 | `./logs/api_calls/YYYY-MM-DD_api_calls.jsonl` | JSONL | | 应用程序 | stdout/stderr | 文本 | | Flask | Flask 控制台 | 文本 | ### 问题排查 **检查 API 调用日志:** ``` # 查看今天的 API 调用 tail -f ./logs/api_calls/$(date +%Y-%m-%d)_api_calls.jsonl # 按 user ID 搜索 python investigate_abuse.py --user-id eval-user-abc123 # 获取用户统计信息 python investigate_abuse.py --user-id eval-user-abc123 --stats ``` **检查错误:** ``` # 如果 JSON 解析失败，请检查 debug 文件 cat json_error_debug.json # 检查 Flask 日志 tail -f /path/to/flask.log ``` ## 🚀 部署 ### Docker **Dockerfile:** ``` FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . # 创建目录 RUN mkdir -p generated logs/api_calls CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8080", "main:app"] ``` **构建并运行:** ``` docker build -t openimpactcascade . docker run -p 8080:8080 \ -e ANTHROPIC_API_KEY='your-key' \ -e SECRET_KEY='your-secret' \ -v $(pwd)/logs:/app/logs \ openimpactcascade ``` ### Google Cloud Run ``` # 构建 gcloud builds submit --tag gcr.io/$PROJECT_ID/openimpactcascade # 部署 gcloud run deploy openimpactcascade \ --image gcr.io/$PROJECT_ID/openimpactcascade \ --platform managed \ --region us-central1 \ --allow-unauthenticated \ --set-env-vars ANTHROPIC_API_KEY='your-key',SECRET_KEY='your-secret' \ --memory 1Gi \ --timeout 300 ``` ### 环境变量 | 变量 | 必需 | 默认值 | 描述 | |----------|----------|---------|-------------| | `ANTHROPIC_API_KEY` | 是 | - | 从 console.anthropic.com 获取的 API 密钥 | | `SECRET_KEY` | 是 (生产环境) | - | Flask session 密钥 (使用 `openssl rand -hex 32` 生成) | | `FLASK_ENV` | 否 | production | `development` 或 `production` | | `PORT` | 否 | 8080 | 应用程序运行端口 | ## 🧪 测试 ### 手动测试 ``` # 测试问卷生成 python ai_question_generator.py # 测试模拟 python simulation.py # 测试用户跟踪 python user_tracking.py ``` ### 集成测试 ``` # 启动应用 python main.py # 在另一个终端中： # 测试 health endpoint curl http://localhost:8080/health # 测试问卷生成 curl -X POST http://localhost:8080/generate \ -F "industry=Healthcare" \ -F "region=Canada" # 检查日志 ls -la ./logs/api_calls/ ``` ## ✅ Cascade-Archetype 测试计划 在演示前或演示时使用此检查清单来验证 cascade-archetype grounding 功能 (路径 A)。 它的组织结构允许您先运行 **标志位关闭回归测试** (证明没有破坏任何功能)，然后再运行 **标志位开启功能** 测试。 ### 预检 ``` # 1. 确认卡片存在并解析（无需服务器） python -c "import sys; sys.path.insert(0,'app'); from cards.library import CardLibrary; \ lib=CardLibrary('app/generated/cascade_archetypes'); lib.load(); \ print('cards:', [c.id for c in lib.all()])" # 预期：cards: ['oic-ca-001-b', 'oic-ca-010', 'oic-ca-011'] # 2. Byte-compile 已编辑的模块 python -m py_compile app/config.py app/cards/library.py app/ai_question_generator.py app/main.py ``` ### A. 回归测试 — 标志位关闭 (默认) | # | 步骤 | 预期结果 | |---|------|-----------------| | A1 | 在 `OIC_CARDS_ENABLED` / `OIC_ARCHETYPE_SELECT` **未设置** 的情况下启动应用 | 应用启动；`/health` 返回健康 | | A2 | 打开 `/generate` | **不** 显示 archetype 下拉菜单；仅显示行业/地区/组织规模 | | A3 | 生成问卷 (医疗保健 / 加拿大) | 完全像以前一样成功；元数据 `grounding_mode` = `web_only` (或缺失) | | A4 | 访问 `/archetype/view/oic-ca-010` | 返回 HTTP 404 错误页面 ("not enabled") | | A5 | 主页 | 路径 A = "grounded analysis"，路径 B = "directional" 文案正确渲染 | ### B. 功能测试 — 标志位开启 ``` export OIC_CARDS_ENABLED=1 export OIC_ARCHETYPE_SELECT=1 # 重启应用 ``` | # | 步骤 | 预期结果 | |---|------|-----------------| | B1 | 打开 `/generate` | 组织规模下方出现 archetype **下拉菜单**，默认为 *"Let AI suggest threats"* | | B2 | 打开下拉菜单 | 列出 3 个 archetype (`001-b` 勒索软件，`010` IT→OT 枢轴，`011` SIS)，每个都带有 `[IT]`/`[OT]` 徽章；场景提示随更改而更新 | | B3 | 选择一个 archetype (例如 `010`) | 出现 *"View full cascade ↗"* 链接 | | B4 | 点击 *"View full cascade ↗"* | 在 **新标签页** 中打开 `/archetype/view/oic-ca-010`，呈现为 HTML (标题、列表)，带有 **返回** 按钮；原始标签页中的生成表单保持不变 | | B5 | 在视图页面点击 **返回** | 新标签页关闭 (或导航回表单)；进行中的选择被保留 | | B6 | 选择 `oic-ca-001-b` + 医疗保健/加拿大并生成 | 服务器日志显示 `Grounding on cascade archetype: oic-ca-001-b` 和 **cascade-grounded** 网络搜索；问卷已生成 | | B7 | 检查生成的问卷元数据 | `grounding_mode` = `cascade`，`selected_archetype_id` = `oic-ca-001-b`，`selected_card_ids` = `["oic-ca-001-b"]` | | B8 | 查看问题 | 暴露问题反映了 cascade 的瓶颈点；理由引用了 archetype/锚定事件；网络上下文塑造了频率/幅度 (而不是新的威胁) | | B9 | 选择 *"Let AI suggest threats"* 并生成 | 回退到现有的纯网络路径；`grounding_mode` = `web_only` | | B10 | 使用 OT archetype (`010`/`011`) 生成 | Cascade-grounded 查询使用卡片的 `dbir_pattern` 和锚定事件 (检查服务器日志查询行) | ### C. 边缘情况 | # | 步骤 | 预期结果 | |---|------|-----------------| | C1 | 带有未知 `selected_archetype_id` 的 POST `/generate` | 记录警告并回退到纯网络生成 (无崩溃) | | C2 | 访问 `/archetype/view/does-not-exist` (标志位开启) | 错误页面，HTTP 404 ("not found") | | C3 | 缺少 `markdown` 包 | 视图页面仍将卡片渲染为预格式化文本 (优雅降级) | | C4 | 在缺少网络搜索密钥的情况下生成 | 仅卡片 grounding 仍能生成问卷 | ### D. Docker / 部署验证 ``` docker build -t openimpactcascade:demo . # 确认 image 中附带的卡片 docker run --rm openimpactcascade:demo ls /app/generated/cascade_archetypes # 预期这三个 oic-ca-*.md 文件 docker run -p 8080:8080 \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -e SECRET_KEY=$SECRET_KEY \ -e OIC_CARDS_ENABLED=1 -e OIC_ARCHETYPE_SELECT=1 \ openimpactcascade:demo # 然后针对 container 重新运行 B 部分 ``` ## 🐛 故障排除 ### 常见问题 **"ANTHROPIC_API_KEY environment variable must be set"** ``` # 检查是否已设置 echo $ANTHROPIC_API_KEY # 设置它 export ANTHROPIC_API_KEY='your-key-here' ``` **JSON 解析错误** - AI 偶尔会生成无效的 JSON - 应用程序最多重试 3 次并调整参数 - 检查 `json_error_debug.json` 获取详情 - 尝试不同的行业/地区组合 **生成时间长 (20-40 秒)** - **这是正常的！** AI 正在： - 搜索威胁情报来源 - 验证咨询内容 - 交叉引用 MITRE ATT&CK - 研究记录在案的事件 - 在生成期间显示进度消息 **聊天助手不工作** ``` # 检查是否启用 AI curl http://localhost:8080/health # 检查浏览器控制台是否有错误 # 验证 API key 是否已设置 # 检查 Flask 日志是否有异常 ``` **Session Cookie 警告** - 在生产环境中设置 `SECRET_KEY`： export SECRET_KEY=$(openssl rand -hex 32) **日志文件未创建** ``` # 确保目录存在 mkdir -p ./logs/api_calls # 检查权限 chmod 755 ./logs/api_calls ``` ## 🔄 路线图与未来增强 ### 计划功能 1. **用户身份验证** - 注册和登录系统 - 多租户支持 - 团队协作 2. **增强分析** - 历史风险追踪 - 趋势分析 - 行业基准测试 3. **高级控制** - 控制有效性评分 - ROI 计算 - 控制推荐引擎 4. **报告** - PDF 报告生成 - 执行摘要 - 自定义报告模板 5. **API 增强** - 用于集成的 RESTful API - Webhook 支持 - 批处理 6. **性能** - 问卷缓存 (未来的优化方向) - 通过优化的 prompt 实现更快的生成 - 大型分析的后台处理 ### 📚 检索架构 (基于文件的语料库) OpenImpactCascade 现在使用 **Markdown + Frontmatter** 架构，而不是依赖托管的 Vector DB (如 Vertex AI RAG) (详见 `ADR-0012`)： - **确定性过滤**: 根据 `_index.json` 中的特定元数据切面 (行业、地区、标签) 检索上下文切片。 - **低边际成本**: 通过注入稳定的文档切片来最大化 prompt 缓存，从而实现可行的免费层 SaaS 扩展。 - **可追溯的治理**: 带有结构化 YAML frontmatter 的 Markdown 语料库确保了透明的来源可追溯性以及对摄取内容的严格治理。 - **网络搜索填补**: 仅在语料库缺乏覆盖范围时动态执行网络搜索，受域/组织级别的策略规则监管。 ## 📚 文档 ### 核心文档 - **README.md** (此文件) - 主要应用程序文档 - **SAFEGUARDS_README.md** - API 安全防护和防止滥用 - **flask_readme.md** - 额外的 Flask 实现细节 ### 代码文档 - `ai_question_generator.py` - 有关 AI 生成的信息，请参阅文档字符串 - `simulation.py` - 有关蒙特卡洛分析的信息，请参阅文档字符串 - `user_tracking.py` - 有关追踪系统的信息，请参阅文档字符串 ### 外部资源 - [Anthropic API 文档](https://docs.anthropic.com) - [FAIR 方法论](https://www.fairinstitute.org) - [MITRE ATT&CK](https://attack.mitre.org) - [Anthropic API 安全防护](https://support.claude.com/en/articles/9199617-api-safeguards-tools) ## 🤝 贡献 ### 开发设置 1. 克存储库 2. 创建虚拟环境: `python -m venv venv` 3. 激活: `source venv/bin/activate` 4. 安装依赖: `pip install -r requirements.txt` 5. 设置 API 密钥: `export ANTHROPIC_API_KEY='your-key'` 6. 运行测试: `python -m pytest tests/` 7. 启动应用: `python flask_oic_v215.py` ### 代码风格 - 遵循 PEP 8 - 尽可能使用类型提示 - 为所有函数添加文档字符串 - 保持功能集中且小规模 ### 提交更改 1. 创建功能分支: `git checkout -b feature/your-feature` 2. 通过清晰的提交记录进行更改 3. 彻底测试 4. 更新文档 5. 提交 Pull Request ## 📄 许可证 [在此处填写您的许可证] ## 📞 支持 ### 获取帮助 1. **文档**: 查看此 README 和 SAFEGUARDS_README.md 2. **日志**: 查看应用程序和 API 调用日志 3. **健康检查**: `curl http://localhost:8080/health` 4. **调试文件**: 检查 `json_error_debug.json` 以排查解析错误 ### 报告问题 报告问题时，请包含： - 应用程序版本 - 环境 (开发/生产) - 复现步骤 - 来自日志的错误消息 - 浏览器控制台错误 (如果是 UI 问题) ### 联系方式 有关以下内容的问题： - **应用程序**: 查看文档 - **API 安全防护**: 请参阅 SAFEGUARDS_README.md - **Anthropic API**: 联系 [email protected] - **安全问题**: 私下向维护者报告 ## 🎯 快速参考 ### 常用命令 ``` # 启动应用程序 python main.py # 检查 health curl http://localhost:8080/health # 查看 API 日志 tail -f ./logs/api_calls/$(date +%Y-%m-%d)_api_calls.jsonl # 测试用户跟踪 python user_tracking.py # 调查用户 python investigate_abuse.py --user-id # 生成 requirements pip freeze > requirements.txt ``` ### 关键文件 | 文件 | 用途 | |------|---------| | `main.py` | 带有 LEF 分解的主 Flask 应用程序 | | `ai_question_generator.py` | 带有 TEF/Vulnerability 的 AI 问题生成 | | `simulation.py` | 带有 PERT/对数正态分布的蒙特卡洛模拟 | | `corpus/` | Markdown + Frontmatter 知识库包 | | `user_tracking.py` | 用户追踪和 API 安全防护 | | `templates/questionnaire_chat_rationale.html` | 带有理由显示的交互式 UI | | `documentation/FAIR_LEF_DECOMPOSITION_PROPOSAL.md` | TEF × Vulnerability 方法论 | | `SAFEGUARDS_README.md` | 防止滥用文档 | ### 重要 URL | URL | 用途 | |-----|---------| | http://localhost:8080 | 应用程序主页 | | http://localhost:8080/health | 健康检查 | | http://localhost:8080/generate | 生成问卷 | | https://console.anthropic.com | API 密钥管理 | ## ✅ 部署检查清单 部署到生产环境之前： - [ ] 设置 `ANTHROPIC_API_KEY` - [ ] 设置 `SECRET_KEY` (使用 `openssl rand -hex 32` 生成) - [ ] 设置 `FLASK_ENV=production` - [ ] 仅启用 HTTPS - [ ] 配置安全的 session cookie - [ ] 设置日志轮转 - [ ] 启用速率限制 - [ ] 配置用户身份验证 (如果需要) - [ ] 测试健康检查 endpoint - [ ] 测试问卷生成 - [ ] 测试聊天助手 - [ ] 验证用户追踪日志 - [ ] 编写滥用响应流程文档 - [ ] 更新隐私政策 - [ ] 培训支持团队 **版本**: 2.2.1 (LEF 分解) + Cascade-Archetype Grounding (路径 A，受标志位控制) **最后更新**: 2026 年 6 月 **状态**: 生产就绪 (评估模式) **关键增强**: TEF × Vulnerability 分解；可选的带有 cascade-grounded 网络搜索的 cascade-archetype grounding 有关安全防护的详细实现，请参阅 **[SAFEGUARDS_README.md](SAFEGUARDS_README.md)** 有关 LEF 分解方法论，请参阅 **[FAIR_LEF_DECOMPOSITION_PROPOSAL.md](documentation/FAIR_LEF_DECOMPOSITION_PROPOSAL.md)**

标签：FAIR模型, Flask, 人工智能辅助, 威胁情报, 开发者工具, 网络安全, 蒙特卡洛模拟, 请求拦截, 逆向工具, 隐私保护