Repository navigation
Releases
Releases · matinfo-tech/pii-airlock
v0.8.2
v0.8.0
Added
- Project home
.pii-airlock/, created bypii-airlock init:config.yaml(the project
policy, committed),.gitignore,maps/(encrypted mappings, local) andoff(paused).
Like.codegraph/, it is also the switch: the hooks only act at or below a project home. pii-airlock initnow does the whole setup in one step: project home, user-level hooks for
Claude Code and Copilot (skipped when the plugin is enabled), detection models. The gateway
is optional and only hinted at.pii-airlock on/offpause a project on this machine (policy and maps are kept);
pii-airlock statusshows state, hooks, daemon, policy and maps in one screen.SessionStarthook: Claude is told the project's PII rules in guarded projects.scrubkeeps its mapping in.pii-airlock/maps/(outside a project:
~/.local/state/pii-airlock/maps/), encrypted;restorefinds it without--map.
Changed
- Breaking: hooks are silent outside guarded projects; set
activation: alwaysin
~/.config/pii-airlock/config.yamlfor the old everywhere behaviour. - Breaking: the policy moved to
.pii-airlock/config.yaml..pii-airlock.yamland the
yaml pii-airlockblock in.claude/skills/pii-airlock/SKILL.mdare no longer read; user
rules go in~/.config/pii-airlock/config.yaml(--scope user). - Breaking:
pii-airlock policy init/policy showare gone: useinit/status. - The plugin launcher only blocks for a missing CLI inside guarded projects.
v0.7.0
[0.7.0] - 2026-11-01
Added
- The hook daemon now runs on Windows too, so hooks take ~60 ms there instead of 0.5-3 s per call.
It uses loopback TCP with a secret token (a file only the user can read); the client checks
the daemon's proof of the token before sending any text, so a process on a stale port never
sees a request. Unix sockets stay the transport elsewhere.pii-airlock daemon statusshows
which one is in use.
v0.6.0
[0.6.0] - 2026-10-31
Added
- GitHub Copilot:
pii-airlock install-hook --target copilotwrites apreToolUsehook file
for the Copilot CLI and cloud agent. The hook understands Copilot's payload (camelCase,
toolArgsas JSON text), scans every tool argument and answers in Copilot's format.
AGENTS.md documents VS Code custom-endpoint models through the gateway and what stays
uncovered (default models, inline suggestions, prompts in the CLI). - The
PreToolUsereply now also carries top-levelpermissionDecisionfields, which Copilot
reads (Claude Code ignores them); the hook also scans every argument of MCP and lower-case
(Copilot) tools, and acceptstool_inputgiven as a JSON string.
v0.5.0
[0.5.0] - 2026-10-31
Added
- Claude Code plugin:
/plugin marketplace add matinfo/pii-airlock, then
/plugin install pii-airlock@pii-airlock. Registers the hooks, adds a/pii-airlock:setup
skill, and fails closed (blocks) when the CLI is not installed. A test keeps the plugin's
hooks and version in step withinstall-hookandpyproject.toml. pii-airlock scrub --encrypt-mapwrites the mapping file encrypted (same scheme as the
gateway's file store);restore --mapdetects and opens it with the machine's key.- German and Italian identifiers:
DE_TAX_ID(Steuer-IdNr., checksum + keyword),DE_TAX_NUMBER,
andIT_VAT_CODE(ITprefix orP.IVAkeyword, Luhn). National phone formats for
Germany and Italy (030 12345678,0170 1234567,06 12345678,333 1234567).
Fixed
- Presidio's
IT_VAT_CODEfired on any 11-digit run, such as a German phone number: replaced
by the stricter built-in rule. Phone numbers inside another identifier (IBAN, card, tax ID)
are no longer reported separately.
v0.4.0
[0.4.0] - 2026-10-31
Security
- Project config is no longer blindly trusted. A cloned repo's
.pii-airlock.yaml/
SKILL.mdcould shiphook_on_error: open,entity_actions: {PERSON: allow},
passthrough_pathsormapping_dirand switch protections off. Until you trust the
project (pii-airlock trust; your ownallow/deny/actionedits keep a trusted
project trusted, agit pullthat changes the files does not) only settings that
tighten apply: deny-list terms, custom patterns,block/redactactions,deny/
block/closeddecisions.policy showlists what is ignored. - DOCX: footnotes, endnotes and comments that python-docx keeps as raw bytes are scrubbed
too, plus comment and tracked-change authors, field codes and hyperlink targets. - Propagation no longer blanks common words: a value found alone ("Will", "Server")
matches its exact spelling only; name parts still match in any case. - Header-profiled CSV columns now obey
entity_actions(block / redact / allow); they used
to be tokenized and stored in the mapping regardless. Redacted persons no longer reach
surrogate fakes (and so the saved mapping). - Gateway and
scrub(CSV/JSON/DOCX): a value detected in one message (or cell) is now
scrubbed in every other one, earlier ones included. Before, "Jean Dupont" found
only in the last message left a bare "dupont" in an earlier message in clear. - Gateway: OpenAI Responses API (Codex CLI) requests were forwarded with PII in
clear;input,instructions, function-call arguments and outputs are now scrubbed,
andoutput[]/response.*.deltaevents restored. - Gateway: tool traffic is scrubbed for all providers — Anthropic
tool_use/
tool_result/ textdocument, OpenAItool_callsandtoolmessages, Gemini
functionCall/functionResponse. Tool-call arguments are restored (JSON-escaped). - Gateway now fails closed: bodies sent to endpoints it cannot scrub (file uploads,
audio, …) are refused with 403, and non-JSON bodies on scrubbed endpoints with 400.
Newpassthrough_pathsconfig opts specific paths out. - Gateway also scrubs embeddings, moderations, Anthropic
count_tokens/ message
batches, and GeminicountTokens/embedContent. - Detection now runs for every configured language and merges results; pattern
recognizers (email, phone, IBAN, credit card, …) are registered for every language,
so a non-English first language no longer disables them. - Hooks:
Readnow scans the file content, not just its path;Grep,WebFetch,
WebSearch,NotebookEditand MCP tools are checked too. - Hooks: prompts with PII are blocked by default (
prompt_decision: block) and the
user is shown a scrubbed version. Previously the prompt was sent with only a note to
the model. - Hooks fail closed when detection can't run (
hook_on_error: closed), instead of
silently letting the input through.
Added
- Per-entity policy
entity_actions: {ENTITY: tokenize|redact|allow|block}and
pii-airlock action ENTITY ACTION [--scope user]:redactwrites an irreversible
[ENTITY]that never enters a mapping;allowignores the type;blockrefuses
the request (gateway 403,scrubexit 1 with nothing written, hooks deny and block
prompts regardless ofhook_decision/prompt_decision) without echoing the value.
Accumulates across user and project policy;exclude_entitiesis now shorthand
forallow. ner_backend: gliner: one multilingual GLiNER model (gliner_model, default
urchade/gliner_multi_pii-v1) instead of a spaCy model per language; extra
pii-airlock[gliner], model fetched bydownload-models, shown indoctor. Long
texts scanned in overlapping windows; patterns keep emails/phones/IDs. On the eval
corpus: PERSON precision 0.95 (spaCy sm 0.68), overall 0.98 (0.67), recall 1.00.- Eval harness:
--backend gliner. - Surrogate mode (
token_style: surrogate): realistic, stable fakes instead of tokens
(Jasper Iverson,jasper.iverson@example.com, same-shape phones, Luhn-valid cards,
checksum-valid IBANs, RFC 5737 IPs), restored in responses, streams (fakes split
across chunks) and tool-call arguments. Name parts and email local parts share the
full name's fakes. Fakes never collide with the input or each other; other
entities keep tokens. Mapping files (v2) store the fakes. - Stable tokens (default):
<PERSON_558644>is an HMAC of the value with a local key
(~/.local/state/pii-airlock/token.key, owner-only), so a value keeps one token
across requests, files, processes, trimmed histories and subagents, and prompt
caches keep hitting.token_rotation: day|week|never(defaultday: unlinkable
across days).token_style: sequentialrestores<PERSON_1>numbering. - Hook daemon: hooks no longer load the spaCy models on every tool call (0.5-3 s).
The first call starts a background daemon (Unix socket, user-only, idle exit after
hook_daemon_idle_minutes); later calls take ~60 ms. Project policy is reloaded per
call, a daemon running older code steps aside, failures still fail closed.
pii-airlock daemon start|stop|status|run, shown indoctor.hook_daemon: off
disables it (no daemon on Windows). hook_fallback: regex: when no daemon answers, hooks can use patterns only
(emails, phones, IBAN, cards, IPs, IDs, secrets, deny list) instead of loading
models; names and places are not detected in that mode.- Analysis cache: model findings are remembered per text (by digest, no copy of the
text kept), so the conversation history chat clients resend on every turn is not
analyzed again (~8x faster on a 20-turn chat).analysis_cache_size, 0 disables. - Batched analysis: the gateway,
scrubon CSV/JSON/DOCX and hook file scans run
all their strings through spaCy as one batch (about 2x faster than one by one). - Detection eval harness (
tests/eval): labeled EN+FR corpus of fake PII, per-entity
recall / precision / leak-free report (python -m tests.eval.run_eval -v) and a CI job
that fails belowthresholds.json. - Built-in recognizers (regex + checksum, every language): French NIR, Swiss AHV/AVS,
SIRET/SIREN, FR/CH national phone formats, and secrets (cloud/API keys, JWTs,
private keys, URL and assignment passwords).builtin_recognizers: falsedisables. - Per-project policy in
.claude/skills/pii-airlock/SKILL.md(a Claude Code skill plus
ayaml pii-airlockconfig block); user-level skill for personal rules. - Policy keys
allow_list,deny_list,custom_patterns, accumulated across layers. - Commands
pii-airlock policy init|show,pii-airlock allow,pii-airlock deny.
Hook messages show the one-command fix for a false positive. - Mapping files are encrypted at rest (AES-256-GCM, key derived from
token.key) with the
file mapping backend.mapping_encryption: falseopts out; existing plain files still load.
New dependency:cryptography.
Changed
- Tokens default to the stable format (
<PERSON_558644>instead of<PERSON_1>);
settoken_style: sequentialfor the old numbering. - Other mentions of a detected value are scrubbed too, including parts of person
names ("Dupont" after "Jean Dupont"), and values found earlier in the same
request or file. NER often finds a name once and misses the rest. - CSV: columns whose header marks personal data (
Nom,Prénom,email,
Téléphone,IBAN,date of birth, …, EN/FR/DE) are tokenized cell by cell,
even when NER can't recognize a lone value; the header row is kept. - Tokens are numbered in reading order (
<PERSON_1>is the first person mentioned). - Noisy entity types are skipped by default (
exclude_entities:DATE_TIME,URL,
NRP,US_DRIVER_LICENSE,US_BANK_NUMBER,US_PASSPORT,
IN_VEHICLE_REGISTRATION): every web fetch, date or long number in a command used
to trigger a hook prompt. List one inentities(or setexclude_entities: [])
to keep it. Newscore_thresholdssets a minimum score per entity type. - A weekly CI job (
eval-gliner.yml, also manual) runs the eval with the GLiNER backend
againsttests/eval/thresholds-gliner.json, without the torch install on every push. - The eval corpus covers German and Italian too (
de_core_news_sm,it_core_news_sm).
Fixed
- Hooks apply the policy of the project Claude Code reports (event
cwd), not the
hook process's directory; a malformed policy block fails closed instead of crashing
the hook. - Streaming restore keeps one buffer per choice / content block / tool call, and
releases held-back text before the block or choice ends — no more synthetic chunk
aftermessage_stop/[DONE]and no missingevent:line (Anthropic SDK errors). install-hookupgrades the tool matcher of an existing pii-airlock entry.- International phone numbers (
+49 30 ...,+39 02 ...) leaked in German and Italian
text: Presidio scores a bare number 0.4 and only boosts it on English context words.
A built-in rule now catches any+CCnumber. - Digit groups inside an IBAN or card number are no longer also reported as a phone number.
v0.2.3
v0.2.2
v0.2.1
v0.2.0 — local PII gateway for AI agents
pii-airlock keeps real personal data out of your AI tools — detection and substitution run entirely on your machine.
Install
pipx install pii-airlock
pii-airlock download-modelsThree ways to use it
- Gateway — point any OpenAI / Anthropic / Gemini client at the local proxy; PII is scrubbed out of requests and restored in responses (incl. streaming).
pii-airlock proxy - CLI pipe —
pii-airlock scrub→ LLM →pii-airlock restore(reversible, deterministic tokens) - Claude Code hooks — guardrails on prompts and tool data
Highlights
- Provider-agnostic core; one small adapter per provider
- Reversible, deterministic
<TYPE_N>tokens; mapping never leaves your machine - No-leak-on-failure: a scrub error blocks the request rather than forwarding PII
- Runs on macOS, Linux, Windows (Python 3.10–3.14), verified in CI
See AGENTS.md for per-agent setup and CHANGELOG.md for full details.