ThreatWatch-AI

ThreatWatch AI is an AI-powered threat operations platform that detects, investigates, and neutralizes threats in real time—transforming signals into actionable intelligence for security teams.

Comment

ThreatWatch AI

Stage Stack AI Runtime

ThreatWatch AI is a threat-operations platform for phishing, scam, and suspicious-message analysis across email, chat, SMS, and URLs.

It combines:

  • a rule engine
  • a machine-learning detection path
  • optional AI-assisted analysis
  • an executive dashboard
  • a floating copilot
  • self-hosted or BYOK LLM support

The local product is designed to run as a single operator surface on http://localhost:5080.

Quick Links

Quick Start

git clone https://github.com/nusabyte-my/ThreatWatch-AI.git
cd ThreatWatch-AI
cp .env.example .env
docker compose up --build -d

Open:

  • UI: http://localhost:5080
  • Health: http://localhost:5080/api/v1/health

Services:

Surface URL Purpose
UI http://localhost:5080 Main operator dashboard
API http://localhost:5080/api/v1 Backend API base
Health http://localhost:5080/api/v1/health Runtime verification

Feature Status

Area Status Notes
Dashboard Implemented Executive posture, KPI, incidents, navigation
Investigation Workspace Implemented Verdict, risk, timeline, evidence, AI trace
Analytics Implemented Mix, quality, categories, reasons, incidents
Rules Manager Implemented UI plus auth/RBAC-aware backend flow
AI Copilot Implemented Chat, summary, action, exec briefing, custom prompts
Branded Print Brief Implemented Printable incident report
BYOK LLM Implemented OpenAI and Anthropic request-level support
Self-Hosted Gemma Implemented Ollama-backed assistant and recommendation path
Gmail / Chrome Stub Implemented as stub Needs runtime validation
Thunderbird Stub Implemented as stub Needs runtime validation
Outlook Web Stub Implemented as stub Needs runtime validation
Production Hardening Partial Good baseline, still needs deeper validation and ops work

Demo Flow

For evaluators, reviewers, or first-time users:

  1. Open http://localhost:5080
  2. Use Dashboard to review posture and recent incidents
  3. Click Launch investigation
  4. Paste suspicious content or upload a .eml
  5. Run a threat assessment
  6. Review the verdict, summary, timeline, evidence, and AI trace
  7. Open AI Copilot for summary, action, or executive briefing
  8. Use Print brief for a stakeholder-ready incident report

Executive Summary

ThreatWatch AI helps teams move from suspicious content to a clear incident decision quickly.

Business value:

  • reduces time to triage suspicious messages
  • gives leadership-readable incident summaries instead of opaque scores
  • keeps detection explainable through rules, signals, indicators, and timeline views
  • supports local AI with Ollama/Gemma or hosted AI through BYOK
  • provides a path to analyst workflow, governance, and reporting in one interface

What the platform does:

  • scans pasted text, URLs, and .eml email files
  • assigns a verdict: safe, suspicious, or scam
  • shows evidence, indicators, and recommended action
  • stores scans for analytics and recent-incident review
  • supports AI copilot chat and AI recommendation enrichment
  • includes mail-client integration stubs for Chrome/Gmail, Thunderbird, and Outlook Web

What Is Included

Core platform:

  • executive dashboard
  • investigation workspace
  • analytics view
  • rules manager
  • floating AI copilot
  • branded incident print brief

Backend:

  • FastAPI API
  • PostgreSQL persistence
  • route-level rate limiting
  • security headers and request-size limits
  • auth/RBAC foundation for rule operations
  • Google Safe Browsing enrichment
  • assistant endpoints for chat and recommendation

AI:

  • standard engine: rules + ML
  • AI pipeline: deeper analysis with model support
  • BYOK support for OpenAI / Anthropic
  • self-hosted Ollama support for Gemma

Integrations:

  • Chrome extension stub
  • Thunderbird extension stub
  • Outlook Web extension stub

Tech Stack

Frontend:

  • HTML / CSS / Vanilla JavaScript
  • single-page dashboard UI in frontend/index.html
  • nginx-served operator console on http://localhost:5080

Backend:

  • Python
  • FastAPI
  • Uvicorn
  • Pydantic
  • SQLAlchemy

