Metadata-Version: 2.4
Name: pdforensic-authentic-check
Version: 0.2.0
Summary: PDF forensics toolkit: detect edited or tampered PDFs, recover previous versions, extract metadata (Info, XMP), check signatures and find out how a PDF was created.
Author-email: Alex Mkwizu <alexgmkwizu@gmail.com>
License-Expression: MIT AND BSD-3-Clause
Project-URL: Homepage, https://github.com/genie360s/pdforensic
Project-URL: Documentation, https://github.com/genie360s/pdforensic/blob/main/docs/USER_GUIDE.md
Project-URL: Repository, https://github.com/genie360s/pdforensic
Project-URL: Issues, https://github.com/genie360s/pdforensic/issues
Project-URL: Changelog, https://github.com/genie360s/pdforensic/blob/main/CHANGELOG.md
Keywords: pdf,pdf-forensics,forensics,digital-forensics,document-forensics,pdf-analysis,pdf-metadata,metadata,xmp,tamper-detection,pdf-tampering,edited-pdf,document-fraud,document-verification,fraud-detection,incremental-update,pdf-revisions,pdf-version-recovery,digital-signature,pdf-provenance,pdf-a,pdf-x,qpdf,pikepdf,pdfresurrect,dfir,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Legal Industry
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: src/pdfresurrect/LICENSE
Requires-Dist: pikepdf>=9
Dynamic: license-file

# 📄 pdforensic: PDF forensics toolkit

