A lightweight Python toolkit for forensic analysis of PDF files using pdfresurrect and unix kernel shell utilities.
pdforensic wraps common PDF forensic techniques into an easy-to-use Python and CLI interface — allowing you to extract metadata, recover previous versions, count EOF markers, and inspect version layers of PDF files.
.
├── bin
│ ├── pdfresurrect
│ └── pdfresurrect.1
├── LICENSE
├── pdforensic
│ ├── __init__.py
├── README.md
├── setup.py
└── tests
├── pdf-to-test
│ ├── pdf-to-test-a.pdf
│ └── pdf-to-test-b.pdf
├── test_check_eof_markers.py
├── test_check_versions.py
├── test_retrieve_all-versions.py
└── test_retrieve_metadata.py
This package has been built to work on unix kernel i.e., linux OS and MacOS.
You will require Python 3.13.x to work with this package.
This package is an ongoing experiment to understand how to check for an edited PDF and automate the process.
It is built on top of pdfresurrect which is a C tool that reads the PDF at it's lowest level extracting metadata , object streams , check for previous versions by checking for cross-referencing of streams and also able to rewrite previous versions.
The pdfresurrect functionalities have been wrapped to be reusable quickly with Python.
An additional functionality from my PDF research has been added that check for %%EOF markers its absence means the PDF is corrupted and not in a proper format. A linearized or an original or freshly saved has 1 %%EOF marker , more than 1 means the PDF has been tampered with.
Hence you can use above functionalities to build a PDF verification algorithim if you do now what type of PDF file you will be processing by comparing it's properties against new incoming PDF's.
You can use pdforensic directly from Python code by importing its core functions.
from pdforensic import (
extract_pdf_metadata,
recover_pdf_versions,
count_pdf_eof_markers,
check_no_of_versions
)- Extract PDF Metadata
from pdforensic import extract_pdf_metadata
metadata = extract_pdf_metadata("tests/pdf-to-test/pdf-to-test-a.pdf")
print(metadata)Returns:
{
'Versions': '1',
'PDF Version': '1.4',
'Title': 'My Document',
'Producer': 'Skia/PDF',
...
}- Recover Previous Versions
from pdforensic import recover_pdf_versions
message = recover_pdf_versions("tests/pdf-to-test/pdf-to-test-b.pdf")
print(message)Example output:
Recovered 2 version(s). Found in: pdf-to-test-b-versions/- Count %%EOF Markers
from pdforensic import count_pdf_eof_markers
count = count_pdf_eof_markers("tests/pdf-to-test/pdf-to-test-a.pdf")
print(f"EOF markers: {count}")- Check Number of PDF Versions
from pdforensic import check_no_of_versions
num_versions = check_no_of_versions("tests/pdf-to-test/pdf-to-test-a.pdf")
print(f"PDF contains {num_versions} version(s).")🧪 Pro Tip You can integrate these tools into a PDF auditing script or pipeline for digital forensics, penetration testing, academic research, or version tracking.
🔧 Command-Line Interface (CLI)
Once installed (with pip install -e .), the following CLI commands are available:
Command Description
pdf-meta Extract metadata from a PDF file
pdf-recover Recover previous versions of a PDF
pdf-eof Count %%EOF markers in a PDF
pdf-versions Check number of versions in a PDF (via -q)
Example Usage
pdf-meta <pdf_path>
pdf-recover <pdf_path>
pdf-eof <pdf_path>
pdf-versions <pdf_path>
git clone https://github.com/yourusername/pdforensic.git
cd pdforensic
pip install -e .
#This installs pdforensic in editable mode, meaning any changes you make to the code will take effect immediately.pip install -e '.[dev]'
#This includes testing tools i.e., pytest.pip install git+https://github.com/genie360s/pdforensic.gitMIT License © 2025 Alex Mkwizu