|
| 1 | +# MORI SOC — API Design |
| 2 | + |
| 3 | +FastAPI (Python 3.12). `server.py` is a thin orchestrator that assembles a `RouteContext` and registers ~16 domain modules under [`src/mori_soc/api/routes/`](../src/mori_soc/api/routes/). OpenAPI is served at `/docs`. |
| 4 | + |
| 5 | +## Auth & access model |
| 6 | + |
| 7 | +| Mechanism | Where | Notes | |
| 8 | +|---|---|---| |
| 9 | +| **Session cookie** `mori_session` | browser `/ui`·`/admin` | issued by `POST /auth/login` (httponly, 7-day); local users + optional LDAP bind | |
| 10 | +| **RBAC roles** | per request | `admin · security · monitor · auditor · helpdesk · user`. Risk/controls/evidence = `admin·security`; infra/help-desk see only their own servers | |
| 11 | +| **Ingest token** | `POST /ingest/*` | `MORI_INGEST_TOKEN` via `Authorization: Bearer` or `X-MORI-Token` (session fallback) | |
| 12 | +| **Language** | any | `?lang=`/`mori_lang` cookie → KO/EN response where localized (e.g. `/guides`) | |
| 13 | + |
| 14 | +**Conventions** — JSON in/out; `200` ok · `400` bad body · `401` unauth · `403` role · `404` missing · `503` backend (e.g. ingest needs `MORI_DATABASE_URL`). Reads hit the query backend live per request; writes are cache-aside + write-through to Postgres. |
| 15 | + |
| 16 | +--- |
| 17 | + |
| 18 | +## Endpoints by domain |
| 19 | + |
| 20 | +### Auth · profile |
| 21 | +`GET /login` · `POST /auth/login` · `GET /auth/logout` · `GET /auth/me` · `GET|POST /auth/profile` · `POST /auth/signup-request` · `GET /auth/signup-requests` · `PATCH /auth/signup-requests/{req_id}` |
| 22 | + |
| 23 | +### Pages · health |
| 24 | +`GET /` · `GET /ui` · `GET /admin` · `GET /catalog` · `GET /health` (insecure-config warning when demo creds/no token) |
| 25 | + |
| 26 | +### Dashboard · query |
| 27 | +`GET /dashboard/summary` · `POST /query` · `POST /interpret` (NLQ) · `GET|POST /dashboard/preferences` · `GET|POST /admin/dashboard/preferences` · `GET /admin/dashboard/user-preferences` · `DELETE /admin/dashboard/user-preferences/{username}` |
| 28 | + |
| 29 | +### Assets |
| 30 | +`GET /assets` (fleet+zabbix+trivy rollup) · `POST /assets/refresh` (on-demand poll: zabbix\|fleet\|wazuh\|trivy) · `GET|POST /assets/owners` · `DELETE /assets/owners/{hostname}` · `GET|PUT /assets/plans/{host_id}` · `GET /fleet/hosts` · `GET /zabbix/hosts` · `GET /trivy/vulnerabilities` |
| 31 | + |
| 32 | +### Alerts · Triage · Incidents |
| 33 | +`GET /alerts` · `PATCH /alerts/{alert_id}/triage` · `POST /alerts/{alert_id}/zabbix/suppress` · `POST /alerts/{alert_id}/zabbix/unsuppress` · `GET|POST /incidents` · `PATCH /incidents/{incident_id}` · `POST /incidents/{incident_id}/notes` |
| 34 | + |
| 35 | +### Vulnerabilities · Risk |
| 36 | +`GET /vulnerabilities/{vuln_id}/action` · `PUT /vulnerabilities/{vuln_id}/plan` · `PUT|DELETE /vulnerabilities/{vuln_id}/exception` · `GET|PUT /vulnerabilities/{vuln_id}/risk` (3×3 matrix) · `GET /vulnerabilities/risk-summary` · `GET|PUT /settings/risk` |
| 37 | + |
| 38 | +### Compliance · Control catalog |
| 39 | +`GET /compliance/pdca` · `GET /compliance/pdca/pending.csv` · `GET /compliance/reports` · `GET /compliance/reports/{report_type}` · `GET /dashboard/evidence-gaps` · `GET /dashboard/host-remediation/{hostname}` · `GET /controls/tree` (incl. `coverage.review` reviewed/draft) · `GET /controls/detail/{id}` · `PUT /controls/status/{id}` · `POST /controls` · `DELETE /controls/{id}` · `POST /controls/import-nlp` · `GET|PUT /controls/claude-key` |
| 40 | + |
| 41 | +### Evidence (catalog) |
| 42 | +`GET /controls/detail/{id}/evidence.pdf` · `…/evidence.csv` · `GET /controls/evidence-bundle.zip?scope=mapped|all` · `GET|POST /controls/detail/{id}/evidence-records` · `POST …/evidence-records/auto` (dated live snapshot) · `DELETE …/evidence-records/{evidence_id}` · `GET|POST /controls/evidence-snapshot/config` · `POST /controls/evidence-snapshot/run` |
| 43 | + |
| 44 | +### Account governance |
| 45 | +`GET /accounts/overview` · `GET /accounts/overview.csv` · `GET /accounts/host/{host_key}` · `…/privileged` · `GET|POST /accounts/approvals` · `DELETE /accounts/approvals/{id}` · `POST /accounts/approval-requests` · `POST /accounts/approvals/{id}/approve|reject` · `GET|POST /accounts/view-roles` |
| 46 | + |
| 47 | +### Guides · settings · webhooks |
| 48 | +`GET /guides` · `GET /guides/{id}` (KO/EN by `?lang=`) · `PUT /guides/{id}` · `GET|POST /webhooks` · `DELETE /webhooks/{id}` · `POST /webhooks/{id}/test` |
| 49 | + |
| 50 | +### Admin: audit · RBAC · LDAP |
| 51 | +`GET /admin/action-audit-log` · `POST /admin/action-audit-log` · `GET /admin/audit-log` · `GET /admin/logs` · `GET|POST /admin/role-permissions` · `GET /admin/user-tab-permissions` · `POST|DELETE /admin/user-tab-permissions/{username}` · `GET /admin/ldap/status` · `GET|POST /admin/ldap/users` · `POST /admin/ldap/users/{uid}/password|role` · `DELETE /admin/ldap/users/{uid}` |
| 52 | + |
| 53 | +### Ingest (token-gated, push) |
| 54 | +| Endpoint | Source → | Effect | |
| 55 | +|---|---|---| |
| 56 | +| `POST /ingest/trivy` | Trivy scan JSON | vulnerabilities + evidence | |
| 57 | +| `POST /ingest/wazuh` | Wazuh alert(s) | → Alert Triage queue | |
| 58 | +| `POST /ingest/evidence` | CSOP before/after diff | evidence envelope | |
| 59 | +| `POST /ingest/accounts` | osquery local accounts | `host_accounts` (governance) | |
| 60 | +| `GET /evidence` | — | list ingested evidence | |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +## Data flow (read-only evidence layer) |
| 65 | + |
| 66 | +```mermaid |
| 67 | +flowchart LR |
| 68 | + subgraph SRC["Source tools (unchanged)"] |
| 69 | + ZBX[Zabbix]:::s |
| 70 | + FLEET[Fleet / osquery]:::s |
| 71 | + WZ[Wazuh]:::s |
| 72 | + TRV[Trivy]:::s |
| 73 | + LOKI[Loki]:::s |
| 74 | + end |
| 75 | + subgraph MORI["MORI — evidence layer"] |
| 76 | + POLL[Pollers / ingest]:::m --> DB[(PostgreSQL<br/>schema 001-011)]:::db |
| 77 | + DB --> API[FastAPI /ui]:::m |
| 78 | + API --> JUDGE[Triage - Risk - Control status]:::m |
| 79 | + JUDGE --> EVID[Evidence PDF/CSV/ZIP + audit log]:::m |
| 80 | + end |
| 81 | + ZBX -->|"REST poll 30s"| POLL |
| 82 | + TRV -->|"token push / daily"| POLL |
| 83 | + WZ -->|"/ingest/wazuh"| POLL |
| 84 | + FLEET -.->|"Phase 3 poller"| POLL |
| 85 | + API -.->|"deep link"| GRAF[Grafana / Loki<br/>viewing layer]:::v |
| 86 | + JUDGE -->|"write-back L1-3"| ZBX |
| 87 | +
|
| 88 | + classDef s fill:#dbeafe,stroke:#2563eb,color:#111827 |
| 89 | + classDef m fill:#dcfce7,stroke:#16a34a,color:#111827 |
| 90 | + classDef db fill:#fef9c3,stroke:#a16207,color:#111827 |
| 91 | + classDef v fill:#f3f4f6,stroke:#6b7280,color:#111827 |
| 92 | +``` |
| 93 | + |
| 94 | +See also: [DB ERD](./DB_ERD.md) · [collection standards](./collection-standards.md) · [full reference](../README_FULL.md). |
0 commit comments