RAGbase Shield

RAGbase Shield

Use Claude, ChatGPT and Copilot on your case files, masking your clients' names before sending.

RAGbase Shield 0.4.0 is a free, open-source tool (Apache-2.0). On your own computer, it replaces client names and numbers with codes before the text goes to the AI. When the AI answers, Shield puts the real names back, also on your computer.

This is local, reversible pseudonymisation. It is not anonymisation: facts, dates and amounts stay readable by the AI. Nothing goes to RAGbase. Shield sends no usage statistics.

Version française (la version de référence pour les cabinets français) : README.fr.md

Contents:

• For lawyers: the essentials
• Install
• Daily use
• Results: public head-to-head of 11 November 2026
• Limits (please read)
• Privacy model in 5 lines
• For developers and IT
• Links
• Going further

For lawyers: the essentials

What Shield does

You write or open this text (invented example):

M. Thibault Mercadier, domicilié 12 rue des Glycines, 69007 Lyon, conteste sonlicenciement par la société Ateliers Brunelac SAS, notifié le 3 mars 2025.Il réclame 48 000 € devant le conseil de prud'hommes de Lyon (RG n° 25/01234).Contact : [email protected]

The AI receives this text:

M. PERSONNE_A, domicilié ADRESSE_1, conteste sonlicenciement par la société SOCIETE_A SAS, notifié le 3 mars 2025.Il réclame 48 000 € devant le conseil de prud'hommes de Lyon (RG n° RG_1).Contact : EMAIL_1

This is the real output of the 0.4.0 engine (rules mode, the default) on this example. A test checks it. Note what stays readable: the date, the amount, the court. The AI needs them to do the work. The detection rules are built for French legal documents first, with English support. With RAGBASE_SHIELD_LOCALE=en, codes use English labels (PERSON_A, COMPANY_A, ADDRESS_1).

Inside one dossier, a person always keeps the same code. "M. Mercadier", "Thibault Mercadier" and "MERCADIER Thibault" all become PERSONNE_A.

Three rules to remember

1. Connect a folder. Do not attach the file to the chat. A file attached to a chat reaches the AI provider before Shield can act. Add the case folder to Shield. The AI then reads the documents through Shield, masked.
2. Do not paste raw text into the chat box. Go through Shield first (the "Masquer" page in Shield Desk, or the browser extension). To talk about a person in the chat, write their code (PERSONNE_A), not their name.
3. Text already sent cannot be recalled. Shield protects only what goes through it. If a name was sent by mistake, Shield cannot undo it.

What reaches the AI provider, what stays with you

Details: docs/PRIVACY_MODEL.md.

Codes

Shield does not mask courts, institutions (Cour de cassation, CNIL, URSSAF...), laws, codes, articles, months and days.

Install

Downloads (installers, Claude Desktop extension, SHA256SUMS): the releases page, https://github.com/ragbase/ragbase-shield/releases/latest. Python package: ragbase-shield on PyPI.

With uv (one command). uv is the open-source tool that downloads and runs Shield.

On a Mac: open the Terminal app, paste this line, press Enter.

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows: open PowerShell, paste this line, press Enter.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close the window and open a new one. Then start Shield Desk:

uvx ragbase-shield desk

Your browser opens http://127.0.0.1:7878 with a private link that holds a secret token. This is a local page: it works only on your computer. To open it again, run the command again or use the link shown in the Terminal. The address alone, without the token, shows "Token refused". Keep the Terminal window open: closing it stops Shield Desk and the browser extension.

With pip: pip install ragbase-shield, then ragbase-shield desk. The optional name recognition model: pip install "ragbase-shield[ner]" (see docs/NER.md).

On a Mac, the first use may ask for keychain access for the Shield key: click "Always Allow".

Daily use

With Claude Desktop, Claude Code, ChatGPT desktop or Copilot in VS Code

