PDFiD

Industry-Standard PDF Threat Analyzer — a PowerShell structural analyzer and risk-assessment tool for PDF files.

PDFiD scans PDF files and reports structural keywords, suspicious object counts, risk scores, MITRE ATT&CK technique mappings, and file hashes. It can extract URLs, JavaScript/action payloads, and embedded attachments/images, and supports JSON output for SIEM/SOAR integration and summary reporting for enterprise batch analysis.

---

Features

• Keyword analysis — counts structural and suspicious PDF keywords (/JS, /Launch, /OpenAction, /AA, /XFA, /EmbeddedFile, and more).
• Risk scoring — weighted keyword counts produce a Clean / Low / Medium / High / Critical classification.
• MITRE ATT&CK mapping — maps suspicious keywords to ATT&CK techniques (e.g. T1059.007, T1204.002).
• Hashing — SHA256 and MD5 of every scanned file.
• Payload extraction — extracts JavaScript / action payloads and URLs.
• Attachment extraction — extracts embedded attachments and image streams to disk.
• Encryption & metadata — reports encryption details, dates, producer/creator, and page count.
• Incremental update detection — flags PDFs with incremental updates.
• Magic-byte detection — identifies embedded file types (EXE, ELF, Mach-O, ZIP, 7z, images, etc.).
• Output formats — text, CSV, and structured JSON (SIEM/SOAR ready).
• Summary reporting — aggregate statistics across a batch of files.
• Parallel processing — concurrent scanning (1–16 workers) for large batches.
• Fully configurable — keywords, risk weights, MITRE mappings, thresholds, and UI strings are driven by pdfid.config.json.

---

Requirements

• PowerShell 5.1 or later (Windows PowerShell / PowerShell Core).
• No external modules required.

---

Usage

.\PDFiD.ps1 [options] [pdf-file|directory|@file] ...

Arguments

Argument	Description
pdf-file	A single file, several files, and/or @file.
@file	Run PDFiD on each file listed in the text file.
wildcards	Supported (e.g. *.pdf).

Options

Option	Alias	Description
-Version		Show the program's version number and exit.
-Help		Show help and exit.
-Scan	-s	Scan the given directory.
-All	-a	Display all keyword names found in the PDF.
-Extra	-e	Display extra data (dates, producer, creator, page count, encryption).
-Force	-f	Force scanning even if the file does not start with %PDF.
-NoZero	-n	Suppress output for counts equal to zero.
-Recurse	-r	Recurse directories.
-Output	-o	Output report to a log file.
-Csv	-c	Output CSV data.
-Json	-j	Output JSON data (structured, SIEM/SOAR ready).
-Summary	-m	Output aggregate summary statistics.
-ThreatLevel	-t	Display threat-level classification.
-Url	-u	Extract and display URLs found in the PDF.
-Payload	-p	Extract and display JavaScript / action payloads.
-Extract	-x	Extract embedded attachments and image streams to disk.
-ExtractDir		Directory for extracted files (defaults to <basename>-attachments).
-Config		JSON config file for custom keyword sets and risk weights.
-Parallel		Max concurrent files to process (1–16, default 1).
-NoProgress		Suppress the progress bar during batch processing.
-Keyword		Filter output to only the given keyword(s) (e.g. /JS).

---

Examples

# Basic scan of a single file
.\PDFiD.ps1 'C:\temp\report.pdf'

# Scan a directory recursively with threat-level classification
.\PDFiD.ps1 -Scan C:\temp -Recurse -ThreatLevel

# Wildcard scan, JSON output to a file
.\PDFiD.ps1 'C:\temp\*.pdf' -NoZero -Extra -Json -Output report.json

# Extract URLs and JavaScript payloads
.\PDFiD.ps1 'C:\temp\report.pdf' -Url -Payload -ThreatLevel

# Extract embedded attachments to a directory
.\PDFiD.ps1 'C:\temp\report.pdf' -Extract -ExtractDir C:\temp\extracted

# Show only the /JS count
.\PDFiD.ps1 'C:\temp\report.pdf' -Keyword /JS

# Show only the /JS payload content
.\PDFiD.ps1 'C:\temp\report.pdf' -Payload -Keyword /JS

# Enterprise batch scan with summary and parallel processing
.\PDFiD.ps1 -Scan C:\malware_repo -Recurse -Json -Summary -ThreatLevel -Parallel 4

---

Exit Codes

Code	Meaning
0	Clean (no high/critical risk).
1	Errors encountered (e.g. non-PDF files, unreadable files).
2	High risk detected.
3	Critical risk detected.

---

Configuration

All tunables live in pdfid.config.json (in the same directory as the script). Use -Config <file> to point at an alternate config.

Key sections:

Section	Purpose
keywords	The list of structural/suspicious keywords to count.
risk_weights	Per-keyword weight used to compute the risk score.
risk_levels	Score thresholds that map to Clean / Low / Medium / High / Critical.
mitre_map	Keyword → MITRE ATT&CK technique mappings.
keyword_descriptions	Human-readable descriptions for each keyword.
magic_signatures	Byte signatures used to identify embedded file types.
strings	All user-facing UI text (labels, messages, summary, help).
exit_codes	Exit-code values for clean/errors/high/critical.
help_text	The -Help screen content.

If the config file is missing or fails to parse, PDFiD falls back to built-in defaults and warns.

---

Risk Scoring

Each suspicious keyword contributes its weight to a total score. The score is then classified:

Score	Level
0	Clean
1–15	Low
16–40	Medium
41–70	High
71+	Critical

A JS+AutoAction flag is added when JavaScript appears in an auto-execute context (e.g. /OpenAction or /AA), boosting the score.

---

Project Layout

PDFiD.ps1            The analyzer script (self-contained).
pdfid.config.json    All configuration (keywords, weights, MITRE, UI strings).
README.md            This file.

---

License & Credits

Developed by zrnge — https://zrnge.com

Source repository: https://github.com/zrnge/pdfid

Enhanced with risk scoring, MITRE ATT&CK mapping, JSON output, and enterprise batch-analysis features.