RobPinna/Trust-surface

# Trust Surface  ## 功能介绍 **Trust Surface** 是一个证据优先 (evidence-first) 的框架，旨在自动化 CTI 分析师通常需要手动执行的 OSINT 收集与分析工作流。给定一个目标组织（公司名称 + 域名 + 行业），它能够： 1. **收集** 来自 17 个专用连接器的公开信号（DNS、泄露数据、品牌冒充、招聘信息、新闻、社交媒体提及、网络基础设施、采购文档等） 2. **分类** 每个证据信号的质量等级（`BOILERPLATE → LOW → MED → HIGH`）并自动过滤噪音 3. **关联** 使用 BM25 RAG pipeline 对跨源证据进行关联，以揭示非显而易见的关系 4. **推理** 利用 LLM（OpenAI GPT-4.1 / Anthropic Claude / 本地回退机制）对关联证据进行推理，生成结构化的风险假设 5. **评分** 使用多组件置信度公式对每个风险进行评分，综合考虑信号多样性、来源独立性和覆盖深度 6. **报告** 将发现生成为结构化的 PDF/JSON 产物，包含风险叙述、证据链和置信度元数据 分析的重点在于 **信任杠杆 (trust leverage) 和社会工程学风险** —— 即通过组织的公开工作流、供应商关系和沟通渠道暴露的攻击面，攻击者可能利用这些漏洞进行 BEC（商务邮件入侵）、鱼叉式网络钓鱼、冒充或供应链操纵。 ## 项目背景 大多数入门/中级 CTI 工具涉及操作商业平台（Maltego、Recorded Future 等）。本项目从头构建，旨在演示： - 对 **CTI 方法论** 的深刻理解（证据收集 → 关联 → 推理 → 输出） - 应用于安全工具的 **软件工程规范**（类型化 API、ORM schema、质量门禁、测试覆盖率） - 用于情报分析的 **LLM 集成模式**（RAG、多提供商弹性、输出端安全过滤器） - **原创领域建模** —— "信任表面" (trust surface) 和 "操作杠杆" (operational leverage) 概念是对已知社会工程学风险向量的新颖构架 ## 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ FastAPI + Jinja2 Web UI CLI (trust-surface) │ └────────────────────────┬───────────────────────────────────────┘ │ ┌──────────────▼──────────────┐ │ Assessment Orchestrator │ │ (collector_v2 + services) │ └──────┬──────────────┬───────┘ │ │ ┌────────────▼───┐ ┌──────▼──────────────┐ │ 17 Connectors │ │ Evidence Quality │ │ (OSINT sources)│ │ Classifier + Scorer │ └────────────────┘ └──────┬───────────────┘ │ ┌───────────▼──────────────┐ │ RAG Pipeline (BM25) │ │ 6-query extraction plan │ └───────────┬──────────────┘ │ ┌───────────▼──────────────┐ │ LLM Reasoner │ │ (OpenAI / Anthropic / │ │ deterministic fallback) │ └───────────┬──────────────┘ │ ┌───────────▼──────────────┐ │ Risk Story Builder │ │ Confidence Scoring │ │ PDF / JSON Export │ └──────────────────────────┘ ``` ### 源码布局 ``` Operational-Leverage-Framework/ ├── app/ # FastAPI runtime application │ ├── connectors/ # 17 OSINT data connectors │ ├── routers/ # API endpoints │ ├── services/ # Core business logic │ │ ├── collector_v2.py # Orchestration and collection │ │ ├── evidence_quality_classifier.py │ │ ├── signal_model.py # Confidence scoring formula │ │ ├── risk_story.py # Risk narrative builder │ │ └── trust_workflows.py # Trust surface mapping │ └── utils/ # Reporting, graphing, PDF export ├── src/operational_leverage_framework/ # Typed public package │ ├── cli/ # CLI entry point (trust-surface) │ ├── core/scoring.py # Reusable scoring API │ ├── io/json_loader.py # Evidence input parsing │ └── models/evidence.py # Evidence schema ├── src/rag/ # BM25 retrieval pipeline ├── src/reasoner/ # LLM reasoning layer ├── examples/ # Offline deterministic scenarios ├── tests/ # Unit, integration, smoke tests ├── docs/ # Architecture and design decisions └── scripts/ # Build, setup, safety tools ``` ## 连接器 (17) | Connector | Source | API Key | Signal type | |-----------|--------|---------|-------------| | `website_analyzer` | Target website | No | Vendor deps, workflow cues | | `official_channel_enumerator` | Public social/web | No | Channel ambiguity | | `public_role_extractor` | Public web | No | Role exposure | | `email_posture_analyzer` | DNS (SPF/DMARC/DKIM) | No | Email spoofing risk | | `dns_footprint` | DNS (A/MX/NS/CNAME) | No | Infrastructure exposure | | `subdomain_discovery` | DNS brute + CT | No | Attack surface expansion | | `brand_impersonation_monitor` | DNS + RDAP + crt.sh | No | Typosquat / lookalike domains | | `gdelt_news` | GDELT API | No | News mentions (EN + AR for MENA) | | `media_trend` | Public news | No | Brand sentiment trend | | `social_twitter` | Twitter/X v2 API | Bearer token | Social mentions (EN + AR for MENA) | | `job_postings_live` | Public job boards | No | Stack/vendor disclosure | | `vendor_js_detection` | Website JS analysis | No | Workflow vendor fingerprinting | | `procurement_documents` | Public procurement | No | Partner/supplier relationships | | `public_docs_pdf` | Indexed PDFs | No | Document exposure | | `public_role_extractor` | LinkedIn/public | No | Org chart leakage | | `virustotal` | VirusTotal API | Required | Domain/IP reputation | | `shodan` | Shodan API | Required | Host/port/vuln exposure | | `hibp_breach_domain` | HIBP API | Required | Credential breach data | ## 分析的风险类型 | Risk type | Description | |-----------|-------------| | **Impersonation** | Brand lookalike domains, channel spoofing, fake portals | | **Fraud process** | Invoice fraud vectors, payment workflow exposure | | **Social engineering** | Trust relationship exploitation, pretexting surface | | **Operational leverage** | Vendor/partner chain as entry point for manipulation | | **Credential exposure** | Breach data correlated with active infrastructure | ## 关键设计决策 - **证据优先，而非启发式优先** —— 每个风险发现都至少可以追溯到一个收集到的证据项，包含源 URL 和质量权重 - **样板文件抑制** —— 通用分析供应商（GTM, GA4 等）被分类为 `BOILERPLATE`，并从置信度计算中排除 - **具有离线回退功能的多提供商 LLM** —— 推理器支持 OpenAI GPT-4.1、Anthropic Claude 以及用于可重现离线演示的确定性本地路径 - **无向量存储的 BM25 RAG** —— 证据使用 BM25 TF-IDF 在本地索引；无 embedding API 成本，无外部依赖 - **LLM 输出的安全过滤器** —— 推理器 prompt 明确禁止生成可操作的攻击指令 完整架构原理请参阅 [docs/decisions.md](docs/decisions.md)。 ## 评分模型 置信度（1–100）计算公式： ``` confidence = baseline_avg + signal_diversity_bonus # unique signal types covered + url_diversity_bonus # source independence - boilerplate_penalty # low-quality evidence weight + critical_signal_bonus # risk-type-specific required signals ``` 每种风险类型都有一组必须存在的 **关键信号** 才能达到 `STRONG` 覆盖率。缺失的关键信号会在输出中显示为 `missing_signals`，为防御者提供明确的差距分析。 ## 快速开始 ### 环境要求 - Python `>= 3.11` - 用于 LLM 推理的 `OPENAI_API_KEY`（推荐）；提供本地/离线模式用于测试 ### 安装设置 ``` python scripts/run.py setup --venv ``` 启用代码质量钩子： ``` python -m pre_commit install ``` ### 运行 Web UI ``` python scripts/run.py web # 打开 http://127.0.0.1:56461 ``` ### 运行 CLI（离线，确定性） ``` pip install -e . trust-surface examples/scenario_hospitality/input.json \ --out output.json --risk-type impersonation ``` ### 配置 将 `.env.example` 复制为 `.env` 并设置值： ``` OPENAI_API_KEY=sk-... SECRET_KEY=change-me PASSWORD_PEPPER=change-me API_KEY_PEPPER=change-me DEFAULT_ADMIN_PASSWORD=change-me ``` 可选连接器密钥（从 Settings 页面在应用内配置）： ``` # Shodan — 主机/端口/漏洞暴露 SHODAN_API_KEY=... # Have I Been Pwned — 域名泄露查询 HIBP_API_KEY=... # Twitter/X v2 — 社交提及监控 TWITTER_BEARER_TOKEN=... # VirusTotal — 域名/IP 信誉 VIRUSTOTAL_API_KEY=... ``` ### 安全检查（在共享导出文件之前） ``` python scripts/run.py safety ``` ## 测试 ``` python -m pytest ``` 测试套件（75 个测试）： | File | Coverage | |------|----------| | `test_evidence_quality_layer.py` | Evidence classification, boilerplate suppression, scoring | | `test_risk_ranking_regressions.py` | Risk ranking stability, DB side effects | | `test_connectors_core.py` | Shodan / BrandImpersonation / HIBP — pure logic + mocked HTTP | | `test_connector_smoke.py` | All 17 connectors — instantiation, interface, API key guards | | `test_cli_smoke.py` | CLI entry point, FastAPI health endpoint | ## 路线图 / TODO 以下功能计划在未来开发中实现： ### 区域专精化 — MENA（中东北非） - [ ] 用于证据分类和信号提取的阿拉伯语 NLP（超越 GDELT 语言过滤器） - [ ] 集成到 LLM 推理 prompt 中的 MENA 特定威胁行为人 TTP 库（APT34, Charming Kitten 等） - [ ] 区域 OSINT 来源：Gulf News, Al Arabiya, NCSC-SA feeds, 区域 CERT 公告 - [ ] GCC/Levant 行业分类法（政府、能源、金融、电信）用于行业调整后的风险评分 - [ ] `brand_impersonation_monitor` 中的阿拉伯域名误植域名生成（阿拉伯脚本形似字） - [ ] 本地化 PDF 报告模板（阿拉伯语/英语双语输出） ### 连接器增强 - [ ] 用真实的 Reddit API 替换模拟社交连接器（公开提及，无需付费） - [ ] 用于品牌滥用信号监测的 Telegram 频道监控 - [ ] LinkedIn 组织足迹（在 ToS 允许范围内的公开抓取） - [ ] 区域采购门户（海湾地区招标数据库） ### 平台 - [ ] 风险假设上的 MITRE ATT&CK 技术标签 - [ ] 多次评估趋势分析（随时间变化的风险增量） - [ ] 团队/多用户评估工作流 - [ ] 用于持续监控模式的 Webhook/SIEM 集成 ## 局限性 - 置信度评分是启发式的且依赖于证据 —— 它们反映的是公开信号覆盖率，而非既定事实 - 公开来源的可见性本质上是不完整的；缺乏信号并不代表没有风险 - LLM 推理步骤的质量取决于收集到的证据；薄弱的证据 → 低置信度的假设 - 社交连接器 (Twitter/X) 需要付费开发者账户才能在免费 API 层级上获得有意义的速率限制 - 这是一个研究/学习项目，而非生产级安全产品 —— 无 SLA，无担保 ## 道德声明 本工具仅使用标准 HTTP 请求和文档化的 API 查询公开可用的信息。它不执行端口扫描、漏洞利用执行、凭据测试或任何形式的主动入侵。所有收集的数据均存储在本地，除了配置的 LLM 提供商外，绝不会传输给第三方。 预期用途：防御性研究、CTI 分析师培训、组织自我评估、学术研究。 ## 许可证 详见 [LICENSE](LICENSE)。

标签：Atomic Red Team, BEC, Claude, CVE检测, DLL 劫持, DNS分析, ESC4, ESC8, GPT-4, LLM, Object Callbacks, OSINT, Python, RAG, Unmanaged PE, 信任风险, 冒充检测, 品牌保护, 商务电子邮件入侵, 大语言模型, 威胁情报, 实时处理, 开发者工具, 数据关联, 数据泄露检测, 无后门, 社会工程学, 网络安全, 网络钓鱼, 自动化分析, 跨站脚本, 逆向工具, 隐私保护, 黄金证书