Leak Scan

leak-scan

Overview — два направления

Скилл закрывает обе границы безопасности вокруг авто-загружаемого каталога ~/.claude/:

Оба скрипта — чистый stdlib Python, UTF-8 stdout (Windows-совместимо), ничего не меняют на диске. Направления независимы: перед публикацией своего — ИСХОДЯЩЕЕ; перед установкой чужого с GitHub — ВХОДЯЩЕЕ.

ИСХОДЯЩЕЕ: PII/деанон перед публикацией (leak_scan.py)

Single consolidated scanner (scripts/leak_scan.py) that finds personal-data and deanonymization leaks before anything goes public. Pure Python UTF-8 — it exists because of a hard-won lesson.

Паттерны живут в двух слоях, и это принципиально:

Инструмент, который ищет утечки, сам легко становится крупнейшей из них: если личный словарь лежит в коде, опубликовать сканер значит опубликовать каталог всего частного разом. Поэтому второй слой вынесен наружу.

Первый запуск: заведи свой словарь (5 минут, один раз)

# Windows
copy "%USERPROFILE%\.claude\skills\leak-scan\scripts\identity.example.json" "%USERPROFILE%\.claude\leak-scan-identity.json"
# macOS / Linux
cp ~/.claude/skills/leak-scan/scripts/identity.example.json ~/.claude/leak-scan-identity.json

Открой копию и впиши СВОИ признаки вместо заглушек (YOURNAME, you@example.com, your-domain.example, 203.0.113.x, Acme Corp) — по паре ["метка", "регулярка"]. Начни с малого: имя и фамилия во всех падежах, личные почты, домены, IP своих серверов, имена клиентов. Дополняй по мере находок.

Скрипт ищет словарь по трём адресам, в порядке убывания приоритета: $LEAK_SCAN_IDENTITY (путь в переменной окружения) → ~/.claude/leak-scan-identity.json → identity.local.json рядом со скиллом. Файл не коммить — он по определению личный.

Без словаря сканер продолжает работать, но ловит только общие формы секретов и печатает предупреждение в stderr. Молчание при отсутствующем словаре — не «чисто», а «личное не проверялось».

Critical lesson — why this script, not grep

grep -F with Cyrillic on Windows SILENTLY fails to match (codepage mismatch) — it returns "clean" while leaks remain. NEVER verify depersonalization with grep/ripgrep for Russian text. ALWAYS use this Python UTF-8 scanner (or LLM agents) as the source of truth.

Two-stage protocol (MANDATORY)

Regex alone gives FALSE confidence. A 248-pattern scan once passed a repo "clean" — then a semantic LLM review of the same repo found a real client name in an example, a live API credit-balance, real production resource names, a private multi-account auth gateway, and ToS-grey subscription-bypass tooling. None matched a literal pattern. So ALWAYS run BOTH stages before declaring clean:

Stage 1 — regex scan (scripts/leak_scan.py): catches literal tells (names, emails, IPs, keys, tokens, known clients, national IDs). Fast, deterministic, exhaustive for what it knows — but «что оно знает» о тебе задаёт твой leak-scan-identity.json, см. выше.

Stage 2 — semantic review (LLM): read the actual content (skill bodies, examples, READMEs) and hunt for what regex CANNOT see:

• Real proper nouns in examples — client/company/person names, project codenames, product names (not in the pattern list)
• Live account state — credit balances, quotas, plan tiers, index/bucket/resource names, account IDs
• Private infrastructure — your servers/ports/paths, internal tools, multi-account setups, hardcoded home-dir conventions
• Bespoke-business reveals — a skill that exposes your employer, market, vertical, methodology, or a real client engagement even with names removed
• Vendor/credential lock-in & ToS-grey tooling — cookie/session bypass, reverse-engineered internal APIs, skills that only work with your private paid key
• Dependencies on unshipped private files — references to scripts/DBs/configs not in the public artifact

For a multi-file repo, fan out a few read-only agents over slices of the tree for Stage 2 (cap concurrency ~2-3 to avoid rate limits). Diff new content against the already-public baseline to separate newly-introduced leaks from pre-accepted ones.

When to Use

• Before pushing/publishing a repo, skill, pack, gist, or archive publicly
• Auditing an already-public artifact for leaks ("did I leave anything in?")
• Verifying a depersonalized build matches the zero-identity standard

Usage

python ~/.claude/skills/leak-scan/scripts/leak_scan.py <dir-or-file> [--allow SUBSTR ...]

• target — directory (recursive) or single file. Scans text files by extension; skips only .git/ and __pycache__/.
• --allow SUBSTR — extra allowlisted substring (repeatable) for project-specific intended strings.
• Output is forced UTF-8 (safe for Cyrillic on any console).

Что НЕ проверено — печатается всегда, до вердикта. Файлы с расширением вне списка текстовых перечисляются блоком «НЕ ПРОВЕРЕНО», и тогда «CLEAN» звучит как «чисто В ПРОВЕРЕННОЙ ЧАСТИ». Иначе «не смотрел» неотличимо от «посмотрел и не нашёл» — на этом уже один раз проехал служебный .canarybak со словарём детектора внутри.

Файлы с именем на _ раньше пропускались, теперь читаются (имя ничего не говорит о содержимом) и лишь помечаются в отчёте отдельной строкой — чтобы было видно, что находка пришла из служебного черновика.

Exit codes: 0 clean · 1 matches found · 2 target not found.

# Quick gate before a push (note: pipe loses exit code — check the printed FOUND/CLEAN)
python ~/.claude/skills/leak-scan/scripts/leak_scan.py ./my-public-repo

What it catches

Строки нижней половины таблицы ищутся, только если заведён leak-scan-identity.json.

