admin / Synapse-Cortex

# Synapse-Cortex v2

A React single-page ITSM app (tickets, assets, SLA policies, MFA, audit trail, NetscanXi asset/ticket import) backed by a pure-JSON FastAPI API, plus an **AI Remediation Module**: Claude selects a guardrailed remediation playbook for a ticket, a human approves it, and a pluggable (simulated by default) SSH executor runs it — with every step recorded permanently on the ticket.

See [docs/admin-guide.md](docs/admin-guide.md), [docs/user-guide.md](docs/user-guide.md), and [docs/api-quickstart.md](docs/api-quickstart.md) (PDF versions alongside each) for full usage docs.

## Running it

```sh
cp .env.example .env    # then edit the values below
docker compose up --build
```

Visit `http://localhost:8000/` — the SPA routes you to `/setup` automatically on a fresh database (there is no default login).

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | `cortex` / `cortex` / `synapse_cortex` | Bundled Postgres container credentials |
| `SECRET_KEY` | *(must be set)* | Session-cookie signing key. Also wraps the credential vault key at rest once one is created (see below) — use a long random value in any real deployment. |
| `ANTHROPIC_API_KEY` | unset | Fallback Claude API key for the AI investigator, used only when no key has been saved from Admin → AI Settings. Leave unset in any deployment where the AI module stays disabled — the app runs fine without it; only the investigate endpoint needs a key (from either source), and fails with a clear error (not a crash) if neither is configured. |
| `SSH_EXECUTOR` | `simulated` | `simulated` (default) logs what it would run and never opens a real connection. `paramiko` is a real-SSH swap-in point that is intentionally not implemented in this release. |
| `ALLOW_AUTO_APPROVE` | `false` | Gate for whether a `global_admin` may configure a playbook to skip the human approval click. A `tenant_admin` can never enable Auto-Approve regardless of this setting. |

See `.env.example` for the full file with comments.

The credential vault (the key that protects vaulted host credentials and the saved Claude API key) is **not** an environment variable in this release — a `global_admin` creates it exactly once from **Admin → Vault** in the running app. The generated key is shown to them a single time to copy elsewhere as a backup; there is no rotate/recreate endpoint anywhere, since replacing it would make everything already encrypted with it permanently undecryptable.

## Architecture

- **Backend**: FastAPI + SQLAlchemy 2.0 + Alembic, Postgres in production (SQLite fallback for local dev without Docker). Session-cookie auth via Starlette `SessionMiddleware`.
- **Frontend**: React 18 + TypeScript + Vite + React Router + TanStack Query + Tailwind CSS, in `frontend/`. Built and served as static files by the same FastAPI process in production — see the `Dockerfile`'s multi-stage build (`node` stage builds `frontend/dist`, copied into the final `python` image).
- **AI Remediation** (`app/ai/`): `investigator.py` (Claude tool-use, constrained to only the tenant's enabled playbooks), `guardrails.py` (pure functions enforcing target-OS + forbidden-command policy, independent of anything client-supplied), `executor.py` (pluggable SSH execution), `vault.py` (Fernet credential encryption; the vault key itself is generated via Admin → Vault and wrapped at rest with `SECRET_KEY`, never a bare environment variable).

## Local development (without Docker)

Backend:

```sh
cd Synapse-Cortexv2
python -m venv .venv && .venv/Scripts/activate  # or source .venv/bin/activate on macOS/Linux
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8440
```

Frontend (separate terminal — proxies `/api` to the backend port above; see `frontend/vite.config.ts` if you change the backend port):

```sh
cd Synapse-Cortexv2/frontend
npm install
npm run dev
```