Skip to content
Projects

HerbiusYang/Vigilyx has 103 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours, +2 in 7 days, and +1 in 15 days. Last checked 2026-11-17 02:54 UTC. Last push 2026-11-13.

How these counts are measured

What you can do

  • Dual Mode: passive mirror mode or inline MTA proxy mode
  • MTA Proxy: inbound SMTP relay for local domains, TLS support, sub-8 second inline verdicts, configurable fail-open or fail-closed behavior
  • Passive Capture: libpcap-based SMTP/POP3/IMAP/HTTP sniffing with no mail server integration
  • 20 Pipeline Entries by Default: 17 always-registered analyzers, 2 conditional ClamAV analyzers, and a final verdict stage; runtime aggregation defaults to clustered D-S fusion (clustered_ds_v1, exposed as ds_murphy for backward compatibility), with tbm_v5, noisy_or, and weighted_max also available

Measured star growth

in 24h
0
in 7 days
+2
in 15 days
+1
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Vigilyx is a Rust-powered email security analysis platform/Gateway for passive traffic monitoring and inline MTA inspection, with threat detection, alerting, and audit workflows.

Security

README.md

Original

Vigilyx

Real-time email threat detection platform

License Rust React Python


Two deployment modes: Mirror (passive network capture) and MTA Proxy (inline SMTP relay with block/quarantine). Vigilyx ships a default 20-entry mail-analysis pipeline, clustered Dempster-Shafer based evidence fusion, DLP, automated response, and a React dashboard in one Docker Compose deployment.

Website

Friendly Links

Community

Architecture

Core control plane (`docker compose up -d`)

                           optional integrations
                    +----------+----------+----------+
                    |    AI    |  ClamAV  | Sandbox  |
                    +----------+----------+----------+

┌──────────────────────────────────────────────────────────────┐
│ vigilyx                                                     │
│ API + frontend control plane                                │
│ - auth, REST, WebSocket, settings, SOAR                     │
│ - serves the React UI                                       │
│ - persists sessions, verdicts, stats, and config state      │
└───────────────┬──────────────────────────────────────┬───────┘
                │                                      │
                │ control topics / API auth            │ SQL
                │                                      │
┌───────────────▼───────────────┐        ┌─────────────▼─────────────┐
│ Valkey / Redis                │        │ PostgreSQL                │
│ Streams + Pub/Sub             │        │ sessions / verdicts       │
│ transport + control bus       │        │ config / audit / state    │
└───────────────────────────────┘        └───────────────────────────┘
Mirror deployment (`docker compose --profile mirror up -d` or `./deploy.sh`)

                           optional integrations
                    +----------+----------+----------+
                    |    AI    |  ClamAV  | Sandbox  |
                    +-----+----+-----+----+-----+----+
                          \          |          /
                           \         |         /
                            v        v        v
┌──────────────────────────────────────────────────────────────┐
│ vigilyx-engine-standalone                                   │
│ Dedicated analysis engine                                   │
│ - consumes Redis Streams                                    │
│ - runs parsing, detection, fusion, DLP, and SOAR hooks      │
└───────────────┬──────────────────────────────────────┬───────┘
                │                                      │
                │ SESSION_* / ENGINE_*                 │ SQL
                │ Streams + Pub/Sub                    │
                │                                      │
┌───────────────▼───────────────┐        ┌─────────────▼─────────────┐
│ Valkey / Redis                │        │ PostgreSQL                │
│ Streams + Pub/Sub             │        │ sessions / verdicts       │
│ transport + control bus       │        │ config / audit / state    │
└───────────────▲───────────────┘        └─────────────▲─────────────┘
                │                                      │
                │ mirror ingress only                  │