Allowlist covers placeholders (your-username, YOUR_*, ${HOME}, ${WORKSPACE}) and credited public OSS authors (garrytan, obra/Jesse Vincent, mvanhorn, Anthropic, …).

Чего словарь не ловит — отдельный смысловой проход

Сканер знает ФОРМЫ: ключ, почта, IP, телефон, имя из личного словаря. Смысла он не знает, поэтому мимо него спокойно проходит целый класс — личное, которое выглядит как обычный текст:

Отсюда правило: перед публикацией добавленное читают, а не только сканируют. Порядок от дешёвого к дорогому:

1. leak_scan.py по области — снимает всё, что имеет форму;
2. дифф только добавленного (git diff -U0 <база>..HEAD) и по нему три вопроса: кто здесь назван кроме меня, что названо идентификатором, откуда взята история;
3. новизна каждой находки: git grep -c "<строка>" <база> против HEAD. Ноль до и два после — значит внесли вы сейчас, а не «так было всегда».

Что нашли именем — в личный словарь; что нашли классом — шаблоном. Пример класса: папки вида _имя_повод/ ловятся (?<![\w-])_[a-z]{3,}_[a-z]{3,}/.

⚠️ \b не работает рядом с подчёркиванием: \bимя\b НЕ найдёт _имя_повод, потому что _ — словесный символ. Для таких имён (?<![a-z0-9])имя(?![a-z0-9]).

Reading the results — intended vs real leak

Not every hit is a leak. After running, triage:

• Real leak → scrub: secrets, national IDs, server IPs, private client names, personal emails, hardware/timezone fingerprints.
• Intended/unavoidable → keep: a public marketplace's own owner/repo in its install command and repository/author.url fields necessarily name the repo. Decide identity policy (full name vs handle vs placeholder) with the user before deciding these are acceptable.
• Baseline pre-existing → if a hit already lives in the live public source, it was previously accepted; flag it but don't treat it as newly introduced.

To compare a new build against an already-published baseline, scan both and diff the hit sets by path.

Extending patterns

• Личные признаки (твоё имя, домен, клиент) → в ~/.claude/leak-scan-identity.json, а НЕ в код скрипта. Иначе сканер снова станет носителем утечки.
• Новая форма секрета (ключ очередного сервиса, чей префикс узнаваем) → GENERIC_PATTERNS в scripts/leak_scan.py: это безлично и полезно всем.
• Ложные срабатывания-плейсхолдеры → ALLOWLIST_SUBSTRINGS там же.
• Разовая нарочная строка → флаг --allow SUBSTR, без правки файлов.

ВХОДЯЩЕЕ: проверка чужого скилла/плагина/агента перед установкой (skill_injection_scan.py)

Любой сторонний скилл или плагин, скачанный с GitHub, попадает в авто-загружаемый каталог ~/.claude/ без единой проверки — а его SKILL.md уходит в контекст модели, его хуки выполняются на каждом вызове инструмента, его .mcp.json может поднять чужой сервер с моими правами. Этот скрипт — гейт перед тем, как чужой код станет частью моего окружения.

Идея и часть правил — из virgiliojr94/book-to-skill (tools/scan_generated_skill.py), адаптировано под этот конфиг и расширено проверками hooks / MCP / npm-lifecycle, которых у источника нет.

Когда запускать

• Скачал скилл/плагин/агента с GitHub и до копирования в ~/.claude/skills|plugins|agents.
• Оцениваешь чужой репозиторий, из которого хочешь забрать код себе.
• Ревизия уже установленного стороннего пакета («а что оно вообще делает при загрузке?»).

Использование

python ~/.claude/skills/leak-scan/scripts/skill_injection_scan.py <цель> [опции]

• <цель> — каталог скилла (со SKILL.md), каталог плагина (с plugin.json), каталог агентов/команд, сборник (skills/+agents/+hooks/), или одиночный .md. Тип определяется автоматически.
• --min-severity CRITICAL|WARN|INFO — порог печати (по умолчанию INFO).
• --allow RULE_ID — заглушить правило (повторяемо), напр. --allow hooks.registered для заведомо доверенного пакета с хуком.
• --include-vendor — сканировать и node_modules/dist/build (по умолчанию помечаются как не проверенные, а не молча пропускаются).
• --json — машинный вывод. --list-rules — список всех правил.

Коды выхода: 0 чисто · 1 есть находки (CRITICAL/WARN) · 2 скан не завершён достоверно (симлинк-цель, превышен лимит).

# Гейт перед установкой (пайп теряет код возврата — смотри печатное CRITICAL/ЧИСТО)
python ~/.claude/skills/leak-scan/scripts/skill_injection_scan.py ./downloaded-skill

Что ловит (35 правил, severity CRITICAL/WARN/INFO)

Как читать результат

• CRITICAL — не устанавливать, пока не понятно, зачем это в пакете.
• WARN — бывает легитимно (хук, MCP-сервер, объявленный allowed-tools), но должно быть заявлено в README пакета; сверь, что ожидаемо.
• Правила ловят форму, а не смысл: текст про безопасность/LLM может совпасть (напр. статья, объясняющая инъекции). Всегда смотри строку в контексте — > excerpt печатается рядом.
• ЧИСТО — не гарантия: прочитай SKILL.md и скрипты глазами. Скан — первый барьер, не последний.

Расширение правил

Правила инлайн в scripts/skill_injection_scan.py: текстовые — _TEXT_RULES, кодовые — _CODE_RULES, структурные (JSON) — функции _scan_hooks / _scan_mcp / _scan_package_json / _scan_json_file. Полный список id — --list-rules. Для разового доверия — --allow RULE_ID, не редактируй файл.