Data and storage:

  • PostgreSQL

AI and detection:

  • rule engine
  • ML-assisted scan flow
  • assistant and recommendation endpoints
  • BYOK support for OpenAI and Anthropic
  • self-hosted Ollama support for Gemma

Infrastructure:

  • Docker
  • docker compose
  • nginx reverse proxy

Integrations:

  • Chrome/Gmail extension stub
  • Thunderbird extension stub
  • Outlook Web extension stub

Build Information

Runtime topology:

  • nginx proxy on port 5080
  • frontend static app behind nginx
  • api FastAPI backend behind nginx
  • db PostgreSQL database

Primary local entry points:

  • UI: http://localhost:5080
  • API base: http://localhost:5080/api/v1
  • Health: http://localhost:5080/api/v1/health

Build and run model:

  • local build uses docker compose
  • frontend is served as a static app
  • backend runs as a containerized FastAPI service
  • nginx unifies frontend and API into one local surface

Current local execution command:

docker compose up --build -d

Stop command:

docker compose down

Project Tree

ThreatWatch-AI/
├── backend/                  FastAPI app, auth, scan logic, analytics, assistant
│   └── app/
│       ├── api/              API routes: scan, auth, rules, analytics, assistant
│       ├── agents/           LLM client and agent pipeline components
│       ├── engine/           Rule and scan engine logic
│       ├── db/               Models, session, bootstrap, migration helpers
│       └── ml/               ML training and prediction path
├── frontend/                 Main dashboard UI and static assets
├── nginx/                    Reverse proxy configuration
├── chrome-extension/         Gmail / Chrome integration stub
├── thunderbird-extension/    Thunderbird integration stub
├── outlook-web-extension/    Outlook Web integration stub
├── docker-compose.yml        Local runtime entry point
├── .env.example              Environment template
├── PLAN.md                   Build and roadmap plan
├── EXECUTIVE_SUMMARY.md      Business-facing one-page summary
└── README.md                 Main project guide

Product Stage

Current maturity:

  • working local full-stack product
  • operator-facing dashboard and investigation workflow implemented
  • analytics, rules, copilot, and print brief implemented
  • self-hosted Gemma path implemented through Ollama
  • extension integrations are currently stubs, not production-ready clients

Current stage label:

  • functional prototype / advanced internal demo

What is production-leaning already:

  • containerized local runtime
  • auth/RBAC foundation
  • security hardening pass
  • route-level rate limiting
  • structured operator workflow

What still needs production follow-through:

  • full browser QA
  • deeper runtime validation
  • stronger auth persistence and audit logging
  • production deployment hardening
  • extension runtime testing across real mail environments

Screens And Demo Notes

Recommended GitHub additions next:

  • dashboard screenshot
  • investigation workspace screenshot
  • analytics screenshot
  • short animated GIF showing scan -> result -> copilot flow

This README is already structured so those visuals can be dropped near the top without changing the rest of the document.

Install And Execute

Prerequisites

  • Docker Desktop
  • Git
  • optional: Ollama for self-hosted Gemma

1. Clone

git clone https://github.com/nusabyte-my/ThreatWatch-AI.git
cd ThreatWatch-AI

2. Configure environment

cp .env.example .env

For local development, the defaults are usually enough.

Important values you may want to set:

  • SECRET_KEY
  • ADMIN_API_KEY
  • AUTH_ENABLED
  • AUTH_USERS_JSON
  • GOOGLE_SAFE_BROWSING_KEY
  • OLLAMA_BASE_URL
  • OLLAMA_MODEL

3. Start the platform

docker compose up --build -d

4. Open the app

  • UI: http://localhost:5080
  • Health: http://localhost:5080/api/v1/health

5. Stop the platform

docker compose down

How To Use

Dashboard

Use Dashboard for:

  • threat posture overview
  • KPI review
  • recent incidents
  • quick navigation into investigation

Analyze

Use Analyze for active casework:

  1. choose Standard Engine or AI Pipeline
  2. choose the channel: Chat, Email, SMS, or URL
  3. paste content or upload a .eml
  4. click Run threat assessment
  5. review:
    • verdict
    • risk
    • executive summary
    • recommended response
    • threat story
    • investigation timeline
    • evidence signals
    • indicators and intel
    • AI trace

