Overview

BinaryWebEngine is an all-in-one security monitoring platform for Linux. It bundles WAF, HIDS, NIDS, file integrity monitoring, malware scanning, ML anomaly detection, kill chain reconstruction, and threat intelligence into a single engine with a real-time dashboard.

Monitor one server or a fleet of machines from a single dashboard. No separate SIEM appliance, no third-party connectors, no complex integrations.

System Requirements

Quick Start

The fastest way to evaluate BinaryWebEngine is with the single-file executable:

# Download the executable
chmod +x bwe

# Start with demo data
./bwe --demo

# Open browser to http://localhost:8000
# Login credentials are displayed on first run
# and saved to credentials.txt

For development or custom deployments, use the Python source:

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Edit config/config.yaml to set API keys
nano config/config.yaml

# Run with demo data
python3 main.py --demo

CLI Reference

Command Center Dashboard

Single-page app with 14 tabs. Auto-refreshes every 10 seconds, with SSE pushing live updates for critical data.

Overview Tab

The default landing page provides a high-level security posture summary:

• Security Posture Banner — Overall risk level (Secure, Elevated, High, Critical) based on active alert severity
• Stat Cards — Alerts (24h), WAF Blocks, Blocked IPs, Quarantined Files, Processes, Connections, Hardening Score
• Recent Alerts — Last 5 alerts with severity badges, module, IP, and resolution status
• Alerts by Engine (24h) — Bar chart breakdown of alerts by detection module
• Kill Chain Status — Active multi-stage attack chains with stage completion
• MITRE ATT&CK Matrix — Tactics heatmap (Initial Access through Exfiltration)
• Alerts Timeline (24h) — Hourly alert volume line chart
• Blocked IPs — Currently blocked IP addresses with country and abuse score
• Recent Events — Live feed of WAF blocks, file changes, process and network detections
• System Health — CPU, memory, disk, and uptime gauges
• Threat Intelligence Summary — Top source countries, attack types, and recent AbuseIPDB lookups

Alerts & Incidents Tab

Centralised alert management console:

• Filter Controls — Search by text, filter by module, source (VPS hostname), severity (Critical/High/Medium/Low), include/exclude low severity, hide self-test events
• Alert Table — Columns: Severity badge, Title (with reason tooltip), Module, IP Address, Timestamp, Actions
• Resolve — Mark individual alerts as resolved with one click
• AI Explain — Click the AI button to generate an LLM-powered explanation of each alert, including context from related events, kill chain status, and IP intelligence PRO
• False Positive Scoring — Click FP to score an alert's likelihood of being benign. Bulk score all visible alerts with the "Score All" button PRO
• Alert Count Badge — Unresolved critical alert count shown in the navigation bar
• Deduplication — Alerts with the same title, IP, and module within a 1-hour window are automatically grouped

Kill Chain Tab

Visualise multi-stage attack chains mapped to the Lockheed Martin framework:

• Each IP's activity is tracked across 7 stages: Reconnaissance → Weaponisation → Delivery → Exploitation → Installation → Command & Control → Actions on Objectives
• Alerts are mapped to MITRE ATT&CK tactics (TA0001–TA0010)
• Composite alerts fire when multiple stages are completed by the same IP
• Click any chain to drill into detailed event timeline
• Chains auto-expire after a configurable TTL
• See the MITRE heatmap on the Overview tab for organisational tactical trends

WAF Dashboard Tab

Comprehensive Web Application Firewall analytics:

• Stats Bar — Total blocked requests, active blocked IPs, rate-limited requests, attack type distribution
• Attack Timeline — Hourly block volume chart
• WAF Event Log — Filterable table (search by IP, attack type, path) with payload preview
• Blocked IPs — List of currently blocked addresses with expiry and reason
• Custom Rules — Create, edit, enable/disable custom WAF rules with regex patterns. Restore defaults. PRO
• Test Console — Send sample requests against the WAF engine and see which signatures fire

Threat Intelligence Tab

IP reputation and threat landscape overview:

