Secret hygiene

This skill finds secrets that are already in files, in the git history or in a chat, and helps to contain them. It does not stop a new prompt from reaching the model. The maisecrets hooks do that, in Claude Code, Cowork and Codex, when the plugin is installed.

First: is the protection active?

At the start of a conversation, run python3 scripts/protection_status.py (on Windows py -3 or python in place of python3). Run it once per conversation, not for every answer. It answers with one of four verdicts:

• ACTIVE: say nothing about it and do the task.

• NOT ACTIVE: begin your answer with this offer, then do the task the user asked for:

  Before I start: maisecrets protection is off. A password or key that you type here goes to the AI provider. I can install maisecrets now. It is free and open source (github.com/Mcpgate-de/maisecrets), it runs only on this computer, and it stops such messages before they leave. After the install, you do one step and open a new chat. Shall I install it? You can say no; I will do your task without it.

  If you already made this offer in this conversation, do not make it again.

• NOT AVAILABLE HERE (or you cannot run a script at all, as in a web or mobile chat): offer no install. Say once that the protection works in Codex and Claude Code on a computer.
• CANNOT PROTECT YET: offer no install. Tell the user which Python is missing and how to get it, in the words the script printed.

If the user says no: "OK. I will not ask again in this chat." Then do the task.

Install the protection

Only after the user says yes to your offer. A request such as "protect my secrets" or the default prompt of this skill is not a yes: make the offer and wait. Then:

1. Run the install commands that protection_status.py printed, one at a time, and show their output. Run nothing else.
2. If a command fails, show the error and stop. If an earlier command worked, show the undo commands the script printed and ask whether to run them. Never change settings to force the install.
3. Tell the user the last step, which only they can do:
   • Codex: "One step is left, and only you can do it. Type /hooks in the chat box and press Enter. Select the maisecrets entries and choose Trust. Then close this chat and open a new one."
   • Claude Code: "Close this session and start a new one."
4. Tell the user how to check it: "In the new chat, ask me: 'Is maisecrets active?' I will run the check and tell you ACTIVE or NOT ACTIVE."

Rules for every task

• Never print, cat, open or quote a file or a value that may hold a secret. Use the scripts below: their output has locations and types, never values.
• Never ask the user to paste a secret. If the user pastes one, do not repeat it.
• Change nothing without the user's yes. Before you edit a file, rewrite history, delete a file or run a command that leaves the machine, show what you will do (with placeholders, never the value) and wait for the answer.
• Say what you do not know. A scan finds what its rules match; say so when you report "nothing found".
• The scripts need Python 3.9 or newer (the stock python3 of macOS works). They live in scripts/ next to this file; in Claude Code that folder is ${CLAUDE_SKILL_DIR}/scripts.

Put a placeholder into a document or a file

A placeholder such as ⟦EMAIL_c1⟧ stands for a value that maisecrets keeps on this computer. When the user asks for that value in a PDF, a .docx, a page or another file, put the value in through the placeholder. Do not ask the user to type the value in.

1. Write the generator as a script file, for example make_pdf.py.
2. Give the placeholder to the script as an argument, and run it: python3 make_pdf.py ⟦EMAIL_c1⟧. The shell reads the value when the command runs. The script reads it from sys.argv[1].
3. Or put the placeholder into the content of the file: Write or Edit in Claude Code, apply_patch in Codex. The file on disk gets the value.

On Windows, step 2 does not work in a PowerShell command or in any shell command of Codex: there a placeholder is refused. (The Bash tool of Claude Code in Git Bash takes it.) Use step 3 there: write a text file with the placeholder alone on a line (for example value.txt), let the script read the value from that file, and then run the script with no placeholder in the command. A value in program code is parsed as code, so put the placeholder into the script itself only where a quote or a backslash cannot break it.

Inline code (python3 -c, node -e) and a quoted heredoc (<<'EOF') cannot take a value: maisecrets stops the command and names this route. You keep seeing the placeholder, also when you read the file again.

Check a repository

1. Scan the files first: python3 scripts/scan_secrets.py <repo>. Add --pii when the user also asks about personal data such as e-mail addresses or IBANs.
2. Then scan the history: python3 scripts/scan_secrets.py <repo> --history --out <file>. --out writes the full report to a file the user can keep and prints only the summary. On a large repository the history scan can take many minutes: tell the user, and run it in the background if your tools allow that.
3. Read the result:
   • shape means the value has a provider's token format, guess means a keyword such as password = stands next to it and it can be noise.
   • tracked means git holds the file. pushed means the commit is on a remote branch (as of the last git fetch), local only means it never left this clone.
   • The same id means the same value. value also at names where it still is today.
   • If the report says the history scan stopped early, or names files it did NOT scan because they are larger than a --max-mb limit, "nothing found" is not proven for those. Offer to scan again with --max-commits raised or without --max-mb.
