@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/risk-compliance/doc-authenticity/scripts/image_forensics.py

@@ -0,0 +1,294 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["Pillow>=10"]
+# ///
+"""Extract metadata, container, and recompression signals from a raster image.
+
+Usage:
+    uv run image_forensics.py input.jpg --out outdir/
+
+Writes image-forensics.json and, for JPEG inputs, ela.png. The output is
+evidence for analyst review, not an automatic authenticity decision.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import io
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from PIL import ExifTags, Image, ImageChops, ImageEnhance, ImageStat
+
+EDITOR_PATTERNS = {
+    "Adobe Photoshop": rb"(?i)(adobe\s+photoshop|photoshop\s+3\.0|8BIM)",
+    "Adobe Lightroom": rb"(?i)(adobe\s+lightroom|lightroom)",
+    "GIMP": rb"(?i)(\bgimp\b|gimp-save)",
+    "Canva": rb"(?i)\bcanva\b",
+    "Affinity": rb"(?i)\baffinity(?:\s+photo)?\b",
+    "Pixelmator": rb"(?i)\bpixelmator\b",
+    "ImageMagick": rb"(?i)(imagemagick|magick)",
+    "Microsoft image tools": rb"(?i)(microsoft.*(?:photo|image)|windows photo editor)",
+}
+
+CAPTURE_PATTERNS = {
+    "Apple": rb"(?i)apple iphone|apple screenshot",
+    "Google": rb"(?i)google pixel",
+    "Samsung": rb"(?i)samsung",
+    "Canon": rb"(?i)canon",
+    "Nikon": rb"(?i)nikon",
+    "Sony": rb"(?i)sony",
+    "Fujifilm": rb"(?i)fujifilm",
+}
+
+
+def serializable(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, bytes):
+        return value[:256].decode("utf-8", "replace")
+    if isinstance(value, (list, tuple)):
+        return [serializable(v) for v in value]
+    if isinstance(value, dict):
+        return {str(k): serializable(v) for k, v in value.items()}
+    return str(value)
+
+
+def extract_exif(image: Image.Image) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    try:
+        for tag, value in image.getexif().items():
+            out[ExifTags.TAGS.get(tag, str(tag))] = serializable(value)
+    except Exception as exc:  # noqa: BLE001
+        out["_error"] = str(exc)
+    return out
+
+
+def jpeg_markers(data: bytes) -> dict[str, Any]:
+    names = {
+        0xD8: "SOI",
+        0xD9: "EOI",
+        0xDA: "SOS",
+        0xDB: "DQT",
+        0xC0: "SOF0",
+        0xC2: "SOF2",
+        0xC4: "DHT",
+        0xDD: "DRI",
+        0xE0: "APP0",
+        0xE1: "APP1",
+        0xE2: "APP2",
+        0xED: "APP13",
+        0xEE: "APP14",
+        0xFE: "COM",
+    }
+    markers: list[dict[str, Any]] = []
+    if not data.startswith(b"\xff\xd8"):
+        return {"valid_soi": False, "markers": markers}
+    markers.append({"name": "SOI", "offset": 0, "length": 2})
+    pos = 2
+    while pos + 1 < len(data):
+        if data[pos] != 0xFF:
+            pos += 1
+            continue
+        while pos < len(data) and data[pos] == 0xFF:
+            pos += 1
+        if pos >= len(data):
+            break
+        code = data[pos]
+        marker_offset = pos - 1
+        pos += 1
+        if code == 0xD9:
+            markers.append({"name": "EOI", "offset": marker_offset, "length": 2})
+            break
+        if code in range(0xD0, 0xD8) or code == 0x01:
+            markers.append(
+                {
+                    "name": names.get(code, f"0xFF{code:02X}"),
+                    "offset": marker_offset,
+                    "length": 2,
+                }
+            )
+            continue
+        if pos + 2 > len(data):
+            break
+        segment_length = int.from_bytes(data[pos : pos + 2], "big")
+        payload = data[pos + 2 : pos + segment_length]
+        entry: dict[str, Any] = {
+            "name": names.get(code, f"0xFF{code:02X}"),
+            "offset": marker_offset,
+            "length": segment_length + 2,
+        }
+        if code in (0xE0, 0xE1, 0xE2, 0xED, 0xEE, 0xFE):
+            entry["identifier"] = (
+                payload[:80].split(b"\x00", 1)[0].decode("latin-1", "replace")
+            )
+        markers.append(entry)
+        pos += segment_length
+        if code == 0xDA:
+            eoi = data.rfind(b"\xff\xd9")
+            if eoi >= 0:
+                markers.append({"name": "EOI", "offset": eoi, "length": 2})
+            break
+    eoi_offset = data.rfind(b"\xff\xd9")
+    return {
+        "valid_soi": True,
+        "markers": markers,
+        "eoi_offset": eoi_offset if eoi_offset >= 0 else None,
+        "bytes_after_eoi": len(data) - eoi_offset - 2 if eoi_offset >= 0 else None,
+        "has_exif_app1": b"Exif\x00\x00" in data,
+        "has_xmp": b"http://ns.adobe.com/xap/1.0/" in data,
+        "has_photoshop_app13": b"Photoshop 3.0" in data or b"8BIM" in data,
+        "has_adobe_app14": any(m["name"] == "APP14" for m in markers),
+    }
+
+
+def estimate_jpeg_quality(image: Image.Image) -> int | None:
+    source = getattr(image, "quantization", None)
+    if not source or 0 not in source:
+        return None
+    source_luma = source[0]
+    probe = Image.new("RGB", (8, 8), "gray")
+    best: tuple[int, int] | None = None
+    for quality in range(30, 101):
+        buf = io.BytesIO()
+        probe.save(buf, format="JPEG", quality=quality)
+        buf.seek(0)
+        with Image.open(buf) as candidate:
+            table = candidate.quantization.get(0, [])
+        if len(table) != len(source_luma):
+            continue
+        distance = sum(abs(a - b) for a, b in zip(source_luma, table))
+        if best is None or distance < best[0]:
+            best = (distance, quality)
+    return best[1] if best else None
+
+
+def recompression_analysis(image: Image.Image, outdir: Path) -> dict[str, Any]:
+    quality = estimate_jpeg_quality(image) or 90
+    rgb = image.convert("RGB")
+    if max(rgb.size) > 5000:
+        rgb.thumbnail((5000, 5000))
+    buf = io.BytesIO()
+    rgb.save(buf, format="JPEG", quality=quality)
+    buf.seek(0)
+    with Image.open(buf) as recompressed:
+        diff = ImageChops.difference(rgb, recompressed.convert("RGB"))
+        gray = diff.convert("L")
+        global_mean = ImageStat.Stat(gray).mean[0]
+        tile_size = max(32, min(rgb.size) // 20)
+        tiles: list[dict[str, Any]] = []
+        for top in range(0, rgb.height, tile_size):
+            for left in range(0, rgb.width, tile_size):
+                box = (
+                    left,
+                    top,
+                    min(left + tile_size, rgb.width),
+                    min(top + tile_size, rgb.height),
+                )
+                mean = ImageStat.Stat(gray.crop(box)).mean[0]
+                tiles.append({"box": list(box), "mean_error": round(mean, 4)})
+        values = sorted(t["mean_error"] for t in tiles)
+        p95 = values[min(len(values) - 1, int(len(values) * 0.95))] if values else 0
+        max_tile = max(tiles, key=lambda t: t["mean_error"], default=None)
+        amplified = ImageEnhance.Contrast(diff).enhance(8)
+        amplified = ImageEnhance.Brightness(amplified).enhance(8)
+        amplified.save(outdir / "ela.png")
+    return {
+        "method": "same-quality JPEG recompression difference",
+        "estimated_quality": quality,
+        "analysis_size": list(rgb.size),
+        "tile_size": tile_size,
+        "global_mean_error": round(global_mean, 4),
+        "p95_tile_error": p95,
+        "max_tile": max_tile,
+        "highest_error_tiles": sorted(
+            tiles, key=lambda t: t["mean_error"], reverse=True
+        )[:10],
+        "ela_path": str(outdir / "ela.png"),
+        "caution": "ELA is heuristic; naturally detailed regions differ from flat regions, and a full-image re-export can hide local edits.",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("input", type=Path)
+    parser.add_argument("--out", required=True, type=Path)
+    args = parser.parse_args()
+    args.out.mkdir(parents=True, exist_ok=True)
+
+    data = args.input.read_bytes()
+    with Image.open(args.input) as image:
+        image.verify()
+    with Image.open(args.input) as image:
+        exif = extract_exif(image)
+        info = {
+            str(k): serializable(v)
+            for k, v in image.info.items()
+            if k not in {"exif", "icc_profile"}
+        }
+        text_blob = (
+            data + json.dumps({"exif": exif, "info": info}, ensure_ascii=False).encode()
+        )
+        editor_matches = [
+            name
+            for name, pattern in EDITOR_PATTERNS.items()
+            if re.search(pattern, text_blob)
+        ]
+        capture_matches = [
+            name
+            for name, pattern in CAPTURE_PATTERNS.items()
+            if re.search(pattern, text_blob)
+        ]
+        result: dict[str, Any] = {
+            "input": str(args.input.resolve()),
+            "file_size": len(data),
+            "size_bytes": len(data),
+            "sha256": hashlib.sha256(data).hexdigest(),
+            "media_type": Image.MIME.get(image.format, "application/octet-stream"),
+            "extension_magic_match": args.input.suffix.lower()
+            in {
+                suffix.lower()
+                for suffix, detected_format in Image.registered_extensions().items()
+                if detected_format == image.format
+            },
+            "format": image.format,
+            "mode": image.mode,
+            "width": image.width,
+            "height": image.height,
+            "frames": getattr(image, "n_frames", 1),
+            "exif": exif,
+            "image_info": info,
+            "editor_matches": editor_matches,
+            "capture_device_matches": capture_matches,
+            "provenance": {
+                "marker_scan_only": True,
+                "cryptographic_validation": "not_performed",
+                "has_c2pa_or_jumbf_marker": any(
+                    token in data.lower()
+                    for token in (b"c2pa", b"jumb", b"contentauth")
+                ),
+                "has_content_credentials_text": b"content credentials" in data.lower(),
+            },
+        }
+        if image.format == "JPEG":
+            result["jpeg"] = jpeg_markers(data)
+            result["recompression"] = recompression_analysis(image, args.out)
+        else:
+            result["recompression"] = {
+                "available": False,
+                "reason": "JPEG ELA is not applicable to this source format; inspect metadata and pixels directly.",
+            }
+
+    output = args.out / "image-forensics.json"
+    output.write_text(
+        json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/risk-compliance/doc-authenticity/scripts/pdf_forensics.py

@@ -0,0 +1,401 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pikepdf>=8", "pdfplumber>=0.11"]
+# ///
+"""Extract forensic signals from a PDF for the doc-authenticity skill.
+
+Usage:
+    uv run pdf_forensics.py input.pdf --out outdir/
+
+Writes:
+    outdir/forensics.json   structural + metadata signals (F1-F9 inputs)
+    outdir/pages/page-N.txt extracted text per page
+    outdir/pages/page-N.fonts.tsv  word-level font map (word, font, size, x0, top)
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+import pdfplumber
+import pikepdf
+
+
+def parse_pdf_date(raw: str | None) -> str | None:
+    """D:20260115093000+00'00' -> 2026-01-15T09:30:00+00:00 (best effort)."""
+    if not raw:
+        return None
+    s = str(raw)
+    m = re.match(r"D:(\d{4})(\d{2})?(\d{2})?(\d{2})?(\d{2})?(\d{2})?([Zz+\-].*)?", s)
+    if not m:
+        return s
+    y, mo, d, h, mi, sec, tz = m.groups()
+    iso = f"{y}-{mo or '01'}-{d or '01'}T{h or '00'}:{mi or '00'}:{sec or '00'}"
+    if tz and tz not in ("Z", "z"):
+        tz = tz.replace("'", ":").rstrip(":")
+        iso += tz if re.match(r"[+\-]\d{2}:\d{2}$", tz) else ""
+    elif tz:
+        iso += "+00:00"
+    return iso
+
+
+def scan_raw_structure(data: bytes) -> dict:
+    """Byte-level scan: save generations and objects redefined across them."""
+    eof_positions = [m.start() for m in re.finditer(rb"%%EOF", data)]
+    startxrefs = len(re.findall(rb"startxref", data))
+    prev_pointers = len(re.findall(rb"/Prev\s+\d+", data))
+
+    # Objects defined more than once = redefined in a later generation
+    # (approximation: also matched inside object streams is not possible since
+    # those are compressed; raw matches are top-level definitions).
+    defs: dict[int, list[int]] = {}
+    for m in re.finditer(rb"(?m)^\s*(\d+)\s+\d+\s+obj\b", data):
+        defs.setdefault(int(m.group(1)), []).append(m.start())
+    updated = sorted(n for n, offs in defs.items() if len(offs) > 1)
+
+    trailing = data[eof_positions[-1] + 5 :] if eof_positions else b""
+    return {
+        "file_size": len(data),
+        "eof_count": len(eof_positions),
+        "startxref_count": startxrefs,
+        "prev_pointers": prev_pointers,
+        "incremental_updates": max(0, len(eof_positions) - 1),
+        "updated_objects": updated[:50],
+        "updated_object_count": len(updated),
+        "bytes_after_last_eof": len(trailing.strip()),
+        "header": data[:16].decode("latin-1", "replace").strip(),
+    }
+
+
+def extract_metadata(pdf: pikepdf.Pdf) -> dict:
+    info = {}
+    try:
+        for k, v in (pdf.docinfo or {}).items():
+            info[str(k).lstrip("/")] = str(v)
+    except Exception as e:  # noqa: BLE001
+        info["_error"] = str(e)
+    return {
+        "producer": info.get("Producer"),
+        "creator": info.get("Creator"),
+        "author": info.get("Author"),
+        "title": info.get("Title"),
+        "creation_date_raw": info.get("CreationDate"),
+        "mod_date_raw": info.get("ModDate"),
+        "creation_date": parse_pdf_date(info.get("CreationDate")),
+        "mod_date": parse_pdf_date(info.get("ModDate")),
+        "all_docinfo": info,
+    }
+
+
+def extract_xmp(pdf: pikepdf.Pdf) -> dict:
+    out: dict = {"present": False}
+    try:
+        meta = pdf.open_metadata()
+        if not str(meta):
+            return out
+        out["present"] = True
+        keys = [
+            ("xmp:CreatorTool", "creator_tool"),
+            ("pdf:Producer", "producer"),
+            ("xmp:CreateDate", "create_date"),
+            ("xmp:ModifyDate", "modify_date"),
+            ("xmp:MetadataDate", "metadata_date"),
+            ("xmpMM:DocumentID", "document_id"),
+            ("xmpMM:InstanceID", "instance_id"),
+        ]
+        for xmp_key, name in keys:
+            try:
+                if xmp_key in meta:
+                    out[name] = str(meta[xmp_key])
+            except Exception:  # noqa: BLE001, S110
+                pass
+        raw = str(meta)
+        out["xmp_toolkit"] = None
+        tk = re.search(r'x:xmptk="([^"]+)"', raw)
+        if tk:
+            out["xmp_toolkit"] = tk.group(1)
+        out["has_history"] = "xmpMM:History" in raw
+        out["has_derived_from"] = "xmpMM:DerivedFrom" in raw
+        agents = sorted(set(re.findall(r"softwareAgent>([^<]+)<", raw)))
+        agents += sorted(set(re.findall(r'softwareAgent="([^"]+)"', raw)))
+        out["history_software_agents"] = sorted(set(agents))
+    except Exception as e:  # noqa: BLE001
+        out["_error"] = str(e)
+    return out
+
+
+def extract_signatures(pdf: pikepdf.Pdf, file_size: int) -> list[dict]:
+    sigs = []
+    try:
+        root = pdf.Root
+        acro = root.get("/AcroForm")
+        if acro is None:
+            return sigs
+        for field in acro.get("/Fields", []):
+            try:
+                if str(field.get("/FT", "")) != "/Sig":
+                    continue
+                v = field.get("/V")
+                entry: dict = {"field_name": str(field.get("/T", ""))}
+                if v is None:
+                    entry["signed"] = False
+                    sigs.append(entry)
+                    continue
+                entry["signed"] = True
+                entry["cryptographic_validation"] = "not_performed"
+                entry["sub_filter"] = str(v.get("/SubFilter", "")) or None
+                entry["signer_name"] = str(v.get("/Name", "")) or None
+                entry["sign_date"] = parse_pdf_date(
+                    str(v.get("/M")) if v.get("/M") is not None else None
+                )
+                br = v.get("/ByteRange")
+                if br is not None:
+                    br = [int(x) for x in br]
+                    entry["byte_range"] = br
+                    # This checks structural coverage only; it does not verify
+                    # the signature value, certificate chain, or trust anchor.
+                    entry["byte_range_covers_file"] = (
+                        len(br) == 4
+                        and br[0] == 0
+                        and br[1] >= 0
+                        and br[2] >= br[1]
+                        and br[3] >= 0
+                        and br[2] + br[3] >= file_size - 4
+                    )
+                sigs.append(entry)
+            except Exception as e:  # noqa: BLE001
+                sigs.append({"_error": str(e)})
+    except Exception as e:  # noqa: BLE001
+        sigs.append({"_error": str(e)})
+    return sigs
+
+
+def extract_fonts_and_annots(pdf: pikepdf.Pdf) -> tuple[list[dict], list[dict], dict]:
+    fonts: dict[tuple, dict] = {}
+    annots: list[dict] = []
+    doc_flags = {
+        "has_javascript": False,
+        "has_embedded_files": False,
+        "has_open_action": False,
+    }
+    try:
+        names = pdf.Root.get("/Names")
+        if names is not None:
+            if names.get("/JavaScript") is not None:
+                doc_flags["has_javascript"] = True
+            if names.get("/EmbeddedFiles") is not None:
+                doc_flags["has_embedded_files"] = True
+        if pdf.Root.get("/OpenAction") is not None:
+            doc_flags["has_open_action"] = True
+    except Exception:  # noqa: BLE001, S110
+        pass
+
+    for pageno, page in enumerate(pdf.pages, 1):
+        try:
+            res = page.get("/Resources", {})
+            fdict = res.get("/Font", {}) if res is not None else {}
+            for _, fobj in fdict.items() if fdict is not None else []:
+                try:
+                    base = str(fobj.get("/BaseFont", "unknown")).lstrip("/")
+                    desc = fobj.get("/FontDescriptor")
+                    if desc is None and fobj.get("/DescendantFonts") is not None:
+                        desc = fobj.get("/DescendantFonts")[0].get("/FontDescriptor")
+                    embedded = bool(
+                        desc is not None
+                        and any(
+                            desc.get(k) is not None
+                            for k in ("/FontFile", "/FontFile2", "/FontFile3")
+                        )
+                    )
+                    m = re.match(r"^([A-Z]{6})\+(.+)$", base)
+                    key = (base, embedded)
+                    rec = fonts.setdefault(
+                        key,
+                        {
+                            "base_font": base,
+                            "family": m.group(2) if m else base,
+                            "subset_prefix": m.group(1) if m else None,
+                            "embedded": embedded,
+                            "subtype": str(fobj.get("/Subtype", "")).lstrip("/"),
+                            "pages": [],
+                        },
+                    )
+                    if pageno not in rec["pages"]:
+                        rec["pages"].append(pageno)
+                except Exception:  # noqa: BLE001, S112
+                    continue
+        except Exception:  # noqa: BLE001, S110
+            pass
+        try:
+            for a in page.get("/Annots", []) or []:
+                sub = str(a.get("/Subtype", "")).lstrip("/")
+                annots.append(
+                    {
+                        "page": pageno,
+                        "subtype": sub,
+                        "contents": str(a.get("/Contents", ""))[:200] or None,
+                        "rect": [float(x) for x in a.get("/Rect", [])] or None,
+                    }
+                )
+        except Exception:  # noqa: BLE001, S110
+            pass
+
+    font_list = sorted(fonts.values(), key=lambda f: f["base_font"])
+    # duplicate subset embeddings of the same family = edit trace (F5)
+    fam_prefixes: dict[str, set] = {}
+    for f in font_list:
+        if f["subset_prefix"]:
+            fam_prefixes.setdefault(f["family"], set()).add(f["subset_prefix"])
+    doc_flags["families_with_multiple_subsets"] = sorted(
+        fam for fam, p in fam_prefixes.items() if len(p) > 1
+    )
+    return font_list, annots, doc_flags
+
+
+def analyze_text(pdf_path: Path, pages_dir: Path) -> tuple[list[dict], list[dict]]:
+    """Per-page text + font map; returns (page_stats, font_anomalies)."""
+    pages_dir.mkdir(parents=True, exist_ok=True)
+    page_stats: list[dict] = []
+    anomalies: list[dict] = []
+    with pdfplumber.open(pdf_path) as pdf:
+        for i, page in enumerate(pdf.pages, 1):
+            text = page.extract_text() or ""
+            (pages_dir / f"page-{i}.txt").write_text(text, encoding="utf-8")
+            words = page.extract_words(extra_attrs=["fontname", "size"]) or []
+            with (pages_dir / f"page-{i}.fonts.tsv").open("w", encoding="utf-8") as fh:
+                fh.write("word\tfont\tsize\tx0\ttop\n")
+                for w in words:
+                    fh.write(
+                        f"{w['text']}\t{w.get('fontname')}\t"
+                        f"{round(float(w.get('size', 0)), 2)}\t"
+                        f"{round(w['x0'], 1)}\t{round(w['top'], 1)}\n"
+                    )
+            page_area = float(page.width) * float(page.height) or 1.0
+            img_area = sum(
+                max(0.0, (im["x1"] - im["x0"]) * (im["bottom"] - im["top"]))
+                for im in page.images
+            )
+            page_stats.append(
+                {
+                    "page": i,
+                    "char_count": len(text),
+                    "word_count": len(words),
+                    "image_count": len(page.images),
+                    "image_coverage": round(min(1.0, img_area / page_area), 3),
+                }
+            )
+            # group words into lines by 'top', find words whose font deviates
+            # from the line's modal font (F6 splice candidates)
+            lines: dict[int, list[dict]] = {}
+            for w in words:
+                lines.setdefault(round(w["top"] / 3.0), []).append(w)
+            for line_words in lines.values():
+                if len(line_words) < 3:
+                    continue
+                fnames = Counter(w.get("fontname") for w in line_words)
+                modal, modal_n = fnames.most_common(1)[0]
+                if len(fnames) == 1 or modal_n < max(3, len(line_words) - 2):
+                    continue
+                for w in line_words:
+                    if w.get("fontname") != modal:
+                        anomalies.append(
+                            {
+                                "page": i,
+                                "word": w["text"],
+                                "font": w.get("fontname"),
+                                "line_modal_font": modal,
+                                "size": round(float(w.get("size", 0)), 2),
+                                "x0": round(w["x0"], 1),
+                                "top": round(w["top"], 1),
+                                "line_text": " ".join(
+                                    x["text"]
+                                    for x in sorted(line_words, key=lambda x: x["x0"])
+                                )[:200],
+                            }
+                        )
+    return page_stats, anomalies
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("pdf", type=Path)
+    ap.add_argument(
+        "--out",
+        type=Path,
+        default=None,
+        help="output dir (default: ./doc-authenticity-out/<stem>)",
+    )
+    args = ap.parse_args()
+
+    if not args.pdf.is_file():
+        print(f"error: {args.pdf} not found", file=sys.stderr)
+        return 2
+    outdir = args.out or Path("doc-authenticity-out") / args.pdf.stem
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    data = args.pdf.read_bytes()
+    result: dict = {
+        "input": str(args.pdf.resolve()),
+        "media_type": "application/pdf",
+        "size_bytes": len(data),
+        "sha256": hashlib.sha256(data).hexdigest(),
+        "extension_magic_match": args.pdf.suffix.lower() == ".pdf",
+        "structure": scan_raw_structure(data),
+    }
+
+    repairs: list[str] = []
+    try:
+        import warnings
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            pdf = pikepdf.open(args.pdf)
+            repairs = [str(w.message) for w in caught]
+    except pikepdf.PasswordError:
+        result["error"] = "encrypted: password required"
+        (outdir / "forensics.json").write_text(json.dumps(result, indent=2))
+        print(json.dumps(result, indent=2))
+        return 1
+    except Exception as exc:  # noqa: BLE001
+        result["error"] = f"PDF parsing failed: {exc}"
+        (outdir / "forensics.json").write_text(json.dumps(result, indent=2))
+        print(json.dumps(result, indent=2))
+        return 1
+
+    with pdf:
+        result["pdf_version"] = str(pdf.pdf_version)
+        result["encrypted"] = pdf.is_encrypted
+        result["linearized"] = pdf.is_linearized
+        result["page_count"] = len(pdf.pages)
+        result["metadata"] = extract_metadata(pdf)
+        result["xmp"] = extract_xmp(pdf)
+        result["signatures"] = extract_signatures(pdf, result["structure"]["file_size"])
+        fonts, annots, doc_flags = extract_fonts_and_annots(pdf)
+        result["fonts"] = fonts
+        result["annotations"] = annots
+        result["structure"].update(doc_flags)
+        result["structure"]["repairs"] = repairs
+
+    try:
+        page_stats, anomalies = analyze_text(args.pdf, outdir / "pages")
+        result["pages"] = page_stats
+        result["text_font_anomalies"] = anomalies
+    except Exception as e:  # noqa: BLE001
+        result["pages_error"] = str(e)
+
+    out_path = outdir / "forensics.json"
+    out_path.write_text(json.dumps(result, indent=2), encoding="utf-8")
+    print(json.dumps(result, indent=2))
+    print(f"\n[written] {out_path}", file=sys.stderr)
+    print(f"[written] {outdir}/pages/page-N.txt + .fonts.tsv", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())