Pdf Action Inspector

PDF动作检查器

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

建筑

PDF动作检查器遵循一个干净的三层架构：

1.岩芯检测层(src/core/inspector.py)

• 目的：业务逻辑和PDF处理
• 退货：Python原生类型（dict、list）可实现最佳性能
• 职责：PDF解析、动作提取、数据验证
• 依赖项：PyPDF2，自定义工具

2.MCP工具层(mcp_server.py)

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

3.FastMCP框架层

• 目的：MCP服务器托管和通信
• 退货：对MCP客户端的结构化工具响应
• 职责：网络通信、协议处理
• 依赖项：FastMCP库

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

项目结构

├── pdf_action_inspector/            # Main package directory
│   ├── mcp_server.py               # MCP server implementation
│   ├── core/                       # Core PDF processing
│   │   ├── inspector.py            # PDF analysis engine
│   │   ├── cache_manager.py        # Caching system
│   │   └── error_handler.py        # Error handling
│   ├── config/                     # Configuration management
│   │   ├── settings.py             # Application settings
│   │   └── policies.py             # Security policies
│   └── utils/                      # Utility functions
│       ├── action_extractor.py     # PDF Action extraction
│       └── pdf_utils.py            # PDF utilities
├── examples/
│   ├── pdf_samples/                # Sample PDFs for testing
│   └── videos/                     # Demo videos
├── tests/                          # Test suite
├── docs/                           # Documentation
├── pyproject.toml                  # Package configuration
├── README.md                       # This file
└── LICENSE                         # MIT License

设置

用户（推荐）

# Quick start with uvx (no installation needed)
uvx pdf-action-inspector

# Or install from PyPI
pip install pdf-action-inspector
pdf-action-inspector

对于开发者

# Clone the repository
git clone https://github.com/foxitsoftware/PDFActionInspector.git
cd PDFActionInspector

# Option 1: Using uv (recommended)
uv sync
uv run pdf-action-inspector

# Option 2: Using 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分析工具：

岩心分析工具

详细分析工具

缓存管理

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

使用加密PDF

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

# First set the password for the encrypted PDF
set_pdf_password("encrypted_document.pdf", "your_password_here")

# Then proceed with analysis
analyze_pdf_actions_security("encrypted_document.pdf")
extract_pdf_actions("encrypted_document.pdf")

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

环境

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

📚 文档

• API文档 -API综合参考和使用指南

发展

# Run tests
uv run python -m pytest tests/ -v

# Run tests with coverage
uv run python -m pytest tests/ --cov=pdf_action_inspector --cov-report=html

# Add dependencies
uv add 

实例分析

以下是使用GitHub Copilot在VS Code中使用MCP服务器分析不同类型PDF的示例：

示例1：恶意JavaScript检测

文件： confuse_js_code.pdf

用户： 分析examples/pdf_samples/confused-js_code.pdf的安全性

AI代理分析：

# Actions Summary
- **Document Level**: One DocumentOpenAction with JavaScript execution
- **Trigger**: Automatic execution when PDF is opened
- **Action Type**: JavaScript execution with obfuscated payload

# Behavior Analysis
- **Obfuscated Code**: Hex-encoded string designed to hide malicious intent
- **Automatic Execution**: No user interaction required - runs immediately on document open
- **Decoded Payload**: `app.launchURL("http://evil.com")` - attempts to redirect user to external malicious site
- **Evasion Technique**: Uses eval() with dynamic string construction to bypass static analysis

# Security Analysis
- **Attack Vector**: Malicious URL redirection through PDF JavaScript
- **Social Engineering**: Disguised as innocent document, automatically executes on open
- **Network Impact**: Attempts unauthorized external network connection
- **User Privacy**: Potential data exfiltration through URL parameters
- **System Risk**: Could be first stage of multi-stage attack

# Conclusion
**Scenario Overview:** Malicious PDF containing obfuscated JavaScript designed to redirect users to potentially harmful external website

**Benign Level:** Malicious - Clear intent to redirect users without consent using obfuscation techniques

**Risk Level:** High - Automatic execution with external network access and obfuscation indicates sophisticated attack

**Confidence Score:** 95 - Clear evidence of malicious intent through obfuscation and unauthorized URL launch

**Recommendation:** 
- Block or quarantine this PDF immediately
- Do not open in environments with JavaScript enabled
- Investigate source and distribution method
- Consider this as potential indicator of targeted attack campaign

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

