星战科技xingzhan.cloud
返回市场
PDF动作检查器

PDF动作检查器

作者：foxitsoftware2 星标更新：2025-08-29
安装使用来源：spider==github.com

项目介绍

PDF 动作检查器

一个用于从PDF文件中提取和分析JavaScript动作的模型上下文协议（MCP）服务器。此工具提供了对PDF动作数据的结构化访问，用于安全分析和研究目的。

架构

PDF 动作检查器遵循清晰的三层架构：

1. 核心检查层 (src/core/inspector.py)

  • 目的：业务逻辑和PDF处理
  • 返回值：Python原生类型（字典、列表），以获得最佳性能
  • 职责：PDF解析、动作提取、数据验证
  • 依赖项：PyPDF2、自定义工具

2. MCP 工具层 (mcp_server.py)

  • 目的：模型上下文协议接口
  • 返回值：JSON字符串，供外部工具使用
  • 职责：输入验证、错误处理、JSON序列化
  • 依赖项：检查核心、FastMCP框架

3. FastMCP 框架层

  • 目的：MCP服务器托管和通信
  • 返回值：向MCP客户端提供结构化的工具响应
  • 职责：网络通信、协议处理
  • 依赖项：FastM-CP库

这种分离确保了干净的接口、更好的可测试性和每层的最佳性能。

项目结构

├── pdf_action_inspector/            # 主包目录
│   ├── mcp_server.py               # MCP服务器实现
│   ├── core/                       # 核心PDF处理
│   │   ├── inspector.py            # PDF分析引擎
│   │   ├── cache_manager.py        # 缓存系统
│   │   └── error_handler.py        # 错误处理
│   ├── config/                     # 配置管理
│   │   ├── settings.py             # 应用设置
│   │   └── policies.py             # 安全策略
│   └── utils/                      # 实用函数
│       ├── action_extractor.py     # PDF动作提取
│       └── pdf_utils.py            # PDF实用工具
├── examples/
│   ├── pdf_samples/                # 测试用的样本PDF
│   └── videos/                     # 演示视频
├── tests/                          # 测试套件
├── docs/                           # 文档
├── pyproject.toml                  # 包配置
├── README.md                       # 本文件
└── LICENSE                         # MIT许可证

设置

对用户（推荐）

# 使用uvx快速启动（无需安装）
uvx pdf-action-inspector

# 或者从PyPI安装
pip install pdf-action-inspector
pdf-action-inspector

对开发者

# 克隆仓库
git clone https://github.com/foxitsoftware/PDFActionInspector.git
cd PDFActionInspector

# 选项1：使用uv（推荐）
uv sync
uv run pdf-action-inspector

# 选项2：使用pip
pip install -r requirements.txt
python pdf_action_inspector/mcp_server.py

Claude桌面配置

推荐配置（使用uvx）：

{
  "mcpServers": {
    "pdf-action-inspector": {
      "command": "uvx",
      "args": ["pdf-action-inspector"]
    }
  }
}

替代方案（如果通过pip安装）：

{
  "mcpServers": {
    "pdf-action-inspector": {
      "command": "pdf-action-inspector"
    }
  }
}

工具

MCP服务器提供了以下工具用于PDF分析：

核心分析工具

工具描述
analyze_pdf_actions_security(file_path)生成带有提取的动作数据的安全分析提示
extract_pdf_actions(file_path)从所有级别（文档、页面、注释、字段）提取原始PDF动作
get_document_overview(file_path)获取全面的文档结构和元数据
load_all_annotations(file_path)提取所有注释及其关联的动作

详细分析工具

工具描述
get_fields_by_name(file_path, field_name)通过名称模糊匹配查找表单字段
get_page_text_content(file_path, page_number)从特定页面提取文本内容
get_pdf_object_information(file_path, object_number)获取详细的PDF对象信息
get_trailer_object(file_path)获取PDF尾部字典和文档结构
load_all_annotations_in_page(file_path, page_index)获取特定页面的注释
get_page_information_by_spans(file_path, page_spans)获取页面范围的信息
get_page_index_by_pdfobjnum(file_path, obj_num)查找包含特定对象的页面

