SPECTRE

Security Platform for Enterprise Cyber Threat Response and Elimination

A real-time network security monitoring and threat response system with AI-powered threat intelligence.

---

Overview

SPECTRE is a comprehensive network security solution that monitors your network in real-time, detects threats, and can automatically block malicious IPs. It features:

• Real-time Connection Monitoring - Track all TCP/UDP connections
• Threat Detection - Identify port scans, brute force attempts, connection floods
• AI-Powered Analysis - Leverage LLM models for intelligent threat assessment (Project M)
• AbuseIPDB & Shodan Integration - Enrich threat data with external intelligence
• Cyberpunk Dashboard - Beautiful web interface for monitoring and control
• Automatic Blocking - Zero-tolerance mode for known bad actors

---

Components

Component	Description
SPECTRE Daemon	Core monitoring service (macOS/Linux)
Web Dashboard	Astro/React frontend with Flask API
Project M	AI Intelligence MCP Server (Claude/GPT-4/Grok/Ollama)
Project Q	Pentesting Toolkit MCP Server

---

Installation

Prerequisites

• Python 3.10+
• Node.js 18+ (for web dashboard)
• Root/Administrator access (for packet capture and firewall)

---

macOS

# Clone the repository
git clone https://github.com/timastras9/spectre.git
cd spectre

# Basic install
./install_macos.sh

# Install with web dashboard
./install_macos.sh --web

# Update to latest version
./install_macos.sh --update

After installation:

# Start the daemon
spectre_macos.py start

# Stop the daemon
spectre_macos.py stop

# View attackers
spectre_macos.py attackers

# Launch CLI dashboard
spectre_dashboard.py

# Launch web dashboard (if installed with --web)
spectre-web

Background service:

# Enable auto-start on login
launchctl load ~/Library/LaunchAgents/com.spectre.agent.plist

# Disable auto-start
launchctl unload ~/Library/LaunchAgents/com.spectre.agent.plist

---

Linux (Debian/Ubuntu/RHEL/Alpine)

# Clone the repository
git clone https://github.com/timastras9/spectre.git
cd spectre

# Run installer (auto-detects distro)
sudo ./install.sh

Or one-liner install:

curl -sSL https://raw.githubusercontent.com/timastras9/spectre/Main/install.sh | sudo bash

After installation:

# Start the service
sudo systemctl enable --now spectre

# Check status
sudo systemctl status spectre

# View logs
journalctl -u spectre -f

# Run manual scan
/opt/spectre/daemon.py

Paths:

• Install: /opt/spectre/
• Logs: /var/log/spectre/
• Data: /opt/spectre/data/

---

Windows 10/11 (via WSL2)

Windows support requires WSL2 (Windows Subsystem for Linux) which provides a real Linux kernel for proper network monitoring.

Step 1: Install WSL2

# Run PowerShell as Administrator
wsl --install

# Restart your computer, then set up Ubuntu when prompted

Step 2: Install Spectre in WSL2

# Open WSL terminal (search "Ubuntu" in Start menu)
git clone https://github.com/timastras9/spectre.git
cd spectre

# Run the Linux installer
sudo ./install.sh

Step 3: Start Spectre

# Start the daemon
sudo systemctl start spectre

# Or run directly
sudo /opt/spectre/daemon.py

Starting the Web Dashboard:

# Terminal 1 - Start API server
cd spectre/web-dashboard/api
python3 server.py

# Terminal 2 - Start web frontend
cd spectre/web-dashboard
npm install
npm run dev

Access the dashboard at http://localhost:4321 from your Windows browser.

Troubleshooting WSL2:

"Running scripts is disabled on this system" (PowerShell):

Set-ExecutionPolicy Bypass -Scope Process -Force

WSL not installed:

# Run as Administrator
wsl --install -d Ubuntu

---

Quick Reference

Platform	Install Command	Start Command	Service Manager
macOS	./install_macos.sh --web	spectre_macos.py start	launchctl
Linux	sudo ./install.sh	systemctl start spectre	systemd
Windows (WSL2)	sudo ./install.sh	systemctl start spectre	systemd
Docker	docker-compose up -d	(automatic)	Docker

---

Docker (Any OS)

Two Docker options available:

Option 1: Dashboard Only (Any OS)

Best for viewing/analyzing threats. Works on Windows, macOS, Linux.

git clone https://github.com/timastras9/spectre.git
cd spectre

# Build and run
docker-compose -f docker-compose.spectre.yml up -d

# Access: http://localhost:5000

Option 2: Full Monitoring (Linux Only)

Complete network monitoring with real-time blocking. Requires Linux host.

git clone https://github.com/timastras9/spectre.git
cd spectre

# Build and run with full monitoring
docker-compose -f docker-compose.full.yml up -d

# Access: http://localhost:5000
# View logs: docker logs -f spectre-full

With AI Features (both options):

export ANTHROPIC_API_KEY="your-key"
export GROK_API_KEY="your-key"
docker-compose -f docker-compose.full.yml up -d

Feature Comparison:

Feature	Dashboard Only	Full Edition
Web Dashboard	✅	✅
AI Analysis	✅	✅
Threat Database	✅	✅
Network Monitoring	❌	✅
Auto-Blocking	❌	✅
Auth Log Detection	❌	✅
Works on macOS	✅	❌
Works on Windows	✅	❌
Works on Linux	✅	✅

Docker Commands:

# Stop
docker-compose -f docker-compose.full.yml down

# Rebuild after updates
docker-compose -f docker-compose.full.yml build --no-cache
docker-compose -f docker-compose.full.yml up -d

# View blocked IPs (full edition)
docker exec spectre-full iptables -L SPECTRE_BLOCK -n

---

Configuration

Environment Variables

Create a .env file in the project root:

# Threat Intelligence APIs (optional but recommended)
ABUSEIPDB_API_KEY=your-api-key-here
SHODAN_API_KEY=your-api-key-here

# AI Provider Configuration (Project M)
LLM_PROVIDER=anthropic           # anthropic, gemini, openai, grok, or ollama
ANTHROPIC_API_KEY=sk-ant-...     # Required for Claude
GOOGLE_API_KEY=AIza...           # Required for Gemini
OPENAI_API_KEY=sk-...            # Required for GPT-4
GROK_API_KEY=xai-...             # Required for Grok

# Ollama Configuration (for local LLM)
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=gemma2:9b
OLLAMA_TIMEOUT=120

Dashboard Settings

Access the dashboard at http://localhost:4321 and click the settings gear to configure:

• Theme - Cyberpunk or Matrix color scheme
• AI Provider - Select Claude, Gemini, GPT-4, Grok, or Ollama
• Auto-Block Threshold - Automatically block IPs above this risk score
• Sound Alerts - Audio notifications for critical threats

---

Usage

Starting SPECTRE

macOS:

# Start via LaunchAgent (auto-starts on login)
launchctl load ~/Library/LaunchAgents/com.spectre.agent.plist

# Or run directly
spectre_macos.py start

Linux:

# Start via systemd
sudo systemctl start spectre

# Or run directly
sudo /opt/spectre/daemon.py

Windows (PowerShell as Admin):

# Start service
Start-Spectre

# Or via sc.exe
sc start Spectre

# Or run directly
spectre.bat

Accessing the Dashboard

1. Start the API server: cd web-dashboard/api && python3 server.py
2. Start the web server: cd web-dashboard && npm run dev
3. Open http://localhost:4321 in your browser

API Endpoints

Endpoint	Method	Description
/api/threats	GET	Recent threat events
/api/connections	GET	Active connections
/api/blocked	GET	Blocked IP list
/api/block	POST	Block an IP
/api/unblock	POST	Unblock an IP
/api/whitelist	GET	Whitelisted IPs
/api/ip/<ip>	GET	Detailed IP lookup
/api/analyze_ip/<ip>	GET	AI threat analysis
/api/llm/status	GET	LLM provider status

---

Project M - AI Intelligence Server

Project M is the unified LLM intelligence server that powers SPECTRE's AI analysis:

# Install Project M
cd m-server
pip3 install -e .

# Configure in .mcp.json
{
  "mcpServers": {
    "m": {
      "command": "python",
      "args": ["-m", "m_server"],
      "cwd": "/path/to/spectre/m-server"
    }
  }
}

Available MCP Tools

• analyze_threat - Full threat analysis with context
• predict_risk - Risk scoring (0-100) with confidence
• explain_attack - MITRE ATT&CK mapping
• generate_report - Security reports
• train_model - Pattern learning from blocked IPs

---

Architecture

                    ┌─────────────────────────┐
                    │    Web Dashboard        │
                    │   (Astro + React)       │
                    └───────────┬─────────────┘
                                │
                    ┌───────────▼─────────────┐
                    │     Flask API Server    │
                    │    (server.py:5000)     │
                    └───────────┬─────────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          │                     │                     │
┌─────────▼─────────┐ ┌─────────▼─────────┐ ┌─────────▼─────────┐
│  SPECTRE Daemon   │ │    Project M      │ │   External APIs   │
│ (packet capture)  │ │  (LLM Analysis)   │ │ (AbuseIPDB/Shodan)│
└───────────────────┘ └───────────────────┘ └───────────────────┘

---

Troubleshooting

Permission Denied on macOS

# Grant Terminal full disk access in System Preferences
# System Preferences > Security & Privacy > Privacy > Full Disk Access

Firewall Not Blocking

# macOS - Check pf status
sudo pfctl -s rules

# Linux - Check iptables
sudo iptables -L -n

Dashboard Not Loading

# Check API server is running
curl http://localhost:5000/api/health

# Rebuild the dashboard
cd web-dashboard && npm run build

---

License

MIT License - See LICENSE file for details.

---

Credits

Built with:

• Astro - Web Framework
• React - UI Components
• Tailwind CSS - Styling
• Flask - API Server
• Claude - AI Analysis (via Project M)

---

"In the world of network security, vigilance is not paranoia - it's survival."