C2PA Inspect (`c2pa-inspect`)

Audits and inspects media assets (images, videos, audio, and documents) for Coalition for Content Provenance and Authenticity (C2PA) Content Credentials, cryptographic signatures, provenance assertions, AI generation metadata, and digital tampering.

Built on Google Credentio data models and C-ABI wrapper architecture.

---

When to Use This Skill

• Auditing one or many media assets for Content Credentials presence.
• Verifying cryptographic validity and detecting file modifications after signing.
• Detecting whether an asset was generated by AI or edited with AI tools via IPTC digitalSourceType.
• Inspecting machine learning training consent and data mining restrictions (c2pa.ai_generative_training, cawg.data_mining).
• Extracting claim generator details (e.g. Adobe Photoshop, Google Credentio, Truepic, Imagen).
• Batch auditing entire asset folders and generating structured JSON or summary tables for automated agent workflows.

---

Progressive Disclosure & Reference Architecture

• C2PA Architecture & Schema Guide: Read references/c2pa-spec-guide.md for JUMBF container embeddings, manifest store hierarchy, and C2PA v1 versus v2 schema differences.
• Badge States & Exit Codes: Read references/badge-states.md for detailed definitions of SIGNED, UNSIGNED, and INVALID badge states, validation status codes, and exit codes.
• AI Provenance & Training Consent: Read references/ai-provenance.md for IPTC digital source type mappings, training-mining permissions, and generative model attribution.
• Inspection Script: Run scripts/inspect_c2pa.py to audit assets.
• Native Library Fetcher: Run scripts/fetch_native_lib.sh to download prebuilt libcredentio_c binaries for Linux and macOS.
• Test Fixtures:
  • assets/sample_crjson_v1.json: C2PA v1 sample manifest fixture.
  • assets/sample_crjson_v2.json: C2PA v2 sample manifest fixture (claim.v2, categorized results).
  • assets/sample_ai_manifest.json: AI training-mining and generative model metadata fixture.

---

Procedural Workflows

1. Inspect a Single Asset

Run scripts/inspect_c2pa.py with a target file path:

python3 scripts/inspect_c2pa.py path/to/asset.jpg

When run against a single file, the script displays a comprehensive detail card:

• Media format and byte size
• Engine used (Google Credentio C-ABI or pure-Python container inspector)
• Status badge (SIGNED, UNSIGNED, or INVALID)
• Manifest label and title
• Claim generator name and version
• Signing certificate issuer, algorithm, and timestamp
• AI provenance details (digital source type, generative model name, prompt, training opt-outs)
• Validation status codes and explanations

2. Batch Audit Multiple Files

Pass multiple file paths or wildcards:

python3 scripts/inspect_c2pa.py image1.jpg video.mp4 graphic.png

Displays a tabular summary listing status, asset name, format, generator, and AI attribution, followed by aggregate percentages across the scanned batch.

3. Recursive Directory Scanning

Scan an entire directory tree using --dir (or -d) and --recursive (or -r):

python3 scripts/inspect_c2pa.py --dir ./assets --recursive

4. Output Structured JSON for Tool Calling

Append --json to produce machine-readable JSON:

python3 scripts/inspect_c2pa.py --dir ./assets --recursive --json

The output contains an aggregate summary object and an assets array with detailed manifest structures, assertions, and validation status entries.

5. Filter by Provenance Status

Use --filter to isolate specific assets:

• --filter signed: Reports only assets with valid Content Credentials.
• --filter unsigned: Identifies assets lacking provenance credentials.
• --filter invalid: Flags tampered or broken credentials.
• --filter ai-only: Filters for assets with AI generation, compositing, or training-mining declarations.

Example:

python3 scripts/inspect_c2pa.py --dir ./media --recursive --filter ai-only

---

Badge States and Exit Codes

Badge State	Exit Code	Description
SIGNED	0	Asset has valid, cryptographically verified C2PA Content Credentials.
UNSIGNED	1	Asset has no C2PA credentials (or unsigned items present under --filter signed).
INVALID	2	Asset has corrupted, tampered, or invalid credentials.
ERROR	3	File not found, unreadable, or invalid command arguments.

---

Engine Hierarchy

The inspector employs a resilient dual-engine architecture:

1. Native Google Credentio C-ABI Engine: When libcredentio_c.so (Linux) or libcredentio_c.dylib (macOS) is available, the script loads it via CFFI to run complete cryptographic validation of claims, X.509 certificate chains, RFC 3161 timestamps, and asset byte hashes.
2. Pure-Python Credentio Container Inspector: When the native library is not compiled or installed, the script performs pure-Python format sniffing and container box parsing (JPEG APP11 JUMBF, PNG caPt/caPI, MP4/MOV uuid/c2pa, WebP JUMB, .c2pa). It extracts manifest claims, generators, assertions, and AI flags with zero external compiled dependencies.