1. In Shield Desk, on the Dossiers page, under "Ajouter un dossier" (Add a folder), type the full path of the client's case folder, then click "Ajouter et analyser" (Add and scan). Shield gives it a code (DOSSIER_1) and reads the documents. The Desk has an EN toggle for English labels (tabs: Matters, Mask, Restore, Files, Log). To copy a folder path: on a Mac, in the Finder, hold Option and right-click the folder, then "Copy ... as Pathname"; on Windows, Shift + right-click, then "Copy as path".
2. Click "Voir les entités" (Show entities) to see the detected names. Add the missing ones with "Add a name or a term", above the list: the client, the parties, a project name. Turn on the "Keep in clear" switch for a name that must stay readable.
3. In the AI app, ask for example: "List my Shield dossiers. Read the documents of DOSSIER_1 and draft submissions. Save the draft with Shield."
4. The AI sees only codes. It saves the draft with the Shield tool.
5. Shield writes the document, with the real names, into the "Shield - sorties" subfolder of the case folder. Open it on your computer and review it.

The AI cannot ask Shield for the real names. Only your computer puts them back.

With any app (Word, Outlook, Copilot, claude.ai, chatgpt.com)

1. Open Shield Desk with the link that uvx ragbase-shield desk shows, page Masquer (Mask). Choose the dossier. Without a dossier, registered names become [PERSONNE] or [SOCIETE] and restore is not possible.
2. Paste your text into the original-text box (not into the chat), then click "Masquer" (Mask).
3. Check the detected items, then click "Copier le texte masqué" (Copy masked text).
4. Paste the masked text into the AI app.
5. Copy the AI's answer. In Shield Desk, page Restaurer (Restore), paste it and click "Restaurer les noms" (Restore names). Shield also lists codes it does not know in this dossier (for example a code the AI invented). Copy the restored text into your document. Never paste it back into the chat: it contains the real names.

From a terminal, the same in two commands: ragbase-shield mask --dossier DOSSIER_1 --clipboard replaces the clipboard with the masked text. ragbase-shield restore --dossier DOSSIER_1 --clipboard puts the real names back into the clipboard.

Results: public head-to-head of 11 November 2026

Full file, with every set, mode, status, method and limit: evaluation/laptop/RESULTS_PUBLIC.md (French first, then English). Protocol fixed in advance: PROTOCOL.md and its addenda in the same folder.

Read this before the numbers:

