Выявляйте проблемы безопасности по мере написания кода Claude
Установите плагин security-guidance, чтобы Claude проверял собственные изменения кода на уязвимости и исправлял их в одном сеансе.
Плагин security guidance заставляет Claude проверять собственные изменения кода на наличие распространённых уязвимостей во время работы и исправлять найденные проблемы в одном сеансе. Плагин выявляет такие проблемы, как инъекции, небезопасная десериализация и небезопасные DOM API, прежде чем код попадёт в pull request, снижая объём работы по проверке безопасности, которая падает на плечи рецензентов.
После установки плагин работает автоматически. Нет ничего, что нужно вызывать, и нет отдельной команды, которую нужно помнить.
Плагин является встроенным в сеанс компаньоном Code Review, который работает на pull request. Этот плагин снижает объём того, что попадает в PR. Code Review ловит то, что остаётся. О том, как плагин работает вместе с проверкой по требованию и сканированием CI, см. Как это работает с другими инструментами безопасности.
Предварительные требования
- Claude Code CLI версии 2.1.144 или позже
- Python 3.8 или позже в вашем
PATH. Плагин пытаетсяpython3,pythonиpy -3в этом порядке - Git репозиторий для каталога, в котором вы работаете. Проверки в конце хода и при коммите используют diff относительно состояния git и пропускаются молча вне репозитория. Проверка шаблонов при каждом редактировании работает везде
При первом запуске плагин создаёт виртуальное окружение под ~/.claude/security/ и устанавливает Claude Agent SDK в него, что требует pip и доступа в сеть. Если эта установка не удаётся, проверка коммита переходит на однократную проверку вместо агентивной. На Windows этап виртуального окружения пропускается, поэтому агентивная проверка коммита работает только если claude-agent-sdk уже импортируемый и в противном случае переходит на тот же способ.
Установка плагина
В сеансе Claude Code установите из официального маркетплейса Anthropic:
/plugin install security-guidance@claude-plugins-official
Установка запрашивает область действия. Выберите область действия пользователя, чтобы записать плагин в ваши пользовательские параметры, поэтому он загружается в каждом новом локальном сеансе, который вы запускаете на этой машине. Если Claude Code сообщает, что маркетплейс не найден, сначала запустите /plugin marketplace add anthropics/claude-plugins-official, затем повторите попытку установки.
Затем активируйте его в текущем сеансе с помощью /reload-plugins, который применяет ожидающие изменения плагина без перезагрузки:
/reload-plugins
Включение в облачных сеансах и общих репозиториях
Плагины с областью действия пользователя не переносятся в Claude Code в веб-версии, потому что эти сеансы работают на инфраструктуре Anthropic, а не на вашей машине. Чтобы включить плагин там или включить его для всех, кто клонирует репозиторий, объявите его в параметрах проекта, которые проверены:
{
"enabledPlugins": {
"security-guidance@claude-plugins-official": true
}
}
Администраторы могут включить плагин на уровне организации, установив enabledPlugins в управляемых параметрах.
Что проверяет плагин
Плагин проверяет работу Claude в трёх точках, каждая на разной глубине:
- При каждом редактировании файла: быстрое сопоставление шаблонов для рискованных вызовов без вызова модели
- В конце каждого хода: фоновая проверка моделью всего, что изменилось в этом ходе
- При каждом коммите или push, который делает Claude: более глубокая агентивная проверка, которая читает окружающий код
Вы можете расширить каждый слой, добавив свои собственные правила. Встроенные проверки не могут быть удалены по отдельности, но вы можете отключить каждый слой независимо.
При каждом редактировании файла
Когда Claude пишет в файл, плагин сканирует новое содержимое на предмет известных рискованных шаблонов. Это сопоставление шаблонов без вызова модели, поэтому оно не добавляет затрат на использование.
Примеры категорий шаблонов:
- Динамическое выполнение кода:
eval(,new Function,os.system,child_process.exec - Небезопасная десериализация:
pickle - Инъекция DOM:
dangerouslySetInnerHTML,.innerHTML =,document.write - Файлы рабочего процесса: редактирование под
.github/workflows/, которое может предоставить разрешения на уровне репозитория
Проверка выполняется после того, как редактирование применяется, и добавляет предупреждение в контекст Claude для следующего шага. Каждое предупреждение срабатывает один раз за шаблон за файл за сеанс, поэтому повторные совпадения в одном файле не заполняют разговор.
Вы можете добавить свои собственные шаблоны в этот слой с помощью файла security-patterns.yaml.
В конце каждого хода
Ход — это один раунд ответа Claude: вы отправляете сообщение, Claude работает и отвечает, и ход заканчивается. После каждого хода плагин вычисляет git diff всего, что изменилось в рабочем дереве во время хода, включая изменения из инструментов редактирования Claude, команд Bash и подагентов, и отправляет его отдельному Claude для проверки, сосредоточенной на безопасности. Проверка выполняется в фоне, поэтому ответ Claude не задерживается. Если проверка обнаруживает проблемы, Claude переспрашивается с результатами и решает их как продолжение.
Это выявляет проблемы, которые сопоставление строк не может, такие как:
- Обход авторизации
- Небезопасные прямые ссылки на объекты
- Инъекции
- Подделка запроса на стороне сервера
- Слабая криптография
Вы видите как результат, так и решение Claude прямо в вашем сеансе. Проверка охватывает до 30 изменённых файлов за ход и срабатывает максимум три раза подряд, прежде чем вернуться к вам.
При каждом коммите или push, который делает Claude
Когда Claude запускает git commit или git push через свой инструмент Bash, плагин запускает более глубокую агентивную проверку изменения в фоне. Эта проверка читает окружающий код, включая вызывающие функции, санитайзеры и связанные файлы, чтобы решить, является ли результат реальным, прежде чем сообщить о нём. Дополнительный контекст снижает количество ложных срабатываний на шаблонах, которые выглядят опасно в изоляции, но безопасны в вашей кодовой базе.
Этот слой срабатывает только на коммитах и push, которые Claude делает через свой инструмент Bash. Коммиты, которые вы запускаете из собственной оболочки, включая экранирование оболочки ! внутри сеанса, не проверяются. Проверки коммитов и push ограничены 20 в течение часа. Если результаты проверки коммита дублируют то, что уже сообщила проверка в конце хода, Claude не переспрашивается, поэтому чистый коммит не производит видимого вывода из этого слоя.
Независимость проверки и ограничения
Плагин не просит один и тот же экземпляр Claude, который написал код, оценить себя. Проверка при каждом редактировании — это детерминированное сопоставление строк без участия модели. Проверки в конце хода и при коммите выполняются как отдельный вызов Claude со свежим контекстом и сосредоточенным на безопасности приглашением: рецензент начинает с diff, не имеет инвестиций в исходный подход и инструктирован только находить проблемы.
Ни один из слоёв не блокирует записи или коммиты. Результаты достигают Claude, который пишет код, как инструкции, Claude решает их в разговоре, и модель проверки может пропустить проблемы. Рассматривайте плагин как один слой защиты в глубину, а не как полное решение безопасности. См. Как это работает с другими инструментами безопасности.
Добавьте свои собственные правила
Плагин имеет две точки расширения: файл руководства Markdown для проверок на основе модели и файл шаблонов YAML или JSON для сопоставления строк при каждом редактировании. Оба являются дополнительными. Вы можете добавлять проверки, но не можете отключать встроенные из этих файлов.
Добавьте руководство для проверок на основе модели
Создайте .claude/claude-security-guidance.md в вашем проекте и опишите вашу модель угроз и контрольный список проверки на простом языке. Проверки на основе модели загружают его как дополнительный контекст наряду со встроенным контрольным списком уязвимостей.
Следующий пример предназначен для веб-сервиса с управляемыми ролями маршрутами администратора и политикой логирования данных клиентов:
# Security guidance for this repo
- Do not log `customer_id` or `account_number` at INFO level or above.
- All routes under `/admin` must call `require_role("admin")` before any database read.
- Use `crypto.timingSafeEqual` for token comparison instead of `===`.
Эти правила — руководство для рецензента, а не детерминированные ограждения. Плагин выявляет нарушения как результаты для Claude, чтобы исправить, но он не блокирует записи и не гарантирует, что каждое нарушение будет выявлено. Руководство является дополнительным только: правило, которое говорит игнорировать класс уязвимостей, не подавляет эти результаты. Для жёсткого принудительного исполнения объедините плагин с хуком, который блокирует редактирование или проверкой CI.
Добавьте пользовательские шаблоны для каждого редактирования
Создайте .claude/security-patterns.yaml для добавления правил regex или подстроки к проверке шаблонов при каждом редактировании. Они выполняются как детерминированные сопоставления строк наряду со встроенными шаблонами:
patterns:
- rule_name: internal_api_key
substrings: ["sk_live_", "AKIA"]
reminder: "Hardcoded API key prefix. Load credentials from the secret manager."
- rule_name: tenant_unfiltered_query
regex: "\\.objects\\.all\\(\\)"
paths: ["**/src/tenants/**"]
reminder: "Multi-tenant code must filter by org_id."
| Поле | Тип | Описание |
|---|---|---|
rule_name |
string | Идентификатор, показанный в предупреждении |
reminder |
string | Текст предупреждения, добавленный в контекст Claude, ограничен 1 КБ |
regex |
string | Python regex, сопоставленный с отредактированным содержимым |
substrings |
list | Буквальные подстроки; предоставьте это или regex |
paths |
list | Необязательные glob шаблоны; правило применяется только к совпадающим файлам. Glob шаблоны сопоставляются с полным путём файла, поэтому добавьте префикс **/ к шаблонам, относительным к проекту |
exclude_paths |
list | Необязательные glob шаблоны для пропуска; то же сопоставление, что и paths |
Плагин также читает .claude/security-patterns.yml и .claude/security-patterns.json с той же схемой. JSON работает на любой установке Python. Формы YAML требуют, чтобы PyYAML был импортируемым, который плагин не устанавливает для вас. Плагин загружает до 50 пользовательских правил и пропускает regex, которые выглядят подверженными катастрофическому возврату.
Расположения поиска файлов правил
Плагин ищет claude-security-guidance.md и security-patterns.yaml в одних и тех же местах, независимо от того, как был включен плагин:
| Область | Путь | Примечания |
|---|---|---|
| User | ~/.claude/claude-security-guidance.md |
Применяется к каждому проекту на вашей машине |
| Project | .claude/claude-security-guidance.md |
Проверено в репозитории |
| Project local | .claude/claude-security-guidance.local.md |
Gitignored, для личных переопределений |
Плагин загружает все существующие местоположения и объединяет их с объединённым ограничением 8 КБ для файла руководства. Администраторы могут распространять правила на уровне организации, отправляя файл с областью действия пользователя в ~/.claude/ через управление устройствами. Те же пути применяются к security-patterns.yaml.
Стоимость использования
Проверка шаблонов при каждом редактировании не делает вызов модели и не добавляет затрат. Проверки в конце хода и коммита каждая тратит дополнительное использование модели, которое считается в вашем использовании как любой другой запрос Claude. Проверка коммита является агентивной и может занять несколько ходов модели за коммит, ограничено 20 проверками в течение часа. Ожидайте примерно один вызов проверки за ход, который изменяет файлы, и одну более глубокую проверку за коммит, оба подлежат ограничениям выше.
Обе проверки на основе модели используют Claude Opus 4.7 по умолчанию. Установите SECURITY_REVIEW_MODEL для выбора другой модели для проверки в конце хода и SG_AGENTIC_MODEL для проверки коммита.
Плагин доступен на всех планах.
Отключение или удаление
Чтобы отключить отдельные слои, сохраняя остальные, установите соответствующую переменную окружения:
| Переменная | Эффект |
|---|---|
ENABLE_PATTERN_RULES=0 |
Отключить проверку шаблонов при каждом редактировании |
ENABLE_STOP_REVIEW=0 |
Отключить проверку diff в конце хода |
ENABLE_COMMIT_REVIEW=0 |
Отключить проверку коммита и push |
ENABLE_CODE_SECURITY_REVIEW=0 |
Отключить все проверки на основе модели сразу |
SECURITY_GUIDANCE_DISABLE=1 |
Отключить плагин полностью без удаления |
Чтобы приостановить плагин в области действия пользователя:
/plugin disable security-guidance@claude-plugins-official
Чтобы удалить его из области действия пользователя:
/plugin uninstall security-guidance@claude-plugins-official
Если плагин был включен через .claude/settings.json проекта, отключение его из /plugin записывает переопределение в ваш .claude/settings.local.json вместо редактирования проверенного файла, поэтому плагин остаётся отключённым для вас, а товарищи по команде не затронуты. Если он был включен через управляемые параметры, только администратор может его отключить.
Как плагин интегрируется с Claude Code
Плагин полностью построен на hooks, механизме для запуска вашего собственного кода в определённых точках цикла Claude. Он регистрирует:
| Hook event | Назначение |
|---|---|
SessionStart |
Начальная загрузка окружения Python плагина |
UserPromptSubmit |
Захват базовой линии рабочего дерева, которую проверка в конце хода использует для diff |
PostToolUse на Edit, Write и NotebookEdit |
Сопоставление шаблонов при каждом редактировании |
Stop |
Проверка diff в конце хода, выполняется в фоне |
PostToolUse на Bash, отфильтрованный по git commit и git push |
Проверка коммита и push, выполняется в фоне |
Если вы создаёте свои собственные hooks, исходный код плагина является рабочим примером запуска отдельного вызова модели из hook и возврата результата в сеанс.
Как это работает с другими инструментами безопасности
Плагин — это один слой в подходе защиты в глубину. Он выявляет проблемы раньше всего, пока код ещё находится в редакторе, но это не гарантия и не заменяет более поздние проверки. Типичный стек:
| Этап | Инструмент | Что он охватывает |
|---|---|---|
| В сеансе | Security guidance plugin | Распространённые уязвимости в коде, который пишет Claude, исправлены в одном сеансе |
| По требованию | /security-review |
Однократная проверка безопасности на текущей ветке, выполняется по вашему запросу |
| На pull request | Code Review, планы Team и Enterprise | Многоагентная проверка корректности и безопасности с полным контекстом кодовой базы |
| В CI | Ваши существующие статические анализаторы и сканеры зависимостей | Правила, специфичные для языка, проверки цепочки поставок и принудительное исполнение политики, которые плагин не пытается выполнять |
Каждый более поздний этап выявляет то, что пропустили более ранние. Ценность плагина в снижении объёма, который их достигает, а не в исключении необходимости в них.
Troubleshooting
Плагин записывает диагностику времени выполнения в ~/.claude/security/log.txt. Проверьте там в первую очередь, если проверки не появляются.
Распространённые причины, по которым слой проверки пропускается без сообщения в разговоре:
- Каталог не является git репозиторием: проверки в конце хода и при коммите требуют состояния git и пропускаются вне репозитория
- Сеанс не имеет аутентификации Anthropic: проверки на основе модели пропускаются и работает только проверка шаблонов при каждом редактировании
- Файл
security-patterns.yamlприсутствует, но PyYAML не импортируемый: файл игнорируется. Используйтеsecurity-patterns.jsonвместо этого
Связанные ресурсы
Чтобы углубиться в части, которые эта страница затрагивает:
- Code Review: настройка многоагентной проверки во время PR
- Автоматизируйте действия с помощью hooks: создавайте свои собственные проверки в одних и тех же точках жизненного цикла
- Откройте и установите плагины: просмотрите другие официальные плагины