• Top Source Countries — Choropleth-style breakdown of traffic origins
• Attack Type Distribution — Pie chart of WAF attack categories
• Recent AbuseIPDB Lookups — Live feed of IP reputation queries with abuse score, country, ISP, and category
• Top Traffic IPs — Ranked by hit count with abuse scores, country, and block status
• IP Search — Look up any IP address for reputation data and historical events
• Auto-Block Settings — Configure abuse score threshold and enable/disable automatic IP blocking

Hardening Tab

CIS benchmark-inspired security audit with actionable recommendations:

• Overall Score — 0–100% security posture rating with color-coded indicator
• Category Cards — SSH configuration, file permissions, kernel parameters, password policy, firewall rules
• Findings Table — Each check shows: status (pass/fail), description, current value, expected value, and remediation command
• Export — Download audit results as JSON for compliance evidence
• Run the audit on demand or view the last cached result

Audit Trail Tab

Tamper-evident, cryptographically chained audit log:

• Append-only JSONL format with HMAC-SHA256 chaining between entries
• Each entry contains: timestamp, event type, actor, details, and a hash linking it to the previous entry
• Verification Status — "Chain Verified" or "Tamper Detected" indicator
• Event Table — Filterable by event type (config change, login, license apply, alert action, etc.)
• Export — Download the full audit log
• The first entry's prev_hash is 64 zeros — any modification to an entry breaks the chain

Alert Rules Tab

Create automated notification rules:

• Rule Table — Name, Severity, Module, Pattern, Webhook URL, Enabled status
• Create Rule — Specify name, severity filter, module filter, regex pattern (matched against alert title), and optional webhook URL
• Webhook Integration — Each rule can POST JSON payloads to an external endpoint (Telegram, Discord, Slack, custom SOAR)
• Enable/Disable — Toggle rules on and off without deleting them
• Rules are evaluated in real-time as alerts fire

Reports Tab

Generate and download executive security reports:

• Compliance Report — Executive summary HTML report with 8 sections: Executive Summary, Security Scorecard, Incident Breakdown, WAF Analysis, Top Threat Actors, Critical/High Alerts, Recommendations, Methodology. PDF export available. PRO
• Threat Summary — Lightweight threat landscape overview
• Data Export — Export alerts, WAF events, or traffic data as CSV or JSON
• Scheduled reports (configurable interval, default 7 days)

Processes Tab

Live system process monitoring with suspicion scoring:

• Process Table — PID, Name, CPU%, Memory, Suspicious flag, Command line
• Summary Bar — Total processes, suspicious detections, resource usage
• Auto-Refresh — Live updates via SSE every 5 seconds
• Detection Heuristics: cryptominer patterns, parent-child anomalies (e.g., php-fpm spawning bash), resource hijacking with sustained CPU/memory spikes
• Exclusion List — Configured in settings to whitelist known processes

Network Tab

Live network connection monitoring:

• Connection Table — Process, Local Address, Remote Address, Remote Port, Status (ESTABLISHED/TIME_WAIT/etc.)
• Summary Bar — Total connections, established count, suspicious detections
• Auto-Refresh — Live updates via SSE every 5 seconds
• Detection Heuristics: non-standard port connections, reverse shell port patterns, Tor exit node connections, excessive outbound connections
• Trusted CIDR ranges configurable in settings

Files Tab

File integrity monitoring management:

• Monitored Directories — List of directories under watch with add/remove controls
• File Hash Table — Each monitored file shows: path, SHA-256 hash, file size, last verified timestamp
• Scan on Modify — When enabled, modified files are automatically scanned by the malware scanner
• Add Directory — Add any path to the monitoring set (changes are tracked via inotify/watchdog)
• Whitelist Paths — Exclude paths matching patterns (e.g., /proc, /sys, /dev)

Login Monitor Tab

Multi-source authentication monitoring across 9 services:

• Summary Cards — Total events, failed logins, successful logins, blocked IPs
• Event Table — Timestamp, Source IP, Username, Service (SSH/FTP/MySQL/PostgreSQL/Nginx/Apache/sudo/cron/web), Status (success/failure), Port, Log Source
• Filters — By service, status, search, and date range
• Auto-Blocking — Brute force detection triggers automatic WAF and UFW blocking PRO
• Distributed Credential Stuffing — Same username from 3+ unique IPs within a configurable window triggers a high-severity alert
• Non-Standard Port Detection — Auth failures on uncommon ports are flagged
• Unblock — Release blocked IPs directly from the table

