brunoaugusto1978/threatforge

# ThreatForge **开源网络威胁情报与数字风险防护平台** ThreatForge 是一个用于网络威胁情报（CTI）、数字风险防护（DRP）和数字风险调查的开源平台。它帮助安全分析师、SOC 团队、欺诈团队和研究人员组织指标、丰富可观察对象、监控品牌滥用、确定风险优先级并生成可操作的情报。 ## 当前版本 ``` v0.6.0 ``` ## 可选的 Enterprise 适配器 安装后，ThreatForge Community 可以选择与私有的 ThreatForge Enterprise 包进行集成。 Community 代码库不包含 Enterprise 的实现代码。 请参阅[可选的 Enterprise 适配器](docs/ENTERPRISE_ADAPTER.md)。 ## 产品策略 ThreatForge 计划发布两个版本： - **Community 版**：开源的 CTI 和数字风险防护核心。 - **Enterprise 版**：未来的私有/商业版本，包含许可证管理、试用模式、高级报告和企业级功能。 请参阅[产品策略](PRODUCT_STRATEGY.md)。 ## 核心功能 ### CTI / IOC - **IOC 录入** — 通过 API 注册 IP、域名、URL、哈希、电子邮件和 CVE。 - **公开连接器** — CISA KEV、URLhaus/abuse.ch、MITRE ATT&CK 和 EPSS/FIRST。 - **富化** — 根据可观察对象类型查询相关来源。 - **可解释的评分** — 从 0 到 100 的风险评分，包含透明的因素和推理依据。 - **报告** — 为可观察对象生成技术 Markdown 报告。 ### 品牌监控 / DRP - **品牌录入** — 注册品牌名称、官方域名和关键词。 - **仿冒域名检测** — 使用同形字、相邻键、字母遗漏和诱饵词（如 `secure`、`login`、`pix`、`invoice`、`2fa` 和 `support`）生成变体。 - **证书透明度发现** — 识别在 CT 日志中提及受监控品牌的真实域名。 - **发现结果富化** — DNS、MX、RDAP、域名年龄、证书年龄和 URLhaus 关联。 - **可解释的滥用评分** — 确定活跃、近期且与品牌相似的域名的优先级。 - **告警** — 针对可疑或恶意的发现结果提供 Telegram、Webhook 和 SMTP 告警。 ### Web UI、用户与 RBAC - **Web 登录** — 由 API 在 `http://localhost:8000/` 提供的 UI。 - **身份验证** — 存储在 `httpOnly` 和 `SameSite=Strict` cookie 中的 JWT 会话。 - **安全的密码处理** — 在可用时使用 Argon2id，并以 PBKDF2-HMAC-SHA256 作为回退方案。 - **租户角色** — `admin`、`analyst` 和 `viewer`。 - **平台角色** — `platform_admin`、`support_operator` 和 `support_viewer`。 - **审计日志** — 记录敏感操作，包含用户、操作员、租户、IP 和 user-agent 上下文。 - **Web 安全加固** — CSP、安全标头、登录速率限制和通用身份验证错误提示。 ### 多租户架构 ThreatForge 是多租户的。每个客户都表示为一个隔离的租户。敏感表包含 `tenant_id`，并且属于租户的查询会按租户进行范围限制，以防止跨租户数据泄露。 主要有两种访问模型： - **平台操作员** — 创建和管理租户、操作员、邀请和 API 密钥。为了通过 API 对特定租户进行操作，操作员需使用 `X-Tenant-Id` 标头。 - **租户用户** — 绑定到单个 `tenant_id`，仅允许访问该租户的数据。 API 密钥按租户划分范围。在 `.env` 中配置的 `API_KEY` 值将作为平台自动化密钥使用。 ## 使用 Docker Compose 快速开始 复制示例环境文件： ``` cp .env.example .env ``` 为敏感变量生成强安全性值： ``` openssl rand -hex 32 openssl rand -hex 32 openssl rand -hex 32 ``` 编辑 `.env`： ``` vi .env ``` 至少配置以下内容： ``` API_KEY= POSTGRES_PASSWORD= JWT_SECRET= COOKIE_SECURE=false APP_BASE_URL=http://localhost:8000 ``` 注意事项： - 为 `API_KEY`、`POSTGRES_PASSWORD` 和 `JWT_SECRET` 使用不同的值； - 切勿提交 `.env`； - 对于本地 HTTP 使用，保持 `COOKIE_SECURE=false`； - 对于基于 HTTPS 的生产环境，使用 `COOKIE_SECURE=true`； - `APP_BASE_URL` 用于构建邀请链接。 启动应用： ``` docker compose up -d --build ``` 验证安装： ``` curl http://localhost:8000/health ``` 预期响应： ``` {"status":"ok","service":"threatforge","version":"0.6.9"} ``` API 和 UI 将在以下地址提供： ``` http://localhost:8000 ``` 交互式 API 文档可在以下地址获取： ``` http://localhost:8000/docs ``` ## 自动化隔离自测 运行主要的自测： ``` docker compose exec api python -m app.selftest_isolation ``` 预期结果： ``` TENANT ISOLATION + INVITES + OPERATOR ROLES: ALL TESTS PASSED ✅ ``` 此测试验证： - 首个平台操作员的创建； - 租户创建； - 租户管理员身份验证； - 品牌和可观察对象的租户隔离； - 根据 ID 阻止跨租户访问； - 限定租户范围的 API 密钥； - 包含哈希 token、过期时间和一次性使用的邀请流程； - 未分配租户的支持操作员被阻止访问； - 支持操作员仅能访问分配的租户； - 支持操作员被禁止执行管理和破坏性操作； - 平台管理员暂停/重新激活租户； - 审计日志； - 立即撤销支持操作员的访问权限。 ## 通过 UI 首次访问 打开： ``` http://localhost:8000/ ``` 在全新的安装中，第一步是创建 **平台操作员**。 该首位用户将成为 `platform_admin`，并可以： - 创建租户/客户； - 创建支持操作员； - 创建访问邀请； - 创建租户 API 密钥； - 访问平台操作视图； - 查看审计日志。 ## 推荐的手动验证流程 ### 1. 平台管理员 通过 UI 创建首个平台操作员。 然后创建两个租户，例如： ``` Customer A Customer B ``` 为每个租户创建一个管理员用户。 预期结果： - 平台管理员可以访问平台操作视图； - 租户正确创建； - 客户用户绑定到正确的租户。 ### 2. 租户管理员 以客户 A 的管理员身份登录，并创建属于该租户的数据，例如品牌和可观察对象。 然后以客户 B 的管理员身份登录，并创建不同的数据。 预期结果： - 客户 A 只能看到客户 A 的数据； - 客户 B 只能看到客户 B 的数据； - 直接通过 ID 访问绝不能泄露其他租户的数据。 ### 3. 支持操作员 创建一个支持操作员。 仅授予其访问客户 A 的权限。 预期结果： - 支持人员只能看到客户 A； - 支持人员无法看到客户 B； - 支持人员无法创建租户； - 支持人员无法创建操作员； - 支持人员无法创建 API 密钥； - 支持人员无法执行破坏性操作； - 撤销访问权限后，支持人员将立即失去访问权限。 ## 访问邀请 创建没有管理员密码的租户时，ThreatForge 会生成一封电子邮件邀请。 该邀请包含： - 随机 token； - 存储在数据库中的哈希 token； - 有效期限； - 一次性使用； - 固定的租户绑定； - 仅在接受后激活。 邀请链接使用 `APP_BASE_URL` 构建。 在未配置 SMTP 的开发环境中，邀请会显示在 API 日志中。 要查看 API 日志： ``` docker compose logs -f api ``` 您也可以在本地运行 MailHog： ``` docker compose -f docker-compose.yml -f docker-compose.mailhog.yml up -d --build ``` MailHog UI： ``` http://localhost:8025 ``` ## 无交互式配置 默认流程是通过 UI 创建首个平台操作员。 对于自动化环境，可以通过设置以下内容，在首次启动时创建初始操作员： ``` BOOTSTRAP_OPERATOR_EMAIL=admin.platform@threatforge.local BOOTSTRAP_OPERATOR_PASSWORD= ``` 仅在需要自动化时使用此模式。对于本地开发，通过 UI 引导更简单。 以下变量是以前单租户流程的遗留产物，不应在当前的多租户流程中使用： ``` BOOTSTRAP_ADMIN_EMAIL= BOOTSTRAP_ADMIN_PASSWORD= ``` ## 快速 API 使用指南 定义平台密钥： ``` export API_KEY="value-defined-in-.env" ``` 对于针对特定租户的平台调用，还需要定义 `X-Tenant-Id`。 示例： ``` export TENANT_ID=1 ``` 同步本地 feeds： ``` curl -X POST -H "X-API-Key: $API_KEY" http://localhost:8000/sync/kev curl -X POST -H "X-API-Key: $API_KEY" http://localhost:8000/sync/mitre ``` 在租户中创建可观察对象： ``` curl -X POST \ -H "X-API-Key: $API_KEY" \ -H "X-Tenant-Id: $TENANT_ID" \ -H "Content-Type: application/json" \ -d '{"type": "cve", "value": "CVE-2024-3400"}' \ http://localhost:8000/observables ``` 进行富化和评分： ``` curl -X POST \ -H "X-API-Key: $API_KEY" \ -H "X-Tenant-Id: $TENANT_ID" \ http://localhost:8000/observables/1/enrich ``` 生成 Markdown 报告： ``` curl \ -H "X-API-Key: $API_KEY" \ -H "X-Tenant-Id: $TENANT_ID" \ http://localhost:8000/reports/observable/1 ``` 接受消除危害格式的值，例如： ``` hxxp://example[.]com ``` 它们将被自动标准化。 ## 品牌监控 创建一个带有官方域名的品牌： ``` curl -X POST \ -H "X-API-Key: $API_KEY" \ -H "X-Tenant-Id: $TENANT_ID" \ -H "Content-Type: application/json" \ -d '{"name": "Example Bank", "official_domains": ["examplebank.com"], "keywords": ["examplebank"]}' \ http://localhost:8000/brands ``` 运行扫描： ``` curl -X POST \ -H "X-API-Key: $API_KEY" \ -H "X-Tenant-Id: $TENANT_ID" \ http://localhost:8000/brands/1/scan ``` 列出优先处理的发现结果： ``` curl \ -H "X-API-Key: $API_KEY" \ -H "X-Tenant-Id: $TENANT_ID" \ "http://localhost:8000/brands/1/findings?min_score=45" ``` 更新发现结果状态： ``` curl -X PATCH \ -H "X-API-Key: $API_KEY" \ -H "X-Tenant-Id: $TENANT_ID" \ -H "Content-Type: application/json" \ -d '{"status": "takedown_requested"}' \ http://localhost:8000/brands/findings/10 ``` 使用 `?deep=false` 进行更快的扫描。 对于周期性扫描，请安排任务： ``` POST /brands/{id}/scan ``` 仅针对判定结果等于或高于 `ALERT_MIN_VERDICT` 的发现结果触发告警。 ## Takedown（撤下） ThreatForge 不执行自动 takedown。 它通过帮助团队来支持防御性工作流程： - 识别可疑的发现结果； - 注册证据； - 计算风险； - 管理状态； - 跟踪响应进度。 Takedown 操作必须通过授权渠道并在人工审查下执行。 ## 支持的可观察对象类型 | 类型 | 示例 | 富化来源 | |---|---|---| | `ip` | `203.0.113.10` | URLhaus host | | `domain` | `example[.]com` | URLhaus host | | `url` | `hxxp://evil.example/x` | URLhaus URL | | `hash` | MD5/SHA1/SHA256 | URLhaus payload | | `cve` | `CVE-2024-3400` | CISA KEV + EPSS | | `email` | `a@b.com` | 在 MVP 中仅支持录入 | ## 评分 评分为可解释因素的总和，限制在 0 到 100 之间。 | 因素 | 分数 | 来源 | |---|---:|---| | 列入 CISA KEV | +50 | CISA | | 在 KEV 中已知被勒索软件使用 | +10 | CISA | | EPSS | 最高 +30 | FIRST | | URLhaus 中的活跃 URL | +45，若在线则有额外加分 | abuse.ch | | URLhaus 中包含恶意 URL 的主机 | +35 | abuse.ch | | URLhaus 中的已知 payload | +45 | abuse.ch | 判定结果： | 评分 | 判定结果 | |---:|---| | 70–100 | `malicious` | | 40–69 | `suspicious` | | 1–39 | `low` | | 0 | `no_known_threat` | ## 配置 | 变量 | 必填 | 描述 | |---|---|---| | `API_KEY` | 是 | 通过 `X-API-Key` 标头使用的平台自动化密钥 | | `POSTGRES_PASSWORD` | Docker Compose 必填 | compose 使用的 PostgreSQL 密码 | | `JWT_SECRET` | 推荐 | 用于签署 JWT 会话的 secret | | `DATABASE_URL` | 否 | 默认值：compose PostgreSQL。开发环境支持 SQLite | | `COOKIE_SECURE` | 是 | 本地 HTTP 使用 `false`；生产 HTTPS 使用 `true` | | `APP_BASE_URL` | 是 | 用于生成邀请链接的基础 URL | | `INVITE_TTL_HOURS` | 否 | 邀请有效期（以小时为单位）。默认值：168 | | `CORS_ORIGINS` | 否 | 以逗号分隔的允许来源 | | `ABUSECH_API_KEY` | 否 | 用于 URLhaus 的 abuse.ch Auth-Key | ## 告警配置 | 变量 | 描述 | |---|---| | `ALERT_MIN_VERDICT` | 触发告警所需的最低判定结果：`low`、`suspicious` 或 `malicious` | | `TELEGRAM_BOT_TOKEN` | Telegram bot token | | `TELEGRAM_CHAT_ID` | 目标聊天 ID | | `ALERT_WEBHOOK_URL` | 用于 Slack、Discord、Teams、SIEM 或 SOAR 的 Webhook | | `SMTP_HOST` | SMTP 服务器 | | `SMTP_PORT` | SMTP 端口 | | `SMTP_USER` | SMTP 用户 | | `SMTP_PASSWORD` | SMTP 密码 | | `SMTP_FROM` | 发件人 | | `SMTP_TO` | 收件人 | | `SMTP_STARTTLS` | 启用 STARTTLS | 每个告警渠道都是独立且尽力而为的。一个渠道的失败不会阻止扫描或其他渠道。 ## 实用命令 列出容器： ``` docker compose ps ``` API 日志： ``` docker compose logs -f api ``` 重启： ``` docker compose restart ``` 停止： ``` docker compose down ``` 停止并删除本地卷： ``` docker compose down -v ``` 仅当您想要删除本地数据库并从头开始时，才使用 `docker compose down -v`。 ## Open Core 策略 ThreatForge Community 是开源版本。 ThForge Enterprise 计划作为私有/商业版本，主要专注于： - 许可证管理； - 90 天试用； - 专业的 PDF 报告； - 案例管理； - 调查图表； - 企业集成； - 高级 MSSP 模式； - 高级审计与治理； - 高级连接器。 仅适用于 Enterprise 的模块不得提交到此公共代码库中。 ## 截图 ### Dashboard  ### Indicators  ### Brand monitoring  ### Users  ### Audit trail  ### Operations and tenants  ## 当前状态 ThreatForge Community 已完成开源就绪基线。 当前基线： - CI 工作流； - 安全加固基线； - 公开就绪性验证； - Community/Enterprise 分离； - 可选的 Enterprise 适配器； - 邀请 token 日志脱敏； - Docker 部署； - 租户隔离自测； - 开源治理文档。 请参阅[公开就绪性检查](docs/PUBLIC_READINESS_CHECK.md)。 ## 路线图 下面的路线图列出了计划中的未来工作。已完成的就绪工作将在当前状态部分单独跟踪。 - **v0.7** — 调查案例、案例工作流、分析师笔记、证据附件和案例级别的导出。 - **v0.8** — 时间线、调查活动历史、报告导出和操作审查工作流。 - **v0.9** — 关系图、Neo4j 集成和实体关联视图。 - **v1.0** — 部分 STIX 模型、MISP/OpenCTI 集成、生产环境加固、稳定打包和公开稳定版本发布。 请参阅[Community 路线图](docs/ROADMAP.md)。 ## 许可证 Apache-2.0

标签：IOC分析, IP 地址批量处理, 品牌保护, 威胁情报, 开发者工具, 数字风险保护, 测试用例, 版权保护, 自动化防御, 请求拦截, 逆向工具, 配置审计