Skip to content
Get packs

Guide · Agent skill

How to use the Malicious PDF Static Analysis agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains the analyzing-malicious-pdf-with-peepdf agent skill, a set of instructions and a helper script that lets an AI agent perform static analysis on a suspicious PDF using peepdf, pdfid and pdf-parser. It is written for readers who have never installed an agent skill. By the end you will know what the skill does, how to install it, how to ask for it, and what you need in place before running it.

Malicious PDF Static Analysismukul975/Anthropic-Cybersecurity-Skills · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
  2. 2Prepare an isolated environment. Set up a VM or sandbox for the analysis. Do not analyse the sample on your normal workstation.
  3. 3Install peepdf-3. Run pip install peepdf-3 with Python 3.8 or later.
  4. 4Add pdfid and pdf-parser. Place pdfid.py and pdf-parser.py from the Didier Stevens suite where the agent can run them.
  5. 5Ask for the analysis. Describe the task in plain language and give the path to the suspicious PDF.
  6. 6Review the report. Check the object IDs, URLs, hashes and risk level, and confirm any key finding yourself before acting on it.

What is an agent skill and what does this one make the agent do?

An agent skill is a folder with a SKILL.md file that tells an AI agent how to carry out a specific task. When the agent sees a request that matches the skill's description, it follows the workflow in that file.

This skill covers static analysis of a suspicious PDF, meaning examining the file's structure without opening it normally. The agent scans for risky keywords such as /OpenAction, /JavaScript and /EmbeddedFile, dumps and decodes suspicious objects, and writes a structured report.

  • Triage with pdfid to count suspicious keywords
  • Open the file in peepdf to explore its object structure
  • Locate and dump streams containing JavaScript or encoded data
  • Analyse extracted JavaScript for shellcode, heap sprays or exploit code
  • Cross-reference the file hash with VirusTotal using peepdf's vtcheck command
  • Produce a report with hashes, extracted URLs, a shellcode yes/no finding and a risk level

How do you install the skill?

Download the skill ZIP from this page and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal: unzip into ~/.claude/skills/
  • Project: unzip into the project's .claude/skills/
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What do you need installed before running it?

The skill needs Python 3.8 or later and the peepdf-3 package. You also need pdfid.py and pdf-parser.py from Didier Stevens' suite. Most importantly, run the analysis in an isolated environment such as a VM or sandbox.

Three extras are optional: PyV8 for JavaScript emulation inside peepdf, Pylibemu for shellcode analysis, and VirusTotal access for hash lookups.

  • Python 3.8+
  • peepdf-3 (install with the command below)
  • pdfid.py and pdf-parser.py from the Didier Stevens suite
  • An isolated analysis environment such as a VM or sandbox
  • Optional: PyV8 (JavaScript emulation)
  • Optional: Pylibemu (shellcode analysis)
  • Optional: VirusTotal access (hash lookups)
pip install peepdf-3

How do you trigger the skill with a natural request?

You do not need special syntax. Describe the task in plain language and name the file. The skill is meant for triage of suspicious PDF attachments, analysis of PDF-based exploit documents, and building detection signatures for weaponized PDFs.

Include the file path and say what you want back, such as a report or a list of URLs. The skill's report template includes a SHA-256 hash, suspicious keywords, objects with JavaScript, extracted URLs, shellcode status, embedded file counts, VirusTotal detections and a risk level.

  • "Triage the PDF in ./samples/invoice.pdf from a phishing email and give me the standard analysis report."
  • "Find any JavaScript or OpenAction in this PDF and tell me which objects contain them."
  • "Extract the URLs from this suspicious PDF and list the hashes I should check."
  • "Help me build detection signatures for this PDF-based exploit."

What does a typical run produce?

The output follows a fixed report format. Each field is filled from the analysis, so you can compare samples side by side or paste the report into a case file.

The report includes a risk rating of Critical, High, Medium or Low. Treat that rating as the agent's interpretation of the evidence, not a verdict.

  • Analysis Report ID, file name and SHA-256 hash
  • Suspicious keywords and objects containing JavaScript
  • Extracted URLs and shellcode detected (Yes/No)
  • Embedded files (count and types) and VirusTotal detections
  • Risk Level

What safety rules should you follow?

The skill runs scripts and uses the network. The helper script at scripts/agent.py computes file hashes and runs pdfid to tally keywords. The VirusTotal step sends hash lookups over the network. The skill itself says to use an isolated VM or sandbox, and skipping this risks infection.

Do not run this on your everyday workstation with a live malicious sample. A clean result also does not prove that a PDF is safe; it only means the static checks found nothing.

  • Analyse samples only inside an isolated VM or sandbox
  • Review scripts/agent.py before running it
  • Be aware that VirusTotal lookups go out over the network
  • Do not treat a clean report as proof of safety

What tips help you get better results?

Start with the quick triage scan before opening the file in interactive mode. The reference file lists useful peepdf options, such as -f for force parsing and -l for loose mode, which can help with malformed files.

Use the stream and js_analyse commands on objects that pdfid flagged. Keep notes on object IDs so your report can point to exact locations.

  • Run pdfid first to see which keywords are present
  • Use peepdf -f -l for malformed files
  • Use info, tree and object commands to explore structure
  • Use js_analyse on flagged objects; js_eval needs PyV8
peepdf -f -l malicious.pdf

What people use it for

  • Triaging a PDF attachment reported from a phishing email
  • Documenting a weaponized document sample for a DFIR case file
  • Identifying which objects contain JavaScript or an OpenAction
  • Extracting URLs and hashes as indicators of compromise
  • Learning how PDF-based exploits are structured

Frequently asked questions

How do I install the malicious PDF analysis agent skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need to run it?

You need Python 3.8 or later, peepdf-3, and pdfid.py and pdf-parser.py from the Didier Stevens suite. The skill also says to run analysis in an isolated VM or sandbox. PyV8, Pylibemu and VirusTotal access are optional.

Is this skill free to use?

The skill is published under the Apache-2.0 licence. Check the licence file for the terms that apply to your use. This page does not state any price.

Is it safe to analyse a PDF with this skill?

The skill itself advises using an isolated VM or sandbox, because skipping that risks infection. It runs scripts and uses the network for VirusTotal lookups, so review scripts/agent.py before running it.

Can the skill tell me whether a PDF is safe?

No. The skill is for analysts and a clean result does not prove a PDF is safe. Its risk rating is an interpretation of static evidence that needs human review.

What is the difference between peepdf, pdfid and pdf-parser?

pdfid.py is a quick triage scanner that counts suspicious keywords. pdf-parser.py parses objects in more depth, and peepdf provides an interactive environment for exploring structure and analysing JavaScript.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits security analysts, malware analysts and students who already understand PDF structure and can work in an isolated environment. It is not a good choice for someone who just wants a quick yes or no on whether a PDF is safe; a dedicated sandbox or a specialist analyst will serve that need better.

Download the skill