Fleet Tab

Centralised multi-server management (Hub & Spoke): PRO

• Fleet Map — Visual representation of all connected agents with connection status
• Agent Table — Agent ID, Hostname, IP Address, Status (Online/Offline/Degraded), Last Heartbeat, Version
• Status Indicators: Green (Online, heartbeat received within 30s), Amber (Degraded, 1 heartbeat missed), Red (Offline, 3+ heartbeats missed)
• Config Push — Push configuration updates to individual agents over the mTLS channel
• Source Filter — The Alerts tab includes a source dropdown to filter events by agent hostname
• Communication secured with mutual TLS (mTLS) — fallback to plain TCP with startup warning if not configured

Detection Modules

Web Application Firewall

BinaryWebEngine's WAF engine performs real-time HTTP request inspection using 186 regex signatures across 25 attack categories. It operates as a reverse-proxy-level filter, scoring each request against all signatures and applying configurable thresholds for blocking.

Attack Categories Covered

Inspection Pipeline

1. Blacklist Check — IP checked against blocked list (in-memory with expiry)
2. Dynamic Block — Intel engine auto-block check
3. AbuseIPDB Reputation — Real-time or cached reputation lookup
4. Rate Limiting — Per-IP request rate check (default: 60 req/min)
5. Anomaly Detection — Payload size, request frequency, response code deviation
6. Signature Inspection — Request URI, headers, and body matched against all 186 signatures
7. Custom Rules — User-defined regex rules evaluated last

Each stage can independently block the request. Scoring accumulates across stages for graduated response.

Configuration

waf:
  enabled: true
  rate_limit:
    requests_per_minute: 60
    block_duration: 300
  auto_block_firewall: true

File Integrity Monitor

The File Monitor provides real-time and periodic file integrity verification using the Linux inotify API (via the watchdog library). It establishes SHA-256 baselines for all monitored files and detects any modification, deletion, or permission change.

• Real-Time Detection — Uses watchdog's inotify observer for immediate notification of file system events
• SHA-256 Baseline — Each file's hash, size, and permissions are stored on initial scan and compared on every change
• Webshell Scanning — Modified files are automatically passed to the malware scanner for webshell pattern matching
• Specific File Monitoring — High-value files (e.g., /etc/shadow, /etc/passwd, SSH keys) are polled on a separate schedule
• Whitelist Support — Exclude paths matching glob patterns

How to Use

1. Navigate to the Files tab
2. Click "Add Directory" to add a path under watch
3. Toggle "Scan on Modify" to enable automatic malware scanning
4. Monitor the file hash table for baseline changes

Process Monitor

Continuously polls the system process table (via psutil) and applies heuristic-based suspicion scoring. Detects cryptominers, reverse shells, resource hijacking, and anomalous parent-child process relationships.

• Suspicion scoring based on: parent-child relationships, resource consumption, known malicious patterns
• Sustained CPU/memory spikes tracked with strike counters (3 strikes = alert)
• Cryptominer detection via command-line pattern matching (xmrig, miner, etc.)
• Auto-kill option for high-usage processes (configurable in settings)
• Exclusion list for trusted system processes

Configuration

processes:
  cpu_limit: 90.0
  mem_limit_mb: 1024
  auto_kill_high_usage: false
  excluded:
    - systemd
    - kthreadd
  suspicious_parents:
    - nginx
    - apache2
    - php-fpm
  suspicious_children:
    - bash
    - sh
    - nc
    - python

Network Monitor

Monitors live network connections via psutil, classifying each connection for suspicious characteristics and alerting on anomalies.

• Real-time connection table with process-level attribution
• Detection of: non-standard port connections, reverse shell ports, Tor exit nodes, excessive outbound connections
• CIDR-based trust filtering for private and known-good ranges
• Optional Scapy-based packet capture for deep inspection
• Connection history with suspicion scoring

Malware Scanner

Multi-layered file analysis engine combining regex pattern matching, YARA rules, and VirusTotal hash lookups.

