Documentation

Quick Start

Get SentinelAI running in under 5 minutes.

1. Start the Dashboard

# Clone or download SentinelAI
docker-compose up -d

The dashboard will be available at your configured URL. Default port is 8015.

2. Create an API Key

1. Open the dashboard and log in
2. Go to Settings (gear icon) → API Keys tab
3. Click Create to generate a new API key
4. Copy the key immediately — it won't be shown again

3. Run an Agent

# Windows (PowerShell as Administrator)
cd windows_agent
$env:SENTINEL_API_KEY = "sk_live_your_key_here"
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
python agent.py --dashboard https://your-dashboard-url

# Linux / macOS (as root)
cd linux_agent
export SENTINEL_API_KEY="sk_live_your_key_here"
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
sudo python3 agent.py --dashboard https://your-dashboard-url

4. Verify

You should see the agent register in the dashboard's Agents panel. Events will start appearing within seconds as the monitors initialize.

Dashboard Setup

The dashboard is a Docker stack consisting of FastAPI, PostgreSQL, and Redis.

Docker Compose Services

Environment Configuration

Copy .env.example to .env and configure:

Common Docker Commands

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f web

# Rebuild after changes
docker-compose up -d --build web

# Stop all services
docker-compose down

Windows Agent

The Windows agent provides 25+ concurrent security monitors for comprehensive endpoint protection.

Requirements

• Python 3.10+
• Administrator access (recommended for full capabilities)
• Dependencies: psutil, requests, pywin32, numpy, scikit-learn, lightgbm, xgboost

Installation

# Open PowerShell as Administrator
cd windows_agent

# Create virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set API key
$env:SENTINEL_API_KEY = "sk_live_your_key_here"

# Run the agent
python agent.py --dashboard https://your-dashboard-url

Or use the batch file after setup:

run_agent.bat

Command Line Options

What It Monitors

The Windows agent runs these monitors concurrently:

• Process Monitor — Detects mimikatz, encoded PowerShell, reverse shells, crypto miners, download cradles
• Network Monitor — Suspicious ports (4444, 5555, 1337), outbound + inbound connections, port scans, brute force, DDoS
• Event Log Parser — Failed logins (4625), privilege escalation (4672), new services (4697), scheduled tasks (4698), audit log cleared (1102)
• Registry Watch — Run keys, Services, Winlogon persistence entries
• Startup Monitor — Startup folder and registry Run entries
• Scheduled Tasks — New task creation for persistence
• USB Monitor — Device connections and removals
• Hosts File — DNS hijacking via hosts file modifications
• Browser Extensions — Chrome/Edge new extension installs
• Clipboard — Passwords, API keys, crypto wallet addresses
• DNS Queries — DNS tunneling and suspicious domain lookups
• PowerShell Logging — Script block execution capture
• WMI — WMI persistence and event subscriptions
• DLL Injection — Injected DLLs in running processes
• Named Pipes — C2 communication channel detection
• Services — New service creation for persistence
• Drivers — Rootkit driver loading
• Firewall Rules — Unauthorized rule changes
• Certificates — Rogue certificates in Windows store
• Windows Defender — Security Center integration
• AMSI — Antimalware Scan Interface events
• ETW — Event Tracing for Windows
• Sysmon — Enhanced process/network logging
• Ransomware Canary — Honeypot files detect encryption
• Data Exfiltration — Large outbound transfers (50MB/min threshold)

Agent Logs

The agent writes to sentinel_agent.log in the current directory. Use --verbose for detailed output.

Linux & macOS Agent

The Linux agent provides 16 monitors; macOS provides 10 platform-specific monitors.

Linux Monitors

macOS-Specific Monitors

In addition to core process/network monitoring, macOS agents include: pf Firewall, Launch Daemons, Keychain Access, Gatekeeper, TCC Privacy, and XProtect integration.

Installation

# Linux / macOS
cd linux_agent
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export SENTINEL_API_KEY="sk_live_your_key_here"
sudo python3 agent.py --dashboard https://your-dashboard-url

API Keys & Authentication

User Authentication

The dashboard uses JWT (JSON Web Token) authentication. Users log in with email and password, receiving a token for subsequent API calls.

Agent API Keys

Agents authenticate using API keys (prefixed with sk_live_). Each key is tied to a user account and determines which agents that user can see.

Creating API Keys

1. Log in to the dashboard
2. Go to Settings → API Keys
3. Click Create
4. Copy the key immediately (shown only once)
5. Set as environment variable: SENTINEL_API_KEY=sk_live_xxx

Auto-Response

SentinelAI can automatically respond to threats based on severity without manual intervention.

Capabilities

• IP Blocking — Automatically blocks malicious IPs via the OS firewall (netsh on Windows, iptables on Linux, pf on macOS)
• Process Termination — Kills dangerous processes detected by the ML engine
• File Quarantine — Moves suspicious files to a quarantine directory

Configuration