4. Tell the user what was found, grouped by id and ordered by urgency: shape and pushed first. Give file, line, commit, date and author. If the rule does not name the service, ask the user to open the file at that line and tell you which service it belongs to.
5. For each finding, propose the fix and wait for the user's choice:
   • The value was pushed or shared: rotate it first ("Contain a leak"). Deleting the file does not help, because the value stays in the history and in every clone.
   • The file must not be in git: add it to .gitignore and run git rm --cached <file>.
   • The value is only in the history: rotate it if it was pushed. Rewriting the history (git filter-repo) is a second step; it needs a force push and every collaborator must clone again.
   • The value is a test fixture or a placeholder: say so, and suggest a clearly fake value.
6. Suggest a guard against the next leak: a pre-commit secret scan (for example betterleaks, the successor of gitleaks), and the maisecrets plugin for the agent itself.

Check what the AI agents already received

Claude Code and Codex keep every session on this computer. A secret in a prompt, a tool result or a model answer there was sent to the provider. This is the fastest way to answer "what did my agents already leak?".

1. Run python3 scripts/audit_transcripts.py --out <file>. Add --days 30 for a quick look, --claude or --codex for one agent, --pii for personal data. On a machine with many sessions it takes minutes: tell the user, and run it in the background if you can.
2. Report the values under "REACHED THE PROVIDER" first, shape before guess: each one was sent to Anthropic or OpenAI and must be rotated ("Contain a leak"). Values only in local records did not provably reach a provider.
3. Only when the user asks, offer to clean the local copies: --scrub lists the files, and only --scrub --yes, after the user's explicit yes, replaces the values. Say every time that this cleans only this computer: the provider keeps what it received, so rotation comes first.

Contain a leak

Use this when a value may have reached a chat, a commit, a push, a log, a ticket or a screenshot. It needs no shell, so it also works in a chat without tools.

1. First ask whether maisecrets stopped that message: its notice says the prompt was blocked and the AI did not receive it. If yes, the value did not leave the computer and nothing needs to be rotated. Say so plainly.
2. Otherwise ask which service the value belongs to and where it went. Do not ask for the value.
3. Rotate first, clean up second. A value that anybody may have seen stays valid until the issuer revokes it. Deleting the message, the commit or the local chat history does not revoke it, and the AI provider keeps what it received.
4. Give the steps for that service from references/rotation.md. If the service is not listed, give the generic steps from the same file.
5. Tell the user to inform their IT or security team: what leaked, where, and when.
6. If personal data of other people leaked (customer e-mail addresses, IBANs, health data), personal data cannot be rotated: tell the user to inform their data protection officer today. The GDPR can require a notice to the authority within 72 hours.
7. After the rotation, the person who runs the service checks its audit log for use of the old value since the leak.
8. Then clean up, each step only after the user's yes: remove the value from the file or the history (see "Check a repository"), ask the chat or ticket owner to delete the message, and update every place that uses the new value.

Before you read a file full of secrets

Some files hold secrets by their nature: a password export (passwords.csv, logins.csv, a Bitwarden, KeePass, 1Password or LastPass export), a browser recording (.har: cookies and login tokens), a contact or calendar export (.vcf, .ics), a key file. If you read one, every value in it goes to the AI provider. The hooks replace only what their rules find.

When the user asks you to read such a file, or a file turns out to be one (its name, its header row, or a first look that shows passwords, tokens or many personal records):

1. Do not open it, and do not read more of it. Stop and offer a masked copy:

   This looks like a <password export / HAR recording / contact list>. If I read it, every value in it goes to the AI provider. I can make a masked copy first and read only that. Shall I?

2. If the user says yes, run python3 scripts/redact_copy.py <file>. It writes <name>.redacted<ext> next to the original. It reads a password export by its header row and its file name, and every cookie and credential header of a HAR recording.
3. Read only the copy, never the original. Tell the user the path of the copy, and pass on what the script says it does NOT replace.
4. If the user says no, do not read the file. Ask what they need from it.

If you already read part of such a file, say so. Treat what you read as received by the provider (see "Contain a leak").

Make a file safe to share

1. Run python3 scripts/redact_copy.py <file>. It writes <name>.redacted<ext> next to the original and prints only the counts. Add --secrets-only to keep personal data.
2. Tell the user the path of the copy. Do not open the original. If the user wants to check the copy, open the copy only.
3. Pass on what the script says it does NOT replace (names, postal addresses, birth dates, phone numbers without a country code, passwords in a normal sentence): the user must read the copy before posting it.
4. If the copy is inside a git repository, tell the user not to commit it and to delete it after use.