• Webshell Detection — Regex patterns targeting PHP, ASP, JSP, Perl, and Python obfuscation techniques (base64, hex, gzinflate, etc.)
• YARA Rules — Loaded from config/malware_rules.yar, matching on file content and metadata
• VirusTotal — File hash lookup against the VirusTotal database PRO
• Quarantine — Suspicious files are moved to the quarantine directory with cryptographic hash mapping. Quarantine supports restore and permanent deletion

Login Monitor

Parses log files from 9 services to detect brute force attacks, credential stuffing, and authentication anomalies in real time.

Detection Capabilities

• Brute Force — Per-IP failure tracking within sliding time window (default: 5 failures in 60s). Triggers critical alert, WAF block, and UFW denial
• Distributed Credential Stuffing — Same username from 3+ unique IPs within 300s → high-severity alert
• Credential Stuffing Success — Successful login from an IP with prior failures → high alert
• Non-Standard Ports — Auth failures on non-standard ports → medium alert

Anomaly Detection

Two-tier machine learning system for behavioural anomaly detection:

Anomaly Detector v1 (Production)

• Welford's Online Algorithm — Per-endpoint rolling mean and variance without storing all data points
• Z-Score Detection — Flags requests with payload size, frequency, or response code deviation beyond configurable threshold
• Isolation Forest — Unsupervised ML trained on feature vectors (payload size, response code, request rate). Warmup period of 100 samples before inference
• Configurable contamination rate and warmup period

Anomaly Detector v2 (Advanced)

• LSTM Sequence Profiling — ONNX Runtime neural network inference for per-IP request sequence analysis
• Page-Hinkley Concept Drift — Detects distribution shifts in request patterns over time
• Falls back to z-score if ONNX model is unavailable

Kill Chain & MITRE ATT&CK

The Kill Chain engine maps every alert to the Lockheed Martin 7-stage intrusion kill chain and MITRE ATT&CK framework (TA0001–TA0010). It composites related events from the same IP into multi-stage attack narratives.

• Chains are created on first alert from an IP and progress through stages as related events fire
• Composite alerts are emitted when an IP completes multiple stages
• Chains auto-expire after configurable time-to-live
• MITRE heatmap on the Overview tab shows organisational tactical trends

Correlation Engine

Cross-module signal correlation combines indicators from file, process, network, and WAF monitoring to detect multi-vector attacks. Pre-defined correlation rules identify patterns like:

• File modification + suspicious process spawn + outbound network connection
• WAF SQLi alert + subsequent process injection attempt
• Multiple login failures + successful login from different IP + file access

Correlated events fire composite alerts with higher severity than individual signals.

Threat Intelligence & AI

Threat Intelligence (AbuseIPDB)

BinaryWebEngine integrates with AbuseIPDB for real-time IP reputation lookups. Every request is checked against a local cache (24-hour TTL) and the AbuseIPDB API for abuse score, category, country, ISP, and domain information.

• CIDR Suppression — Configure CIDR ranges to skip (trusted partners) or always look up (critical infrastructure)
• Auto-Blocking — When enabled, IPs exceeding the abuse score threshold are automatically blocked at the WAF and firewall level PRO
• Threshold Configuration — Set the abuse score percentage (1–100) that triggers blocking
• 24-Hour Cache — Reputation data is cached per IP to reduce API calls and improve response time
• Geo/ISP Enrichment — Each lookup provides country, ISP, domain, and abuse type categories

Setup

1. Obtain an API key from AbuseIPDB
2. In the dashboard, go to Settings → API Keys and enter the key
3. Or set ABUSEIPDB_API_KEY as an environment variable
4. Configure auto-block threshold in Settings → Intel

AI Assistant PRO

The AI Assistant provides LLM-powered security analysis using NVIDIA, Google Gemini, or OpenAI models. All AI responses are grounded in real engine data and verified against the provided context to prevent hallucinations.

Capabilities