文件： test-signature_action.pdf

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

AI代理分析：

# Actions Summary
- **Annotation Level**: Widget annotation (Signature field) with mouse-down action on page 1
- **Trigger**: User clicks on signature field (AnnotMouseDown event)
- **Action Type**: JavaScript execution that modifies a "Price" field value

# Behavior Analysis
- **Field Interaction**: When user clicks on the signature field "Signature_0", it triggers JavaScript execution
- **Hidden Value Modification**: The JavaScript code `var field= this.getField("Price"); field.value=100` automatically sets a "Price" field to value 100
- **User Experience**: User expects to sign the document but unknowingly triggers modification of financial data
- **Timing**: Action executes immediately upon mouse-down on signature field, before actual signing

# Security Analysis
- **Integrity Risk**: The signature action modifies document content beyond the intended signing process
- **User Deception**: User is unaware that clicking to sign will also change a price value to 100
- **Data Manipulation**: Financial or business-critical data ("Price" field) is being altered without user consent
- **Audit Trail**: This hidden modification may not be visible in standard signature audit processes
- **Trust Violation**: Undermines the integrity expectation of digital signature workflows

# Conclusion
**Scenario Overview:** PDF with signature field that contains hidden JavaScript to modify a price field when user attempts to sign

**Benign Level:** Misuse - While not overtly malicious, this represents improper use of signature actions to modify document data

**Risk Level:** Medium - Unauthorized field modification during what should be a trusted signature process poses moderate security risk

**Confidence Score:** 90 - Clear evidence of undisclosed value modification tied to signature interaction

**Recommendation:** 
- Review signature workflows for unexpected side effects
- Implement validation to ensure signature actions only perform signing-related operations
- Consider this a potential indicator of document tampering or fraudulent intent
- Audit other documents from the same source for similar hidden behaviors

示例3：干净文档分析

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

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

AI代理分析：

# Actions Summary
- **Document Level**: No actions detected at document level
- **Page Level**: No actions detected at page level  
- **Annotation Level**: No actions detected at annotation level
- **Field Level**: No actions detected at field level
- **Overall**: Complete absence of interactive Actions throughout the 21-page document

# Behavior Analysis
- **Static Document**: This is a purely static PDF document without any interactive elements or executable content
- **Content Type**: Technical specification document (ISO/DIS 32000-2 PDF 2.0) - appears to be official ISO documentation
- **Document Structure**: Standard PDF structure with 21 pages, no form fields, no annotations with actions
- **Publisher Context**: Created with "Adobe PDF Library 15.0" and "Acrobat PDFMaker 15 for Word" - legitimate authoring tools
- **File Size**: 1,011,774 bytes indicates substantial content typical of technical documentation

# Security Analysis
- **No JavaScript**: Document contains absolutely no executable JavaScript code at any level
- **No Interactive Forms**: No AcroForm fields present that could contain hidden actions
- **No Suspicious Annotations**: No widget annotations or other interactive elements that could harbor malicious code
- **Standard PDF Structure**: Follows standard PDF 1.7 specification without suspicious modifications
- **Legitimate Metadata**: Document metadata indicates creation through standard Adobe tools for technical documentation
- **File Integrity**: Large file size and multi-page structure consistent with legitimate technical specification document

# Conclusion
**Scenario Overview:** Clean technical specification document (ISO PDF 2.0 standard) with no interactive elements or security concerns

**Benign Level:** Benign - Standard documentation PDF created through legitimate authoring tools with no suspicious characteristics

**Risk Level:** Info - Document poses no security risk and is safe for all environments including those with JavaScript enabled

**Confidence Score:** 100 - Complete absence of any Actions or interactive elements provides absolute certainty of safety

**Recommendation:** 
- Safe to open and use in any environment without restrictions
- No special precautions needed when handling this document
- Can be distributed and shared without security concerns
- Suitable for use in high-security environments

示例4：财务文件价格操纵

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

观察我们的人工智能代理如何检测到恶意签名字段，当用户试图签署文档时，该字段会将价格从1000美元秘密更改为100美元。

这些示例演示了该工具如何处理不同的场景：恶意代码、可疑行为和干净文档。

⚠️ 重要免责声明

该项目提供 PDF安全分析框架 它显示所有嵌入式PDF操作，并支持人工智能辅助的风险评估。它作为MCP服务器模块与安全工作流集成。

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

该框架提供了什么：

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