┌───────────────┴───────────────┐        ┌─────────────┴─────────────┐
│ vigilyx-sniffer               │        │ vigilyx                   │
│ libpcap capture               │        │ API + frontend control    │
│ -> Streams (primary)          │        │ plane                     │
│ -> Pub/Sub (shadow/control)   │        │                           │
└───────────────────────────────┘        └───────────────────────────┘
Inline MTA add-on (`--profile mta`)

Mail client / upstream MTA
            |
            v
┌──────────────────────────────────────────────────────────────┐
│ vigilyx-mta                                                 │
│ SMTP proxy + embedded Engine                                │
│ - accepts, rejects, or quarantines inline                   │
│ - reads config and stores verdict state via PostgreSQL      │
│ - uses Redis for shared transport / control paths           │
└──────────────────────────────────────────────────────────────┘
            |
            v
      downstream MTA
  • SOAR is library logic executed inside the engine and API flows, not a standalone container.
  • AI, ClamAV, and Sandbox are engine-side integrations used by the dedicated mirror-mode engine and the embedded MTA engine when enabled.
  • docker compose up -d alone starts only the control-plane services (vigilyx, postgres, redis). Add --profile mirror for passive capture or --profile mta for inline SMTP.
  • STANDALONE_ENGINE remains only for backward compatibility. Current compose defaults and deploy.sh normalize it to false, so mirror mode uses the dedicated engine container and MTA mode uses the embedded engine inside vigilyx-mta.

Features

  • Dual Mode: passive mirror mode or inline MTA proxy mode
  • MTA Proxy: inbound SMTP relay for local domains, TLS support, sub-8 second inline verdicts, configurable fail-open or fail-closed behavior
  • Passive Capture: libpcap-based SMTP/POP3/IMAP/HTTP sniffing with no mail server integration
  • 20 Pipeline Entries by Default: 17 always-registered analyzers, 2 conditional ClamAV analyzers, and a final verdict stage; runtime aggregation defaults to clustered D-S fusion (clustered_ds_v1, exposed as ds_murphy for backward compatibility), with tbm_v5, noisy_or, and weighted_max also available
  • Threat Intel: OTX, VirusTotal, and AbuseIPDB with a local IOC cache
  • DLP: 30 sensitive-data patterns, HTTP session analysis, draft box abuse, file transit, self-send, and chunked upload tracking
  • YARA: built-in and database-backed YARA rule scanning
  • Temporal Analysis: CUSUM, EWMA, Hawkes process, and HMM-based attack-phase modeling
  • SOAR: alert dispatch, email notifications, webhooks, and disposition rules
  • Real-Time Dashboard: React SPA with WebSocket updates
  • Optional Integrations: AI service, ClamAV, CAPEv2 sandbox, bundled or host-level TLS

Quick Start

Recommended remote-first workflow:

# 1. Point deploy.sh at your target host
cp deploy.conf.example deploy.conf
$EDITOR deploy.conf

# 2. Pre-pull the pinned Rust builder image on the target host
ssh root@<server> "docker pull rust:1.97.1-bookworm"

# 3. One-time initialization (sync source, generate remote .env if missing, create build container)
./deploy.sh --init

# 4. Review the remote runtime configuration
ssh root@<server> "cd <repo-root> && vi deploy/docker/.env"
# Mirror mode: set SNIFFER_INTERFACE
# Optional: AI_ENABLED=true, HF_ENDPOINT=https://hf-mirror.com
# MTA mode: set MTA_DOWNSTREAM_HOST, MTA_DOWNSTREAM_PORT, and MTA_LOCAL_DOMAINS

# 5. Deploy the topology you want
./deploy.sh                 # mirror mode (default developer path)
./deploy.sh --backend       # backend/API + mirror engine image refresh
./deploy.sh --frontend      # frontend only
./deploy.sh --sniffer       # sniffer only
./deploy.sh --mta           # inline MTA deployment

# 6. Release-grade packaging
./deploy.sh --production
./deploy.sh --production --mta

Manual Docker Compose on the target host is still supported:

# 1. Generate secrets from the project root
bash scripts/generate-secrets.sh

