feat(studio): web UI for raptor under packages/studio/

[yesnet0]

Summary

A FastAPI + Jinja2 web UI that reads and writes raptor's project data, triggers all pure-Python and Claude-backed command kinds via a SQLite job queue with live SSE log streaming, and renders raptor's full finding schema inline.

Launch from the repo root:

pip install -r requirements.txt     # includes studio's five new deps
python3 raptor_studio.py            # → http://127.0.0.1:8765

Developed in the open at https://github.com/yesnet0/raptor-studio over 27 commits with screenshots, tests, and a full PRD / changelog. This PR squashes that history for reviewability; the companion repo keeps the full timeline.

Feature surface

Browsing

• Dashboard with cross-project KPIs (or welcome state when no projects exist)
• Findings with raptor's full schema rendered inline — final_status / verdict × impact / Stage E feasibility (protections, exploitation_paths, chain_breaks tagged [source]/[binary], what_would_help) / PoC / Source-Sink-Flow proof
• Per-finding relevant-persona cards ranked by vuln category, tool, status, filename hints — capped at 4
• Per-run detail: kind-aware artifact summary with scan metrics, fuzzing report, validation bundle counts, inline CodeQL dataflow_*.svg diagrams, OSS-forensics walkthrough (evidence-source count, hypothesis timeline with confirmed/rejected badges, final forensic report — all rendered from markdown)
• Run diff: classify findings across two runs into new / carried / resolved with status + verdict transition arrows
• Exploits / Patches / Reports / Activity browsers, each walking the run dirs' well-known subdirs
• /personas global browser (10 expert briefs from tiers/personas/) + /glossary explaining schema terms
• Three-lane IA (source / binary / forensics) with type-adaptive sidebar

Triggering

• Create project (3 types, progressive-disclosure form)
• SQLite-backed job queue at $STUDIO_DATA_DIR/jobs.db + daemon-thread worker
• Pure-Python kinds: scan, agentic, codeql, fuzz → spawn python3 raptor_*.py
• Claude-backed kinds: understand, validate, oss-forensics, crash-analysis → wrap as bash -c "raptor project use <name> && claude -p '<slash-cmd>'"
• Live log streaming via SSE (/api/jobs/{id}/stream)
• Cancel SIGTERMs the process group
• Every trigger form shows the Equivalent CLI for reproducibility

Configuration

• /settings edits ~/.config/raptor/models.json in raptor's exact 4-role schema
• Env-var fallback status table (ANTHROPIC_API_KEY, etc.)
• RAPTOR_MAX_COST display

Schema preservation

Projects created via the UI write raptor's 7-field project.json schema exactly — indistinguishable from raptor project create. Studio-only metadata (type, source_repo, focus, vendor_report_url, language, corpus_dir) lives in $STUDIO_DATA_DIR/project-extras/<name>.json. Raptor's CLI ignores the sidecar. A round-trip test imports core/project/schema.py::validate_project and runs it against studio output.

Finding schema rendered verbatim from raptor's output — no reinterpretation. SARIF 2.1.0 fallback when no findings.json exists.

Tests

python -m pytest packages/studio/tests/
# 161 passed, 1 skipped

17 test modules including test_worker_integration which actually spawns subprocesses to cover completed / failed / cancelled / missing-executable paths end-to-end (~8.5s total).

Architecture

packages/studio/
├── app.py                  # FastAPI entry, ~20 routes
├── config.py               # env-driven runtime paths
├── services/               # 14 modules — readers, writers, classifiers,
│                           #   SQLite jobs, subprocess worker, SARIF,
│                           #   markdown render, personas, diff, forensics
├── templates/              # 23 Jinja2 templates, inline CSS, dark + light
├── static/                 # transparent-bg pixel-art velociraptor
├── tests/                  # 17 modules (incl. live subprocess)
├── scripts/                # seed_demo.py, process_avatar.py
└── docs/
    ├── PRD.md              # product scope + invariants
    ├── CHANGELOG.md        # commit-by-commit narrative
    └── UX_RECONCILIATION.md    # design narrative

