diff --git a/CHANGELOG.md b/CHANGELOG.md index 38b3b9c..3c20620 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,3 +24,39 @@ 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`, `group_permission`, `user_group`, `engagement_member`, `ttp`, + `ttp_version`, `scenario`, `scenario_step`, `run`, `run_step`, `run_step_cleanup`, + `detection`, `evidence`, `report`, `soc_session`, `audit_log`. +- Alembic baseline migration `202605210001_initial_schema`: every table + enum + index + + idempotent `audit_log` grants for the write-only Postgres role. +- `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 + +- **D-008** `ttp_version` table re-introduced alongside `run.snapshot_json` (overrides H32). +- **D-009** `audit_log` hash chain (`prev_hash` / `row_hash`) shipped v1. +- **D-010** 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 2888fa9..3b1a8cb 100644 --- a/tasks/spec-decisions.md +++ b/tasks/spec-decisions.md @@ -56,3 +56,30 @@ Never re-displayable. **Decision.** Reverse proxy (Caddy + TLS + IP allowlist) handled by existing RT infrastructure. Mimic ships an HTTP listener on localhost only; the deployment playbook wires it behind the existing proxy. + +### D-008 — `ttp_version` table (overrides spec H32) +**Context.** Spec H32 reads "snapshot of replayability = `run.snapshot_json` only +(no separate `ttp_version` table)". The kickoff backlog (B0.2, team-lead +directive) explicitly re-introduces the table. +**Decision.** Both coexist: +- `ttp_version` (immutable, hash-stamped) tracks every publication / edit of a + TTP. Used by importers, audit log, and TTP diffs. +- `run.snapshot_json` remains the source of truth for replay independence (each + run carries a self-contained snapshot of the resolved TTPs). +Net cost: one extra table for clear semantics — TTP lineage and run replay +solve different problems. + +### D-009 — 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. +**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) and avoids a destructive migration later. + +### D-010 — Type-hinting strategy for the ORM +**Context.** Flask-SQLAlchemy 3 rejects per-base `type_annotation_map`. +**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 9dfd1c9..51d0327 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -2,23 +2,26 @@ 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. `ttp_version`, - `c2_credential`, `user`, `group`, `user_group`, `permission`, `group_permission`, - `soc_session`, audit_log with write-only Postgres role). -- [ ] 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. +- [x] B0.3 — SQLAlchemy 2 typed mapped classes for every spec §8 aggregate (engagement, + host, user/group RBAC, ttp/ttp_version, 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), `{{ 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: 38 unit tests passing, integration scaffold ready + (testcontainers Postgres + `/healthz` smoke). ## Frontend (`ux-frontend`)