# 2. Edit configuration
vi deploy/docker/.env

# 3. Build and start
cd deploy/docker
docker compose build

# Mirror mode (control plane + standalone engine + sniffer)
docker compose --profile mirror up -d

# Mirror mode + AI
docker compose --profile mirror --profile ai up -d

# Mirror mode + bundled TLS
docker compose --profile mirror --profile tls up -d

# Inline MTA mode
docker compose --profile mta up -d

docker compose up -d without a profile only starts the control-plane containers. Use --profile mirror or --profile mta for an actual traffic-processing deployment.

Production: keep API_LISTEN=127.0.0.1 and terminate TLS on the host with Caddy or Nginx. See Deployment Guide.

Without HTTPS, login credentials and JWT tokens are transmitted in cleartext.

By default, the API binds to 127.0.0.1:8088; set API_LISTEN=0.0.0.0 only for temporary non-TLS testing.

After TLS is provisioned, open https://<server-or-domain>. Without TLS, access http://127.0.0.1:8088 from the server itself or through an SSH tunnel.

Login as admin with API_PASSWORD from deploy/docker/.env.

Important: API_PASSWORD must be set explicitly in .env. Default fallback credentials are disabled.

Services

Container Port Profile Purpose
vigilyx 8088 default API + frontend control plane
vigilyx-engine-standalone - mirror Dedicated analysis engine for passive deployments
vigilyx-sniffer host net mirror Packet capture for passive deployments
vigilyx-mta 25 / 465 mta SMTP proxy relay with embedded engine
vigilyx-postgres 5433 local default PostgreSQL persistence
vigilyx-redis 6379 local default Streams + Pub/Sub message bus
vigilyx-ai 8900 local ai Optional semantic/NLP and VT scrape service
vigilyx-clamav 3310 local antivirus Antivirus scanning
vigilyx-sandbox 8000 local sandbox Experimental CAPEv2 detonation
vigilyx-caddy 80 / 443 tls Bundled TLS reverse proxy

sandbox is experimental and intended for isolated internal testing with KVM/libvirt. It is not required for standard deployment or public release.

Detection Modules

17 always-registered analyzers in the default engine build:

Module Detection Target
header_scan Forged sender indicators, SPF/DMARC results, Received-chain IOC hits
content_scan Urgency language, financial bait, keyword and phrase heuristics
semantic_scan AI-assisted semantic phishing analysis
link_scan Short links, homoglyphs, IDN attacks, suspicious parameters
link_reputation Domain, URL, and IP reputation via OTX, VT, and AbuseIPDB
link_content DGA traits, brand impersonation, mixed-script domains
attach_scan Type-vs-extension mismatch via magic-byte detection
attach_content Macros, scripts, and encrypted archive heuristics
attach_hash SHA-256 matching against known malicious samples
yara_scan Built-in and database-backed YARA rule matching for EML and attachments
domain_verify Envelope and DKIM domain alignment, link-domain trust scoring, impersonation suppression
identity_anomaly Sender inconsistency and first-contact detection
html_scan Obfuscation, hidden elements, CSS cloaking, zero-width tricks
html_pixel_art Pixel tracking, beacons, and invisible iframe patterns
mime_scan MIME validation and header injection checks
transaction_correlation Cross-session fraud and business-process correlation
anomaly_detect Statistical feature anomalies

Additional pipeline entries and optional integrations:

  • av_eml_scan and av_attach_scan: enabled by configuration, but only registered when ClamAV is reachable
  • verdict: final aggregation stage for all module output
  • sandbox_scan: extra optional analyzer when the CAPEv2 sandbox integration is configured

This yields the default 20-entry pipeline documented above: 17 always-registered analyzers + 2 conditional ClamAV analyzers + 1 final verdict stage. sandbox_scan is outside that baseline and remains an optional add-on.

