MiniSOC

MiniSOC is a desktop-first SOC MVP built with React, FastAPI, SQLAlchemy, Alembic, and Electron. It supports two healthy operating modes:

• Web development mode for engineers working on the frontend and backend separately
• Desktop product mode for operators who launch one packaged app and get a local backend automatically

The project keeps the report-aligned MVP flows intact:

• Dashboard
• Alerts
• Incidents
• AI Analyst
• Users
• Admin runtime and audit visibility

What MiniSOC is

MiniSOC is a self-hosted security operations workspace for small teams, labs, demos, and desktop deployments. It lets an operator sign in, triage alerts, promote alerts into incidents, investigate incidents, request contextual AI analysis, manage users, and inspect audit activity.

It is not positioned as a managed SIEM platform or a multi-tenant enterprise SOC.

Supported modes

1. Web development mode

Use this when actively building the product.

• Frontend runs with Vite
• Backend runs with FastAPI
• PostgreSQL is the normal database target
• OpenSearch is optional for live alert ingestion
• Wazuh API is optional for manager and agent telemetry

2. Desktop development mode

Use this when testing the Electron shell locally.

• Electron starts first
• Electron launches the local backend automatically
• SQLite is used by default
• First-run setup is handled in-app
• OpenSearch and Wazuh remain optional

3. Packaged desktop mode

Use this for end users.

• The user installs MiniSOC and launches MiniSOC.exe
• Electron starts the embedded backend automatically
• Electron waits for backend health before opening the main UI
• The packaged build uses a bundled backend executable, not a shipped raw Python virtual environment
• SQLite is used by default unless explicitly overridden
• Desktop config is stored under the app userData directory

Architecture

flowchart TD
    Operator["Operator"] --> Renderer["React renderer"]
    Operator --> Electron["Electron main process"]
    Electron --> Renderer
    Electron --> Backend["Bundled FastAPI runtime"]
    Renderer -->|REST + WebSocket| Backend
    Backend --> DB[("PostgreSQL or SQLite")]
    Backend --> OS["Optional OpenSearch"]
    Backend --> WZ["Optional Wazuh API telemetry"]
    Backend --> AI["Optional AI providers"]

Loading

Runtime truth

Alert data

• OpenSearch is the preferred source for live alert documents
• If OpenSearch is unavailable, MiniSOC serves clearly labeled fallback alerts
• Alert assignment, status, and incident linkage are persisted locally in the application database

Wazuh integration

Wazuh is supported as an optional manager telemetry integration, not as a full standalone SIEM ingestion pipeline.

What is implemented:

• Wazuh manager URL configuration
• Optional Wazuh API username and password
• Manager status polling
• Agent summary polling
• Health visibility in the Admin module panel

What is not claimed:

• Full Wazuh event ingestion through the Wazuh API
• Deep Wazuh workflow orchestration
• Replacement of OpenSearch as the main alert document source

AI integration

MiniSOC supports contextual AI analysis for alerts and incidents.

• groq, gemini, and ollama are supported provider targets
• Ollama base URL is runtime-configurable
• AI write endpoints are limited to admin and analyst roles
• AI requests are optional and degrade safely if providers are not configured
• Playwright tests stub AI responses so E2E validation does not require external model access

Desktop security and config ownership

Desktop config ownership is intentionally split by responsibility:

Category	Source of truth
Desktop runtime settings	Electron-owned desktop config in userData/desktop-config.json
Sensitive desktop secrets	Electron safeStorage encrypted values when available
Effective backend runtime config in desktop mode	Environment variables injected by Electron into the embedded backend process
Web development config	Environment variables loaded by the backend and Vite
Session-scoped UI preferences	Frontend state stores

Sensitive desktop fields are no longer stored as plain JSON when OS-backed secure storage is available. MiniSOC now protects these at rest:

• JWT signing secret
• Seeded admin password
• Groq API key
• Gemini API key
• Wazuh API password

Important boundary:

• Desktop secrets are protected at rest in config storage
• The embedded backend still receives secrets through environment variables at process start
• That means MiniSOC desktop mode is appropriate for trusted single-user or single-workstation deployments, not hostile multi-user desktops
• If Electron safeStorage is unavailable, desktop setup fails closed unless MINISOC_ALLOW_INSECURE_DESKTOP_STORAGE=1 is set for local debugging only

See docs/security/desktop-security.md for the local threat model.

Auth and realtime security

• Access tokens now include a database-backed session identifier (jti)
• Default access-token lifetime is 12 hours and can be changed with ACCESS_TOKEN_EXPIRE_MINUTES
• /api/auth/logout revokes the current token session
• WebSocket connections use /api/auth/ws-ticket one-time tickets through the Sec-WebSocket-Protocol header instead of bearer tokens in query strings

First-run desktop experience

Desktop mode now includes a guided /setup flow before login when the local runtime has not been finalized yet.

The setup flow covers:

• administrator password initialization
• OpenSearch host and TLS settings
• optional Wazuh API telemetry settings
• AI provider configuration
• secure storage readiness

The seeded admin identity is now re-synchronized from desktop config on desktop startup, so password setup and password rotation actually take effect.

Repository layout

The repository is organized around the runtime surfaces that matter in production and development:

• src/ contains the React renderer, routed MVP pages, shared UI, and frontend tests
• backend/ contains the FastAPI app, migrations, seed logic, and backend tests
• electron/ contains the desktop shell, preload bridge, config encryption, and startup orchestration
• scripts/ contains build and test helpers used by npm scripts
• tests/e2e/ contains Playwright end-to-end coverage
• infra/docker/ contains optional local infrastructure helpers for PostgreSQL and SIEM dependencies
• docs/ contains architecture, security, reports, and archived planning material

Developer prerequisites

End users of the packaged desktop app do not need these tools. Developers do.

• Node.js 20+
• Python 3.11+
• PostgreSQL for normal web mode
• Optional OpenSearch and Wazuh services for integration testing

Environment variables

Use .env.example as the starting point for local development.

Important backend variables:

• DATABASE_URL
• SECRET_KEY
• DEMO_ADMIN_EMAIL
• DEMO_ADMIN_PASSWORD
• DEFAULT_AI_MODEL
• GROQ_API_KEY
• GEMINI_API_KEY
• OLLAMA_BASE_URL
• OPEN_SEARCH_*
• WAZUH_MANAGER_URL
• WAZUH_API_USERNAME
• WAZUH_API_PASSWORD
• WAZUH_API_VERIFY_SSL
• WAZUH_API_TIMEOUT_SECONDS

Important frontend variable:

• VITE_API_BASE_URL

Local development

Install dependencies

npm install
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
cd ..

Optional helper Compose files live under:

• infra/docker/postgres.compose.yml
• infra/docker/siem.compose.yml

Run web development mode

Start PostgreSQL and optional services however you prefer, then:

cd backend
.venv\Scripts\activate
alembic upgrade head
python -m app.seed
uvicorn app.main:app --reload

In a second terminal:

npm run dev

Run desktop development mode

npm run desktop:dev

That command:

• starts the Vite renderer
• launches Electron
• has Electron start the backend automatically
• uses SQLite by default for the desktop runtime

Build and packaging

Frontend production build

npm run build

Desktop backend runtime build

npm run desktop:backend:build

This produces a packaged backend executable under backend/dist-desktop/minisoc-backend/.

Desktop package build

npm run desktop:build

Desktop installer build

npm run desktop:dist

The packaged Electron app includes:

• compiled renderer assets from dist/
• Electron main and preload code
• a packaged backend runtime under release/.../resources/backend-runtime/

It does not rely on shipping backend/.venv as the desktop runtime contract.

Verification commands

Frontend unit tests

npm run test

Frontend type check

npm run typecheck

Frontend lint

npm run lint

Backend tests

npm run test:backend

Electron config regression tests

npm run test:electron-config

End-to-end tests

Install the browser once:

npx playwright install chromium

Then run:

npm run test:e2e

The Playwright harness boots:

• a disposable SQLite-backed backend
• Alembic migrations
• seed data
• a production preview renderer pointed at that backend

Covered flows include:

• login
• dashboard load
• alerts interaction
• incident workflow
• AI analyst basic flow
• admin page access

Security checks

npm audit --audit-level=moderate
bandit -r backend/app
pip-audit -r backend/requirements.txt

pip-audit is included in CI validation. If it is not installed locally, install it into a tooling environment rather than adding it to runtime dependencies.

Desktop smoke test

After npm run desktop:build, Windows developers can run:

npm run desktop:smoke

The smoke runner launches the unpacked desktop app with isolated MINISOC_USER_DATA_DIR, enables MINISOC_DESKTOP_SMOKE=1, waits for the startup path to write desktop-smoke.json, and exits.

Troubleshooting

Desktop backend stopped

Check the backend log file under the MiniSOC app data directory. The Admin runtime panel also shows the current config path and backend log path.

Desktop startup failed because the renderer could not be found

Rebuild the renderer and desktop package:

npm run build
npm run desktop:build

Secure storage unavailable

MiniSOC expects Electron safeStorage to be available for desktop secret protection. If it is not available, desktop setup will block completion unless you explicitly allow insecure local debugging with:

MINISOC_ALLOW_INSECURE_DESKTOP_STORAGE=1

Do not use that flag for distributed builds.

OpenSearch offline

MiniSOC continues to operate with fallback alerts. The runtime status panel will mark OpenSearch as degraded.

Wazuh offline or unconfigured

MiniSOC still works. Wazuh health is optional and only affects manager and agent telemetry visibility.

Production boundary

MiniSOC is now substantially more hardened than a local-only demo:

• packaged desktop backend runtime instead of a raw shipped virtual environment
• OS-backed secret protection at rest for desktop config when available
• first-run setup flow
• database-backed token revocation and one-time WebSocket tickets
• SSRF-oriented URL validation for local service integrations
• backend health-gated Electron startup
• single-instance Electron guard
• SQLite self-bootstrap in desktop mode
• fallback behavior when OpenSearch is unavailable
• explicit Wazuh telemetry scope
• Playwright coverage for core operator flows

For a “done forever” program or a full enterprise SOC as that term is usually understood, MiniSOC is not complete at that bar, and this repository does not claim to be. The list below records concrete gaps rather than implied completeness.

Still not claimed as complete enterprise hardening:

• no refresh-token auth system
• no tamper-proof secret isolation from same-user malware on the desktop host
• no full Wazuh ingestion pipeline
• no code signing or auto-update infrastructure yet
• no HA or remote orchestration layer

Key docs

• README.md
• docs/REPOSITORY_STRUCTURE.md
• docs/security/desktop-security.md
• docs/architecture/minisoc-complete-blueprint.md
• docs/reports/miniguard-report-action-summary.md