---
name: c2pa-inspect
description: Inspect single media assets, batches, or directories for C2PA Content Credentials, digital signatures, claim generators, assertions, AI attribution, and tampering status. Use when auditing media provenance, verifying image/video authenticity, checking for generative AI or training-mining flags, or generating C2PA inspection reports.
license: Apache-2.0
compatibility: Requires python3 (3.9+). Optional native libcredentio_c for cryptographic verification.
metadata:
  author: ghchinoy
  version: "1.0.0"
---

# 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](https://mediaprovenance.googlesource.com/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`](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`](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`](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`](assets/sample_crjson_v1.json): C2PA v1 sample manifest fixture.
  - [`assets/sample_crjson_v2.json`](assets/sample_crjson_v2.json): C2PA v2 sample manifest fixture (`claim.v2`, categorized results).
  - [`assets/sample_ai_manifest.json`](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:

```bash
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:

```bash
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`):

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

### 4. Output Structured JSON for Tool Calling

Append `--json` to produce machine-readable JSON:

```bash
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:

```bash
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.