Subsystems: Data Security Engine (HTTP DLP, 30 patterns), temporal analyzer (CUSUM/EWMA/Hawkes/HMM), and verdict fusion with circuit breakers.

Threat Levels

Level Score Meaning
Safe < 0.15 No meaningful threat indicators
Low 0.15 - <0.40 Minor suspicious signals
Medium 0.40 - <0.65 Multiple risk indicators, needs analyst review
High 0.65 - <0.85 Strong threat evidence
Critical >= 0.85 Confirmed malicious, immediate action required

Project Structure

crates/
├── vigilyx-core/       Shared types and security primitives
├── vigilyx-parser/     SMTP, MIME, and protocol parsing shared by sniffer and MTA
├── vigilyx-sniffer/    Packet capture and passive session publishing
├── vigilyx-db/         PostgreSQL and Redis abstractions
├── vigilyx-engine/     Detection modules, fusion, DLP, temporal analysis
├── vigilyx-api/        REST API, WebSocket push, auth, metrics
├── vigilyx-soar/       Alerts and disposition logic
└── vigilyx-mta/        SMTP proxy with embedded engine
frontend/               React SPA (Vite + TypeScript)
python/vigilyx_ai/      FastAPI AI / VT scrape service
site/                   VitePress project site and public docs

Development

Vigilyx uses a remote-first workflow. Edit locally, but run Rust compilation and verification in the remote vigilyx-rust-builder container. Do not treat local cargo runs as the authoritative verification path.

# One-time setup
cp deploy.conf.example deploy.conf
$EDITOR deploy.conf
ssh root@<server> "docker pull rust:1.97.1-bookworm"
./deploy.sh --init

# Day-to-day deployment
./deploy.sh
./deploy.sh --backend
./deploy.sh --frontend
./deploy.sh --sniffer
./deploy.sh --sniffer --config-only
./deploy.sh --mta

# Release-grade builds
./deploy.sh --production
./deploy.sh --production --backend
./deploy.sh --production --frontend
./deploy.sh --production --sniffer
./deploy.sh --production --mta

# Project site / docs
cd site
npm ci
npm run dev

./deploy.sh defaults to the fast developer path (release-fast + docker-compose.fast.yml). ./deploy.sh --production switches back to the full Dockerfiles and Docker-side cargo --release image builds. By default it deploys the mirror topology; if the remote deployment mode is pinned to mta, deploy.sh keeps the MTA image in sync automatically, and ./deploy.sh --mta forces an inline-proxy rollout. For env/compose/host-tuning adjustments that do not need a rebuild, use ./deploy.sh --config-only with the relevant component flag.

The public project site lives in site/ and is published through GitHub Pages with the workflow in .github/workflows/pages.yml. For GitHub-hosted Pages, the default URL is https://herbiusyang.github.io/Vigilyx/. For a custom domain, set PAGES_CUSTOM_DOMAIN, or override PAGES_SITE_URL and PAGES_BASE_PATH in repository variables.

Passive mirror deployments can also reuse the host-side capture tuning helper directly:

ssh <server> "cd <repo-root> && bash scripts/apply-capture-host-tuning.sh --env-file deploy/docker/.env"

Manual verification on the remote build host:

ssh <server> "docker exec vigilyx-rust-builder cargo clippy --workspace -- -D warnings"
ssh <server> "docker exec vigilyx-rust-builder cargo test --workspace"
ssh <server> "docker exec vigilyx-rust-builder cargo fmt --check"

Frontend toolchain:

nvm use
bash scripts/check-frontend-toolchain.sh
cd frontend
npm ci
  • Frontend development is pinned to Node 24.19.0 via .nvmrc.
  • Use npm 12.0.2 for lockfile updates. The repo declares this in frontend/package.json and enforces it with frontend/.npmrc.
  • Run scripts/check-frontend-toolchain.sh before local or remote frontend work if you need to confirm the active Node/npm pair.
  • ./deploy.sh --frontend and the production deploy/docker/Dockerfile.api both build the frontend with the same pinned Node 24.19.0 + npm 12.0.2 toolchain.
  • For routine installs, use npm ci.
  • When changing dependencies, run npm install ... in frontend/ and commit the updated package-lock.json in the same change.

