132 lines
5.9 KiB
Markdown
132 lines
5.9 KiB
Markdown
# Basic Auth Management Runbook
|
||
|
||
**Установлено**: 2026-05-23 (PR #426, commit `cc2d148`)
|
||
**Realm**: `"GenDesign Pilot"`
|
||
**URL**: <https://gendsgn.ru/>
|
||
|
||
## Добавить пользователя
|
||
|
||
```bash
|
||
./scripts/auth/add_user.sh <username>
|
||
# Вводи пароль интерактивно; скрипт добавляет в caddy/users.caddy.snippet
|
||
```
|
||
|
||
После: commit snippet → PR → merge → GHA deploy → Caddy reload (автоматически в deploy.yml).
|
||
|
||
## Удалить пользователя
|
||
|
||
1. `./scripts/auth/remove_user.sh <username>` ASAP
|
||
2. Commit + push + PR (merge приоритетным)
|
||
3. `docker compose exec caddy caddy reload` после deploy
|
||
4. Сгенерировать новый credential через `add_user.sh`
|
||
5. Уведомить остальных стейкхолдеров о замене
|
||
|
||
## Просмотр текущих пользователей
|
||
|
||
```bash
|
||
./scripts/auth/list_users.sh
|
||
```
|
||
|
||
## Credencial rotation
|
||
|
||
При компрометации пароля: remove_user + add_user с новым паролем + PR-merge + разослать новый credential.
|
||
|
||
## Аудит логи
|
||
|
||
- **Auth audit**: `/var/log/caddy/auth_audit.log` — все события basic_auth (включая raw Authorization).
|
||
Содержит plain credentials в Base64 — accessible только root на VPS.
|
||
Используется forwarder'ом (см. `ops/glitchtip-auth-forwarder/forwarder.py`).
|
||
Retention: 7 дней (roll_size 10MiB, keep 3, 168h).
|
||
|
||
- **Access log**: `/var/log/caddy/gendsgn.ru.log` — все requests, format JSON.
|
||
Тоже содержит raw Authorization из-за global `log_credentials` (Caddy 2.x — опция только global, нельзя per-block).
|
||
Retention: 30 дней (roll_size 50MiB, keep 5, 720h).
|
||
|
||
Failed auth последние 100:
|
||
|
||
```bash
|
||
docker compose -f docker-compose.prod.yml exec caddy \
|
||
grep -P '"status":401' /var/log/caddy/auth_audit.log | tail -100 | jq
|
||
```
|
||
|
||
### Security note
|
||
|
||
`log_credentials` — опция под `servers { }` global block, нельзя per-virtual-host. Plain Base64 credentials попадают в **оба** log файла. Mitigation:
|
||
- VPS root-only (только SSH key authorized owner)
|
||
- Retention: gendsgn.ru.log = 30 дней, auth_audit.log = 7 дней
|
||
- Не выгружать логи на внешние системы без redaction
|
||
|
||
## Диагностика
|
||
|
||
```bash
|
||
# Посмотреть 401-ошибки в auth audit log
|
||
ssh gendesign 'docker compose -p gendesign exec caddy tail -f /var/log/caddy/auth_audit.log' | grep '"status":401'
|
||
|
||
# Reload конфига Caddy без перезапуска
|
||
ssh gendesign 'docker compose -p gendesign exec -T caddy caddy reload --config /etc/caddy/Caddyfile'
|
||
```
|
||
|
||
## GlitchTip auth event forwarding
|
||
|
||
Sidecar `gendesign-auth-forwarder` шлёт 401 события в GlitchTip как Sentry warning events.
|
||
|
||
- Состояние: `docker compose -p gendesign ps | grep auth-forwarder`
|
||
- Logs: `docker compose -p gendesign logs -f glitchtip-auth-forwarder`
|
||
- GlitchTip dashboard: <https://errors.gendsgn.ru/> — фильтр `event_type:basic_auth_failed`
|
||
- Storm digest: при >10 failed auth за 60s → отдельный `event_type:basic_auth_storm` event
|
||
- Мониторы (GlitchTip uptime, SentryUptimeBot) — получают 401 стабильно из-за отсутствия credentials; они фильтруются как individual events, учитываются только в storm digest
|
||
|
||
Если sidecar упал — failed auth события **не теряются** (offset persistent в `auth_forwarder_state` volume), но в GlitchTip не доезжают пока container down.
|
||
|
||
### Перезапуск forwarder
|
||
|
||
```bash
|
||
ssh gendesign 'docker compose -p gendesign restart glitchtip-auth-forwarder'
|
||
```
|
||
|
||
### Переменные окружения forwarder
|
||
|
||
Задаются в `/opt/gendesign/.env` на VPS:
|
||
|
||
| Переменная | Описание | Обязательна |
|
||
|---|---|---|
|
||
| `GLITCHTIP_DSN` | Sentry DSN GlitchTip (project backend) | Да |
|
||
|
||
## Deploy
|
||
|
||
Sidecar собирается локально на VPS на каждом запуске `deploy.yml` (после merge в main).
|
||
Не требует pre-push image build, не использует GHCR.
|
||
|
||
Forwarder контейнер пересоздаётся `--force-recreate` чтобы подхватить новый image при изменении кода.
|
||
|
||
В случае sidecar не запустился:
|
||
|
||
```bash
|
||
ssh gendesign 'docker compose -p gendesign -f docker-compose.prod.yml logs --tail=100 glitchtip-auth-forwarder'
|
||
```
|
||
|
||
Если build fail на VPS — проверь `ops/glitchtip-auth-forwarder/Dockerfile` локально:
|
||
|
||
```bash
|
||
docker build ops/glitchtip-auth-forwarder/
|
||
```
|
||
|
||
## Phase 2 — реализовано (PR #430)
|
||
|
||
GlitchTip forwarder sidecar добавлен в `ops/glitchtip-auth-forwarder/`.
|
||
Архитектура: Python 3.12 slim, sentry-sdk 2.18, tail live Caddy log, offset в named volume.
|
||
Deploy автоматизирован через `deploy.yml` — ручной SSH на VPS не нужен.
|
||
|
||
## Phase 3 — реализовано (PR #436)
|
||
|
||
`log_credentials` + `auth_audit.log` → forwarder получает реальный username из 401.
|
||
|
||
- Global `log_credentials` в Caddyfile — Caddy перестаёт редактировать Authorization header.
|
||
- Отдельный `auth_audit.log` (retention 7d) — forwarder читает именно его.
|
||
- `_extract_attempted_username` декодирует Basic auth → `attempted_username` tag в GlitchTip event.
|
||
- Результат: GlitchTip event получает `attempted_username:testbruteforce` вместо `(none)`.
|
||
|
||
## Phase 4 (TODO)
|
||
|
||
- При >30 users — миграция на OAuth/NextAuth
|
||
- Разделение admin/user по доступу через Caddy path matcher или app-level RBAC
|