curo1305
157 lines
6.9 KiB
Markdown
157 lines
6.9 KiB
Markdown
---
|
|
phase: 04-folders-sharing-quotas-document-ux
|
|
plan: "07"
|
|
subsystem: security-hardening
|
|
tags:
|
|
- audit-log
|
|
- sec-08
|
|
- sec-09
|
|
- d-13
|
|
- admin
|
|
|
|
dependency_graph:
|
|
requires:
|
|
- "04-05"
|
|
- "04-06"
|
|
provides:
|
|
- audit-log-backfill-auth
|
|
- audit-log-backfill-documents
|
|
- audit-log-backfill-admin
|
|
- sec-08-credentials-enc-exclusion
|
|
- sec-09-delete-user-minio-cleanup
|
|
affects:
|
|
- backend/api/auth.py
|
|
- backend/api/admin.py
|
|
- backend/api/documents.py
|
|
|
|
tech_stack:
|
|
added: []
|
|
patterns:
|
|
- "write_audit_log() flush-before-commit pattern (D-14): audit entry flushed in same transaction as primary operation"
|
|
- "SEC-08 CloudConnectionOut whitelist pattern: Pydantic response model excludes credentials_enc by omission"
|
|
- "SEC-09 pre-delete MinIO cleanup: collect docs, delete_object best-effort, then session.delete(user)"
|
|
|
|
key_files:
|
|
created: []
|
|
modified:
|
|
- backend/api/auth.py
|
|
- backend/api/admin.py
|
|
- backend/api/documents.py
|
|
- backend/tests/test_admin_api.py
|
|
|
|
decisions:
|
|
- "write_audit_log for login_failed uses metadata_=None (no PII) — T-04-07-01"
|
|
- "document.uploaded and document.deleted audit metadata contains only size_bytes and storage_backend — T-04-07-02"
|
|
- "audit write for login success written just before return, inside a session.commit() call since create_refresh_token already flushed"
|
|
- "delete_document audit log written after storage.delete_document commits, in a new flush + commit — storage service owns its own commit"
|
|
- "admin.user_deleted audit written with session.flush() before session.delete(user) to keep user FK intact"
|
|
- "test_admin_impersonation_not_found updated to accept 405 in addition to 404/422 (Rule 1 auto-fix)"
|
|
|
|
metrics:
|
|
duration: "~25 minutes"
|
|
completed_at: "2026-05-25T19:51:37Z"
|
|
tasks_completed: 2
|
|
files_modified: 4
|
|
---
|
|
|
|
# Phase 4 Plan 7: Audit Log Backfill, SEC-08 CloudConnectionOut, SEC-09 Delete-User Summary
|
|
|
|
## One-liner
|
|
|
|
Audit log backfill for all D-13 event categories (auth, document, admin), SEC-08 credentials_enc exclusion via CloudConnectionOut Pydantic model, SEC-09 MinIO object cleanup in delete-user endpoint.
|
|
|
|
## What Was Built
|
|
|
|
### Task 1: Audit Log Backfill — auth.py and documents.py
|
|
|
|
Added `from services.audit import write_audit_log` to both files and backfilled write_audit_log calls into 8 auth handlers and 2 document handlers:
|
|
|
|
**auth.py (9 write_audit_log calls):**
|
|
- `auth.login_failed` — login with wrong credentials; metadata_=None (no PII, T-04-07-01)
|
|
- `auth.login` — successful login; metadata_={"totp_used": bool}
|
|
- `auth.backup_code_used` — backup code consumed during login
|
|
- `auth.logout` — refresh token revoked; user_id extracted from RefreshToken row
|
|
- `auth.sign_out_all` — all sessions revoked; metadata_={"sessions_revoked": count}
|
|
- `auth.password_changed` — password updated by user
|
|
- `auth.totp_enrolled` — TOTP enabled and backup codes generated
|
|
- `auth.totp_revoked` — TOTP disabled
|
|
|
|
Added `request: Request` parameter to `change_password` and `disable_totp` (previously missing).
|
|
|
|
**documents.py (2 write_audit_log calls):**
|
|
- `document.uploaded` — upload confirmed; metadata_={"size_bytes": N, "storage_backend": "minio"} — NO filename, NO extracted_text (T-04-07-02)
|
|
- `document.deleted` — document deleted; metadata_={"size_bytes": N}
|
|
|
|
Added `request: Request` parameter to `confirm_upload` and `delete_document`.
|
|
|
|
### Task 2: SEC-08, SEC-09, Admin Audit Writes — admin.py
|
|
|
|
**CloudConnectionOut (SEC-08):**
|
|
```python
|
|
class CloudConnectionOut(BaseModel):
|
|
"""SEC-08: credentials_enc deliberately excluded."""
|
|
id: str
|
|
provider: str
|
|
display_name: str
|
|
status: str
|
|
connected_at: datetime
|
|
model_config = {"from_attributes": True}
|
|
```
|
|
Model placed in admin.py for Phase 5 import-ready use. credentials_enc absent by whitelist.
|
|
|
|
**Admin audit log writes (5 additional write_audit_log calls):**
|
|
- `admin.user_created` — new user created by admin
|
|
- `admin.user_deactivated` — user deactivated
|
|
- `admin.user_activated` — user reactivated
|
|
- `admin.quota_changed` — metadata_={"old_bytes": N, "new_bytes": M}
|
|
- `admin.ai_provider_assigned` — metadata_={"provider": ..., "model": ...}
|
|
|
|
**DELETE /api/admin/users/{user_id} (SEC-09):**
|
|
- Auth: `get_current_admin`
|
|
- Guard: 400 if target user is admin (T-04-07-04)
|
|
- Collects all Document rows for user via `select(Document).where(Document.user_id == user_id)`
|
|
- Calls `get_storage_backend().delete_object(doc.object_key)` for each — try/except (best-effort)
|
|
- Writes `admin.user_deleted` audit log via `session.flush()` BEFORE `session.delete(user)`
|
|
- Cascades delete to quota, documents, refresh_tokens via FK ON DELETE CASCADE
|
|
- Returns 204 No Content
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] test_admin_impersonation_not_found: 405 not accepted**
|
|
- **Found during:** Task 2 test run
|
|
- **Issue:** Adding `DELETE /api/admin/users/{user_id}` caused FastAPI to return 405 Method Not Allowed for GET requests to `/api/admin/users/impersonate` (previously 422 UUID parse error). The test only accepted {404, 422}.
|
|
- **Fix:** Updated assertion to accept 405 in addition to 404/422. Security invariant is still met: there is no GET impersonation endpoint. 405 means the path is handled but only via DELETE — which is the user-delete endpoint, not impersonation.
|
|
- **Files modified:** backend/tests/test_admin_api.py
|
|
- **Commit:** 8e6005c
|
|
|
|
## Threat Model Coverage
|
|
|
|
| Threat ID | Status |
|
|
|-----------|--------|
|
|
| T-04-07-01 | Mitigated: login_failed metadata_=None, no PII |
|
|
| T-04-07-02 | Mitigated: document audit contains only size_bytes and storage_backend |
|
|
| T-04-07-03 | Mitigated: CloudConnectionOut model excludes credentials_enc |
|
|
| T-04-07-04 | Mitigated: DELETE /users/{id} returns 400 for admin accounts |
|
|
| T-04-07-05 | Mitigated: MinIO objects deleted before DB record in delete-user |
|
|
| T-04-07-06 | Mitigated: 8 auth event types + 2 doc events + 5 admin events logged |
|
|
|
|
## Verification Results
|
|
|
|
- `pytest tests/test_auth_api.py tests/test_documents.py -x -v` — 43 passed, 5 xfailed
|
|
- `pytest tests/test_admin_api.py tests/test_security.py -x -v` — 18 passed, 2 xfailed
|
|
- `pytest tests/ -x` — 92 passed, 1 failed (pre-existing test_extract_docx missing python-docx), 3 skipped, 10 xfailed
|
|
- `grep -c "write_audit_log" backend/api/auth.py` → 9 (>= 6 required)
|
|
- `grep -c "write_audit_log" backend/api/documents.py` → 3 (>= 2 required)
|
|
- `grep -c "write_audit_log" backend/api/admin.py` → 6 (>= 4 required)
|
|
- No email/password in login_failed metadata confirmed by grep
|
|
- No filename/extracted_text in document audit calls confirmed by grep
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- backend/api/auth.py exists and contains write_audit_log import and 9 calls
|
|
- backend/api/admin.py exists and contains CloudConnectionOut, delete_user endpoint, 6 write_audit_log calls
|
|
- backend/api/documents.py exists and contains write_audit_log import and 3 calls (import + 2 calls)
|
|
- Commits e451b16 and 8e6005c exist in git log
|