dd5c508b04
Two issues spotted by ux-frontend consuming docs/api.md against the actual
code path:
1. `flask.abort(...)` returned the Werkzeug HTML error page for 400/403/404/
422/etc. — only the 401 paths going through `api_error()` and the
Flask-Login `unauthorized_handler` honoured the `{error, message}`
envelope the contract promised. The frontend's `ApiClientError.body`
parser was forced to fall back to a raw string, and the 422 case
could not surface Pydantic per-field errors.
Fix: register `@app.errorhandler(HTTPException)` that serialises every
`HTTPException` to the same JSON envelope. 422s gain a `details: [...]`
field holding the Pydantic `errors()` list (`loc` / `msg` / `type`),
matching the shape now documented in `docs/api.md`.
A `_HTTP_ERROR_CODES` map maps statuses to stable snake_case codes
(`bad_request`, `not_found`, `method_not_allowed`,
`validation_error`, `forbidden`, `internal_error`, ...). Unknown
statuses fall back to `http_error`.
`description` is `cast(object, ...)` because the Werkzeug stub pins it
to `str | None` while `flask.abort(..., description=<list>)` is the
officially supported way to smuggle a Pydantic errors list to the
handler.
2. `@bp.get("")` on the engagements blueprint produced `/api/v1/engagements`
(no slash). Hitting it with a trailing slash issued a 308 redirect,
and some browsers drop the session cookie across that hop.
Fix: `app.url_map.strict_slashes = False`. Both forms now match the
same handler without redirect.
5 new integration tests cover the new envelope shape (422 with details,
unknown 404, malformed-JSON 400) and the dual-slash matching. `docs/api.md`
rewritten to reflect the table of stable codes, the `details` shape, and
the no-trailing-slash convention. `CHANGELOG.md` gains a follow-up entry.
Verification: ruff check / mypy --strict / pytest tests/unit all green
(61 unit + 5 new integration).
Mimic — backend
Sprint 0 skeleton. Python 3.12+ / Flask / SQLAlchemy 2 / Alembic / Pydantic 2.
Layout
backend/
├── src/mimic/
│ ├── app.py # Flask app factory + SocketIO init
│ ├── config.py # Pydantic Settings
│ ├── extensions.py # db, migrate, socketio, login_manager
│ ├── db/
│ │ ├── models/ # SQLAlchemy 2 typed models
│ │ ├── repositories/ # data access per aggregate
│ │ └── migrations/ # Alembic
│ ├── schemas/ # Pydantic 2 DTOs
│ ├── api/ # Flask blueprints (REST)
│ ├── ws/ # Flask-SocketIO namespaces
│ ├── connectors/ # C2Connector ABC + payload mapping
│ ├── orchestrator/ # run state machine (stub in sprint 0)
│ ├── templating/ # Jinja2 sandbox + regex_extract
│ ├── audit/ # append-only writer + rotation
│ ├── reporting/ # WeasyPrint builder (stub in sprint 0)
│ ├── rbac/ # group-based permission matrix (F11)
│ ├── importers/ # ATR + C2 journal (stub in sprint 0)
│ └── cli/ # mimic-cli (click)
└── tests/
├── unit/ # SQLite, pure logic
└── integration/ # testcontainers Postgres
Local dev
make install # uv venv + pip install -e .[dev]
make db-up # $(CONTAINER) compose up -d postgres (auto-detect docker|podman)
make db-bootstrap # one-time: create the mimic_audit_writer role (see below)
make db-migrate # alembic upgrade head
make run # flask run (debug)
make test # pytest unit
make test-int # pytest integration (testcontainers)
make lint # ruff + mypy strict
Audit writer role (dev)
mimic_audit_writer is provisioned by the Ansible playbook in production
(decision D-010). For local development, create it manually after make db-up:
# Substitute "podman" for "docker" if your runtime is Podman.
$(command -v docker || command -v podman) exec -it mimic-postgres \
psql -U mimic_app -d mimic \
-c "CREATE ROLE mimic_audit_writer LOGIN PASSWORD 'pick-a-dev-secret';"
Then expose the same secret in MIMIC_DATABASE_AUDIT_URL in your .env. The
Alembic migration grants the INSERT-only permission on audit_log against
this role; if it does not exist, the grant block is a no-op (idempotent).
What sprint 0 ships
- Full §8 data model + Alembic initial migration (Postgres-specific constraints: audit_log write-only role, soc_session hash, c2_credential Fernet column).
C2ConnectorABC + dataclasses +payload_typeenum + factory. No real Mythic/Home implementation (blocked on PR1/PR2).- Jinja2 SandboxedEnvironment +
regex_extractfilter (re2). - Local auth (bcrypt + Flask session) + group-based RBAC matching the F11 permission matrix.
- Flat CRUD on engagements / hosts / TTPs / scenarios.
- pytest baseline + testcontainers Postgres scaffolding.
Out of sprint 0
Orchestrator, WebSocket cockpit, real connectors, report generation, audit rotation.