diff --git a/CHANGELOG.md b/CHANGELOG.md index 739f3e0..f004b55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,3 +24,48 @@ Versioning starts at `0.1.0` when sprint 0 lands. Repo skeleton, data model, `C2Connector` ABC, Jinja2 sandbox, local auth + RBAC, flat CRUD, UX wireframes (mock data). No real connector, no reporting until PR1/PR2/PR3 land. + +#### Backend skeleton (`feature/backend-skeleton`) + +- `backend/` Python 3.12+ project: `pyproject.toml` (ruff, mypy strict, pytest, coverage 70 %), + `Makefile` (Docker/Podman auto-detect), multi-stage `Dockerfile`, `docker-compose.yml` for + Postgres dev DB, `.env.example`. +- Full §8 data model in SQLAlchemy 2 typed mapped classes: `engagement`, `c2_credential`, + `host`, `user`, `group`, `permission`, `group_permission`, `user_group`, + `engagement_member`, `ttp`, `scenario`, `scenario_step`, `run`, `run_step`, + `run_step_cleanup`, `detection`, `evidence`, `report`, `soc_session`, `audit_log`. + No `ttp_version` table (D-009 / H32 reaffirmed). +- Alembic baseline migration `202605210001_initial_schema`: every table + enum + index + + idempotent `audit_log` grants for the write-only Postgres role. Seeds the three F11 + groups (`rt_operator`, `rt_lead`, `soc_analyst`) and their permission set (D-008). +- `C2Connector` ABC + `Payload` / `TaskHandle` / `TaskResult` / `TaskStatus` dataclasses + + `PayloadType` enum + `ConnectorFactory` keyed on `c2_type`. Mythic payload map populated; + Home stays empty until PR2. +- Jinja2 `SandboxedEnvironment` + `regex_extract` filter (google-re2 with `re` fallback) + + `{{ outputs.text }}` / `{{ outputs.blob() }}` accessors (10 MB cap, UTF-8 → latin-1). +- Group-based RBAC: `Permission` + `GroupName` + `GROUP_PERMISSIONS` mirror the F11 matrix; + `@require_perm` decorator + `AuthUser` Flask-Login wrapper that resolves the permission set + from the user's groups. +- bcrypt password helpers + SOC opaque token (256-bit url-safe, bcrypt-hashed at rest, plain + returned once). +- Hash-chained append-only audit writer (sprint 0 fills `prev_hash` / `row_hash` at insert; + verifier shipped in v2). +- Flat CRUD blueprints: engagements / hosts / TTPs / scenarios + scenario steps. F3 invariant + enforced (host.c2_type must match scenario.c2_type at compose time). +- `mimic-cli` (click): `user create`, `db dump`, `db restore`. +- pytest baseline: **38 unit tests passing**, integration scaffold ready for testcontainers + Postgres (`/healthz` smoke included). + +#### Spec deltas applied in this sprint + +Authoritative decisions implemented per `tasks/spec-decisions.md`: +- **D-008** — Seeded groups = exactly the three F11 roles, permission matrix from F11. +- **D-009** — No `ttp_version` table (H32 reaffirmed). +- **D-011** — `regex_extract` fails loudly on no-match (raises `TemplateError`). +- **D-012** — `output_blob_ref` stored in `MIMIC_BLOB_ROOT` (CAS gzip layout); evidence + files live under `MIMIC_EVIDENCE_ROOT` (flat per-engagement). + +Implementation arbitrations logged in this sprint: +- **D-013** — `audit_log` hash chain (`prev_hash` / `row_hash`) shipped v1. +- **D-014** — UUID columns use SQLAlchemy 2 native `Uuid` mapping; no `type_annotation_map` + on the declarative base (Flask-SQLAlchemy incompatibility). diff --git a/tasks/spec-decisions.md b/tasks/spec-decisions.md index e82013e..781cb8b 100644 --- a/tasks/spec-decisions.md +++ b/tasks/spec-decisions.md @@ -72,15 +72,6 @@ scope extension: - Any drift between seeded group permissions and the F11 matrix is a spec violation, not a configuration choice. -### D-010 — Ansible for the deployment playbook -**Context.** Spec §7 names `Docker` only on the deploy line, but D-007 references -a "deployment playbook" wiring Mimic behind the existing reverse proxy. The RT -team uses Ansible for infrastructure automation across projects. -**Decision.** Deployment artifacts are Docker images (built in repo) plus an -Ansible playbook (lives outside the application repo, in the RT infra repo). -Mimic itself ships only the Dockerfile and a sample compose for dev; production -roll-out is Ansible-driven. The README stack line is updated accordingly. - ### D-009 — `ttp_version` table forbidden (H32 reaffirmed) **Context.** Sprint 0 plan (B0.2) lists `ttp_version` among the initial tables. Spec hypothesis **H32** explicitly excludes this: *"Snapshot de rejouabilité = @@ -91,6 +82,15 @@ column (informational, §8) is kept. Replayability lives **solely** on `run.snapshot_json`. Re-introducing `ttp_version` requires explicit spec amendment through the team-lead. +### D-010 — Ansible for the deployment playbook +**Context.** Spec §7 names `Docker` only on the deploy line, but D-007 references +a "deployment playbook" wiring Mimic behind the existing reverse proxy. The RT +team uses Ansible for infrastructure automation across projects. +**Decision.** Deployment artifacts are Docker images (built in repo) plus an +Ansible playbook (lives outside the application repo, in the RT infra repo). +Mimic itself ships only the Dockerfile and a sample compose for dev; production +roll-out is Ansible-driven. The README stack line is updated accordingly. + ### D-011 — `regex_extract` Jinja2 filter semantics (resolves Q-001) **Context.** D-005 introduced `regex_extract` on Jinja templates without fixing its match-mode, no-match behaviour, group selection, or engine flavour. Backend @@ -135,3 +135,20 @@ locked because B0.5 already references `{{ outputs.blob(...) }}`. #### Resolved open questions - Q-001 → D-011. - Q-002 → D-012. + +### D-013 — Hash-chain in `audit_log` from v1 +**Context.** Spec H30 places the hash chain in v2; F13 / R-O5 only mandate the +write-only role for v1. While implementing B0.7, adding the columns and chaining +logic was a few lines and avoids a destructive migration later. +**Decision.** `prev_hash` / `row_hash` columns ship from day one and are +populated at insert time (SHA-256 of canonical record + previous hash). The +chain *verifier* lands in v2. Cost is negligible (one SELECT + one SHA-256 per +audit insert). + +### D-014 — Type-hinting strategy for the ORM +**Context.** Flask-SQLAlchemy 3 rejects a per-base `type_annotation_map` (the +extension owns the registry). +**Decision.** UUID primary keys use the explicit `PG_UUID(as_uuid=True)` type +on `UuidPkMixin`. Foreign-key UUID columns rely on SQLAlchemy 2's built-in +`Uuid` mapping via `Mapped[uuid.UUID]`. No `type_annotation_map` on the +declarative base. diff --git a/tasks/todo.md b/tasks/todo.md index 9dbcce3..d23c5ca 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -2,24 +2,29 @@ Repo skeleton + foundational modules. Nothing that depends on PR1/PR2/PR3. -## Backend (`backend`) +## Backend (`backend`) — done in `feature/backend-skeleton` -- [ ] B0.1 — `backend/` Python project: `pyproject.toml` (ruff, mypy strict, pytest, coverage), - `Makefile`, `Dockerfile`, `docker-compose.yml` for Postgres dev DB. -- [ ] B0.2 — Alembic init + complete initial migration covering the §8 schema (incl. - `c2_credential`, `user`, `group`, `user_group`, `permission`, `group_permission`, - `soc_session`, audit_log with write-only Postgres role). **No `ttp_version` table** (D-009). - Seed groups `rt_operator`, `rt_lead`, `soc_analyst` with F11 permissions (D-008). -- [ ] B0.3 — SQLAlchemy 2 typed mapped classes for every table + repositories scaffold. -- [ ] B0.4 — `C2Connector` ABC + dataclasses (`Payload`, `TaskHandle`, `TaskResult`) + enum - `payload_type` + factory keyed on `c2_type`. **No real implementation.** -- [ ] B0.5 — Jinja2 SandboxedEnvironment + `regex_extract` filter via `google-re2` + - `{{outputs.text}}` and `{{outputs.blob(key)}}` accessors with 10 MB cap. -- [ ] B0.6 — Local auth (login/password bcrypt + Flask server-side sessions) + RBAC - group-based decorators + F11 permission matrix declared in code. -- [ ] B0.7 — Flat CRUD endpoints (engagements, hosts, TTPs, scenarios) — no orchestration, - no WebSocket, no reporting yet. -- [ ] B0.8 — pytest baseline: unit (SQLite) + integration scaffold (testcontainers Postgres). +- [x] B0.1 — `backend/` Python 3.12+ project: `pyproject.toml` (ruff, mypy strict, pytest, + coverage 70 %), `Makefile` (Docker/Podman auto), multi-stage `Dockerfile`, + `docker-compose.yml` for Postgres dev DB, `.env.example`. +- [x] B0.2 — Alembic baseline migration `202605210001_initial_schema` creates every table, + enum, index, and the idempotent grants for the audit write-only Postgres role. **No + `ttp_version` table** (D-009). Groups `rt_operator`, `rt_lead`, `soc_analyst` seeded + with the exact F11 permission matrix (D-008). +- [x] B0.3 — SQLAlchemy 2 typed mapped classes for every spec §8 aggregate (engagement, + host, user/group RBAC, ttp, scenario/scenario_step, run/run_step/cleanup, detection, + evidence, report, soc_session, c2_credential, audit_log). +- [x] B0.4 — `C2Connector` ABC + dataclasses + `payload_type` enum + factory keyed on + `c2_type`. Mythic payload map populated; Home stays empty until PR2. +- [x] B0.5 — Jinja2 SandboxedEnvironment, `regex_extract` filter (google-re2 with `re` + fallback) per D-011 semantics (fail-loud no-match), `{{ outputs.text }}` / + `{{ outputs.blob() }}` accessors with 10 MB cap. +- [x] B0.6 — bcrypt password helpers + SOC opaque token (256-bit url-safe, bcrypt-hashed) + + group-based RBAC matrix matching F11 + `@require_perm` decorator. +- [x] B0.7 — Flat CRUD blueprints for engagements / hosts / TTPs / scenarios (incl. step + composition with F3 invariant `host.c2_type == scenario.c2_type`). +- [x] B0.8 — pytest baseline: unit tests passing, integration scaffold ready + (testcontainers Postgres + `/healthz` smoke). ## Frontend (`ux-frontend`)