pdforensic-authentic-check 0.1.1__tar.gz

pdforensic_authentic_check-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Mkwizu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdforensic_authentic_check-0.1.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: pdforensic-authentic-check
+Version: 0.1.1
+Summary: A simple PDF forensic toolkit using pdfresurrect and bash utilities
+Author: Alex Mkwizu
+Author-email: alexgmkwizu@gmail.com
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: summary

pdforensic_authentic_check-0.1.1/README.md

@@ -0,0 +1,167 @@
+# 📄 pdforensic
+
+
+> A lightweight Python toolkit for forensic analysis of PDF files using [pdfresurrect](https://github.com/enferex/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.
+
+## Project Directory
+```
+.
+├── 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
+```
+## The Package
+
+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](https://github.com/enferex/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.
+
+## 🐍 Using the Python Package
+
+You can use **pdforensic** directly from Python code by importing its core functions.
+
+### 📦 Importable Functions
+
+```python
+from pdforensic import (
+    extract_pdf_metadata,
+    recover_pdf_versions,
+    count_pdf_eof_markers,
+    check_no_of_versions
+)
+```
+1. Extract PDF Metadata
+
+```python
+from pdforensic import extract_pdf_metadata
+
+metadata = extract_pdf_metadata("tests/pdf-to-test/pdf-to-test-a.pdf")
+print(metadata)
+```
+Returns:
+
+```python
+
+{
+  'Versions': '1',
+  'PDF Version': '1.4',
+  'Title': 'My Document',
+  'Producer': 'Skia/PDF',
+  ...
+}
+```
+
+2. Recover Previous Versions
+
+```python
+
+from pdforensic import recover_pdf_versions
+
+message = recover_pdf_versions("tests/pdf-to-test/pdf-to-test-b.pdf")
+print(message)
+```
+
+Example output:
+```python
+Recovered 2 version(s). Found in: pdf-to-test-b-versions/
+```
+
+3. Count %%EOF Markers
+
+```python
+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}")
+```
+
+4. Check Number of PDF Versions
+
+```python
+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.
+
+### 📦 Using CLI
+
+**🔧 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
+```bash
+
+pdf-meta <pdf_path>
+
+pdf-recover <pdf_path>
+
+pdf-eof <pdf_path>
+
+pdf-versions <pdf_path>
+
+```
+## 🛠️ Installation
+
+### Option 1: Clone and Install from GitHub (Recommended)
+
+```bash
+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.
+```
+
+### Option 2: Install with Dev Dependencies (for testing and development)
+```bash
+pip install -e '.[dev]'
+#This includes testing tools i.e., pytest.
+```
+### Option 3: Install directly via GitHub URL (no clone)
+```bash
+pip install git+https://github.com/genie360s/pdforensic.git
+```
+
+
+
+#### 📜 License
+
+MIT License © 2025 Alex Mkwizu

pdforensic_authentic_check-0.1.1/pdforensic/__init__.py

@@ -0,0 +1,17 @@
+"""
+pdforensic - Lightweight PDF forensics utility wrapping pdfresurrect and other shell tools.
+"""
+
+from .retrieve_metadata import extract_pdf_metadata
+from .retrieve_all_versions import recover_pdf_versions
+from .check_versions import check_no_of_versions
+from .check_eof_markers import count_pdf_eof_markers
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "extract_pdf_metadata",
+    "recover_pdf_versions",
+    "check_no_of_versions",
+    "count_pdf_eof_markers"
+]

pdforensic_authentic_check-0.1.1/pdforensic/check_eof_markers.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+
+import argparse
+import re
+
+def count_pdf_eof_markers(pdf_path):
+    """
+    Count the number of %%EOF markers in a PDF file.
+    
+    Args:
+        pdf_path (str): Path to the PDF file.
+
+    Returns:
+        int: Number of %%EOF markers.
+        -1: If file not found or unreadable.
+    """
+    try:
+        with open(pdf_path, 'rb') as f:
+            content = f.read()
+
+        matches = re.findall(rb"%%EOF", content)
+        return len(matches)
+
+    except FileNotFoundError:
+        return -1
+    except Exception as e:
+        print(f"Error reading PDF: {e}")
+        return -1
+
+def cli():
+    """
+    Command-line interface for counting %%EOF markers in a PDF file.
+    """
+    parser = argparse.ArgumentParser(description="Count %%EOF markers in a PDF file")
+    parser.add_argument("pdf_path", type=str, help="Path to the PDF file")
+    args = parser.parse_args()
+
+    count = count_pdf_eof_markers(args.pdf_path)
+    if count == -1:
+        print("❌ Could not open or read the PDF.")
+    else:
+        print(f"Number of %%EOF markers found: {count}")
+
+if __name__ == "__main__":
+    cli()

pdforensic_authentic_check-0.1.1/pdforensic/check_versions.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+
+import subprocess
+import argparse
+
+def check_no_of_versions(pdf_path):
+    """
+    Check the number of versions of a PDF file using the pdfresurrect tool.
+
+    Args:
+        pdf_path (str): The path to the PDF file.
+
+    Returns:
+        int: The number of versions found in the PDF file.
+    """
+    try:
+        result = subprocess.run(
+            ['./bin/pdfresurrect', '-q', pdf_path],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        output = result.stdout.strip()
+        if ':' in output:
+            parts = output.split(':')
+            version_str = parts[1].strip()
+            if version_str.isdigit():
+                return int(version_str)
+        print(f"Unexpected output: {output}")
+        return 0
+    except subprocess.CalledProcessError as e:
+        print(f"Error checking PDF versions: {e}")
+        return 0
+
+def cli():
+    """
+    Command-line interface for checking number of PDF versions.
+    """
+    parser = argparse.ArgumentParser(description="Check the number of PDF versions using pdfresurrect")
+    parser.add_argument("pdf_path", type=str, help="Path to the PDF file")
+    args = parser.parse_args()
+
+    versions = check_no_of_versions(args.pdf_path)
+    print(f"Number of versions found: {versions}")
+
+if __name__ == "__main__":
+    cli()

pdforensic_authentic_check-0.1.1/pdforensic/retrieve_all_versions.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+
+import subprocess
+import argparse
+import os
+
+def recover_pdf_versions(pdf_path):
+    """
+    Recover previous versions of a PDF using pdfresurrect -w.
+    If previous versions are recovered, list them from the auto-created folder.
+
+    Args:
+        pdf_path (str): Path to the PDF file.
+
+    Returns:
+        str: Status message with recovered file listing if applicable.
+    """
+    try:
+        result = subprocess.run(
+            ['./bin/pdfresurrect', '-w', pdf_path],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+
+        output = result.stdout.strip()
+        print(f"\n[pdforensic output]:\n{output}\n")
+
+        # Case 1: Only one version
+        if "There is only one version of this PDF" in output:
+            return "There is only one version of this PDF. No previous versions recovered."
+
+        # Case 2: Folder exists with recovered versions
+        base_name = os.path.splitext(os.path.basename(pdf_path))[0]
+        version_folder = f"{base_name}-versions"
+
+        if os.path.isdir(version_folder):
+            recovered_files = os.listdir(version_folder)
+            print(f"Recovered versions & summary text of change found in: {version_folder}/")
+            for f in recovered_files:
+                print(f"✔ {f}")
+            return f"Recovered {len(recovered_files)} version(s)."
+        else:
+            return "Warning: Recovery folder not found, although output indicated multiple versions."
+
+    except subprocess.CalledProcessError as e:
+        return f"Error recovering PDF versions: {e}"
+
+def cli():
+    """
+    Command-line interface for recovering PDF versions.
+    """
+    parser = argparse.ArgumentParser(description="Recover previous PDF versions using pdfresurrect")
+    parser.add_argument("pdf_path", type=str, help="Path to the PDF file")
+    args = parser.parse_args()
+
+    message = recover_pdf_versions(args.pdf_path)
+    print(f"\nResult: {message}")
+
+if __name__ == "__main__":
+    cli()

pdforensic_authentic_check-0.1.1/pdforensic/retrieve_metadata.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+
+import subprocess
+import argparse
+
+def extract_pdf_metadata(pdf_path):
+    """
+    Extract PDF forensic metadata using pdfresurrect -i.
+
+    Args:
+        pdf_path (str): Path to the PDF file.
+
+    Returns:
+        dict: Metadata extracted from the PDF.
+    """
+    metadata = {}
+    try:
+        result = subprocess.run(
+            ['./bin/pdfresurrect', '-i', pdf_path],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+
+        lines = result.stdout.strip().splitlines()
+
+        for line in lines:
+            if line.strip() == "":
+                continue
+
+            # Handle Version X -- Y objects
+            if line.startswith("Version") and "--" in line and "objects" in line:
+                metadata["object_summary"] = line.strip()
+                continue
+
+            # Handle key: value
+            if ":" in line:
+                key, value = line.split(":", 1)
+                metadata[key.strip()] = value.strip().strip("()")
+
+        return metadata
+
+    except subprocess.CalledProcessError as e:
+        print(f"Error extracting metadata: {e}")
+        return {}
+
+def cli():
+    """
+    Command-line interface for extracting PDF metadata.
+    """
+    parser = argparse.ArgumentParser(description="Extract PDF metadata using pdfresurrect")
+    parser.add_argument("pdf_path", type=str, help="Path to the PDF file")
+    args = parser.parse_args()
+
+    meta = extract_pdf_metadata(args.pdf_path)
+    print("Extracted PDF Metadata:")
+    for key, value in meta.items():
+        print(f"{key}: {value}")
+
+if __name__ == "__main__":
+    cli()

pdforensic_authentic_check-0.1.1/pdforensic_authentic_check.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: pdforensic-authentic-check
+Version: 0.1.1
+Summary: A simple PDF forensic toolkit using pdfresurrect and bash utilities
+Author: Alex Mkwizu
+Author-email: alexgmkwizu@gmail.com
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: summary

pdforensic_authentic_check-0.1.1/pdforensic_authentic_check.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+setup.py
+pdforensic/__init__.py
+pdforensic/check_eof_markers.py
+pdforensic/check_versions.py
+pdforensic/retrieve_all_versions.py
+pdforensic/retrieve_metadata.py
+pdforensic_authentic_check.egg-info/PKG-INFO
+pdforensic_authentic_check.egg-info/SOURCES.txt
+pdforensic_authentic_check.egg-info/dependency_links.txt
+pdforensic_authentic_check.egg-info/entry_points.txt
+pdforensic_authentic_check.egg-info/requires.txt
+pdforensic_authentic_check.egg-info/top_level.txt
+tests/test_check_eof_markers.py
+tests/test_check_versions.py
+tests/test_retrieve_all-versions.py
+tests/test_retrieve_metadata.py

pdforensic_authentic_check-0.1.1/pdforensic_authentic_check.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pdforensic_authentic_check-0.1.1/pdforensic_authentic_check.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+pdf-eof = pdforensic.check_eof_markers:cli
+pdf-meta = pdforensic.retrieve_metadata:cli
+pdf-recover = pdforensic.retrieve_all_versions:cli
+pdf-versions = pdforensic.check_versions:cli

pdforensic_authentic_check-0.1.1/pdforensic_authentic_check.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest

pdforensic_authentic_check-0.1.1/pdforensic_authentic_check.egg-info/top_level.txt

@@ -0,0 +1 @@
+pdforensic

pdforensic_authentic_check-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pdforensic_authentic_check-0.1.1/setup.py

@@ -0,0 +1,26 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name='pdforensic-authentic-check',
+    version='0.1.1',
+    description='A simple PDF forensic toolkit using pdfresurrect and bash utilities',
+    author='Alex Mkwizu',
+    author_email='alexgmkwizu@gmail.com',
+    packages=find_packages(),
+    include_package_data=True,
+    install_requires=[],  # Add any dependencies like PyPDF2 if used
+    extras_require={
+    "dev": ["pytest"]
+    },
+    entry_points={
+        'console_scripts': [
+            'pdf-meta=pdforensic.retrieve_metadata:cli',
+            'pdf-recover=pdforensic.retrieve_all_versions:cli',
+            'pdf-eof=pdforensic.check_eof_markers:cli',
+            'pdf-versions=pdforensic.check_versions:cli'
+        ],
+    },
+)

pdforensic_authentic_check-0.1.1/tests/test_check_eof_markers.py

@@ -0,0 +1,9 @@
+from pdforensic.check_eof_markers import count_pdf_eof_markers
+
+def test_count_eof_in_single_version_pdf():
+    count = count_pdf_eof_markers("tests/pdf-to-test/pdf-to-test-b.pdf")
+    assert count == 1
+
+def test_count_eof_in_multi_version_pdf():
+    count = count_pdf_eof_markers("tests/pdf-to-test/pdf-to-test-a.pdf")
+    assert count > 1

pdforensic_authentic_check-0.1.1/tests/test_check_versions.py

@@ -0,0 +1,9 @@
+from pdforensic.check_versions import check_no_of_versions
+
+def test_check_single_version_pdf():
+    count = check_no_of_versions("tests/pdf-to-test/pdf-to-test-a.pdf")
+    assert count == 1
+
+# def test_check_multi_version_pdf():
+#     count = check_no_of_versions("tests/pdf-to-test/pdf-to-test-b.pdf")
+#     assert count > 1

pdforensic_authentic_check-0.1.1/tests/test_retrieve_all-versions.py

@@ -0,0 +1,13 @@
+import os
+from pdforensic.retrieve_all_versions import recover_pdf_versions
+
+def test_recover_pdf_versions_single_version():
+    result = recover_pdf_versions("tests/pdf-to-test/pdf-to-test-b.pdf")
+    assert "only one version" in result.lower()
+
+def test_recover_pdf_versions_multi_version():
+    result = recover_pdf_versions("tests/pdf-to-test/pdf-to-test-a.pdf")
+    assert "recovered" in result.lower()
+    folder = "pdf-to-test-a-versions"
+    assert os.path.exists(folder)
+    assert len(os.listdir(folder)) > 0

pdforensic_authentic_check-0.1.1/tests/test_retrieve_metadata.py

@@ -0,0 +1,7 @@
+import os
+from pdforensic.retrieve_metadata import extract_pdf_metadata
+
+def test_extract_pdf_metadata_returns_dict():
+    metadata = extract_pdf_metadata("tests/pdf-to-test/pdf-to-test-a.pdf")
+    assert isinstance(metadata, dict)
+    assert "PDF Version" in metadata