Устранение неполадок¶

По областям. Каждый пункт: что вы видите → почему → что делать.

Установка и старт¶

Бэкенд падает: ENCRYPTION_KEY must be explicitly set when APP_ENV='production' Ожидаемый fail-fast. Задайте корректный Fernet-ключ в .env (команда генерации — в сообщении ошибки).

Бэкенд падает: invalid format (not a valid Fernet key) Опечатка в ENCRYPTION_KEY. Сгенерируйте заново; если данные уже записаны под старым ключом — восстановите его, не перезаписывайте вслепую.

password authentication failed for user "umbryx" при старте DB_PASSWORD изменён после инициализации volume PostgreSQL. Либо верните старый пароль, либо сбросьте volume (docker compose down -v — уничтожает данные).

Приложение недоступно на :3000 docker compose ps для состояний сервисов; проверьте публикуемый PORT и форвардинг reverse-proxy.

Конфигурация¶

Сессии слетают после каждого рестарта JWT_SECRET не задан — автогенерация при каждом старте, если персистенция не удалась. Задайте явно.

CORS-ошибки после переноса UI на другой origin Пропишите CORS_ORIGINS с origin UI (никогда *; используются учётные данные).

WS за reverse proxy не обновляется live Блок location /ws/ требует заголовков апгрейда HTTP/1.1 и длинных read-таймаутов (рабочий паттерн — в поставляемых nginx-конфигах). Фронтенд тем временем откатывается на polling.

База данных и миграции¶

Ошибка миграции при старте Несовпадение версий кода/БД (например, БД восстановлена из более новой резервной копии). Восстановите согласованные версии или осознанно сделайте alembic stamp <revision>.

Медленные списки на огромных проектах Осторожно поднимайте DATABASE_STATEMENT_TIMEOUT; лучше подключите read-replica (DATABASE_REPLICA_URL).

Аутентификация и авторизация¶

401 везде после logout в другом месте Refresh-токены ротируются при использовании и попадают в blacklist при logout (с Redis). Перевойдите.

403 на действия, которые роль «должна мочь» Сверьтесь с фактической матрицей — например, findings.approve принадлежит только reviewer; credentials.read_secret — owner/admin/editor/operator. См. Контроль доступа.

Экран first-run setup появился на экземпляре с пользователями Вы попадаете не в ту БД (проверьте DATABASE_URL / монтирование volume) — setup показывается только при пустой таблице users.

Сканы и исполнение¶

Скан падает: no attacker host / 404 на attacker_ssh Executor не настроен. Infra → Connections → добавьте attacker SSH-таргет (или включите executor-флаг у пул-workstation). Модуль attacker_ssh должен быть включён.

No usable SSH credential found for attacker host Кред существует, но не привязан к этому attacker-хосту, либо хост не помечен как attacker-side. Исправьте привязку в Connections.

Задача висит в queued Пул воркеров исчерпан или WORKER_BACKEND=arq без сервиса worker. Проверьте System → Health и бейдж воркера в Jobs. Отличайте от awaiting ROE approval — там нужен approve/reject от owner/admin.

Задача падает: Blocked by ROE/scope guard Цель вне scope, запрещённая активность или вне рабочего окна. Скорректируйте ROE/scope; при подтверждении проверка повторяется.

Данные и шифрование¶

Cannot read encrypted value / ошибки расшифровки ENCRYPTION_KEY отличается от того, которым писались данные. Восстановите оригинальный ключ или перешифруйте через backend/scripts/rekey.py (сначала dry-run). Без старого ключа данные невосстановимы.

Импорт зашифрованного ZIP просит пароль Экспорты с секретами учётных данных шифруются AES с одноразовым паролем, показанным при экспорте. Потерянный пароль — только повторный экспорт с исходного экземпляра.

Loot показывает «No inline preview» Форматы office/БД — только скачивание, by design. Расшифровка файлов для предпросмотра доступна только platform-admin.

Отчёты и лимиты¶

Кнопка PDF возвращает HTML-файл WeasyPrint отсутствует в этом образе бэкенда — сервер откатывается на HTML. Установите/включите образ с поддержкой PDF.

429 Too Many Requests Встроенные лимиты: экспорт отчётов 10/мин, вход 5/мин (плюс блокировка аккаунта), reveal учётных данных 30/мин, вебхуки 120/мин.

Лицензирование (EE)¶

402 на записи, баннер про wind-down Лицензия истекла после grace. Загрузите обновлённый токен (System → License); данные и teardown доступны всё это время.

Heartbeat пишет в лог License Server unreachable Сетевой путь до LICENSE_SERVER_URL закрыт. Не критично до контрактного срока; air-gapped-экземплярам следует переключить канал в offline.

Токен отвергается при загрузке Токен привязан к железу/ключу другого экземпляра — для нового хоста нужен новый раунд C2V.