metacls 0.3.1

Bulk metadata scrubbing for PDF, Office and image files.
Strip the metadata, keep the document — with a before/after proof report.

_{Pairs with MetaScout: MetaScout finds the leaks, MetaCLS fixes them.}

_{🇬🇧 English · 🇹🇷 Türkçe}

What is this?

An organisation runs MetaScout against its own site and finds a pile of published PDFs and Office documents leaking author names, internal file paths, software/OS fingerprints and GPS coordinates. Now someone has to actually clean those files. That's MetaCLS.

Point it at a folder (or drag files into the web UI, or POST them to the API) and it:

1. scans every supported file for embedded metadata,
2. strips it — aggressively by default — writing cleaned copies (originals untouched) or overwriting in place,
3. verifies each cleaned file by re-scanning it, and
4. reports exactly what was removed, per file, as JSON and a styled HTML page you can hand to a security team as evidence.

It only touches metadata — the document's visible content (body text, images, a scanned signature) is never modified.

What it removes

--keep Title (repeatable) spares a named field from the otherwise-aggressive strip. --backup keeps <name>.orig next to an --in-place scrub.

Two opt-in flags go past metadata into identity data that's technically content: --strip-form-values blanks PDF form values — AcroForm fields (/V /DV) and their cached appearance, plus the <xfa:data> packet of an XFA form (the XFA template and schema are kept); --strip-office-authors blanks Office tracked-change / comment author names and dates (the change and comment text stays, so accept/reject still works).

Install

pip install metacls                     # core: PDF + Office scrubbing
pip install 'metacls[api]'              # + the REST API service
pip install 'metacls[media]'            # + audio tag scrubbing (mutagen)
pip install 'metacls[archive]'          # + .7z recursion (py7zr)
pip install 'metacls[msg]'              # + read-only .msg inspection (extract-msg)
pip install 'metacls[image-fallback]'   # + Pillow (weak image fallback if exiftool is absent)

Image scrubbing needs the exiftool binary on PATH:

brew install exiftool                        # macOS
sudo apt install libimage-exiftool-perl      # Debian / Ubuntu

PDF, Office (modern and legacy .doc/.xls/.ppt), ODF and SVG scrubbing are pure Python and need nothing extra. LibreOffice (soffice) is only used as a fallback for a legacy container the in-place patcher can't parse.

Python 3.10+ is supported. On a brand-new Python where pikepdf has no wheel yet, install under 3.12 instead.

CLI

Inspect — see what's in the files (read-only)

metacls inspect ./published-docs
metacls inspect leak.pdf report.docx --json

Run this on the files MetaScout flagged to see exactly what they carry before you scrub.

Clean

# default: originals untouched, cleaned copies written under ./metacls_cleaned/,
# mirroring the input tree, plus report.json + report.html
metacls clean ./published-docs

# overwrite the originals instead (asks first; -y to skip the prompt)
metacls clean ./published-docs --in-place

# preview only, change nothing
metacls clean ./published-docs --dry-run

# keep document titles, Turkish report
metacls clean ./published-docs --keep Title --report-lang tr

# just some files
metacls clean a.pdf b.docx c.jpg --out ./clean