Services are provider-agnostic and do not import raptor's runtime except services/raptor_version.py which imports RaptorConfig.VERSION directly. Root launcher raptor_studio.py mirrors the raptor_agentic.py / raptor_codeql.py / raptor_fuzzing.py pattern — sys.path bootstrap + argparse + uvicorn.run.

Non-goals (deliberate)

• Auth / multi-user — raptor is single-user by design
• Replacing the CLI — every UI action surfaces its Equivalent CLI so power users can reproduce outside the browser; the UI is additive, not a wall

New dependencies (requirements.txt)

fastapi>=0.110.0
uvicorn[standard]>=0.27.0
jinja2>=3.1.0
python-multipart>=0.0.9
markdown>=3.5

All pure-Python (uvicorn's C extensions are optional via httptools).

Test plan

• 161 pytest pass (incl. 4 live-subprocess worker tests)
• Schema round-trip: projects created via UI validated by raptor's validate_project
• TestClient smoke: /, /personas, /glossary, /api/health all 200
• File-serving route: path-traversal returns 403; disallowed extension returns 403
• SSE log stream closes cleanly on job terminal status
• Manual acceptance on maintainer's machine

[danielcuthbert]

I have tested this PR locally against the current repo state. The Studio work looks useful and the tests pass cleanly against the PR's declared base branch, but there are a few security issues I think we should fix before merging.

Validation performed:

• PR head test run: packages/studio/tests passed (160 passed, 1 skipped)
• Merge result into origin/dev: clean merge, Studio tests passed, project/startup tests passed
• FastAPI smoke checks passed for /, /personas, /glossary, and /api/health
• compileall passed for the Studio, project, and startup modules

Security risks to resolve:

1. CSRF / local web UI drive-by actions

   Studio has state-changing POST routes without CSRF tokens or origin checks:

   • packages/studio/app.py project settings route
   • packages/studio/app.py job creation route
   • packages/studio/app.py global settings route

   Even when bound to 127.0.0.1, a malicious website can submit cross-origin forms to localhost. It would not need to read the response to mutate settings or enqueue expensive / unsafe RAPTOR jobs. We should add CSRF protection and reject state-changing requests with missing or untrusted Origin / Sec-Fetch-Site headers.

2. Worker subprocesses inherit the full host environment

   packages/studio/services/worker.py currently builds the subprocess environment from os.environ. That bypasses RAPTOR's existing guidance for untrusted repo analysis. Studio-launched scans should start from RaptorConfig.get_safe_env(), add PYTHONUNBUFFERED=1, and only preserve required provider/API config deliberately.

3. Stored XSS via report Markdown rendering

   packages/studio/services/markdown_render.py allows raw inline HTML, and templates render the result with | md | safe. RAPTOR outputs can contain model text, repo-controlled content, vendor report snippets, findings, and other untrusted material. A malicious report could execute script inside Studio and then call same-origin Studio endpoints. We should sanitise rendered Markdown with something like bleach/nh3, or disable raw HTML and only render escaped content.

4. Remote binding is too easy for an unauthenticated UI

   raptor_studio.py allows --host 0.0.0.0, while Studio also exposes filesystem browsing APIs. If someone starts this on all interfaces, remote users on the network can interact with the UI and browse paths visible to the RAPTOR process. I would make non-loopback binding require an explicit --allow-remote flag with a strong warning, and ideally add authentication before supporting remote use.

5. Main branch integration is not clean yet

   The PR targets dev and merges cleanly there. It does not merge cleanly directly into current main; .gitignore conflicts. main also now uses pinned dependency style, while this PR adds loose requirements such as fastapi>=..., uvicorn>=..., and markdown>=.... If we want this to land on main, it needs a rebase/retarget pass and pinned dependencies in the current style.

In short: functionally this is in good shape against dev, but I would like the web UI security boundaries tightened before we merge it.

[yesnet0]

Hey gents, checking in on this - Can I help with anything?

[grokjc]

Picking up on what @danielcuthbert said... want to tag-team the security fixes?