Operating Guide

The full operating manual for the SDSE platform. Start at the top if you have not used the platform before; jump to a heading if you have.

What the platform is

The SDSE platform — Spec-Driven Security Engineering — is the security delivery arm of the Qatar National Super App programme. It replaces the one chatbot pattern with a coordinated workforce of nine specialist agents, a curated control-framework library, and a tamper-evident evidence pipeline.

Three things make it different:

1. Specs, not opinions. Every claim a specialist agent produces is grounded in a written spec and cites the authority it rests on.
2. Workforce, not assistant. Each specialist sticks to its scope. A lead orchestrator routes work, and a red-team agent challenges deliverables before they reach a human.
3. Evidence-first. Every deliverable is paired with an artefact that lands in a WORM evidence bucket. Auditors can replay decisions.

Quick tour

The blue Get started button in the header opens the welcome modal at any time.

Workflows

Ingest a control framework

Adding a framework like NCA ECC or PDPPL so the compliance mapper can cite it.

1. Drop the framework PDF (or text export) into the staging uploads bucket.
2. The ingestion worker watches the bucket, extracts passages, and writes them to the pgvector store.
3. The Compliance Mapper agent can then crosswalk controls in that framework against the rest of the library.

The ingestion job records its run-ID in the evidence bucket. If you don't see your framework in the dashboard within a few minutes, check the worker logs.

Query an agent

Each specialist agent is reachable from its detail page (live chat interface ships next). A typical session looks like:

1. State the question in spec form — "propose a CMEK pattern for our Cloud SQL deployment that satisfies NCA ECC 1-4-1".
2. The lead orchestrator routes to the right specialist.
3. The specialist drafts its answer with citations.
4. The red-team agent reviews and flags weaknesses.
5. You see the final answer plus any review notes.

Collect evidence

The Evidence Collector agent gathers configuration snapshots, audit logs, and screenshots into a tamper-evident bundle:

# A typical evidence pull (illustrative)
sdse evidence collect --scope cloudsql --framework nca-ecc

Bundles are written to the staging sdse-stg-evidence-* bucket, which is configured with a 7-year retention lock.

Architecture in one breath

• Frontend: Next.js 15, served by GKE.
• Backend: FastAPI on GKE, talks to Cloud SQL (Postgres + pgvector, CMEK, private IP).
• Worker: Ingestion worker on GKE, reads from the uploads bucket and writes to pgvector.
• CI/CD: GitHub Actions with Workload Identity Federation. No long-lived JSON keys.
• Public ingress: Static IP → Google-managed TLS cert → Cloud Armor (SQLi, XSS, LFI, RCE, rate limit) → GKE Ingress.

Environments

The platform is engineered so the prod migration is a re-binding of credentials and project IDs — not an architectural rewrite.

Operating tips

• The dashboard polls /api/health every 15 seconds. If you see Unreachable, check GKE pod status before assuming the platform is down.
• Agent activity figures on the dashboard are synthetic in staging. They become live once the agent workforce is wired in.
• Red-team flags are not bugs — they are by design. Every flag is logged so the human reviewer can decide what to do with it.

Getting help

• Report an issue: use the Get started button to re-open the welcome guide.
• For platform-level issues, file a ticket in the engagement tracker (Jira / GitHub Issues depending on your team).
• The lead-orchestrator agent itself can answer most "what does this platform do" questions.

This guide is rendered from embedded markdown — to edit, modify frontend/src/app/help/page.tsx.