Analyzing Malicious PDF With Peepdf

Documents

analyzing-malicious-pdf-with-peepdf

Analyzing Malicious PDF With Peepdf is an Agent Skill for documents published in the xalgord/xalgorix repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Perform static analysis of malicious PDF documents using peepdf, pdfid, and pdf-parser to extract embedded JavaScript, shellcode, and suspicious objects.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/xalgord/xalgorix/blob/HEAD/internal/tools/skills/data/malware-analysis/analyzing-malicious-pdf-with-peepdf/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/analyzing-malicious-pdf-with-peepdf, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Analyzing Malicious PDF with peepdf

When to Use

When triaging suspicious PDF attachments from phishing emails
During malware analysis of PDF-based exploit documents
When extracting embedded JavaScript, shellcode, or executables from PDFs
For forensic examination of weaponized document artifacts
When building detection signatures for PDF-based threats

Detection Gaps & Validation

Hex-escaped names dodge pdfid keyword counts. /JavaScript written as /J#61vaScript (and /OpenAction, /Launch similarly) won't increment pdfid's counters, so pdfid alone undercounts. Normalize names and re-scan with pdf-parser.py --search before concluding the PDF is clean.
Objects hide inside object streams. Malicious JS/actions packed in compressed /ObjStm are invisible to surface keyword scans; decompress with pdf-parser.py -O (or peepdf object listing) to expose them.
Nested/stacked filters. A stream may chain FlateDecode -> ASCIIHexDecode -> JBIG2; decode every filter layer (pdf-parser.py -f) or the payload looks like noise.
Incremental updates and split JS. Later %%EOF/xref sections and /OpenAction can override earlier benign content, and JS is often concatenated across objects then eval'd - analyze the effective final version.
Confirm a hit: fully extract the JavaScript, deobfuscate it in box-js or a JS engine, run any extracted shellcode through scdbg/libemu, and confirm embedded URLs//EmbeddedFile payloads are live and hostile.
False positives: legitimate PDFs use JavaScript for form validation and /OpenAction for navigation; signed Adobe/forms workflows are common. Confirm exploit/download behavior before rating malicious.

Prerequisites

Python 3.8+ with peepdf-3 installed (pip install peepdf-3)
pdfid.py and pdf-parser.py from Didier Stevens suite
Isolated analysis environment (VM or sandbox)
Optional: PyV8 for JavaScript emulation within peepdf
Optional: Pylibemu for shellcode analysis

Workflow

Triage with pdfid: Scan PDF for suspicious keywords (/JS, /JavaScript, /OpenAction, /Launch, /EmbeddedFile).
Interactive Analysis: Open PDF in peepdf interactive mode to explore object structure.
Identify Suspicious Objects: Locate objects containing JavaScript, streams, or encoded data.
Extract Content: Dump suspicious streams and decode filters (FlateDecode, ASCIIHexDecode).
Deobfuscate JavaScript: Analyze extracted JS for shellcode, heap sprays, or exploit code.
Check VirusTotal: Use peepdf vtcheck to cross-reference file hash with AV detections.
Generate IOCs: Extract URLs, domains, hashes, and shellcode signatures.

Key Concepts

Concept	Description
/OpenAction	Automatic action executed when PDF is opened
/JavaScript /JS	Embedded JavaScript code in PDF objects
/Launch	Action that launches external applications
/EmbeddedFile	File embedded within the PDF structure
FlateDecode	zlib compression filter used to hide content
Object Streams	PDF objects stored in compressed streams

Tools & Systems

Tool	Purpose
peepdf / peepdf-3	Interactive PDF analysis with JS emulation
pdfid.py	Quick triage scanning for suspicious keywords
pdf-parser.py	Deep object-level PDF parsing
VirusTotal	Hash lookup and AV detection cross-reference
CyberChef	Decode and transform extracted payloads

Output Format

Analysis Report: PDF-MAL-[DATE]-[SEQ]
File: [filename.pdf]
SHA-256: [hash]
Suspicious Keywords: [/JS, /OpenAction, etc.]
Objects with JavaScript: [Object IDs]
Extracted URLs: [List]
Shellcode Detected: [Yes/No]
Embedded Files: [Count and types]
VirusTotal Detections: [X/Y engines]
Risk Level: [Critical/High/Medium/Low]