WinSentinel v1.2.0

AI-assisted host forensics platform for live artifact collection, risk analysis, evidence export, and analyst workflows.

What Is Implemented

• Live host scraping (process, network, registry, event logs)
• Realtime live-scan progress API (GET /api/scrape/progress)
• Risk scoring + sequence analysis + grounded chat
• Deterministic vulnerability correlation engine (VCGv1) for Windows + Linux
• Live MITRE ATT&CK mapping + Navigator-ready coverage output
• Super timeline API (process + network + persistence + event + historical)
• Optional YARA scanning (with fallback signature engine)
• Threat-intel feed matching + alert dispatch (webhook/email/SIEM HTTP)
• Lightweight fleet/multi-host ingest + hunt APIs
• Response actions (process kill/file quarantine; guarded by env flag)
• Offline forensics APIs for EVTX, PCAP, and memory-image quick scan
• Chain-of-custody aware exports (CSV/XLSX/PDF/JSON)
• Dashboard mode toggle via WINSENTINEL_AUTH_DISABLED (demo no-login or secured auth)
• Real case records from scrape history (/api/cases/list)
• Optional Supabase case-store sync/read integration

Runtime Defaults

• Backend API: http://localhost:5006
• Frontend dev server: http://localhost:3000
• Primary persistence: SQLite (backend/forensic_data.db, backend/audit_trail.db, backend/users_auth.db)

Quick Start (2-3 Minute Demo)

1. Start the stack

./start_stack.sh start

2. Get bootstrap admin password (first run only)

If the admin account was just created, password is written to:

• backend/.winsentinel_bootstrap_admin_password

3. Run smoke flow

Secured mode (auth enabled):

export WS_USERNAME=admin
export WS_PASSWORD='your-password'
./scripts/smoke_test.sh

Demo mode (no-login UI/API auth bypass):

export WS_AUTH_DISABLED=true
./scripts/smoke_test.sh

Or one command (starts stack + smoke test):

export WS_USERNAME=admin
export WS_PASSWORD='your-password'
./scripts/demo_run.sh

Installation

Backend

cd backend
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# or: .\.venv\Scripts\activate  # Windows
pip install -r requirements.txt

Frontend

cd frontend
npm install
npm run dev

Auth and Security Setup

Copy env template:

cd backend
cp .env.example .env

Set these values before using self-service auth actions:

• WINSENTINEL_AUTH_SELF_SERVICE_KEY=... (required for register/reset endpoints)
• WINSENTINEL_JWT_SECRET_KEY=... (recommended in non-dev)

Notes:

• POST /api/auth/login is the supported login route.
• Query-string login fallback is removed.
• Register/reset endpoints require security_key that matches WINSENTINEL_AUTH_SELF_SERVICE_KEY.

AI Providers (OpenRouter + Bytez)

LLM_PROVIDER=hybrid supports:

• OpenRouter (OPENROUTER_API_KEY, OPENROUTER_MODEL)
• Bytez (BYTEZ_API_KEY, BYTEZ_MODEL, BYTEZ_API_URL)

You can set provider order with ONLINE_PROVIDER_ORDER=openrouter,bytez.

Local Fine-Tuning (RTX 3050 6GB Ready)

New Unsloth pipeline for unsloth/Llama-3.2-3B-Instruct:

cd backend/training
chmod +x run_finetune_llama32.sh
./run_finetune_llama32.sh

What it does:

• Generates training dataset from local scrape history + synthetic DFIR cases
• Runs 4-bit QLoRA fine-tuning for low-VRAM GPUs
• Saves adapter output to backend/models/winsentinel-llama32-3b-lora

Files:

• backend/training/generate_unsloth_dataset.py
• backend/training/train_unsloth_llama32_3b.py
• backend/training/run_finetune_llama32.sh

Use the fine-tuned adapter in backend runtime:

cd backend
cat >> .env <<'EOF'
OFFLINE_PROVIDER=hf_adapter
LOCAL_ADAPTER_MODEL_PATH=./models/winsentinel-llama32-3b-lora
LOCAL_ADAPTER_BASE_MODEL=unsloth/Llama-3.2-3B-Instruct
LOCAL_ADAPTER_LOAD_IN_4BIT=true
EOF

Then restart backend. In hybrid mode, WinSentinel now prefers the local fine-tuned adapter response when offline inference succeeds.

Frontend API Configuration (Portable)

Frontend uses VITE_API_BASE when set; otherwise it uses relative /api.

Examples:

# Default local backend
VITE_API_BASE=http://localhost:5006 npm run dev

# Remote backend
VITE_API_BASE=https://your-host.example.com npm run dev

Dev proxy target can be changed with:

• VITE_API_PROXY_TARGET (default: http://localhost:5006)

Optional Supabase Integration

WinSentinel can sync/read case summaries to/from Supabase.

Set in backend/.env:

• SUPABASE_URL=https://<project-ref>.supabase.co
• SUPABASE_SERVICE_ROLE_KEY=...
• SUPABASE_CASES_TABLE=winsentinel_cases (default)
• SUPABASE_TIMEOUT_SECONDS=10

Integration status endpoint:

• GET /api/integrations/supabase/status

Recommended table schema (minimum columns):

• Ready-to-run SQL: docs/supabase_cases_schema.sql

• case_id (text, primary key)

• timestamp (timestamptz/text)

• status (text)

• priority (text)

• risk_score (int)

• risk_level (text)

• title (text)

• description (text)

• summary (text)

• findings_count (int)

• warnings_count (int)

• artifact_counts (jsonb)

• findings (jsonb)

• warnings (jsonb)

Analysis Algorithm (Judge-Friendly)

WinSentinel now uses a hybrid model:

• Primary engine: deterministic Vulnerability Correlation Graph (VCGv1)
• Secondary engine: AI reasoning overlay for prioritization and analyst narrative

VCGv1 (no black-box prediction) works on both Windows and Linux artifacts:

1. Extracts signals from process, network, persistence (registry/cron/systemd/startup), and event logs.
2. Maps evidence to explicit vulnerability rules (execution abuse, persistence, auth weakness, defense evasion, C2).
3. Correlates matched rules into attack-chain stages and computes deterministic risk score.
4. Outputs evidence-linked remediation actions.

The AI layer does not replace deterministic findings; it enriches reasoning and prioritization.

New analysis endpoints:

• POST /api/analysis/vulnerability-scan (deterministic + optional AI reasoning)
• GET /api/analysis/mitre/live
• GET /api/analysis/super-timeline
• POST /api/analysis/yara-scan
• POST /api/analysis/offline/evtx
• POST /api/analysis/pcap/inspect
• POST /api/analysis/memory/quick-scan

Core API Endpoints

• GET /health
• POST /api/auth/login
• GET /api/auth/me
• POST /api/scrape/start
• GET /api/scrape/progress
• POST /api/analysis/vulnerability-scan
• POST /api/analysis/process-tree
• POST /api/export/forensic-report
• POST /api/chat
• GET /api/cases/list
• POST /api/cases/assign
• POST /api/cases/notes/add
• GET /api/cases/notes
• GET /api/fleet/hosts
• POST /api/fleet/ingest
• POST /api/fleet/hunt
• GET /api/integrations/alerts/status
• GET /api/integrations/virustotal/status
• GET /api/integrations/threat-intel/status
• POST /api/integrations/threat-intel/refresh
• GET /api/integrations/supabase/status
• POST /api/response/kill-process
• POST /api/response/quarantine-file

NPM Helper Scripts

From repository root:

• npm run build
• npm run smoke:test
• npm run demo:run

Current Status

Hackathon demo build, actively hardening for production.

Last updated: 2026-02-21