• Severity Threshold — Set minimum severity for auto-response (e.g., HIGH or CRITICAL only)
• Cooldown Period — Prevents blocking the same IP repeatedly
• IP Whitelist — Trusted IPs that are never blocked

Configure auto-response from the dashboard's Monitoring section.

ML Detection Engine

SentinelAI uses a three-stage detection pipeline.

Stage 1: Advanced ML v2.0 (Local)

The primary detection engine runs entirely on the endpoint:

• 150+ features extracted across process, network, file, registry, behavioral, context, and anomaly dimensions
• Ensemble models: LightGBM + XGBoost + Random Forest with weighted voting
• Behavioral analysis: Attack chain detection (reconnaissance, lateral movement, exfiltration)
• Anomaly detection: Baseline learning with Isolation Forest
• MITRE ATT&CK: Maps to 45+ techniques with confidence scores

Stage 2: Legacy Heuristics

Fallback for when ML models are unavailable:

• Whitelist check (known safe applications)
• Blacklist check (known malware names/hashes)
• Command-line pattern matching for suspicious arguments

Stage 3: Bygheart AI Escalation (Optional)

For uncertain cases (40-70% ML confidence):

• Deep threat classification
• Remediation recommendations
• False positive detection

Benchmark Results

Autonomous Learning

The ML model improves over time:

• Learns from high-confidence (>80%) predictions
• Accepts user feedback to correct false positives
• Auto-retrains every 24 hours with 500+ samples
• Persists learning between agent restarts

Retraining

# Activate virtual environment
.\venv\Scripts\activate

# Train with synthetic data
python train_ml.py

# Run tests
python test_ml.py

# Benchmark
python benchmark_ml.py

Notifications & Alerts

Supported Channels

Configuration

Configure notification channels from the dashboard Settings page. Set the minimum severity threshold for each channel to control alert volume.

Integrations

VirusTotal

Check file hashes, URLs, IPs, and domains against VirusTotal's database. Requires a free VirusTotal API key configured in the dashboard settings.

AlienVault OTX

Threat intelligence feed integration for IP and domain reputation lookups.

Abuse.ch Feeds

Integrates with URLhaus, FeodoTracker, ThreatFox, and MalwareBazaar for known malware indicators.

Snort IDS

The Docker stack includes a Snort connector that ingests Snort IDS alerts into the SentinelAI pipeline.

Docker Projects

Any Docker container can send threat data to SentinelAI:

# From any Docker container
import requests
requests.post("http://host.docker.internal:8015/api/v1/threats/analyze", json={
    "source_ip": "192.168.1.100",
    "threat_type": "suspicious_activity",
    "severity": "HIGH",
    "description": "Unusual database query pattern detected"
})

API Reference

Health Check

GET /api/v1/health

Returns service health status.

Authentication

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

username=user@example.com&password=yourpassword

Returns a JWT token for subsequent authenticated requests.

Threat Analysis

POST /api/v1/threats/analyze
Content-Type: application/json
X-API-Key: sk_live_xxx

{
    "source_ip": "192.168.1.100",
    "threat_type": "malware",
    "severity": "HIGH",
    "description": "Suspicious process detected"
}

Recent Threats

GET /api/v1/threats/recent
Authorization: Bearer <jwt_token>

Agent Registration

POST /api/v1/windows/agent/register
Content-Type: application/json
X-API-Key: sk_live_xxx

{
    "hostname": "DESKTOP-ABC123",
    "platform": "Windows",
    "platform_version": "10.0.19041",
    "capabilities": ["process", "network", "eventlog", "firewall"]
}

List Connected Agents

GET /api/v1/windows/agent/list
Authorization: Bearer <jwt_token>

Agent Stats

GET /api/v1/agents/stats
GET /api/v1/agents/fleet-overview
Authorization: Bearer <jwt_token>

AI Analysis Stats

GET /api/v1/ai/stats
Authorization: Bearer <jwt_token>

Remote Commands

Send commands to connected agents from the dashboard.

Available Commands

Sending Commands via API

POST /api/v1/windows/agent/{hostname}/commands/queue
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
    "command": "block_ip",
    "args": {"ip": "10.0.0.5"}
}

Agents poll for commands every 30 seconds and execute them locally.

Troubleshooting

"Dashboard not reachable"

• Ensure Docker is running: docker-compose up -d
• Check the dashboard URL and port are correct
• Verify firewall allows connections to the dashboard port
• Check Docker logs: docker-compose logs -f web

"Access Denied" errors on agent

• Run the agent as Administrator (Windows) or root (Linux/macOS)
• Some processes may be protected by the OS

No events appearing in dashboard

• Check the agent is running (look for log output)
• Verify the API key is set correctly
• Check agent logs in sentinel_agent.log
• Test the API: GET /api/v1/health

Agent not registering

• Verify the SENTINEL_API_KEY environment variable is set
• Check the dashboard URL is reachable from the agent machine
• Look for registration errors in agent logs

High false positive rate

• Use the dashboard to mark false positives — the ML model learns from feedback
• Retrain the model with python train_ml.py
• Check if legitimate software is triggering heuristic rules