• Alert Explanation — One-click AI analysis of any alert with context from related events, kill chain status, process trees, and known WAF signatures
• Conversational Chat — Full-system AI chat that can query live data: alerts, blocked IPs, WAF events, traffic statistics, intelligence data, process/network state, hardening scores, audit entries, custom WAF rules, fleet status
• Tool Calling — The AI can request real-time data by generating tool markers in responses. Supported tools: get_alerts, get_login_events, get_waf_events, get_traffic, get_intel, get_processes, get_network, get_hardening, get_audit, get_custom_rules, get_fleet
• Action Suggestions — The AI can suggest actions (block IP, resolve alert, unblock IP, add directory) rendered as clickable buttons
• Grounding Verification — All responses are post-processed to verify that any IPs, file paths, or timestamps mentioned exist in the provided context data

Provider Configuration

How to Use

1. Configure an AI provider API key in Settings → API Keys
2. Apply a license key that includes the ai feature (Settings → Subscription)
3. Click the AI button next to any alert for an explanation
4. Use the floating chat widget (bottom-right) for conversational queries
5. Click suggested action buttons in AI responses to execute remediation

False Positive Advisor PRO

Reduces alert fatigue by scoring each alert for false positive likelihood. Uses a combination of heuristic factors and optional AI enhancement:

• Heuristic Scoring — Considers: same-IP alert frequency, known scanner ASNs, safe port usage, process whitelist matches, WAF signature false-positive reputation
• AI Enhancement — When the AI Assistant is active, a full LLM analysis is performed for each alert with natural-language explanation of the score
• Batch Scoring — Score all unresolved alerts at once from the Alerts tab
• Score Persistence — Scores are cached in the database so they are not recalculated

JA3 Fingerprinting

Passive TLS fingerprinting captures JA3 hashes from network traffic to identify known malicious TLS clients, C2 frameworks, and automated attack tools.

• Captures JA3 hashes via Scapy or tshark packet capture
• Matches against a built-in database of known C2 profiles
• Alerts on previously unseen or suspicious fingerprints

Enterprise Management

Fleet Management PRO

The Hub & Spoke fleet architecture enables centralised monitoring of multiple servers from a single BinaryWebEngine dashboard — no separate SIEM required.

Architecture

Setup Guide

Hub (one per fleet):

# Generate certificates (first time only)
./scripts/gen_fleet_certs.sh --agents web-01,db-01,api-01

# Start hub
export BWE_AGENT_MODE=hub
./bwe

Agent (each worker):

export BWE_AGENT_MODE=agent
export BWE_HUB_HOST=10.0.0.1
export BWE_AGENT_CERT=certs/web-01.pem
./bwe

• Heartbeat — Agents send signed heartbeats every 30s. The hub marks agents offline after 3 missed heartbeats (90s)
• Config Push — Push configuration diffs to individual agents from the Fleet tab. Agents apply changes live or queue restart-required flags
• Security — Mutual TLS with per-agent client certificates. Falls back to plain TCP with a warning if fleet.mtls_enabled: false
• Source Filter — The Alerts tab "All sources" dropdown lets you filter by agent hostname

SIEM Forwarding PRO

Forward alerts to external SIEM platforms in standard formats:

• Formats — CEF (Common Event Format), JSON, LEEF
• Transports — TLS, UDP, TCP
• Compatibility — Splunk, ELK Stack, QRadar, ArcSight, Sumo Logic
• Configure in Settings → Engine or via the API

SOAR & Notifications PRO

Multi-channel alert notifications with HMAC-signed webhook verification:

• Channels — Discord (rich embeds), Telegram (HTML messages), Slack
• SOAR Platforms — Tines, Shuffle, n8n, PagerDuty, Splunk SOAR
• Verification — Webhook payloads are signed with X-BWE-Signature header using HMAC-SHA256
• Severity Filtering — Configurable minimum severity threshold for notifications
• Per-Rule Webhooks — Alert Rules tab allows custom webhook URLs per rule

Compliance Reports PRO

Auto-generated executive reports for CISOs, auditors, and compliance reviews:

• HTML Reports — Professional dark-themed layout with 8 sections
• PDF Export — High-quality PDF via WeasyPrint engine
• Report Sections: Executive Summary, Security Scorecard (8 metrics: Total Alerts, WAF Blocks, Monitored Files, Quarantined Files, Suspicious Processes, Suspicious Connections, Unresolved Alerts, Resolution Rate), Incident Breakdown by Severity + Module, WAF Analysis with attack type distribution, Top Threat Actors by IP with abuse scores, Critical and High Severity Alerts table, Recommendations (context-aware based on risk level), Methodology
• Scheduling — Auto-generate on configurable interval (default 7 days)
• Access from the Reports tab or GET /report/compliance

