admin / Strike

# StrikeXi v2 — NCSC CAF Cyber Maturity Assessment Platform

An enterprise-grade, fully containerised web application for conducting Cyber
Maturity Assessments against the **NCSC Cyber Assessment Framework (CAF)**.
It scores weighted responses, auto-generates an actionable remediation roadmap,
and exports a professional PDF report.

> **This is Version 2.** It runs alongside v1 (frontend on **:8081**, separate
> containers/volumes) and adds everything below **without removing any v1
> feature**.

---

## What's new in v2

1. **Self-service signup** — a public **Create an account** page on the login
   screen. New sign-ups get the new **`user`** role and capture **Surname,
   First Name, Company Name, Email Address, Contact Number**, plus a chosen
   **username** and **password**. Password policy: **≥ 8 chars, ≥ 1 capital
   letter, ≥ 1 special character**. **MFA is enforced on first login** (the
   account is created MFA-required and is routed straight to enrolment).
   - `user`-role accounts can **only see assessments they create** — never
     anyone else's.
2. **Admin user visibility** — the Users screen shows an **Account type** column
   distinguishing **Self-service signups** from **Admin-created** users, plus
   their profile details (company, email, contact).
3. **Risk Assessment Summary** — a new report section that converts the
   maturity responses into a residual-**risk** view (overall rating, per-
   objective risk, prioritised **key risk areas**, and a narrative). Shown in
   the results UI **and** included in the exported **PDF**.
4. **Admin can delete assessments** — a Delete action on the dashboard
   (admin-only), cascading to answers/scores/roadmap.
5. **Admin Users Report** — export **all users** (admin-created + self-service)
   with full details as **PDF or CSV** from the Users screen (admin-only).

---

## 1. Architecture & Tech Stack

| Layer      | Technology                              | Container          |
|------------|-----------------------------------------|--------------------|
| Frontend   | HTML + CSS + vanilla JS (SPA), Nginx    | `strikexi-frontend`|
| Backend    | Python **FastAPI** + SQLAlchemy + JWT   | `strikexi-backend` |
| PDF engine | WeasyPrint (HTML/CSS → PDF, inline SVG) | (in backend)       |
| Database   | **PostgreSQL 16**                       | `strikexi-db`      |

- Orchestrated with **Docker Compose**.
- **Named volumes** (`strikexi_pgdata`, `strikexi_reports`) persist data and
  generated reports across hypervisor reboots.
- Nginx serves the SPA and reverse-proxies `/api/*` to the backend.

### Directory layout

```
strikexi/
├── docker-compose.yml
├── .env.example
├── README.md
├── db/
│   ├── init/
│   │   ├── 01_schema.sql        # tables incl. principle/objective scores, remediation mappings + audit log
│   │   └── 02_seed.sql          # ALL 4 CAF objectives + 14 principles, weighted Qs, principle-specific remediations
│   └── sample_caf_questions.json
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app/
│       ├── main.py              # app, CORS, startup admin seed
│       ├── config.py
│       ├── database.py
│       ├── models.py            # SQLAlchemy ORM
│       ├── schemas.py           # Pydantic
│       ├── security.py          # bcrypt + JWT + audit helper
│       ├── scoring.py           # weighted scoring + remediation trigger engine
│       ├── pdf_report.py        # PDF report w/ SVG donut + bar charts
│       ├── itsm.py              # Jira/ServiceNow adapter stubs (future-proofing)
│       └── routers/
│           ├── auth.py          # login (2-step MFA) / logout / me
│           ├── users.py         # user administration + self-service password/MFA
│           ├── catalogue.py     # CAF questionnaire tree
│           ├── assessments.py   # CRUD, save/pause, complete, roadmap, PDF, ITSM push
│           └── audit.py         # audit log viewer
├── frontend/
│   ├── index.html
│   ├── nginx.conf
│   ├── css/app.css
│   └── js/app.js
└── docs/
    ├── build_user_guide.py
    └── StrikeXi_User_Guide.pdf
```

---

## 2. Build & Run

```bash
cd strikexi
cp .env.example .env          # then EDIT secrets (SECRET_KEY, passwords)
docker compose up -d --build
```

Then open:

- **Web UI:** http://localhost:8081  (v2; v1 stays on :8080)
- **Default login:** `admin` / value of `ADMIN_PASSWORD` in `.env`
- **New users:** click **Create an account** on the login page (self-service)

Useful commands:

```bash
docker compose logs -f backend     # tail backend logs
docker compose ps                  # container status
docker compose down                # stop (data kept in volumes)
docker compose down -v             # stop AND wipe data volumes
```

> First boot runs `db/init/*.sql` automatically to create the schema and seed
> the CAF taxonomy, weighted questions and remediation mappings. The backend
> seeds the bcrypt-hashed admin user on startup.

---

## 3. Core Functionality

- **Questionnaire engine** — covers **all 4 CAF Objectives (A–D) and all 14
  Principles** (A1–A4, B1–B6, C1–C2, D1–D2), served as a tree from
  `/api/catalogue`. See `db/sample_caf_questions.json` for the full list.
- **Weighted scoring** (`scoring.py`) — option score × question weight, rolled
  up to principle → objective → overall (0–100). Per-principle scores are
  snapshotted in `assessment_principle_scores` for the report breakdown.
- **Remediation mapping** — `remediation_mappings` links each of the 14
  principles to a **principle-specific** remediation with detailed mitigation
  guidance and a `threshold`; principles scoring below it automatically queue a
  `remediation_actions` row.
- **Save / pause / review** — assessments persist as `in_progress` or
  `completed` and are listed on the dashboard.