缓存管理

工具描述
set_pdf_password(file_path, password)为加密的PDF文件设置密码
clear_pdf_cache(file_path)清除特定文件或所有缓存文件的缓存
get_cache_status()获取当前缓存状态信息

架构： MCP工具层返回JSON字符串供外部使用，而内部检查核心返回Python字典以获得更好的性能和类型安全性。

处理加密的PDF文件

对于受密码保护的PDF文件，在分析之前需要先设置密码：

# 首先为加密的PDF设置密码
set_pdf_password("encrypted_document.pdf", "your_password_here")

# 然后进行分析
analyze_pdf_actions_security("encrypted_document.pdf")
extract_pdf_actions("encrypted_document.pdf")

注意： 密码仅存储在当前会话的内存中，并不会持久保存到磁盘。

环境

  • PDF_CACHE_TIMEOUT_SECONDS=120 - 缓存超时时间
  • LOG_LEVEL=INFO - 日志级别

📚 文档

开发

# 运行测试
uv run python -m pytest tests/ -v

# 运行带覆盖率的测试
uv run python -m pytest tests/ --cov=pdf_action_inspector --cov-report=html

# 添加依赖项
uv add <package_name>

示例分析

这里有一些使用VS Code中的MCP服务器分析不同类型的PDF的例子：

示例1：恶意JavaScript检测

文件： confuse_js_code.pdf

用户： 分析examples/pdf_samples/confuse_js_code.pdf的安全性

AI代理分析：

# 动作总结
- **文档级别**：一个DocumentOpenAction带有JavaScript执行
- **触发**：当PDF打开时自动执行
- **动作类型**：带有混淆负载的JavaScript执行

# 行为分析
- **混淆代码**：设计用于隐藏恶意意图的十六进制编码字符串
- **自动执行**：不需要用户交互 - 在文档打开时立即运行
- **解码负载**：`app.launchURL("http://evil.com")` - 尝试将用户重定向到外部恶意网站
- **规避技术**：使用eval()与动态字符串构造来绕过静态分析

# 安全分析
- **攻击载体**：通过PDF JavaScript进行恶意URL重定向
- **社会工程**：伪装成无辜文档，自动在打开时执行
- **网络影响**：尝试未经授权的外部网络连接
- **用户隐私**：可能通过URL参数泄露数据
- **系统风险**：可能是多阶段攻击的第一阶段

# 结论
**场景概述**：包含混淆JavaScript的恶意PDF，旨在将用户重定向到潜在有害的外部网站

**良性程度**：恶意 - 明确意图使用混淆技术未经同意地重定向用户

**风险等级**：高 - 自动执行并具有外部网络访问和混淆表明复杂的攻击

**信心得分**：95 - 通过混淆和未经授权的URL启动明确证据恶意意图

**建议**：
- 立即阻止或隔离此PDF
- 不要在启用JavaScript的环境中打开
- 调查来源和分发方法
- 考虑作为针对攻击活动的潜在指标

示例2：签名字段带有JavaScript动作

文件： test-signature_action.pdf

用户： 分析examples/pdf_samples/test-signature_action.pdf中的签名字段动作

AI代理分析：

# 动作总结
- **注释级别**：第一页上的Widget注释（签名字段）带有鼠标按下动作
- **触发**：用户点击签名字段（AnnotMouseDown事件）
- **动作类型**：JavaScript执行修改“价格”字段的值

# 行为分析
- **字段交互**：当用户点击签名字段“Signature_0”时，它会触发JavaScript执行
- **隐藏值修改**：JavaScript代码`var field= this.getField("Price"); field.value=100`自动将“价格”字段设置为100
- **用户体验**：用户期望签署文档，但不知情地触发了财务数据的修改
- **时机**：在实际签署前，鼠标按下签名字段时立即执行动作

# 安全分析
- **完整性风险**：签名动作修改了超出预期签署过程的文档内容
- **用户欺骗**：用户不知道点击签署也会将价格值改为100
- **数据操纵**：金融或业务关键数据（“价格”字段）在未经用户同意的情况下被更改
- **审计轨迹**：这种隐藏的修改可能不在标准签名审计过程中可见
- **信任破坏**：破坏了数字签名工作流程的完整性期望