Optional local Vite HMR:

nvm use
ssh -L 8088:127.0.0.1:8088 <server>
cd frontend
npm ci
npm run dev

Containerized frontend override for local development only:

cd deploy/docker
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
nvm use
cd ../../frontend
npm ci
npm run build -- --watch

Configuration

All runtime configuration lives in deploy/docker/.env.

Variable Required Default Description
PG_PASSWORD Yes -- PostgreSQL password
REDIS_PASSWORD Yes -- Redis password
API_JWT_SECRET Yes -- JWT signing key (minimum 32 chars)
API_PASSWORD Yes -- Initial admin password
INTERNAL_API_TOKEN Yes -- Internal token for sniffer and engine to API
AI_INTERNAL_TOKEN Yes -- AI-scoped token for API and engine to AI
SNIFFER_INTERFACE No eth0 Capture network interface
SNIFFER_WORKERS No 16 Sniffer worker thread count; mirrored email traffic usually does not need dozens of workers
SNIFFER_HOST_TUNING No true Let deploy.sh apply host-side NIC/sysctl/RPS tuning for the capture interface
SNIFFER_HOST_IRQ_REBALANCE No true Rebalance capture NIC IRQs away from reserved sniffer worker CPUs
SNIFFER_HOST_IRQ_CPU_LIST No empty Optional explicit CPU list for NIC IRQs, e.g. 16-23,32-39
AI_ENABLED No false Allow vigilyx and the engine to call the AI service; still start vigilyx-ai with the ai profile
VIGILYX_MODE No empty Lock frontend deployment mode to mirror or mta
MTA_LOCAL_DOMAINS MTA -- Comma-separated local recipient domains accepted by the MTA
MTA_DOWNSTREAM_HOST MTA -- Downstream MTA address
MTA_DOWNSTREAM_PORT MTA 25 Downstream MTA SMTP port
MTA_INLINE_TIMEOUT_SECS MTA 8 Inline verdict timeout
MTA_FAIL_OPEN MTA false Relay on engine failure (true) or return SMTP 451 (false)
RUST_LOG No info Log level; never use debug in production

Full variable list: see .env.example.

Security

  • JWT auth (HS256 + Argon2) with forced password change on first login
  • Per-IP login rate limiting
  • Constant-time internal token comparison
  • One-time WebSocket ticket flow with no JWT in the URL
  • Redis and PostgreSQL bound to 127.0.0.1
  • CSP headers, SSRF protection, and masked error responses
  • Non-root containers and request tracing via X-Request-Id
  • Host-level or bundled TLS termination options

See Deployment Guide for production hardening.

Tech Stack

Layer Stack
Backend Rust 1.97.1, tokio, axum, sqlx, redis, pnet/pcap, yara-x, petgraph, dashmap, rayon, crossbeam, tracing
Frontend React 18, TypeScript, Vite, React Router
AI Python 3.12, FastAPI, Transformers, PyTorch
Infra Docker Compose, PostgreSQL 17, Valkey/Redis 8, Caddy 2

Donate

We are committed to giving back the vast majority of funds received to society. The target allocation is:

Allocation % Details
Public welfare 80% Support vulnerable groups, rural education, students, and charitable organizations
Project development 10% AI training, GPU compute, infrastructure, CI/CD, and API operating costs
Team building 10% Security researcher recruitment, contributor bounties, and community operations

Fund usage details will be published on the /community page of the Vigilyx dashboard in a future release.

Contributing

See CONTRIBUTING.md.

License

AGPL-3.0 -- if you deploy Vigilyx as a network service, you must make the source code available to your users.