Overview

This MCP (Model Context Protocol) server analyzes JavaScript embedded in PDF files to identify potentially malicious behaviors. It extracts JavaScript actions, normalizes and deobfuscates code where possible, and feeds contextualized evidence to an AI risk assessor that returns a structured threat evaluation. The result is a concise risk report that highlights suspicious APIs, hidden execution paths, and recommended remediation steps.

The server is useful for developers and security teams who need automated, reproducible triage of PDF-based threats — for example, scanning incoming attachments, enriching alerts in a SIEM, or integrating into CI pipelines that validate documents. Because it separates extraction/parsing from model-driven assessment, teams can tune detection thresholds, inspection depth, and integrate custom ML backends using the MCP-compatible interface.

Features

Extraction of JavaScript actions embedded in PDF objects and annotations
Deobfuscation and normalization of JavaScript snippets for clearer analysis
Contextual AI risk scoring that maps behaviors to risk categories (e.g., code execution, file I/O, shell invocation)
Structured output suitable for programmatic consumption (JSON)
HTTP API endpoints for single-file analysis, batch processing, and health checks
Configuration options for model endpoint, thresholds, and analysis depth
Extensible pipeline so teams can add custom parsers or additional static checks

Installation / Configuration

Prerequisites:

Node.js (16+ recommended) and npm or yarn
An AI model endpoint (OpenAI-compatible or a custom MCP model server)
Git

Clone the repository and install dependencies:

git clone https://github.com/foxitsoftware/PDFActionInspector.git
cd PDFActionInspector
# switch to the appropriate branch if desired
git checkout develop

# install dependencies
npm install
# or
yarn install

Configuration is provided via environment variables or a JSON config file. Example .env:

# .env
PORT=8080
MODEL_ENDPOINT=https://api.openai.com/v1/chat/completions
MODEL_KEY=sk-xxxxxx
MODEL_NAME=gpt-4o-mini
RISK_THRESHOLD=0.6
ANALYSIS_DEPTH=full
LOG_LEVEL=info

Alternatively, a JSON configuration:

{
  "server": { "port": 8080 },
  "model": {
    "endpoint": "https://api.openai.com/v1/chat/completions",
    "key": "sk-xxxxxx",
    "modelName": "gpt-4o-mini"
  },
  "thresholds": { "risk": 0.6 },
  "analysis": { "depth": "full" }
}

Start the server:

npm run start
# or in development
npm run dev

Available Resources

The server exposes REST endpoints (example paths; actual routes may vary by release):

Method	Path	Description
POST	/analyze	Upload a PDF and return a risk analysis report
POST	/analyze/batch	Submit multiple PDFs for batch processing
GET	/health	Health and readiness probe
GET	/version	Server and model configuration info

Sample curl request to analyze a PDF:

curl -X POST "http://localhost:8080/analyze" \
  -H "Authorization: Bearer $MODEL_KEY" \
  -F "file=@/path/to/suspicious.pdf"

Sample JSON response (trimmed):

{
  "file": "suspicious.pdf",
  "riskScore": 0.87,
  "categories": ["Code Execution", "Obfuscated JavaScript"],
  "findings": [
    {
      "type": "EmbeddedAction",
      "objectId": "10 0 R",
      "snippet": "app.launchURL('http://malicious.example', true)",
      "confidence": 0.95,
      "explanation": "Attempts to open a remote URL which can trigger payload download."
    }
  ],
  "recommendations": ["Quarantine file", "Block source domain at proxy"]
}

Use Cases

Email attachment scanning: automate inspection of incoming PDF attachments and quarantine items with high riskScore before delivery to end users.
Incident response triage: quickly extract actionable evidence (suspicious API calls, deobfuscated code) to accelerate analyst investigation and reduce manual reverse engineering time.
CI/Content validation: integrate the /analyze endpoint into document workflows to prevent distributing PDFs with embedded scripts in controlled environments.
Threat intel enrichment: feed findings into SIEMs or threat platforms to correlate with alerts, IPs, or campaign indicators.

Concrete example — integrating with a mail gateway:

On attachment receipt, POST the attachment to /analyze.
If riskScore >= 0.7, tag the message as high-risk and route to quarantine.
Store the analysis JSON as an artifact for forensic review.

Notes and Best Practices

Tune RISK_THRESHOLD and ANALYSIS_DEPTH depending on false positive tolerance and performance constraints.
Always run the server behind an authenticated gateway; model keys and analysis results are sensitive.
Combine AI-based scoring with deterministic static checks (signature lists, YARA rules) for better coverage.
For high-volume environments, consider batching and asynchronous analysis to avoid blocking mail flow.

This MCP server is intended to be extensible: teams can replace the model backend, add custom extractors, or augment reports with external threat intelligence to fit existing security pipelines.

PDFActionInspector MCP Server JavaScript Risk Analysis