neon-bar86.ru/.agents/skills/fix-finding/SKILL.md

name, description

name

description

fix-finding

Исправление и верификация конкретной security-находки в проекте НЕОН (site/crm/db). Использовать, когда пользователь явно просит исправить, закрыть или залечить уязвимость или finding из аудита — «исправь F-3», «закрой находку из AUDIT/FINDINGS.md», «почини IDOR из аудита и проверь». НЕ использовать для обычных багов, рефакторинга, ревью кода/дизайна, полного аудита (полный аудит делает скилл security-audit — он только документирует) или деплоя.

Fix Finding — минимальный проверенный фикс security-находки в НЕОН

Превратить текущую security-находку в минимальный, проверенный на живом стенде код-фикс. Если код уже безопасен — доказать это и вернуть no_change. Аудит (поиск и документирование) делает скилл security-audit; этот скилл — вторая стадия над его результатами.

Источник находки

Найди ID и контекст в одном из мест:

• AUDIT/FINDINGS.md — вывод аудит-скилла security-audit;
• АУДИТ-ПЕРЕД-РЕЛИЗОМ.md — предрелизный аудит, нумерация 1–38 (пункт с пометкой «вопрос к владельцу» — не фикси, это blocked);
• F-N — сквозная нумерация security-фиксов в комментариях кода (docker-compose.yml, crm/server.py) и в crm/_security_smoke.mjs;
• прямое описание от пользователя (файл/эндпоинт + путь атаки).

Если в находке нет файла/эндпоинта — сначала локализуй путь атаки по коду. Фиксить можно только явно запрошенную находку; соседние находки — доложить, не чинить.

Порядок свойств результата

Оценивай результат в этом порядке; более раннее никогда не меняется на более позднее. «Минимальный» = наименьшее проектно-нативное изменение, закрывающее все более ранние свойства, а не наименьшее число строк:

1. текущее состояние корректно классифицировано: уязвимо / уже безопасно / недоказано
2. фикс полностью закрывает нарушенную security-границу
3. легитимное поведение и совместимость сохранены
4. проверки проекта (см. гейты ниже) пройдены
5. реализация следует конвенциям проекта
6. патч содержит только необходимый охват

Карта проекта