Analytics

Use Analytics for:

  • incident mix
  • detection quality snapshot
  • categories and repeated reasons
  • hot indicators
  • channel concentration
  • recent threat cards

Rules

Use Rules to:

  • sign in as admin / analyst
  • review rules
  • create rules
  • toggle rules

AI Copilot

Use the floating AI Copilot to:

  • summarize a case
  • get next-best action
  • generate an exec briefing
  • suggest rule direction
  • ask custom case questions

Self-Hosted Gemma

ThreatWatch AI supports self-hosted assistant responses through Ollama.

Run Ollama

Example:

ollama serve
ollama pull gemma4:e2b

Configure ThreatWatch AI

Set in .env:

OLLAMA_BASE_URL=http://host.docker.internal:11434
OLLAMA_MODEL=gemma4:e2b

In the dashboard:

  • switch to AI Pipeline
  • choose ollama/gemma4:e2b
  • run a scan or use the copilot

If Ollama is unavailable, the platform falls back gracefully instead of crashing.

Authentication

Rule operations support:

  • bearer token auth
  • roles: viewer, analyst, admin
  • legacy X-API-Key fallback for admin workflows

Example local bootstrap account:

  • username: admin
  • password: changeme_admin_password

Change this immediately for any real environment.

Key Endpoints

Core:

  • POST /api/v1/scan
  • POST /api/v1/scan/ai
  • POST /api/v1/scan/upload
  • GET /api/v1/scan/{id}
  • POST /api/v1/scan/{id}/feedback
  • GET /api/v1/stats
  • GET /api/v1/analytics/summary
  • GET /api/v1/health

Auth and rules:

  • POST /api/v1/auth/login
  • GET /api/v1/auth/me
  • GET /api/v1/rules
  • POST /api/v1/rules
  • PATCH /api/v1/rules/{id}/toggle

Assistant:

  • POST /api/v1/assistant/chat
  • POST /api/v1/assistant/recommend

Example API Calls

Standard scan

curl -X POST http://localhost:5080/api/v1/scan ^
  -H "Content-Type: application/json" ^
  -d "{\"text\":\"URGENT: Your account is locked. Verify now.\",\"channel\":\"email\"}"

AI scan

curl -X POST http://localhost:5080/api/v1/scan/ai ^
  -H "Content-Type: application/json" ^
  -d "{\"text\":\"URGENT: Your account is locked. Verify now.\",\"channel\":\"email\",\"include_explanation\":true}"

Login

curl -X POST http://localhost:5080/api/v1/auth/login ^
  -H "Content-Type: application/json" ^
  -d "{\"username\":\"admin\",\"password\":\"changeme_admin_password\"}"

Extensions

Included stubs:

  • chrome-extension/README.md
  • thunderbird-extension/README.md
  • outlook-web-extension/README.md

These use the same backend scan APIs and are intended as starting points for productized mail-client integrations.

Security Notes

Current hardening includes:

  • security headers at nginx
  • trusted-host enforcement
  • request-size limits
  • route-level rate limits
  • safer auth handling
  • no-store API responses
  • optional Safe Browsing enrichment

Still recommended for production:

  • stronger user storage and password hashing
  • audit logs
  • secrets rotation
  • production-specific CORS and origin tightening

Repo Structure

backend/                  FastAPI app, rules, auth, assistant, analytics
frontend/                 Dashboard UI and static assets
nginx/                    Reverse proxy config
chrome-extension/         Gmail/Chrome extension stub
thunderbird-extension/    Thunderbird extension stub
outlook-web-extension/    Outlook Web extension stub
docker-compose.yml        Local stack entry point
.env.example              Environment template
PLAN.md                   Build and roadmap plan

Verification

After startup, verify:

curl http://localhost:5080/api/v1/health

Expected:

{"status":"ok","service":"threatwatch-api"}

Then open:

http://localhost:5080

Current Status

Implemented:

  • dashboard + investigation UI
  • analytics summary API and frontend
  • rules manager UI
  • auth/RBAC foundation
  • BYOK model path
  • Ollama / Gemma support
  • assistant APIs
  • branded incident printing
  • browser/mail integration stubs

Best next step:

  • real browser QA and final runtime validation across the full UI and extensions

Built With

Share this project:

Updates