内容
# 阅读房间
## 基于LLM的文件系统智能，用于目标敏感数据发现
**Adhithya Rajasekaran**
**ACM SecDev 2026 · 蒙特利尔**
---
## 一句话总结
**阅读房间** 是一个以元数据为优先的敏感数据发现系统，它提出：
> 我们能否在打开更少的文件的情况下找到敏感文件？
该系统不直接读取每个文件，而是首先检查文件系统元数据，按风险对路径进行排名，并仅对少量选定的文件打开内容。每次访问决策都会被记录。
---
## 核心思想
大多数敏感数据发现系统通过以下方面来评估：
* 他们发现的内容
* 他们的召回率
* 精确度
* 假阳性率
本项目认为，还应该通过以下方面来评估：
> **为了找到它，他们必须阅读的内容。**
每个文件一开始都是 **关闭** 的。
该系统首先进行仅元数据检查：
* 文件和目录名称
* 扩展名
* 大小
* 权限
* 目录结构
* 路径上下文
然后，它对路径进行评分，选择可能的候选文件，并仅打开这些文件进行有针对性的扫描。
---
## 仓库状态
该仓库目前包含 **v1 系统**。
ACM SecDev 2026 海报报告了后续 **v2 评估生成** 的结果。v2 工作正在积极开发中，完成后将发布在这里。
在 v2 发布之前，海报的 v2 暴露和对抗性评估数据无法从此仓库完全重现。
| 领域 | 状态 | 备注 |
| --------------------- | ------------: | -------------------------------------------------------------------------------------------------------------- |
| v1 系统 | 可用 | 作为 MCP 服务器使用 `fastapi_mcp` 挂载的 FastAPI 应用程序 |
| v1 MCP 工具 | 可用 | 15 种用于文件系统检查、风险评分、候选人选择、有针对性的扫描和分析师反馈的工具 |
| v1 评估框架 | 可用 | 种子合成基线，并将选择性扫描与详尽基线进行比较 |
| v2 评估系统 | 开发中 | 确定的 FS-BOM 读取门控，适用于合成的 5K / 10K 文档 |
| 海报数据 | 基于 v2 | 报告后续评估生成结果，但并非完全可从当前树重现 |
---
## 来源和角色
研究理念、系统设计和评估方法由 **Adhithya Rajasekaran** 提出，他是 ACM SecDev 2026 海报的唯一作者。
**Lakshman Shanmugam** 贡献了代码实现和评估执行，目前正在合作开发 v2 系统，并参与完整论文（正在进行中）。
| 工作流 | 贡献者 |
| ------------------------------- | ------------------------------------------------------ |
| 研究理念 | Adhithya Rajasekaran |
| 系统设计 | Adhithya Rajasekaran |
| 评估方法 | Adhithya Rajasekaran |
| ACM SecDev 2026 海报 | Adhithya Rajasekaran |
| v1 海报和初始研究 | Adhithya Rajasekaran |
| 初始代码设置 + 帮助 | Lakshman |
| v2 实现和论文 WIP | Lakshman、Adhithya、Dhinakaran、Navya、Kishore、Balaji |
---
## 许可证、预印本和联系方式
| 项目 | 详情 |
| -------- | ------------------------------------------ |
| 许可证 | MIT — 见 `LICENSE` |
| 预印本 | 即将发布；arXiv 认可正在进行中 |
| 联系方式 | `rajasekaran.adhit@gmail.com` |
| LinkedIn | `linkedin.com/in/adhi1991` |
---
## 文档
| 文件 | 目的 |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `docs/SYSTEM_GUIDE.md` | 完整的 v1 系统指南：架构、安装、API 参考、MCP 工具和 MCP 客户端使用 |
| `eval/README.md` | 评估框架说明 |
| `EXPERIMENTATION.md` | 实验笔记 |
| `eval/FIXTURES_NOTE.md` | 关于故意植入的合成秘密的说明 |
---
# 系统概述
“阅读房间”遵循三阶段的选择性发现工作流程。
```text
阶段 1：仅元数据库存
↓
阶段 2：风险评分和候选人选择
↓
阶段 3：有针对性的内容扫描
```
---
## 阶段 1：仅元数据库存
第一阶段 **不** 打开文件内容。
它收集结构性和元数据信号，例如：
| 信号 | 示例 |
| ----------------- | -------------------------------------------- |
| 路径 | `/finance/payroll/2025/report.xlsx` |
| 文件名 | `employee_tax_ids.csv` |
| 扩展名 | `.csv`, `.xlsx`, `.pdf`, `.env` |
| 大小 | 小型配置文件 vs. 大型存档 |
| 权限 | 全局可读、仅所有者、组可读 |
| 目录上下文 | `/tests/`, `/src/`, `/backups/`, `/exports/` |
这会创建文件系统材料账单样式视图：**FS-BOM**。
---
## 阶段 2：风险评分
每个路径都使用元数据派生的信号进行评分。
v2 FS-BOM 评分是具有零训练的手动加权启发式：
```text
sᵢ =
0.45 · 路径关键词
+ 0.25 · 扩展名
+ 0.15 · 全局可读
+ 0.15 · 大小与预算
```
| 组件 | 权重 | 含义 |
| -------------- | -----: | ------------------------------------------------------------ |
| 路径关键词 | 0.45 | 路径或文件名中的敏感词 |
| 扩展名 | 0.25 | 文件类型风险 |
| 全局可读 | 0.15 | 权限暴露 |
| 大小与预算 | 0.15 | 文件是否在读取预算内合理扫描 |
关键属性是，此分数仅使用元数据计算。
在评分过程中不会读取文件内容。
---
## 阶段 3：有针对性的内容扫描
只有选定的候选文件才会被打开。
然后，系统会对敏感内容进行有针对性的扫描，包括：
* 机密信息
* 个人身份信息（PII）
* 受保护的健康信息（PHI）
* 卡数据
* 合规敏感文件
当前的 v1 系统还支持分析师反馈，以便随着时间的推移调整评分权重。
---
# 有什么不同？
传统的扫描通常从读取所有内容开始。
“阅读房间”从相反的假设开始：
> 除非有理由打开文件，否则文件应保持关闭状态。
贡献不仅仅在于更好的检测。贡献在于 **暴露核算**。
| 问题 | 传统扫描器 | 阅读房间 |
| --------------------------------------- | ------------------- | ---------------------------- |
| 是否发现了敏感数据？ | 是/否 | 是/否 |
| 精确度如何？ | 有测量 | 有测量 |
| 读取了多少内容？ | 通常不重要 | 核心指标 |
| 内容读取是否合理？ | 通常隐含 | 显式且记录 |
| 清单阶段能否避免内容？ | 通常否 | 是 |
| 是否通过工具能力限制访问？ | 通常否 | 是，通过 MCP 工具子集 |
---
# MCP 访问边界
该系统使用 MCP 工具，以便将文件系统访问划分为单独的能力。
在仅元数据库存阶段，代理仅获得结构导向的工具。
在该阶段，不提供内容读取工具。
这意味着访问边界由以下方式强制执行：
> **MCP 工具清单中的功能子集。**
每个功能都是一个独立的、命名的、可记录的工具调用。
在官方文件系统 MCP 服务器上运行的 v2 版本中：
```text
版本/提交：___
工具：14
传输：stdio
```
库存阶段记录了：
```text
零内容读取调用
```
这从工具调用日志中得到验证。
在用于该运行的固定版本中，`search_files` 仅执行名称/路径匹配。不执行内容 grep。
---
# 重要隐私说明
FS-BOM **无内容**，但 **非无元数据**。
元数据仍然可能是敏感的。
例子：
* 文件名可能泄露患者姓名。
* 文件夹路径可能泄露法律事务。
* 所有权可能泄露团队结构。
* 时间戳可能泄露商业活动。
* 权限可能泄露暴露。
所以声明不是“零暴露”，而是较窄的声明：
> 基于元数据的发现比全扫描创建的暴露面更小。
元数据库存应继承与内容读取相同的访问边界、保留策略和审计日志期望。
---
# 评估总结
本项目中讨论了两代评估。
| 评估 | 仓库状态 | 目的 |
| ------------- | ----------------: | ------------------------------------------------------------------------------------------------------------------ |
| v1 评估 | 可用 | 使用合成基准证明选择性扫描，并与详尽基准进行比较 |
| v2 评估 | 开发中 | 在更大的合成文档集中评估确定的 FS-BOM 读取门控，并植入变体和对抗集 |
---
## v1 评估
当前仓库包括一个评估框架：
* 植入合成基准
* 运行选择性扫描
* 运行详尽基准
* 比较结果
报告的指标包括：
| 指标 | 含义 |
| --------------- | --------------------------------------------------- |
| 召回率 | 找到的植入阳性比例 |
| 精确度 | 标记结果为真阳性的比例 |
| 扫描减少 | 打开的文件数量减少 |
| 墙上时钟时间 | 与详尽扫描相比的运行时 |
---
## v2 评估
ACM SecDev 2026 海报报告了 v2 评估生成的结果。
此次评估使用：
* 合成 5K / 10K 文档集
* 10-种子评估矩阵
* 种子源配置文件
* 对抗逃避集
* 确定的 FS-BOM 读取门控
* 校验和固定的装置完整性
| 术语 | 含义 |
| ----------------- | --------------------------------------------------------- |
| 5K 文档集 | 排除不可评估的文件后为 4,700 个评估文件 |
| 10K 文档集 | 排除不可评估的文件后为 9,333 个评估文件 |
| M10 | 10-种子评估矩阵 |
| 516 行校验和 | 通过哈希固定文件，清单完整性 |
| 195 个测试 | 跨 macOS 和 WSL2 的 v2 测试套件 |
门控是确定的。种子随机化装置生成，而不是门控本身。
---
# 海报图澄清
本节澄清了 ACM SecDev 2026 海报图。
---
## 单一装置模型辅助示例
海报一行报告了一个单一的 Flask 装置：
```text
Flask 273f · A:273 0.71 0/2 · B:100 0.71 0/2 · C(LLM+MCP):8 1.00 2/2
```
这意味着：
```text
打开的文件 · 精确度 · 上下文陷阱抑制
```
| 通道 | 含义 | 打开的文件 | 精确度 | 上下文陷阱抑制 |
| ---- | ---------------------- | -----------: | --------: | -----------------------: |
| A | 读取基线 | 273 | 0.71 | 0 / 2 |
| B | 启发式短名单 | 100 | 0.71 | 0 / 2 |
| C | 有限 LLM + MCP 通道 | 8 | 1.00 | 2 / 2 |
从 273 个打开的文件减少到 8 个打开的文件是：
```text
273 → 8 = 97% 减少
```
这是 **单个装置的说明**，而不是缩放基准。
不应将其与单独的 v2 文档级读取减少图混淆。
| 图表 | 适用范围 |
| -------------- | ----------------------------------------- |
| 97% 减少 | 仅适用于单个 Flask 装置 |
| ~75% 减少 | 适用于 5K / 10K 文档集上的确定门控 |
---
## 陷阱抑制澄清
海报中出现了两个陷阱抑制值，但它们来自不同的实验。
| 值 | 实验 | 解释 |
| ----: | ------------------------------------------ | ------------------------------ |
| 0.1 | 5K 规模下的确定元数据门控 | 弱诱饵抑制 |
| 2 / 2 | 有限 LLM 通道 | 两个装置诱饵均抑制 |
元数据 alone 不能可靠地区分每个诱饵。
例如：
```text
/tests/sample_card.txt
/src/customer_card_export.csv
```
两个路径可能包含与卡数据相关的信号，但只有其中一个可能代表实际敏感暴露。
LLM 通道可以推理小装置中的上下文。是否在规模上成立是未来的工作。
---
## 召回率澄清
海报将两个组分开：
| 组 | 含义 | 结果 |
| ----------------------- | ---------------------------------------------- | -------------: |
| 基植入阳性 | 实际植入的敏感文件 | 100% 召回 |
| 对抗逃避集 | 设计用于击败元数据信号的硬案例 | 部分召回 |
100% 召回率声明仅适用于 **基植入阳性**，而不适用于对抗逃避集。
---
## 对抗逃避结果
对抗集包含：
| 指标 | 值 |
| ------------------------------- | ----: |
| 总对抗案例 | 2,730 |
| 种子 | 10 |
| 每种子案例 | 273 |
| S3 类案例每种子 | 107 |
| 每种子错过案例 | 23 |
| 总错过案例 | 230 |
| 总捕获 | 2,500 |
| 总捕获率 | 91.6% |
| S3 类对抗召回 | 78.5% |
| 仓库配置文件召回 | 100% |
| 本地文件系统配置文件召回 | 100% |
| 共享驱动配置文件召回 | 100% |
所有错过案例都在 S3 类配置文件中。
这预计是最难的部分，因为扁平的对象存储命名空间通常缺乏有用的路径语义。
例子：
```text
s3://bucket/a8f31d9c-blob
s3://bucket/export-00017
s3://bucket/tmp-object-92
```
使用不透明的对象键，基于元数据的分类具有较少的上下文可以推理。
这是方法映射边界，而不是隐藏的失败。
---
## 海报勘误
海报第 04 部分的标题为：
```text
92.7% of 2,730 陷阱案例被捕获
```
正确的汇总数据是：
```text
2,730 − 230 = 2,500 被捕获
2,500 / 2,730 = 91.6%
```
| 海报元素 | 状态 |
| ---------------------------------- | --------- |
| 标题：“92.7% 被捕获” | 不正确 |
| 字幕：“230 of 2,730 错过” | 正确 |
| 每配置文件栏 | 正确 |
| 第 07 节：“每种子 23 次错过” | 正确 |
| 正确汇总 | 91.6% |
---
## 术语：陷阱的两种含义
“陷阱”一词有两种含义。
| 术语 | 含义 | 期望行为 |
| --------------------- | --------------------------------------------- | ---------------- |
| 对抗陷阱案例 | 系统应捕获的硬阳性案例 | 捕获它 |
| 诱饵陷阱 | 植入的非敏感或上下文诱饵 | 抑制它 |
简而言之：
```text
对抗陷阱应被捕获。
诱饵陷阱应被跳过。
```
---
# 部署配置文件
海报描述了部署配置文件 A-E。
这些与单个装置示例中的 A / B / C 通道不同。
| 配置文件 | 用例 |
| ------- | --------------------------------- |
| A | 端点 DLP 辅助 |
| B | 代码和机密扫描 |
| C | 跨驱动器隐私发现 |
| D | 合规证据审查 |
| E | 组织控制的推理 |
每个配置文件共享相同的访问边界原则，但每个配置文件需要单独验证。
# 扫描器基准线
海报与本地扫描器基准线进行比较。
| 扫描器 | 召回率 | 精确度 | 陷阱分数 |
| -------------- | -----: | --------: | ---------: |
| Gitleaks | 0.16 | 0.65 | 0.88 |
| TruffleHog | 0.16 | 0.96 | 1.00 |
| detect-secrets | 0.14 | 0.56 | 0.90 |
这些是秘密扫描器。
“Read the Room”真实数据包含了传统秘密扫描范围以外的敏感数据家族：
* 个人可识别信息（PII）
* 受保护的健康信息（PHI）
* 卡片数据
* 合规敏感文件
* 秘密
该项目并不声称简单地优于这些工具。
其声称的贡献是：
> 基于访问边界的发现，具备明确的暴露核算。
---
# 误报上下文
海报引用了生产DLP（数据泄露防护）误报挑战。
“80%+ 误报”的表述遵循Ponemon Institute的报告，即生产DLP部署中的误报率在50–80%之间。海报使用了上限表述。
---
# 本存储库的内容
当前的v1树状结构包括：
* FastAPI 应用程序
* 通过`fastapi_mcp`挂载的MCP服务器
* 文件系统检查工具
* 基于图的風險評估
* 候选人选择
* 有针对性的扫描
* 分析师反馈
* 评估框架
* 合成fixture生成
---
## v1 MCP 工具
v1系统暴露了15种工具，涵盖：
| 工具领域 | 目的 |
| --------------------- | ------------------------------------------ |
| 文件系统检查 | 检查结构和元数据 |
| 图分析 | 构建和分析文件系统关系 |
| 風險評估 | 按敏感性可能性对路径进行排名 |
| 候选人选择 | 选择文件进行有针对性的扫描 |
| 有针对性的扫描 | 打开和检查选定的文件 |
| 分析师反馈 | 根据审查调整评分行为 |
该系统既可以以以下方式公开：
| 接口 | 用途 |
| ----------- | ------------------------------------- |
| HTTP 路由 | 直接API工作流 |
| MCP 工具 | 通过MCP客户端的代理工作流 |
---
# 扫描器作者的注意事项
本存储库故意在其评估种子中包含合成秘密。
参见：
```text
eval/FIXTURES_NOTE.md
```
如果扫描器标记这些值，则表示它按预期工作。
该结果也说明了研究问题的一部分：许多工具可以识别类似秘密的字符串，但它们并不总是了解读取文件是否是必要的，或者周围的上下文是否重要。
---
# 引用
```text
A. Rajasekaran,
"Read the Room: 基于LLM的文件系统智能，用于有针对性的敏感数据发现,"
海报，ACM SecDev 2026.
预印本即将发布。
```
---
# 最后的备注
如果您在真实的数据集上运行此程序，则错误报告的价值超过星级。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器