• crm/ — Python 3, stdlib + psycopg, без фреймворков. server.py — HTTP + REST + роли; notes_api.py — доски заметок (примешан в Handler); storage.py — PostgreSQL (боевой), storage_sqlite.py — dev-двойник (ограничен: игры/доски/брони/миксы сайта/сброс нумерации → 501); js/app.js + index.html + css/ — панель персонала; seed/*.json — каталог; migrate/notes_boards.sql — канонический DDL досок.
• site/ — React + Vite + Tailwind, собирается в статику под nginx. nginx.conf — edge: лимит POST /api/orders (10/мин с IP), real_ip из X-Forwarded-For, /media/ отдаёт фото CRM; src/lib/crm.ts — мост к API.
• docker-compose.yml — site (наружу 127.0.0.1:8080), crm (127.0.0.1:47613), db (PostgreSQL 17, не публикуется). Секреты только из .env.
• Роли CRM: владелец / администратор / официант / кальянщик — матрица в README; пять слоёв защиты заказов (nginx-лимит → лимит на гостя → дедупликация → глобальный тормоз → honeypot).
• Git в проекте НЕТ: перед правкой делай снимок (см. ниже), diff собирай по снимкам.

Фикс может жить на любом из трёх слоёв (nginx → server.py → storage). Логика storage продублирована в двух бэкендах: фикс в storage.py почти всегда должен зеркалиться в storage_sqlite.py (и наоборот) — аудит не раз писал «в обоих бэкендах». Учитывай и панель (crm/js/app.js): что она ожидает от изменённого эндпоинта.

Патч-контракт (до правки)

Изучи саму реализацию, её прямых вызователей, соседние хелперы и разметку роль×эндпоинт в README. Установи из кода, а не из находки:

• атакующий вход и конкретный путь источник → sink (или сломанный контроль);
• security-инвариант и узкую общую границу, где его enforce;
• легитимное поведение, API-контракты, семантику ошибок, совместимость;
• ближайшие прецеденты в этом же коде (экранирование esc() в панели, параметризованный SQL %s, whitelist статики, лимитеры).

Находка — задача о потоке данных и границе, а не о примере входа из отчёта. Проверь эквивалентные кодировки, alternate-формы парсера, алиасы, всех вызователей, оба бэкенда и каждую копию security-чувствительного состояния, которая может обойти фикс. Небезопасное состояние обрабатывай явно — не принимай, не обрезай и не переинтерпретируй его молча.

Предпатчевое расследование

До правки запусти один свежий read-only субагент (Agent tool, general-purpose, с инструкцией не менять файлы). Если делегирование недоступно — сделай тот же проход сам отдельно, свежим взглядом:

• Исследователь границы и совместимости: независимо трассирует путь источник → sink, находит общую границу enforcement, затронутые входы, альтернативные представления и состояния, переходы валидация → использование, конкретные sibling-пути и обходы. Фиксирует легитимные сценарии и публичное поведение, которые обязаны остаться, и проверяет вызователей, режимы, ошибки, побочные эффекты, конвенции, готовые хелперы и применимые команды проверки.

Расследование требует ссылок на файлы/строки проекта и разделения фактов, выводов и открытых вопросов. По завершении сверь с собственной трассировкой и выбери границу фикса.

Снимки вместо git

Перед первым изменением скопируй оригиналы изменяемых файлов в AUDIT/FIXES/.snapshots/<ID>/ (создай каталог). По снимкам собери diff для ревью и отчёта (PowerShell Compare-Object, fc или git diff --no-index, если git есть на хосте). Не оставляй временных файлов-двойников вида .bak в рабочем дереве после завершения.

Реализация

1. Протрассируй путь и верни no_change, если код уже безопасен — без спекулятивных правок.
2. Где возможно, прогони через границу минимальный высокосигнальный repro и один легитимный контрольный запрос по тому же пути (живой стенд ниже).
3. Сделай наименьший фикс на общей границе. Предпочитай соседние хелперы и установленные API. Не расширяйся на редизайн, уборку и соседние находки.
4. До верификации атакуй свой патч, а не защищай: проверь каждого прямого вызователя изменённого хелпера и обе ветки каждого изменённого условия. Найди (а) один sibling-путь, представление или копию, которые всё ещё доходят до sink, (б) один обычный/дефолтный вход, который патч начал отвергать или переинтерпретировать. Если хоть одно есть — переделай.
5. Верифицируй по гейтам (порядок обязателен).

Гейты верификации

1. Синтаксис/сборка — только изменённое:
   • Python: python -m py_compile crm\server.py crm\storage.py crm\storage_sqlite.py crm\notes_api.py (в crm/);
   • сайт (если тронут site/): из site/ — npx tsc --noEmit, затем npm run build;
   • движок миксов (если тронут site/src миксы/стоп-лист): npm run test:engine.
2. Security-триггер — repro находки на живом стенде больше не воспроизводится + один альтернативный класс вредоносного входа.
3. Легитимный контроль — обычный сценарий по тому же пути работает; соседние роли не сломаны (токены owner/admin/waiter — матрица в README).

Живой стенд

• Postgres-стек (нужен для игр, досок, броней, миксов, сброса нумерации — в sqlite это 501): docker compose up -d --build, CRM на 127.0.0.1:47613, сайт на 127.0.0.1:8080.
• SQLite-стенд без Docker: start-crm.bat (CRM_DB=sqlite, CRM_ALLOW_DEFAULT_PASSWORDS=1, порт 47613).
• Сайт-дев: в site/ npm run dev; если docker уже держит 8080 — npm run dev -- --port 8090 --strictPort.
• Перед стартом проверь, кто слушает порт (netstat -ano | findstr :47613): 8080/47613 держит docker-стек, 8081 — чужой процесс, его не трогать.
• Доступы стенда — из .env (SMOKE_* нет в .env — задавай при запуске скрипта).

Регрессионный артефакт

Проект верифицирует фиксы smoke-скриптами по образцу crm/_security_smoke.mjs: fetch против 127.0.0.1:47613, PASS/FAIL, ненулевой exit при провале, пароли через env (SMOKE_OWNER_PW, SMOKE_WAITER_PW). Добавь проверки фикса в _security_smoke.mjs или создай сфокусированный crm/_fix_<ID>.mjs по тому же образцу. Помни побочные эффекты: lockout-тест закрывает waiter.mark на 15 минут (порядок проверок важен), тест смены пароля обязан возвращать пароль обратно.

Ревью кандидата

После реализации и фокусных проверок запусти одного свежего read-only субагента (Agent tool; инструкции не редактировать и не делегировать). Дай ему только находку, корень проекта, авторизованный объём, конвенции и текущий diff кандидата — без обоснований, отчёта исследователя и заявлений, что тесты прошли. Если делегирование недоступно — сделай этот проход сам, отдельно, до финальной верификации:

• Ревьюер обходов и регрессий: реконструирует инвариант и ищет конкретный выживший маршрут через затронутые входы, эквивалентные представления, границы парсеров, алиасы, оба бэкенда, слой nginx и щели валидация → использование; трассирует изменённые условия и вызователей на предмет конкретной поломки легитимных входов, контрактов, ошибок, побочных эффектов и конвенций.

Находки ревьюера — гипотезы: подтверждай их по коду или фокусным запуском, правь только подтверждённые в рамках находки и совместимости. Затем прогони затронутые гейты заново и убедись, что временных и посторонних изменений не осталось. Только один цикл ревью.

Верни blocked, если находка может быть реальной, но не хватает существенных данных, инструментария, доступа или это продуктовое решение владельца (пример: №38 «waiter вне смены видит телефоны» из предрелизного аудита) — тогда безопасный фикс невозможно завершить или проверить.

Отчёт

Напиши AUDIT/FIXES/<ID>.md и проставь в источнике находки (AUDIT/FINDINGS.md или АУДИТ-ПЕРЕД-РЕЛИЗОМ.md) статус фикса со ссылкой на отчёт. В финальном ответе в чате обязательно:

• outcome: fixed / no_change / blocked
• конкретный уязвимый путь, security-инвариант и легитимное поведение, которое обязано было сохраниться
• выбранная стратегия и почему это самый узкий полный вариант (либо — какое решение владельца отсутствует при blocked)
• изменённые файлы и добавленные тесты/артефакты
• команды по гейтам с результатами pass/fail/unknown
• как показано, что исходная находка больше не воспроизводится
• как показано, что легитимное поведение сохранилось
• оставшиеся пробелы и пропущенные проверки, если есть

Жёсткие правила

• Не докладывай fixed, пока не пройдены все гейты по порядку. Проверку можно пропустить только с обоснованием по коду; недоступная существенная проверка = blocked и явное указание, чего не хватило.
• Не полагайся только на чтение кода, когда возможен фокусный repro на стенде.
• Не расширяй патч на уборку, соседние находки и редизайн без доказательства, что без этого граница не закрывается.
• Не удаляй и не затирай правки пользователя — git нет, снимки единственная страховка; не трогай crm/data/, crm/media/, .env и site/dist.
• Не ослабляй авторизацию, ролевую матрицу, пять слоёв защиты заказов, валидацию входа, fail-fast на дефолтных паролях и лимитеры ради зелёных проверок.
• Не деплой на прод (docker compose up -d --build site crm) без явной команды владельца — верификация идёт на локальном стенде.
• Не прячь пробелы доказательств: если среда не дала проверить — назови команду и чего не хватает.