[![PyPI version](https://img.shields.io/pypi/v/pdforensic-authentic-check)](https://pypi.org/project/pdforensic-authentic-check/)
[![Python versions](https://img.shields.io/pypi/pyversions/pdforensic-authentic-check)](https://pypi.org/project/pdforensic-authentic-check/)
[![CI](https://github.com/genie360s/pdforensic/actions/workflows/ci.yml/badge.svg)](https://github.com/genie360s/pdforensic/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/genie360s/pdforensic/blob/main/LICENSE)

**Find out whether a PDF was edited, see what changed, recover its earlier versions, read all of its metadata and learn how it was made.** A command-line tool and Python library for PDF forensic analysis, tamper detection and document verification on Linux, macOS and Windows.

```bash
uv tool install pdforensic-authentic-check
pdforensic analyze invoice.pdf
```

New to this? The **[user guide](https://github.com/genie360s/pdforensic/blob/main/docs/USER_GUIDE.md)** walks through installation and every feature in plain language, with no programming needed.

## What it tells you about a PDF

| Question | What pdforensic reports |
|---|---|
| **Was this PDF edited after it was created?** | Every later save still recorded in the file, and exactly which parts each save added, changed or deleted. |
| **What did it say before?** | Each earlier version, recovered byte for byte as a PDF you can open. |
| **What metadata does it carry?** | Title, author, dates, creating software (Info dictionary and XMP), file IDs, MD5/SHA-1/SHA-256 hashes, fonts, images, attachments, JavaScript, forms. |
| **How was it made?** | Exported from Word or Excel, generated by a library (ReportLab, iText, TCPDF and others), printed from a browser, scanned, OCR'd, or post-processed by a PDF editor. |
| **Is the digital signature still intact?** | What each signature covers and whether anything was added after signing. |
| **Which standard does it claim?** | PDF/A, PDF/X, PDF/UA, PDF/E and PDF/VT claims, and print-industry preflight tickets. |
| **Is it encrypted or damaged?** | Encryption details, structural damage, and files that only pretend to be PDFs. |

Every finding comes with its evidence and the clause of the PDF standard (ISO 32000) it rests on.

## Example: an invoice whose title was changed

```text
$ pdforensic analyze invoice-edited.pdf

Revisions   2    %%EOF markers 2    objects 7    pages 1

Metadata (Info dictionary)
  Producer      MuPDF incremental save
  Title         Invoice 0042 (amended)

Revisions
  1: bytes 0-1385, xref table, +7 ~0 -0 objects
  2: bytes 1385-1807, xref table, +0 ~1 -0 objects
       modified object 5 (Info)

Tamper indicators: level=medium, modified after creation: yes
  [medium] File was saved incrementally 1 time(s) after it was first written
  [low   ] File identifier shows the file changed after creation
  [medium] Producer changed in revision 2
           Revision 1: "ReportLab PDF Library - (opensource)"; revision 2: "MuPDF incremental save".
```

(Output shortened.) The original is still inside the file. This writes it out, identical byte for byte to the invoice before the change:

```text
$ pdforensic recover invoice-edited.pdf
revision 1  1385 bytes  sha256 830b0ab2dfa5...  invoice-edited-revisions/invoice-edited-rev1.pdf
```

## Install

Requires Python 3.11 or newer; [uv](https://docs.astral.sh/uv/) fetches it for you.

```bash
uv tool install pdforensic-authentic-check   # the command-line tools
uv add pdforensic-authentic-check            # or as a dependency of your Python project
uvx --from pdforensic-authentic-check pdforensic analyze file.pdf   # or run once without installing
```

Ready-made packages exist for Linux (x86_64, arm64), macOS (Apple Silicon) and Windows (x86_64). First time using a terminal? See [Install it](https://github.com/genie360s/pdforensic/blob/main/docs/USER_GUIDE.md#2-install-it) in the user guide.

## Commands

```bash
pdforensic analyze file.pdf                      # readable report
pdforensic analyze file.pdf --json               # full report as JSON
pdforensic analyze locked.pdf --password secret  # password-protected file
pdforensic recover file.pdf                      # write every earlier version to <name>-revisions/
pdforensic recover file.pdf -o folder --all      # choose the folder; include the current version
pdforensic --version
```

Files are only read: nothing is modified and nothing leaves your computer.

## Python

```python
from pdforensic import analyze, recover_revisions, format_report

report = analyze("invoice.pdf")              # a path or bytes; returns a JSON-serializable dict
print(format_report(report))

report["structure"]["revision_count"]        # 2
report["revisions"][1]["changes"]            # [{"object": 5, "change": "modified", "type": "Info"}]
report["tamper"]["level"]                    # "none" | "info" | "low" | "medium" | "high"
report["tamper"]["indicators"]               # each with id, severity, title, detail, basis
report["provenance"]["generation"]           # e.g. "programmatic", "exported_from_application", "scan"

for item in recover_revisions("invoice.pdf", "earlier-versions"):
    print(item["revision"], item["path"], item["sha256"])
```

All report sections and all 27 findings are described in the [user guide](https://github.com/genie360s/pdforensic/blob/main/docs/USER_GUIDE.md#7-what-every-finding-means).

## Read the result carefully

- Findings are **evidence, not proof**. A file with no findings may still have been altered and then fully re-saved ("Save As", "Print to PDF"), which erases its history.
- **Counting `%%EOF` markers is not enough.** Files prepared for fast web viewing and every PDF exported from Microsoft Word, Excel or PowerPoint have two markers and have never been edited. The `Revisions` count accounts for both.
- Differing file IDs or dates are common in honest files; weigh them with the rest.
- Signature *cryptography* is not verified. The report shows what each signature covers.
- A claim such as PDF/A-1b is what the file declares, not a validation.

## Documentation

| Document | For |
|---|---|
| [User guide](https://github.com/genie360s/pdforensic/blob/main/docs/USER_GUIDE.md) | Everyone: installation, each command, how to read every result, troubleshooting, glossary. |
| [PDF forensics notes](https://github.com/genie360s/pdforensic/blob/main/docs/PDF_FORENSICS.md) | The rules behind each finding, the standards and sources they rest on, speed, and what was verified. |
| [Changelog](https://github.com/genie360s/pdforensic/blob/main/CHANGELOG.md) | What changed in each version. |
| [llms.txt](https://github.com/genie360s/pdforensic/blob/main/llms.txt) | A compact description for AI assistants and agents. |

## How it works

pdforensic is built on [qpdf](https://github.com/qpdf/qpdf) (through [pikepdf](https://github.com/pikepdf/pikepdf)) for fast, robust parsing, decoding and decryption, plus its own byte-level layer for the history that PDF libraries hide: revision boundaries, superseded objects and raw trailers. A typical document is analyzed in a few milliseconds; a 22 MB file with 127,000 objects in about half a second.

The original [pdfresurrect](https://github.com/enferex/pdfresurrect) C tool is bundled and built from source (`src/pdfresurrect`). The four original commands and functions still work:

| Command | Python | What it does |
|---|---|---|
| `pdf-versions` | `check_no_of_versions(path)` | number of versions via `pdfresurrect -q` |
| `pdf-meta` | `extract_pdf_metadata(path)` | creator information via `pdfresurrect -i` |
| `pdf-recover` | `recover_pdf_versions(path)` | writes versions via `pdfresurrect -w` into `<name>-versions/` |
| `pdf-eof` | `count_pdf_eof_markers(path)` | number of `%%EOF` markers |

pdfresurrect does not decode cross-reference streams or XMP and stops on some linearized files; `pdforensic analyze` covers those cases. See [UPSTREAM.md](https://github.com/genie360s/pdforensic/blob/main/src/pdfresurrect/UPSTREAM.md) for the vendored version and its patches.

## Development

```bash
git clone https://github.com/genie360s/pdforensic.git
cd pdforensic
uv sync                 # creates .venv, installs everything, builds pdfresurrect (needs a C compiler)
uv run pytest           # unit, integration, regression and fuzz tests
uv run ruff check .
```

- `pdforensic/forensics.py` builds the report; `pdforensic/_pdf.py` is the raw byte layer; `pdforensic/cli.py` is the command.
- `tests/fixtures` holds PDFs from real producers; `tests/golden` holds the stored reports the regression tests compare against (regenerate with `PDFORENSIC_UPDATE_GOLDEN=1 uv run pytest tests/test_regression.py`).
- `PDFORENSIC_CORPUS=/path/to/pdfs uv run pytest tests/test_corpus.py` runs the analyzer over any folder of PDFs.
- To build pdfresurrect on its own: `cmake -B build && cmake --build build --config Release`.

### Releasing

The version number lives in one place, the [`VERSION`](https://github.com/genie360s/pdforensic/blob/main/VERSION) file. The package metadata, `pdforensic.__version__`, `pdforensic --version` and the report all read it.

```bash
# 1. edit VERSION and CHANGELOG.md, commit, merge to main
git tag "v$(cat VERSION)" && git push origin "v$(cat VERSION)"
# 2. the release workflow checks the tag against VERSION, builds the binaries,
#    wheels and sdist on every platform, and creates the GitHub release
gh release download "v$(cat VERSION)" --pattern "*.whl" --pattern "*.tar.gz" --dir dist
UV_PUBLISH_TOKEN=... uv publish dist/*
```

To publish from the workflow instead, set the repository variable `PUBLISH_TO_PYPI` to `true` and configure PyPI trusted publishing for the `pypi` environment.

## License

MIT License © 2025 Alex Mkwizu. The bundled pdfresurrect source in `src/pdfresurrect` is BSD-3-Clause, © pdfresurrect authors.