• Shield 0.4.0 was built after the first results of this comparison were known. No data set is held-out for Shield 0.4.0. Hexagone 0.3.9 and Presidio 2.2.364 were measured in October 2026 and were not run again. So the comparison is Shield of November against the other tools of October.
• Shield is our product (RAGbase). We ran this test.
• Status of each set for Shield 0.4.0: REF (not held-out: written by the Shield team, 0.3.1 results known), FR-PII-Bench and MAPA (gates), Max (gate, with a fix from this study), Judilibre (not held-out for 0.4.0), English (development set).
• Machine: a Windows VM (6 cores, 16 GB, no graphics card). It is not a laptop.
• "Shield 0.4.0 rules" is the product default. "Shield 0.4.0 GLiNER" means rules plus the GLiNER model on the CPU.
• Tonic: measured internally, not published (Tonic's terms).

Result by the rule fixed in advance (protocol section 11.3; addendum 4, section 20.9). For Shield 0.4.0 the only wording allowed is "the conditions of section 11.3 are met" or "are not met".

Reason, the same for every line: on REF (not held-out), Hexagone Fast and Hexagone Precis leave less personal data readable than Shield 0.4.0, with a clear difference. Clear differences in the same direction on MAPA (gate) and English (development) for Hexagone Fast and Precis, and on FR-PII-Bench (gate) for Hexagone Precis. Detail: Table 14. Tonic: measured internally, not published (Tonic's terms). Speed is not part of this rule.

Key numbers (lower is better; VM, not a laptop). The "Status" column gives the status of REF and Judilibre for each line.

What this means, in short (the claims of Table 13, in both directions):

• The trade-off. On REF (not held-out), Shield 0.4.0 leaves more personal data readable than Hexagone, and it changes far fewer legal terms (courts, laws, codes, articles).
• Personal data readable (P1), where Hexagone leaves less. Hexagone Fast and Hexagone Precis: on REF (not held-out), MAPA (gate) and English (development). Hexagone Precis also on FR-PII-Bench (gate).
• Personal data readable (P1), where Shield 0.4.0 leaves less. Against Hexagone Fast on FR-PII-Bench (gate). Against Presidio on REF, FR-PII-Bench, Max and Judilibre. On English, Presidio leaves less than Shield 0.4.0 rules, and Shield 0.4.0 GLiNER leaves less than Presidio.
• No clear difference (P1). With Hexagone Fast and Hexagone Precis on Max (gate, with a fix from this study) and on Judilibre (not held-out for 0.4.0). With Presidio on MAPA.
• Legal terms changed (P2). Both Shield 0.4.0 rows change fewer legal terms than Hexagone Fast and Precis on every set that has them. Against Presidio: fewer on REF, MAPA and Max for both rows, and on Judilibre for the rules row; no clear difference on Judilibre for the GLiNER row.
• Shield 0.4.0 against 0.3.1. In rules mode the output text is identical on REF, FR-PII-Bench, MAPA and Judilibre. In GLiNER mode, on English (development), Shield 0.4.0 leaves more organisation names readable than 0.3.1: a clear difference against 0.4.0.
• Speed. We do not say that 0.4.0 is faster than 0.3.1: the two sessions are 16 days apart on the same VM.

Limits (please read)

• No OCR. A scanned PDF (an image) has no text. Shield says so and does not read it.
• Detection is never complete. A name nobody registered can slip through: a rare name, a foreign name, a nickname, a typo. Register the parties of each dossier. Those are the names Shield masks most reliably.
• In the public head-to-head, Hexagone leaves less personal data readable on some sets (REF, MAPA and English; Hexagone Precis also on FR-PII-Bench). Shield changes fewer legal terms. Read the results above with their status: no set is held-out for Shield 0.4.0.
• Restored names use the spelling stored in the dossier. "M. Mercadier" can come back as "M. Thibault Mercadier", and capital letters can change. Identifiers come back in the first spelling seen in the dossier (for example "832 456 719" for "832456719"). Re-read the restored document.
• Facts can still identify a client, even without a name: a well-known case, a unique job title, a precise place, an amount. Shield does not mask facts. Review, and generalise when needed.
• ChatGPT web (chatgpt.com) has no native connection. Use Shield Desk or the browser extension.
• Microsoft 365 Copilot (Word, Outlook, Teams, the Copilot app): through Shield Desk only. Warning: Copilot in Word or Outlook reads the open document or email. Open a masked copy, not the original.
• The browser extension masks text you paste or drop. Text you type goes out as typed. A file pasted or dropped into the chat is blocked; "Attach anyway" sends it unmasked. It is not in the Chrome or Edge stores yet.
• The installers are not signed yet. macOS and Windows show a warning the first time.
• An administrator can block Shield: extensions in Claude Team or Enterprise, MCP servers in Copilot Business or Enterprise.
• The GDPR still applies. For you, pseudonymised data are still personal data.

French compliance sheet (CNB, Paris bar, avocats aux Conseils, GDPR): docs/CONFORMITE.fr.md FAQ: docs/FAQ.md

Privacy model in 5 lines

1. Masking and restoring run on your computer. The AI provider receives codes, never the real names that Shield detected or that you registered.
2. The code-to-name table (the vault) is encrypted, one per dossier; its key stays in the OS keychain (or a file only you can read).
3. No tool gives real names to the model, and an AI agent cannot change what is masked.
4. No network call in the library, no telemetry, no update check. The only download you start yourself is the optional name recognition model.
5. Pseudonymised data are still personal data: Shield reduces what the provider sees. It is pseudonymisation, not anonymisation.

Full model: docs/PRIVACY_MODEL.md.

For developers and IT

Architecture in short

• A local engine (rules, dictionaries, check digits) finds names and identifiers, in French and in English (the language is detected per text, or pinned with RAGBASE_SHIELD_LANGUAGE). A name recognition model (NER) is optional; none is installed by default. To add one (about 1.2 GB, Apache-2.0, runs offline, CPU only):

  pip install "ragbase-shield[ner]"      # or: uv pip install "ragbase-shield[ner]"ragbase-shield ner download            # fastino/gliner2-privacy-filter-PII-multi, once, into ~/.ragbase-shield/modelsragbase-shield ner status              # or: ragbase-shield doctor

  The model's finds pass the same whitelist and precision guards as the rules; the hooks and the canary never use it. RAGBASE_SHIELD_NER=off turns it off.

• Replacement by codes (PERSONNE_A) by default, or by realistic pseudonyms (ragbase-shield set DOSSIER_n --replacement synthetic): reversible through the vault, pseudonymisation, not anonymisation.

• One encrypted vault per dossier (SQLite + Fernet). The key lives in the OS keychain, or in a file only you can read (mode 0600).

• A local MCP server (stdio) for Claude, ChatGPT desktop, Codex and VS Code. Its tools take dossier and document codes, never raw text. No tool gives real names to the model.

• Shield Desk: a local web page on 127.0.0.1, with a per-install token.

• Claude Code hooks block a prompt that contains a registered name, and direct reads of a dossier folder.

• No network calls in library code. No telemetry.

Full contract: ARCHITECTURE.md. Privacy model: docs/PRIVACY_MODEL.md.

Command line

ragbase-shield add <folder> [--title TEXT]           # register a dossier folder, prints DOSSIER_n, scans itragbase-shield list                                  # dossiers (real titles: local terminal)ragbase-shield entities <DOSSIER_n>                  # detected and registered entitiesragbase-shield register <DOSSIER_n> --person NAME | --org NAME | --kind KIND VALUEragbase-shield keep-clear <DOSSIER_n> <CODE> [--off]ragbase-shield mask [--dossier D] [--clipboard] [--mode codes|synthetic] [FILE|-]   # prints masked text, or replaces the clipboardragbase-shield set <DOSSIER_n> --replacement codes|synthetic [--language auto|fr|en]  # per-dossier settings (v0.2)ragbase-shield ner status | download [--model fastino|urchade|all] [--dir DIR] [--dry-run] [--force]  # optional NER model (v0.2)ragbase-shield restore --dossier D [--clipboard] [FILE|-]     # prints restored text, or replaces the clipboardragbase-shield desk [--port 7878] [--no-browser]ragbase-shield mcp                                   # stdio MCP server (used by every app integration)ragbase-shield hook <user-prompt-submit|pre-tool-use|post-tool-use>   # Claude Code hooks, JSON stdin/stdoutragbase-shield install <claude-desktop|claude-code|chatgpt|codex|vscode> [--dry-run]ragbase-shield doctor                                # checks install, key storage, each app integrationragbase-shield verify                                # plants synthetic data, runs every path, prints CLEAN or LEAKragbase-shield export <DOSSIER_n> <FILE> / import <FILE>      # encrypted vault handoff (passphrase prompt)ragbase-shield journal [DOSSIER_n]

With uv, prefix with uvx (uvx ragbase-shield doctor), or install the command once: uv tool install ragbase-shield. From a copy of the repository: uv tool install . (or uv tool install --editable . to develop). The configs written by install then work, and doctor checks that each app can start Shield.

From an AI agent's terminal (Claude Code, Codex), entities, restore and export refuse to run, because what they print reaches the model. add, register, keep-clear and import refuse too: an AI assistant cannot change what is masked. list shows codes only. Run these commands in your own terminal, or use Shield Desk.

Supported apps

Check it yourself

• ragbase-shield doctor checks the install, key storage and each app integration.
• ragbase-shield verify plants invented data, runs every path (MCP tools, hooks, Desk) and prints CLEAN or LEAK.
• Tests: uv run --extra dev pytest -q. Synthetic data only.
• Bench: uv run python bench/run_bench.py (recall and precision per kind, on an invented French legal corpus written together with the rules; it is a regression gate, not an accuracy figure for real files).
• Benchmark runners: evaluation/public/ (public benchmarks; data downloaded into the git-ignored .bench_data/), evaluation/holdout-en/ (an invented English corpus), evaluation/laptop/ (the frozen scorer and runners of the public head-to-head).
• Desktop installers: packaging/README.md.

Environment variables

Contributing, security, licence

• Security issues: SECURITY.md. Do not open a public issue.
• Release history: CHANGELOG.md.
• Licence: Apache-2.0. Attributions: NOTICE.
• Test data: invented only. Never put real client data in an issue.

Links

• Source code: https://github.com/ragbase/ragbase-shield
• Releases (installers, .mcpb, SHA256SUMS): https://github.com/ragbase/ragbase-shield/releases/latest
• Issues: https://github.com/ragbase/ragbase-shield/issues
• Product page: https://shield.ragbase.ai
• Install guide per app: docs/INSTALL.md. FAQ: docs/FAQ.md.
• Public results: evaluation/laptop/RESULTS_PUBLIC.md

Going further

Shield reduces what the AI sees. It does not replace an AI that runs on your own machines. If your firm wants a private AI installed on its own hardware, RAGbase offers one: https://ragbase.ai