# Auditing Deidentification Runs

Produce a signed, reproducible, no-PHI audit trail for an OpenMed de-identification run...

- Repository: https://github.com/maziyarpanahi/openmed (5755 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add maziyarpanahi/openmed --skill auditing-deidentification-runs -g -a claude-code -y`
Codex: `npx skills add maziyarpanahi/openmed --skill auditing-deidentification-runs -g -a codex -y`
Cursor: `npx skills add maziyarpanahi/openmed --skill auditing-deidentification-runs -g -a cursor -y`
Gemini CLI: `npx skills add maziyarpanahi/openmed --skill auditing-deidentification-runs -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add maziyarpanahi/openmed`

## Description

Produce a signed, reproducible, no-PHI audit trail for an OpenMed de-identification run via deidentify(audit=True). Use when the user needs compliance evidence, a tamper-evident record of what was redacted and why, to verify nothing was changed, to retain proof for HIPAA/GDPR audits, or to review de-id decisions without exposing plaintext PHI. Covers the AuditReport / AuditSignature / AuditSpan / DetectorInfo fields, why audits store offsets+hashes+provenance+residual-risk and never plaintext, signing with .sign(key), and verifying with .verify(key). Pairs with OpenMed deidentifying-clinical-text and auditing-safe-harbor-checklist.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Auditing de-identification runs

`deidentify(..., audit=True)` returns an `AuditReport` instead of the rewritten
text: a deterministic, **PHI-free** record of every redaction decision, offsets, label, detector confidence and threshold, the action taken, content
hashes, model provenance, and projected residual risk. Sign it to make it
tamper-evident, retain it as compliance evidence, and verify it later without
ever touching the original text. Runs **on-device**.

## When to use this skill

Use it whenever a de-identification needs to be *defensible*: regulatory
retention, internal review, reproducibility checks, or proving to an auditor
that identifiers were detected and handled, all without storing or exposing the
PHI itself.

## Quick start

```python
import openmed

note = "Patient John Doe (MRN 1234567) seen 2024-03-02. SSN 123-45-6789."

# Returns an AuditReport, NOT a DeidentificationResult, when audit=True.
report = openmed.deidentify(note, policy="hipaa_safe_harbor", audit=True)

# Make it tamper-evident with a release HMAC key (keep the key in a vault).
report.sign(b"my-release-hmac-key", key_id="release-2026")

# Persist the no-PHI report (no plaintext identifiers inside).
import json
with open("deid_audit.json", "w") as fh:
    json.dump(report.to_dict(), fh, indent=2)

# Later: verify integrity. Optionally bind to the exact texts via their hashes.
ok = report.verify(b"my-release-hmac-key", original_text=note)
assert ok
```

## What an AuditReport contains

`AuditReport` (from `openmed.core.audit`) carries no plaintext PHI. Key fields:

The rest: https://github.com/maziyarpanahi/openmed/blob/HEAD/skills/auditing-deidentification-runs/SKILL.md