Configuration

BinaryWebEngine is configured via a central YAML file. All settings can be modified at runtime through the Settings modal or API endpoints.

Settings Modal (Dashboard)

Click the gear icon in the top-right corner to open Settings with 5 tabs:

• General — Admin password, database path, log level, alert retention, monitoring directories
• API Keys — AI provider key (NVIDIA/Gemini/OpenAI), AbuseIPDB key, VirusTotal key. Colored status badges show saved/unset state
• Engine — WAF enable/disable, rate limit, auto-block firewall toggle, anomaly detection toggle, login monitor configuration
• Intel — Auto-block enable/disable, abuse score threshold (1–100%), CIDR excluded ranges
• Subscription — License key input and current feature status display

Configuration File (config.yaml)

engine:
  name: BinaryWebEngine
  version: 1.0.0
  log_level: INFO

api:
  host: 0.0.0.0
  port: 8000
  auth:
    admin_user: admin
    admin_password: ""
    secret_key: change-in-production

database:
  path: security_engine.db
  retention_days: 90

waf:
  enabled: true
  rate_limit:
    requests_per_minute: 60
    block_duration: 300
  auto_block_firewall: true

intel:
  enabled: true
  abuse_threshold: 25
  auto_block_enabled: false
  auto_block_threshold: 75

monitoring:
  directories:
    - uploads
    - tmp
  hash_algorithm: sha256
  scan_on_modify: true

processes:
  cpu_limit: 90.0
  mem_limit_mb: 1024
  auto_kill_high_usage: false

login_monitor:
  brute_force_threshold: 5
  brute_force_window_seconds: 60
  block_duration_seconds: 3600
  poll_interval: 10

Operations

API Reference

BinaryWebEngine exposes a REST API for integration with existing tools and workflows. All endpoints require authentication (session cookie or API key).

Authentication & System

Alerts & Incidents

WAF

Traffic & Network

AI

Fleet

Configuration

Security Events

Reports

Real-Time

Monitoring

Alert Rules

System

Environment Variables

Deployment

Single-File Executable (Recommended)

# Run directly (no dependencies needed)
./bwe

# Run with demo data
./bwe --demo

# Run with custom config
./bwe --config /path/to/custom.yaml

systemd Service

sudo cp scripts/bwe-deploy /etc/systemd/system/binarywebengine.service
sudo systemctl daemon-reload
sudo systemctl enable --now binarywebengine

Docker

docker compose up -d

Nginx Reverse Proxy (SSL)

server {
    listen 443 ssl;
    server_name security.example.com;
    ssl_certificate /etc/letsencrypt/live/security.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/security.example.com/privkey.pem;
    location / { proxy_pass http://127.0.0.1:8000; }
    location /ws {
        proxy_pass http://127.0.0.1:8000/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Docker Compose

version: '3.8'
services:
  bwe:
    image: binaryshielders/bwe:latest
    ports:
      - "8000:8000"
      - "9001:9001"
    volumes:
      - ./data:/data
      - ./config:/config
    environment:
      - BWE_ADMIN_PASSWORD=your-secure-password
      - BWE_SECRET_KEY=your-secret-key
    restart: unless-stopped

Troubleshooting

Licensing System

BinaryWebEngine uses an HMAC-SHA256 signed license key system to gate premium features. The public build includes all features unlocked. The licensed build requires a valid key for premium functionality.

Premium Features

Key Format

BWE-XXXXXXXX-features-days-HMAC

• XXXXXXXX = 8-char random hex UID (unique per key)
• features = comma-separated codes (e.g., ai,siem,soar,mh)
• days = validity in days (1–3650)
• HMAC = first 16 hex chars of SHA256-HMAC of payload

How to Apply a License Key

1. Navigate to Settings → Subscription (gear icon in top-right)
2. Enter the license key in the input field
3. Click Apply
4. Premium features unlock immediately no restart required
5. Feature status badges update to show enabled/disabled state