# 结论
**场景概述**：带有签名字段的PDF，其中包含隐藏的JavaScript，当用户尝试签署时会修改价格字段

**良性程度**：滥用 - 尽管不是明显的恶意，但这代表了签名动作的不当使用，以修改文档数据

**风险等级**：中等 - 在应该是一个可信签名过程期间未经授权的字段修改构成了中等安全风险

**信心得分**：90 - 清晰证据显示与签名交互相关的未披露值修改

**建议**：
- 审查签名工作流以避免意外副作用
- 实施验证以确保签名动作仅执行与签署相关操作
- 考虑作为文档篡改或欺诈意图的潜在指标
- 审计来自同一来源的其他文档是否存在类似隐藏行为

示例3：清洁文档分析

文件： without_actions.pdf（ISO PDF 2.0规范文档）

用户： 检查examples/pdf_samples/without_actions.pdf是否有任何恶意动作

AI代理分析：

# 动作总结
- **文档级别**：文档级别未检测到任何动作
- **页面级别**：页面级别未检测到任何动作
- **注释级别**：注释级别未检测到任何动作
- **字段级别**：字段级别未检测到任何动作
- **总体**：在整个21页文档中完全不存在交互式动作

# 行为分析
- **静态文档**：这是一个完全没有交互元素或可执行内容的纯静态PDF文档
- **内容类型**：技术规范文档（ISO/DIS 32000-2 PDF 2.0）- 看起来是官方ISO文档
- **文档结构**：标准PDF结构，21页，没有表单字段，没有带有动作的注释
- **发布背景**：由“Adobe PDF Library 15.0”和“Acrobat PDFMaker 15 for Word”创建 - 合法的创作工具
- **文件大小**：1,011,774字节表示符合技术文档典型内容的大量内容

# 安全分析
- **无JavaScript**：文档在任何级别都绝对不包含可执行的JavaScript代码
- **无交互表单**：没有可能包含隐藏动作的AcroForm字段
- **无可疑注释**：没有小部件注释或其他可能藏有恶意代码的交互元素
- **标准PDF结构**：遵循标准的PDF 1.7规范，没有可疑的修改
- **合法元数据**：文档元数据表明通过标准的Adobe工具创建的技术文档
- **文件完整性**：大文件大小和多页结构与合法的技术规范文档一致

# 结论
**场景概述**：清洁的技术规范文档（ISO PDF 2.0标准），没有任何交互元素或安全问题

**良性程度**：良性 - 通过合法的创作工具创建的标准文档PDF，没有任何可疑特征

**风险等级**：信息 - 文档不构成任何安全风险，适用于包括启用JavaScript的所有环境

**信心得分**：100 - 完全不存在任何动作或交互元素提供了绝对的安全确定性

**建议**：
- 可以在任何环境中不受限制地打开和使用
- 处理此文档时不需要采取特殊预防措施
- 可以在没有安全顾虑的情况下分发和共享
- 适合在高度安全的环境中使用

示例4：金融文档价格操纵

📹 视频演示：分析PDF价格操纵攻击

观看我们的AI代理如何检测一个恶意签名字段，该字段在用户尝试签署文档时秘密地将价格从$1000更改为$100。

这些例子展示了工具如何处理不同的场景：恶意代码、可疑行为和清洁文档。

⚠️ 重要免责声明

该项目提供了一个PDF安全分析框架，揭示所有嵌入的PDF动作，并支持AI辅助的风险评估。它作为一个MCP服务器模块集成到安全工作流中。

我们不对具体分析结果的准确性做出保证。 此工具提供了一种使用AI分析PDF动作安全性的方法和框架。输出结果很大程度上取决于您选择使用的AI模型和代理应用。用户应通过额外的安全措施和专家审查来验证发现。

该框架提供的内容：

  • 全面的数据提取，用于跨所有文档级别的PDF动作
  • MCP服务器集成，用于AI安全分析工作流
  • 结构化的方法，揭示隐藏的PDF行为，用于安全评估