## 4. PDF Reporting & Roadmap

Before export the user confirms **Organisation Assessed** and **Date of
Assessment**. The PDF includes:

- Custom organisation name and date
- Overall maturity score (SVG donut) and per-objective scores (SVG bars)
- **Assessment summary / breakdown** — every assessed principle, grouped by
  objective, with score and status
- **Actionable Maturity Roadmap** — remediation steps ordered by priority, each
  referencing its Objective + Principle and giving detailed mitigation guidance

**Future-proofing:** roadmap items are modelled for ITSM export. `itsm.py`
provides a pluggable adapter interface with Jira/ServiceNow stubs, exposed via
`POST /api/assessments/{id}/push-itsm?system=jira`.

## 5. Security, Users & Auditing

- **Auth:** username/password login; bcrypt hashing; JWT bearer sessions with
  expiry. Three roles: **admin**, **assessor**, and **user** (v2 self-service).
  - **`user`** accounts (self-service signups) can only see assessments they
    create. **`admin`** sees everything; **`assessor`** sees their own.
- **Password policy (v2):** minimum 8 characters, at least one capital letter
  and at least one special character (enforced on signup, admin create, and
  self-service change).
- **First-login MFA (v2):** self-service accounts are created MFA-required and
  are routed to TOTP enrolment on their first sign-in before they can proceed.
- **User administration (admin)** — the **👥 Users** screen lets an admin:
  - **add** users (username, full name, temporary password, role),
  - **edit** users (role, enable/disable, force password change, reset
    password),
  - **delete** users (blocked for accounts that own assessments — disable
    instead), and
  - **reset** a user's MFA.
  - Guards prevent demoting/disabling/deleting the last active administrator.
- **Self-service (⚙ My Account)** — any user can **change their own password**
  and **set up / disable their own MFA**.
- **Multi-factor authentication (TOTP / RFC 6238)** — optional, compatible with
  Google Authenticator, Authy, 1Password, etc.
  - **Admin level:** mark MFA **required** for a user (forces enrolment) at
    creation or via edit, and reset a user's MFA. Required MFA can't be
    self-disabled.
  - **User level:** self-enrol from the account page (QR code + secret, confirm
    with a code).
  - Login becomes a **two-step flow** (password → 6-digit code) when MFA is on.
- **First-login hardening:** the seeded `admin` account is flagged
  *must change password*, forcing a real password to be set on first login.
- **Audit log:** records who did what — LOGIN_SUCCESS, LOGIN_FAILED,
  LOGIN_MFA_CHALLENGE, LOGIN_MFA_FAILED, LOGOUT, PASSWORD_CHANGED,
  MFA_SETUP_BEGIN, MFA_ENABLED, MFA_DISABLED, USER_CREATED, USER_UPDATED,
  USER_DELETED, USER_MFA_RESET, plus assessment/PDF/ITSM events — each with
  timestamp, **acting username** and source IP. Viewable in the UI (admins).

---

## API Quick Reference

| Method | Path                                   | Purpose                       |
|--------|----------------------------------------|-------------------------------|
| POST   | `/api/auth/signup`                     | **(v2)** Public self-service signup (`user` role) |
| POST   | `/api/auth/login`                      | Password step (JWT or MFA challenge) |
| POST   | `/api/auth/login/mfa`                  | Verify TOTP, obtain JWT       |
| GET    | `/api/auth/me`                         | Current user profile          |
| GET    | `/api/users`                           | List users (admin)            |
| GET    | `/api/users/report.csv`                | **(v2)** Users report — CSV (admin) |
| GET    | `/api/users/report.pdf`                | **(v2)** Users report — PDF (admin) |
| POST   | `/api/users`                           | Create user (admin)           |
| PATCH  | `/api/users/{id}`                      | Update user (admin)           |
| DELETE | `/api/users/{id}`                      | Delete user (admin)           |
| POST   | `/api/users/{id}/mfa/reset`            | Reset a user's MFA (admin)    |
| POST   | `/api/users/me/password`               | Change own password           |
| POST   | `/api/users/me/mfa/setup`              | Begin own MFA enrolment       |
| POST   | `/api/users/me/mfa/confirm`            | Confirm + enable own MFA      |
| POST   | `/api/users/me/mfa/disable`            | Disable own MFA               |
| GET    | `/api/catalogue`                       | CAF questionnaire tree        |
| GET    | `/api/assessments`                     | List assessments              |
| POST   | `/api/assessments`                     | Create (start) assessment     |
| DELETE | `/api/assessments/{id}`                | **(v2)** Delete assessment (admin) |
| GET    | `/api/assessments/{id}/risk`           | **(v2)** Risk assessment summary |
| PUT    | `/api/assessments/{id}/answers`        | Save / pause answers          |
| POST   | `/api/assessments/{id}/complete`       | Score + trigger remediations  |
| GET    | `/api/assessments/{id}/roadmap`        | Ordered remediation roadmap   |
| POST   | `/api/assessments/{id}/report`         | Confirm meta + generate PDF   |
| GET    | `/api/assessments/{id}/report/download`| Download PDF                  |
| POST   | `/api/assessments/{id}/push-itsm`      | (Stub) push roadmap to ITSM   |
| GET    | `/api/audit`                           | Audit log                     |

---

## Notes

- The seed includes a **foundational subset** of CAF principles/questions to
  demonstrate the engine end-to-end. Add more rows to `db/init/02_seed.sql`
  (or via the DB) to cover the full framework — no code changes required.
- Always change default secrets before any non-local deployment.