Useful flags: --filetypes, --no-recursive, --out DIR, --keep FIELD, --dry-run, --no-verify, --no-keep-color-profile, --no-keep-orientation, --report-lang en|tr, --password (encrypted PDFs), --strip-pdf-id, --backup (keep <name>.orig with --in-place), --strip-form-values, --strip-office-authors (opt-in — see above), --jobs N (scrub N files in parallel), --quarantine DIR (overwrite the original but move it to DIR/<date>/ first — recoverable, safer than --in-place), --policy publish|internal|minimal (named presets), --exclude GLOB (repeatable — skip files/dirs when walking), --no-follow-symlinks (don't scrub a symlinked file), --progress (a progress bar), and the group-level metacls --debug … (re-raise on the first failing file instead of recording it).

metacls inspect takes --media and --recurse too, so you can point it at an archive or a video and see what's inside before scrubbing.

Project config: a .metacls.toml in the working directory or a parent (up to the git root) sets defaults per command — CLI flags and env vars still win.

[clean]
strip-office-authors = true
jobs = 4
keep = ["Title"]

Exit codes (so it works as a CI gate): 0 clean · 1 a file errored · 2 a cleaned file still carried metadata on the verify re-scan · 3 (--check only) metadata found.

Diff — track a directory over time

metacls clean ./published --out ./scan-jan     # once a month, into dated dirs
metacls clean ./published --out ./scan-feb
metacls diff ./scan-jan ./scan-feb             # what changed?

Shows files added/removed between the two runs and, the useful part, files where metadata reappeared (someone re-saved the document in an editor). Exit code 1 if anything regained metadata — drop it in a cron job.

Watch — keep a drop folder scrubbed

metacls watch /srv/ftp/incoming --move-processed /srv/ftp/scrubbed --interval 10 --settle 5
metacls watch ./inbox --once                       # one pass, for cron
metacls watch ./inbox --pattern 'invoice-*.pdf' -j 4   # filter + parallel backlog

A poll loop for an FTP/SFTP landing zone: a file is only touched once it has stopped changing for --settle seconds (a half-finished upload is never scrubbed), state lives in <dir>/.metacls-watch.json so a restart doesn't reprocess everything, and a file re-dropped with a newer timestamp is handled again. A .metacls-watch.lock file keeps a second watcher off the same directory (a lock left by a dead process is stolen). --pattern GLOB (repeatable) narrows what's picked up; -j/--jobs N scrubs a backlog in parallel; state entries for files that have since vanished are pruned each pass. Scrubs in place by default; --to DIR writes cleaned copies instead. A systemd template unit is in platform/linux/.

Web UI

metacls web           # opens http://127.0.0.1:8770/

Drag files onto the page, get them back scrubbed — individually or as a zip — with a per-file before/after view and the full report. Past runs are listed under History. Local, single-user, no authentication — don't expose it to a network.

REST API

For a Linux server, an FTP drop-box, or a CI pipeline that needs to hand files off to be cleaned:

pip install 'metacls[api]'
metacls api           # http://127.0.0.1:8000/  ·  interactive docs at /docs

# what can this server scrub, and which optional tools are installed?
curl -sS http://127.0.0.1:8000/v1/formats

# submit  (recurse: look inside .zip/.tar/.7z/.eml · media: also audio/video)
curl -sS -X POST http://127.0.0.1:8000/v1/clean \
  -F files=@leak.pdf -F files=@report.docx -F report_lang=en -F recurse=true
# -> {"job_id": "...", "links": {...}}

# poll
curl -sS http://127.0.0.1:8000/v1/clean/<job_id>

# pull the cleaned files + report as a zip
curl -sSL -o cleaned.zip http://127.0.0.1:8000/v1/clean/<job_id>/download

Jobs run in a bounded background thread pool; --max-workers / --max-pending size it. Uploads stream to disk with --max-upload-mb / --max-files caps. GET /v1/formats and GET /v1/health are open even when an API key is set.

Auth: metacls api --api-key KEY (or METACLS_API_KEY) requires that key on every /v1 route except /v1/health and /v1/formats — send it as X-API-Key: KEY or Authorization: Bearer KEY. Both api and web refuse to bind a non-loopback host (0.0.0.0, a LAN IP) with no auth unless you pass --insecure; the supported way to expose either is to bind 127.0.0.1 and put a reverse proxy in front — docs/reverse-proxy.md has ready nginx / Caddy configs.

metacls api --host 0.0.0.0 --api-key "$(openssl rand -hex 24)"
curl -H "X-API-Key: $KEY" -F files=@leak.pdf http://server:8000/v1/clean

Docker

Pull the published image (built for amd64 + arm64 on every release):

docker pull ghcr.io/gorkemguler/metacls:latest

# web UI
docker run --rm -p 127.0.0.1:8770:8770 -v "$(pwd)/metacls_cleaned:/data" \
  ghcr.io/gorkemguler/metacls:latest

# REST API
docker run --rm -p 127.0.0.1:8000:8000 -v "$(pwd)/metacls_cleaned:/data" \
  ghcr.io/gorkemguler/metacls:latest api --host 0.0.0.0 --port 8000 --output-dir /data

# one-off: scrub a mounted folder
docker run --rm -v "$(pwd)/docs:/work" ghcr.io/gorkemguler/metacls:latest \
  clean /work --out /work/cleaned

Or build locally: docker build -t metacls .. docker compose up --build runs the web UI; docker compose --profile api up metacls-api the API. Put a proxy in front before exposing either — see docs/reverse-proxy.md.

How thorough is it?

• PDF — a full QPDF rewrite, not an incremental update, so the removed /Info and XMP aren't left behind in an old xref section. Annotation authors/dates and embedded-file metadata go too; the annotation's visible text and the attached file itself stay. Signed PDFs are skipped, not broken — scrubbing would invalidate the signature; re-export an unsigned copy if you need it cleaned. Encrypted PDFs without --password are skipped; with it, the cleaned copy is written unencrypted (the result says so).
• Office / ODF — the metadata parts are deleted from the package (or, for ODF, emptied), not merely blanked, and the references to them are pruned so nothing dangles.
• Images — exiftool -all=, which is the reference tool for this.
• --verify (on by default) re-scans every cleaned file and lists anything still present in the report; the CLI exits 2 if so.
• Deterministic — scrubbing the same file twice with the same options gives byte-identical output (checked in CI), so a scrub is auditable. --strip-pdf-id is the deliberate exception.

Limitations

• Content is out of scope by design: text in the document body, a visible/scanned signature, text baked into an image — MetaCLS won't touch those. (MetaScout's --scan-content finds them; removing them is a manual edit.)
• Legacy .doc / .xls / .ppt are not scrubbed (convert first).
• Not a certified sanitisation tool. Verify anything high-stakes yourself — that's what metacls inspect on the output, or a second pass with MetaScout, is for.

Desktop integration

All in platform/, one install command each — everything scrubs in place:

• macOS — a drag-and-drop MetaCLS.app (built with osacompile, no Xcode), plus a Finder Quick Action.
• Windows — a WinForms drop window, a Send to menu entry, an Explorer right-click entry, and a winget manifest (template).
• Linux — a .desktop launcher / Open With handler (with a zenity picker), a Nautilus/Nemo/Caja script, and a systemd watch unit.

CI / hooks

metacls clean --check implies --dry-run and exits 3 if any file still carries metadata (0 if clean, 1 on error) — a gate for pre-commit and CI.

# .pre-commit-config.yaml
- repo: https://github.com/gorkemguler/MetaCLS
  rev: main
  hooks: [{ id: metacls }]

# .github/workflows/no-metadata.yml
- uses: gorkemguler/MetaCLS@main
  with:
    paths: docs/ public/
    mode: check        # or "fix" to scrub in place and commit

Roadmap

See ROADMAP.md for what's shipped, the known limitations, and the backlog (inotify watch, SFTP mode, --jobs, --quarantine, .metacls.toml, policy profiles, audio/video, PyPI, recursive-container scrubbing).

License

MIT — see LICENSE.