Johnlloyd17/CybersecurityThreatIntelligence

# CTI 平台 Copilot 指南 ## 预览  ## 公共仓库规则 - 绝不提交真实的 API 密钥、密码、token、cookie、会话 ID、数据库转储、下载的报告、浏览器配置文件或私密扫描结果。 - 在文档和测试中使用脱敏示例，例如 `YOUR_API_KEY`、`example.com`、`8.8.8.8` 和 `test@example.com`。 - 除非明确作为本地示例，否则不要将特定机器的绝对路径添加到公共文档中。优先使用从仓库根目录开始的相对路径。 - 不要提交生成的缓存文件，例如 `__pycache__/`、`.pyc`、运行时 SQLite 数据库、临时 payload 或导出下载文件。 ## 项目概述 CTI 平台是一个基于 PHP + MySQL 的 Cyber Threat Intelligence (网络威胁情报) 仪表盘，配备第一方 Python 扫描引擎。 主要应用领域： - `index.php`：公共着陆页和登录表单。 - `dashboard.php`：已认证的仪表盘。 - `newscan.php`：扫描创建 UI 和模块选择。 - `query.php`：扫描列表、批量操作、导出和扫描管理。 - `scaninfo.php`：扫描详情、结果、日志、图表和设置快照。 - `settings.php`：API 密钥和模块配置 UI。 - `php/`：后端 API、持久化、扫描路由和安全辅助工具。 - `assets/`：前端 JavaScript、CSS、图标和 UI 资源。 - `python/cti_service/`：第一方 Python 引擎的 HTTP 服务。 - `python/cti_engine/`：事件驱动型 CTI 引擎、模块、事件和测试。 - `python/spiderfoot_bridge/`：当 CTI 路由到 SpiderFoot 时使用的桥接器。 - `spiderfoot-master/`：Vendored（内嵌的）SpiderFoot 参考/运行时代码。 - `scripts/`：用于测试、服务启动和桥接运行的本地辅助脚本。 - `test/python/`：CTI 引擎和模块的 Python 单元测试。 ## 本地开发快速入门 典型的本地技术栈： - XAMPP Apache + MySQL，用于 PHP 页面和数据库。 - Python 3.12+，用于 CTI Python 服务和单元测试。 - 浏览器访问 `http://localhost:8080/CybersecurityThreatIntelligence/` 或开发者配置的本地 Apache 端口。 从仓库根目录启动 CTI Python 服务： ``` powershell -NoProfile -ExecutionPolicy Bypass -File ".\scripts\run_cti_python_service.ps1" ``` 等效的直接 Python 命令： ``` python -m python.cti_service ``` 预期的服务启动输出： ``` {"service":"cti-python-engine","host":"127.0.0.1","port":8765} ``` 运行 Python 引擎测试： ``` powershell -NoProfile -ExecutionPolicy Bypass -File ".\scripts\run_cti_engine_tests.ps1" ``` 等效的直接测试命令： ``` python -m unittest discover -s test\python -v ``` ## 数据库导入与导出指南 项目数据库 SQL 文件存储在： ``` db_sql/ ``` 当前的本地数据库导出： ``` db_sql/cti_platform.sql ``` 对于 XAMPP： 1. 从 XAMPP 控制面板启动 Apache 和 MySQL。 2. 通过 `http://localhost/phpmyadmin` 打开 phpMyAdmin。 3. 如果尚未存在名为 `cti_platform` 的数据库，则创建它。 4. 选择 `cti_platform` 数据库。 5. 打开“导入”选项卡。 6. 选择 `db_sql/cti_platform.sql`。 7. 点击“导入”并等待 phpMyAdmin 完成。 对于 WAMP： 1. 启动所有 WAMP 服务。 2. 通过 WAMP 托盘菜单或 `http://localhost/phpmyadmin` 打开 phpMyAdmin。 3. 创建或选择 `cti_platform` 数据库。 4. 打开“导入”选项卡。 5. 选择 `db_sql/cti_platform.sql`。 6. 点击“导入”并等待 phpMyAdmin 完成。 要导出全新的本地数据库备份： 1. 打开 phpMyAdmin。 2. 选择 `cti_platform` 数据库。 3. 打开“导出”选项卡。 4. 选择 SQL 格式。 5. 将文件导出为 `cti_platform.sql`。 6. 将更新后的 SQL 文件放入 `db_sql/`。 在提交导出的 SQL 文件之前，请仔细审查并移除私有 API 密钥、真实用户账户、会话数据、扫描目标、下载报告以及任何其他敏感的本地数据。 ## 身份验证流程 本地登录页面： ``` http://localhost:8080/CybersecurityThreatIntelligence/index.php ``` 本地 SQL 种子数据中可能存在演示凭据，但公共文档和示例绝不能包含生产凭据。 登录流程： 1. `index.php` 渲染登录表单。 2. `assets/js/landing.js` 处理着陆页登录提交。 3. `assets/js/auth.js` 从 `php/api/auth.php?action=csrf` 请求 CSRF token。 4. 浏览器将 JSON 数据 POST 到 `php/api/auth.php?action=login`。 5. `php/api/auth.php` 验证 CSRF、对失败尝试进行速率限制、加载用户、验证密码哈希、重新生成会话 ID，并将已认证的用户存储在 `$_SESSION` 中。 6. 经过身份验证的页面调用 `Auth.requireAuth()`，并将未认证的用户重定向回 `index.php#hero-login-panel`。 7. 注销时调用 `php/api/auth.php?action=logout` 并销毁会话。 重要的身份验证/安全文件： - `php/config.php`：应用配置、会话生命周期、CSRF 设置、bcrypt 成本和数据库默认值。 - `php/security-headers.php`：安全的会话启动、安全标头、CSRF 辅助工具和请求保护。 - `php/RateLimiter.php`：登录失败锁定行为。 - `php/db.php`：PDO 连接和密码辅助工具。 ## 扫描后端选择 `php/ScanExecutor.php` 决定由哪个后端运行扫描。 优先顺序： 1. 通过 `php/CtiPythonServiceRunner.php` 的第一方 CTI Python 引擎。 2. 当 CTI Python 不支持选定的模块/目标组合时，通过 `php/SpiderFootBridgeRunner.php` 的 SpiderFoot 桥接。 3. 作为最终后备的本机 PHP CTI 后端。 只有在满足以下条件时，扫描才能使用 CTI Python 引擎： - 每个选定的模块都在 `CTI_TO_SERVICE` 中进行了映射， - 每个选定的模块都支持 `MODULE_QUERY_SUPPORT` 中的扫描目标类型， - 每个选定的模块都已获得该目标类型的 `PARITY_VERIFIED_SUPPORT` 对等验证批准，并且 - Python 服务可访问。 仅应通过 CTI Python 引擎测试已在 CTI 平台中被列为已实现/已迁移的模块。尚未实现的模块不应预期在 CTI Python 中运行；它们必须使用可用的后备后端或等待迁移完成。 后端选择存储在扫描的 `config_snapshot` 中，使用诸如 `engine_backend` 和 `engine_backend_label` 等字段。 ## CTI Python 服务 服务层位于 `python/cti_service/`。 默认本地服务设置： ``` CTI_ENGINE_HOST=127.0.0.1 CTI_ENGINE_PORT=8765 CTI_ENGINE_MAX_WORKERS=4 ``` PHP 连接到 `CTI_PYTHON_ENGINE_URL`，或默认为： ``` http://127.0.0.1:8765 ``` 主要服务路由： - `GET /`：简单的服务索引和路由列表。 - `GET /health`：健康检查。 - `POST /api/v1/scans`：创建异步扫描作业。 - `GET /api/v1/scans/{scan_id}`：作业状态。 - `GET /api/v1/scans/{scan_id}/logs`：扫描日志。 - `GET /api/v1/scans/{scan_id}/results`：扫描结果投影。 - `POST /api/v1/scans/{scan_id}/terminate`：请求取消。 Python 服务返回投影后的 JSON。它不直接写入 MySQL。 PHP 将投影导入 CTI 表中。 ## CTI Python 引擎 引擎层位于 `python/cti_engine/`。 重要文件： - `targets.py`：将原始目标规范化为 CTI 目标类型。 - `settings.py`：包含冻结的全局/模块设置和 API 配置快照。 - `context.py`：定义 `ScanRequest` 和 `ScanContext`。 - `events.py`：定义规范化的 `ScanEvent` 和 `ScanLogEntry`。 - `module_base.py`：Python 模块的基类约定。 - `registry.py`：模块注册和 watcher 查找。 - `queue.py`：事件队列引擎。 - `projector.py`：将引擎输出转换为与 CTI 兼容的结果行。 - `modules/__init__.py`：注册内置 Python 模块。 - `storage/models.py`：共享的投影/存储数据结构。 引擎流程： 1. PHP 在 `CtiPythonServiceRunner.php` 中构建扫描 payload。 2. `python/cti_service/schemas.py` 验证并规范化请求。 3. `python/cti_service/worker.py` 注册模块并启动队列引擎。 4. 队列为目标创建一个根事件。 5. 注册的模块通过 `watched_types` 接收匹配的事件类型。 6. 模块生成子 `ScanEvent` 对象。 7. 引擎对事件进行去重，计算简单的严重性，并继续构建事件图。 8. 投影器将事件/日志/关联转换为 CTI 结果 JSON。 9. PHP 将投影行导入 MySQL。 ## SpiderFoot 关系 SpiderFoot 并非第一方 CTI 引擎的长期应用运行时。它主要用于以下两方面： - 作为尚未在 CTI Python 中迁移或验证的模块的桥接后端。 - 作为在加强 CTI Python 模块对等性时的行为参考。 官方 SpiderFoot 仓库： ``` https://github.com/smicallef/spiderfoot ``` 在研究 SpiderFoot 的 Python 扫描运行器、模块系统、事件路由和模块行为时，请查阅上游仓库。 ## SpiderFoot 版权与归属 不要将此 CTI 项目描述为“由 SpiderFoot 版权所有”。正确的关系是： - CTI 平台是一个独立的项目。 - SpiderFoot 是一个由其作者创建的独立的上游项目。 - SpiderFoot 在上游仓库中采用 MIT 许可证。 - 任何 SpiderFoot 源代码、模块文件或实质上复制的部分均保留其原始的 SpiderFoot 版权和 MIT 许可证声明。 - 专门为本项目编写的 CTI 源代码归 CTI 项目作者所有，除非文件中另有说明。 推荐的公共措辞： ``` This project includes first-party CTI platform code and may reference or bundle SpiderFoot components for compatibility and parity testing. SpiderFoot is a separate MIT-licensed project. See https://github.com/smicallef/spiderfoot. ``` 如果 `spiderfoot-master/` 目录包含在公共发布中，请保留其中的 SpiderFoot `LICENSE` 文件。如果 CTI 代码仅受到 SpiderFoot 行为的启发，而没有复制 SpiderFoot 的源代码，请将 SpiderFoot 提及为参考项目，而不是 CTI 的版权所有者。 在处理 SpiderFoot 对等性时： - 与对应的 `spiderfoot-master/modules/sfp_*.py` 文件进行比较。 - 在可行的情况下，匹配支持的目标类型、监控事件、生成事件、设置、解析行为和错误行为。 - 保持 CTI 模块代码的第一方身份和可维护性。 - 保留归属，不要移除 SpiderFoot 许可证声明。 - 在测试和手动比较完成之前，不要标记对等支持。 ## 添加或更新 CTI Python 模块 在添加或编辑 Python 模块时： 1. 从 `python/cti_engine/module_base.py` 继承 `BaseModule` 子类。 2. 设置 `slug`、`name`、`watched_types`、`produced_types` 和 `requires_key`。 3. 通过 `ctx.module_settings_for(slug)` 读取模块设置。 4. 通过 `ctx.api_config_for(slug)` 读取 API 凭据。 5. 实现 `async def handle(self, event, ctx)` 并生成 (`yield`) `ScanEvent` 值。 6. 在 `python/cti_engine/modules/__init__.py` 中注册该类。 7. 在 `test/python/` 中添加或更新单元测试。 8. 将 CTI UI slug 和服务 slug 添加到 `CTI_TO_SERVICE`。 9. 将目标支持添加到 `MODULE_QUERY_SUPPORT`。 10. 将 API 密钥状态添加到 `MODULE_REQUIRES_KEY`。 11. 在需要时将反向映射添加到 `SERVICE_TO_CTI`。 12. 仅在对等性审查完成后才更新 `PARITY_VERIFIED_SUPPORT`。 模块实现规则： - 保持网络超时有界。 - 清楚地记录提供商节流、无效密钥和空结果日志。 - 除非故障确实是不可恢复的，否则避免因一个提供商的故障而导致整个扫描崩溃。 - 尽可能对发出的事件进行去重。 - 使用稳定的事件类型和值，以便 CTI 结果保持可预测性。 - 不要向测试中添加真实的 API 响应或私密扫描数据。 ## PHP 持久化规则 Python 引擎返回 JSON。`php/CtiPythonServiceRunner.php` 在事务中将该投影导入 MySQL。 投影导入职责： - 结果成为 `query_history` 行。 - 引擎事件成为 `scan_events` 行。 - 日志成为 `scan_logs` 行。 - 关联成为 `scan_correlations` 行。 - 扫描状态、计数和时间戳在 `scans` 上更新。 在编辑 PHP API 时- 保持响应是 JSON 安全的。 - 不要从 API 端点输出调试文本。 - 使用 `DB::query`、`DB::queryOne`、`DB::execute` 和 `DB::insert` 处理 SQL。 - 使用预处理语句和参数绑定。 - 对变更请求保留 CSRF 检查。 - 将扫描快照保留为扫描期间的冻结配置。 ## 前端规则 - 除非任务明确要求重新设计，否则保留现有的 CTI 视觉语言。 - 避免在 DOM 文本、日志、URL、屏幕截图或导出中暴露 API 密钥。 - 保持扫描操作清晰：刷新、终止、删除、导出、克隆和设置应在视觉上有所区分。 - 如果添加模块 UI 过滤器，请尽可能使用来自 PHP 的规范模块元数据，而不是第二个硬编码列表。 - 优先为纯图标控件提供无障碍标签/工具提示。 ## 公共文档规则 在为 GitHub 更新 Markdown 时： - 使用相对路径，而非私有本地机器路径。 - 展示从仓库根目录运行的命令。 - 脱敏处理凭据和敏感的扫描输出。 - 说明某项功能何时需要 Python 服务。 - 说明某个模块何时需要第三方 API 凭据。 - 说明某个模块何时依赖于本地工具，例如 `nmap`、`nuclei`、`wafw00f`、`whatweb` 或类似的可执行文件。 - 除非模块已经过对等性测试，否则不要承诺与 SpiderFoot 的结果完全一致。 ## 常用命令 启动 CTI Python 服务： ``` powershell -NoProfile -ExecutionPolicy Bypass -File ".\scripts\run_cti_python_service.ps1" ``` 运行 Python 测试： ``` powershell -NoProfile -ExecutionPolicy Bypass -File ".\scripts\run_cti_engine_tests.ps1" ``` 运行直接的 unittest 发现： ``` python -m unittest discover -s test\python -v ``` 检查单个文件的 PHP 语法： ``` php -l php\CtiPythonServiceRunner.php ``` 在浏览器中对 Python 服务进行健康检查： ``` http://127.0.0.1:8765/health ``` ## 故障排除说明 如果浏览器在 `http://127.0.0.1:8765` 显示 `{"error":"Not found"}`，请改用 `/health` 或 `/`。根据当前的服务实现，根路由可能只显示服务元数据。 如果 CTI 回退到 SpiderFoot 或 PHP 而不是 CTI Python，请检查： - Python 服务正在运行， - `CTI_PYTHON_ENGINE_URL` 配置正确， - 选定的模块已在 `CTI_TO_SERVICE` 中列出， - 目标类型已在 `MODULE_QUERY_SUPPORT` 中列出， - 目标类型已在 `PARITY_VERIFIED_SUPPORT` 中获得对等验证批准，并且 - 所需的 API 密钥已在 CTI 设置中配置。 如果基于工具的模块未返回结果，请检查本地可执行文件是否已安装并在 `PATH` 中可用，或者是否在该模块的设置中进行了配置。

标签：API管理, CTI平台, GitHub, OpenVAS, PHP, Python, SpiderFoot, XAMPP, 事件驱动架构, 反取证, 威胁情报分析, 安全专业人士, 安全评估, 实时处理, 密码管理, 情报收集, 情报看板, 情报聚合, 扫描引擎, 数据可视化, 无后门, 漏洞研究, 网络信息收集, 网络威胁情报, 网络安全, 网络安全仪表盘, 资产测绘, 逆向工具, 隐私保护