vikasudasi/exfil-scan

# exfil-scan 在 LLM 输出和 AI 生成的内容到达用户、日志或下游系统之前，扫描其中的数据 exfiltration 信号。 ## 1) 为什么创建 exfil-scan 现代 LLM 应用程序会定期处理敏感的 prompt、内部文档、API 响应和用户数据。 这产生了一个新的安全边界：**输出层**。 EchoLeak 系列攻击（包括 CVE-2025-32711）证明了如何将隐藏或混淆的 payload 嵌入到生成的文本中，并通过工具、链接或解析链来 exfiltration 数据。 传统的扫描器专注于文件、依赖项和运行时流量。 它们并没有以专门构建的方式来检查生成的模型输出。 `exfil-scan` 提供了一个“针对 LLM 响应的病毒扫描器”： - 检查纯文本、JSON、markdown 和日志 - 识别六大类可疑的 exfiltration 模式 - 报告发现的严重程度和位置 - 顺畅集成到 CI/CD 和本地开发者工作流中 ## 2) 它能检测什么 | 类别 | 严重程度 | 检测内容 | |---|---|---| | 隐藏文本 | 高 | 用于隐藏 payload 的零宽度和不可见的 Unicode 序列 | | 编码数据 | 高 | 可能包含编码内容的 Base64/十六进制/八进制/unicode 转义序列 | | URL 中的数据 | 中 | 可疑的超长查询字符串和编码的 URL 参数 payload | | 元数据泄露 | 高 | 结构化/非结构化输出中类似于凭据的密钥和 token 格式 | | Unicode 隐写术 | 中 | 双向控制字符和混合字符的同形异义词风格的单词 | | 结构异常 | 低 | 极端的换行/制表符序列和替换字符编码伪影 | ## 3) 主要功能亮点 - 三种敏感度配置：`low`、`medium`、`high` - 支持 YAML 配置覆盖 - 支持来自 `stdin`、单个文件或目录的输入 - 以 `text`、`json`、`markdown` 或 `html` 格式输出 - 稳定的 exit code，便于自动化 - 简洁的 Python API，可嵌入其他工具 ## 4) 安装说明 ### 从源码安装 ``` git clone https://github.com/your-org/exfil-scan.git cd exfil-scan pip install -e . ``` ### 标准 pip 安装（发布后） ``` pip install exfil-scan ``` ### 开发者安装 ``` pip install -e ".[dev]" pytest ``` ## 5) 快速开始 ### 扫描通过管道传输的 LLM 输出 ``` echo 'api_key: sk-ABCDEFGHIJKLMNOPQRSTUVWXYZ123456' | exfil-scan ``` ### 扫描单个文件 ``` exfil-scan --input output.txt ``` ### 递归扫描目录 ``` exfil-scan --directory ./model-logs --recursive ``` ## 6) CLI 选项参考 | 选项 | 类型 | 默认值 | 描述 | |---|---|---|---| | `-i`, `--input` | 路径 | 无 | 扫描一个输入文件 | | `-d`, `--directory` | 路径 | 无 | 扫描目录中所有受支持的文件 | | `-r`, `--recursive` | 标志 | false | 使用 `--directory` 递归遍历嵌套目录 | | `-c`, `--config` | 路径 | 无 | YAML 配置文件路径 | | `-s`, `--sensitivity` | `low\|medium\|high` | 配置/默认 | 覆盖敏感度配置 | | `-f`, `--format` | `text\|json\|html\|markdown` | `text` | 渲染报告格式 | | `-o`, `--output` | 路径 | stdout | 将渲染后的报告写入文件 | | `--version` | 标志 | 无 | 打印 CLI 版本 | | `-h`, `--help` | 标志 | 无 | 显示用法和参数 | 注意： - 使用 `--input` 或 `--directory`，不能同时使用。 - 如果未提供路径，工具将从 `stdin` 读取。 - 如果发现任何问题，进程将以 exit code `1` 退出。 ## 7) 按输出格式的使用示例 ### 纯文本输出 ``` exfil-scan --input suspicious.txt --format text ``` 预期样式： ``` exfil-scan report ================= Scanned targets: 1 Total findings: 2 1. [HIGH] metadata_leaks/known_token_format:openai_key Location: suspicious.txt:1:10 Description: Matched known credential/token format (openai_key). ``` ### JSON 输出 ``` exfil-scan --input suspicious.txt --format json ``` 预期结构： ``` { "finding_count": 2, "scanned_targets": ["suspicious.txt"], "findings": [ { "category": "metadata_leaks", "rule": "known_token_format:openai_key", "severity": "HIGH", "description": "Matched known credential/token format (openai_key).", "location": "suspicious.txt:1:10", "snippet": "..." } ] } ``` ### HTML 输出 ``` exfil-scan --directory ./outputs --recursive --format html --output report.html ``` 预期行为： - 生成包含扫描结果表格的独立 HTML 页面 - 对内容进行转义以实现安全渲染 - 包含严重程度、类别、规则、位置、描述 ### Markdown 输出 ``` exfil-scan --input suspicious.txt --format markdown --output report.md ``` 预期样式： ``` # exfil-scan 报告 - Scanned targets: 1 - Total findings: 2 ``` ## 8) 配置和敏感度 该代码库附带了 `default-config.yaml`。 你可以使用 `--config` 传入你自己的文件。 敏感度调整： - `low`：较少的误报，更大的阈值 - `medium`：平衡的默认值 - `high`：捕获更多细微的模式 CLI 敏感度覆盖： ``` exfil-scan --input out.txt --sensitivity high ``` ## 9) 自定义模式和策略调整 你可以添加自己的 token 格式和元数据密钥： ``` sensitivity: medium rules: metadata_keys: - api_key - db_password - internal_token token_patterns: custom_jwt: "\\beyJ[A-Za-z0-9_\\-]{10,}\\.[A-Za-z0-9_\\-]{10,}\\.[A-Za-z0-9_\\-]{10,}\\b" corp_secret: "\\bcorp_[A-Za-z0-9]{24,}\\b" ``` 然后运行： ``` exfil-scan --input response.log --config ./my-config.yaml ``` ## 10) 架构概述 模块职责： - `exfil_scan/cli.py`：参数解析、输入选择、输出渲染、退出处理 - `exfil_scan/config.py`：默认值、YAML 加载、递归合并、配置归一化 - `exfil_scan/scanner.py`：六个检测引擎、发现 dataclass、报告格式化 - `tests/test_scan.py`：检测和输出格式的回归测试 执行流程： 1. CLI 解析参数。 2. 配置加载默认值 + 可选的覆盖。 3. 扫描器从 stdin/文件/目录读取文本。 4. 每个启用的类别独立运行。 5. 对发现的结果按严重程度进行排序并渲染。 6. exit code 向自动化传递通过/失败/错误信号。 ## 11) Exit code | 代码 | 含义 | |---|---| | `0` | 未发现异常（正常） | | `1` | 检测到问题 | | `2` | 运行时或参数错误 | 这使得 CI 集成变得非常直接： ``` exfil-scan --directory ./artifacts --recursive --format json --output exfil-report.json ``` 如果发现任何检测内容，你的作业可以根据 exit code `1` 快速失败。 ## 12) 测试 运行测试： ``` pytest ``` 覆盖范围包括： - 所有六个检测类别 - 所有四种输出模式下的报告格式化 - 用于确保行为稳定的规则级别断言 ## 13) 安全说明 `exfil-scan` 是一个启发式扫描器。 它的旨在降低风险并暴露可疑输出，而不是证明内容的安全性。 推荐的部署模式： 1. 在 CI 中针对测试 prompt 和固定输出运行扫描器 2. 在生产环境的防护机制中针对生成的响应运行扫描器 3. 将检测结果路由到分析师分类和遥测系统 4. 基于误报审查持续调整配置阈值 ## 14) 许可证 本项目基于 MIT 许可证授权。 有关完整条款，请参阅 `LICENSE`。 ## 15) 贡献 欢迎贡献。 在提交 PR 时，请包含： - 清晰的复现步骤 - 预期和实际的行为 - 针对新检测逻辑的测试 - 引入新规则时的文档更新

标签：DNS 反向解析, Python, 内容检测, 安全规则引擎, 文档结构分析, 无后门, 逆向工具