Sirius is an open-source comprehensive vulnerability scanner that leverages community-driven security intelligence and automated penetration testing capabilities. v1.0.0 is the first production release, bringing the complete scanning platform, hardened CI/CD workflows, and release-grade deployment readiness. Get started in minutes with our Docker-based setup.
- End Users: Quick Start, Installation, Interface Tour
- Contributors: CONTRIBUTING.md, Issue Tracker, Discussions
- Maintainers: Maintainer Ops Review, CI/CD Guide, Container Testing
- Docker Engine 20.10.0+ with Docker Compose V2
- System Requirements: 4GB RAM minimum, 10GB free disk space
- Network Access: Internet connectivity for vulnerability database updates
- Supported Platforms: Linux, macOS, Windows (with WSL2)
# 1) Generate/merge required runtime secrets (.env)
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
# 2a) Start standard stack
docker compose up -d
# 2b) Start development overlay
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d
# 2c) Optional hardened production overlay
docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -d# Clone repository
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
# Generate and validate startup secrets/config (installer-first)
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
# Start Sirius with release images
docker compose up -d
# Access the web interface
open http://localhost:3000Important:
SIRIUS_API_KEYis required forsirius-ui,sirius-api, andsirius-engine.POSTGRES_PASSWORD,NEXTAUTH_SECRET, andINITIAL_ADMIN_PASSWORDare required.- This repository does not include
docker-compose.user.yaml; usedocker-compose.yaml,docker-compose.dev.yaml, anddocker-compose.prod.yaml.
Sirius now uses an installer-first startup flow. This keeps secrets synchronized across services and removes insecure defaults.
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
docker compose up -dWhat happens:
- Reads
.env.production.example - Merges existing
.envvalues if present - Generates missing required values:
SIRIUS_API_KEYPOSTGRES_PASSWORDNEXTAUTH_SECRETINITIAL_ADMIN_PASSWORD
docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets
docker compose up -ddocker compose -f docker-compose.installer.yaml run --rm sirius-installer --forcedocker compose -f docker-compose.installer.yaml run --rm sirius-installer
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -dSIRIUS_API_KEY=test-key \
POSTGRES_PASSWORD=test-pass \
NEXTAUTH_SECRET=test-secret \
INITIAL_ADMIN_PASSWORD=test-admin-pass \
docker compose config --quiet- Real-time Health Monitoring: Live service health checks for all components
- Centralized Logging: Unified log collection and management system
- Performance Metrics: Container resource utilization tracking
- System Dashboard: Comprehensive monitoring interface at
/system-monitor
- Improved Container Builds: Production-ready Docker configurations
- Better Error Handling: Comprehensive error management and recovery
- SSH Troubleshooting: Enhanced debugging capabilities for deployments
- Automated Testing: Robust container testing and validation
The default configuration provides a complete scanning environment:
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
docker compose up -dUse live-reload/development mounts for active code work:
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -dOptional hardened production settings and validation overlay:
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -dsirius-engineruns withNET_RAWcapability in base/dev/prod compose configurations for ICMP-based fingerprint discovery.- Keep
SIRIUS_API_URLandAPI_BASE_URLpointing tohttp://sirius-api:9001for container-to-container API persistence. - Use
NEXT_PUBLIC_SIRIUS_API_URL=http://localhost:9001so browser calls hit the host-exposed API.
# Check all services are running
docker ps
# Expected services:
# - sirius-ui (port 3000)
# - sirius-api (port 9001)
# - sirius-engine (ports 5174, 50051)
# - sirius-postgres (port 5432)
# - sirius-rabbitmq (ports 5672, 15672)
# - sirius-valkey (port 6379)
# Access web interface
curl http://localhost:3000
# Check API health
curl http://localhost:9001/healthUse this sequence to validate a production rollout from a fresh checkout.
# 1) Start from a clean runtime state
docker compose down -v --remove-orphans
# 2) Generate runtime secrets/config
docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets
# 3) Build from local source deterministically (no registry pulls)
env -u SIRIUS_API_KEY -u POSTGRES_PASSWORD -u NEXTAUTH_SECRET -u INITIAL_ADMIN_PASSWORD \
SIRIUS_IMAGE_PULL_POLICY=never docker compose up -d --build
# 4) Confirm all services are healthy
docker compose ps
# 5) Validate API auth behavior
curl -i http://localhost:9001/host/ # expect 401 (no key)
RUNTIME_KEY=$(docker inspect sirius-api --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY=' | sed 's/^SIRIUS_API_KEY=//')
curl -i -H "X-API-Key: ${RUNTIME_KEY}" http://localhost:9001/host/ # expect 200
# 6) Ensure startup regressions are absent
docker compose logs --no-color sirius-ui sirius-engine | rg -i "ENOTFOUND|permission denied|Failed to open log file"If step 6 returns any lines, capture full logs and investigate before rollout.
Use this path to validate what operators experience when running pulled release images.
# 1) Ensure local builds are not used
docker compose down -v --remove-orphans
# 2) Generate runtime secrets/config
docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets
# 3) Pull and run release images for the selected tag
export IMAGE_TAG=v1.0.0
export SIRIUS_IMAGE_PULL_POLICY=always
docker compose up -d
# 4) Verify running container image IDs match pulled release images
bash scripts/verify-release-images.shExpected result: all checks print ✅ and no service is running an unexpected local image.
Use this check any time you run reset, switch between source/release mode, or see 401 and DB auth errors.
# Validate runtime env parity, stale postgres entrypoint behavior, and auth probes
bash scripts/verify-runtime-auth-contract.shIf this script fails, do not start new scans until the mismatch is corrected.
If sirius-engine is still restarting after this passes, verify runtime preflight tooling:
docker exec sirius-engine sh -lc 'which psql && psql --version'Expected result: prints /usr/bin/psql and a PostgreSQL client version. If missing, pull the corrected release image and recreate services.
If scans complete in backend logs but UI remains non-terminal, run:
# 0) Do NOT use command-scoped secret overrides for single-service restarts.
# Bad (causes key drift): SIRIUS_API_KEY=local-dev docker compose up -d sirius-engine
# Good: keep secrets in .env and recreate dependent services together.
# 1) Verify API key contract is consistent across services
docker inspect sirius-ui --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY='
docker inspect sirius-api --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY='
docker inspect sirius-engine --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY='
# 2) Check engine scanner warnings and terminal status persistence
docker compose logs --no-color sirius-engine | rg -i "source-aware|status|completed|failed|warning|401"
# 3) Check UI auth/session and API bridge logs
docker compose logs --no-color sirius-ui | rg -i "JWT_SESSION_ERROR|SIRIUS_API_KEY|fetch failed|401"
# 4) Verify DB credential consistency from runtime containers
docker compose logs --no-color sirius-postgres sirius-api sirius-engine | rg -i "password authentication failed|database connection not available"
# 5) Run contract verifier
bash scripts/verify-runtime-auth-contract.sh
# 6) Verify templates endpoint is populated and not in missing/empty state
API_KEY=$(docker inspect sirius-api --format '{{range .Config.Env}}{{println .}}{{end}}' | rg '^SIRIUS_API_KEY=' | sed 's/^SIRIUS_API_KEY=//')
curl -s -D - -o /tmp/sirius-templates.json -H "X-API-Key: ${API_KEY}" http://localhost:9001/templates | rg '^HTTP/|^X-Sirius-Template-State'
python3 -c 'import json; print(len(json.load(open("/tmp/sirius-templates.json"))))'If any command surfaces key/secret mismatch, re-run installer and restart:
docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets
docker compose up -d --force-recreateExpected result for step 6: HTTP 200 and template count >= 1. If X-Sirius-Template-State: missing or empty appears, sirius-engine has not initialized template data yet.
# Confirm compose renders successfully and includes NET_RAW
SIRIUS_API_KEY=test-key POSTGRES_PASSWORD=test-pass NEXTAUTH_SECRET=test-secret \
INITIAL_ADMIN_PASSWORD=test-admin-pass \
docker compose -f docker-compose.yaml config | rg "NET_RAW"
# Confirm scanner system template is canonicalized on startup (quick includes fingerprint)
docker compose exec sirius-valkey valkey-cli GET template:quick | rg '"scan_types"'
# Run a scan from UI/API, then verify queue consumers and scan state
docker compose exec sirius-rabbitmq rabbitmqctl list_queues name consumers messages_ready messages_unacknowledged | rg "scan|scan_control"
docker compose exec sirius-valkey valkey-cli GET currentScan- 🔍 Network Discovery: Automated host discovery and service enumeration
- 🛡️ Vulnerability Assessment: CVE-based vulnerability detection with CVSS scoring
- 📊 Risk Management: Comprehensive risk scoring and remediation guidance
- 🎪 Visual Scanning Workflows: Drag-and-drop scan configuration
- 🔄 Automated Scanning: Scheduled and continuous security assessments
- 📡 Remote Agent Support: Distributed scanning across multiple environments
- 💻 Interactive Terminal: PowerShell-based command interface for advanced operations
- 📈 Real-time Dashboards: Live scanning progress and vulnerability metrics
- Network Scanning: Nmap-based port and service discovery
- Vulnerability Scanning: NSE script-based vulnerability detection
- SMB/Windows Assessment: Specialized Windows security testing
- Custom Workflows: User-defined scanning configurations
- Agent-based Scanning: Remote endpoint assessment
Sirius uses a microservices architecture with the following components:
| Service | Description | Technology | Ports | Purpose |
|---|---|---|---|---|
| sirius-ui | Web frontend | Next.js 14, React, TailwindCSS | 3000 | User interface and visualization |
| sirius-api | REST API backend | Go, Gin framework | 9001 | API endpoints and business logic |
| sirius-engine | Multi-service container | Go services + embedded app-agent gRPC server | 5174, 50051 | Scanner, terminal, and agent services |
| sirius-postgres | Primary database | PostgreSQL 15 | 5432 | Vulnerability and scan data storage |
| sirius-rabbitmq | Message queue | RabbitMQ | 5672, 15672 | Inter-service communication |
| sirius-valkey | Cache layer | Redis-compatible | 6379 | Session and temporary data |
graph TD
subgraph clients [Clients]
UI["Sirius UI (Next.js)"]
CLI["Terminal and Agent Runtime"]
end
subgraph core [Core Services]
API["Sirius API (Go/Gin)"]
Engine["Sirius Engine"]
end
subgraph infra [Infrastructure]
MQ["RabbitMQ"]
DB["PostgreSQL"]
Cache["Valkey"]
end
UI -->|"HTTP/WebSocket"| API
CLI -->|"gRPC"| Engine
API -->|"AMQP publish"| MQ
MQ -->|"Queue consume"| Engine
API -->|"SQL read/write"| DB
Engine -->|"SQL read/write"| DB
API -->|"Session/cache ops"| Cache
Engine -->|"Scan state cache ops"| Cache
app-agentruns insidesirius-enginein the default deployment.- The gRPC endpoint is exposed on port
50051. - You do not need a separate
app-agentcontainer for the standard/prod compose flows in this repo.
- PostgreSQL: Vulnerability data, scan results, host information
- SQLite: User authentication and session data (development)
- Valkey/Redis: Caching, temporary scan data, session storage
- RabbitMQ: Message queues for scan requests and agent communication
Your central command center featuring:
- Real-time scanning activity and progress monitoring
- Latest vulnerability discoveries with severity trends
- System performance metrics and resource utilization
- Quick-access controls for common scanning operations
- Executive summary with risk scoring
Advanced scanning capabilities:
- Visual Workflow Editor: Drag-and-drop scan module configuration
- Real-time Progress: Live scan status with detailed logging
- Custom Profiles: Save and reuse scanning configurations
- Scheduled Scans: Automated scanning with cron-like scheduling
- Multi-target Support: Scan multiple hosts, networks, or IP ranges
- NSE Script Integration: Custom Nmap scripts for specialized testing
Comprehensive vulnerability management:
- Dynamic Filtering: Real-time search across all vulnerability data
- Risk Prioritization: CVSS-based severity sorting and filtering
- Detailed Reports: CVE/CPE mapping with remediation guidance
- Export Capabilities: PDF, CSV, and JSON report generation
- Historical Tracking: Vulnerability timeline and remediation progress
- Integration Ready: API endpoints for external security tools
Complete infrastructure visibility:
- Asset Inventory: Comprehensive host and service discovery
- Network Topology: Interactive visualization of discovered infrastructure
- Risk Assessment: Environment-wide security posture analysis
- Service Enumeration: Detailed service versioning and configuration
- Compliance Tracking: Security baseline monitoring and reporting
In-depth system analysis:
- System Profiling: Complete hardware and software inventory
- Port Analysis: Detailed service discovery and version detection
- Security Metrics: Host-specific vulnerability counts and risk scores
- Historical Data: Scan history and security trend analysis
- Remediation Tracking: Fix validation and security improvement monitoring
Advanced operations console:
- PowerShell Environment: Full scripting capabilities for automation
- Agent Management: Remote agent deployment and configuration
- Custom Scripts: Execute custom security testing scripts
- Batch Operations: Bulk scanning and management operations
- System Diagnostics: Real-time system health and performance monitoring
Perfect for security professionals and penetration testers:
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose -f docker-compose.installer.yaml run --rm sirius-installer
docker compose up -dThis configuration provides:
- ✅ Complete scanning capabilities out-of-the-box
- ✅ Pre-configured vulnerability databases
- ✅ No additional setup required
- ✅ Production-ready security scanning
Want to contribute to Sirius? We welcome contributions from the community!
For Developers: Check out our comprehensive Contributing Guide for:
- 🔧 Development environment setup
- 🔄 Development workflow and best practices
- 🧪 Testing and quality assurance
- 📝 Code standards and Git workflow
- 🚀 Submitting pull requests
Quick Links:
Join our community and help make security scanning accessible to everyone!
Sirius provides comprehensive APIs for integration with existing security workflows:
- Sirius exposes REST endpoints on
http://localhost:9001. - The API is protected by
SIRIUS_API_KEYmiddleware. - Include the API key in requests with
X-API-Key: <your key>.
- Real-time Updates: Live scan progress and vulnerability notifications
- Agent Communication: Bidirectional agent management
- System Monitoring: Live system metrics and health status
# Health endpoint
curl http://localhost:9001/health \
-H "X-API-Key: $SIRIUS_API_KEY"
# Example authenticated request
curl http://localhost:9001/api/v1/scan/get/all \
-H "X-API-Key: $SIRIUS_API_KEY"Problem: Services fail to start
# Diagnosis
docker compose ps # Check service status
docker compose logs <service> # View service logs
docker system df # Check disk space
# Solutions
docker compose -f docker-compose.installer.yaml run --rm sirius-installer # Ensure required secrets exist in .env
docker compose down && docker compose up -d --build # Fresh restart
docker system prune -f # Clean up spaceProblem: Infrastructure services (PostgreSQL, RabbitMQ, Valkey) don't start
# This occurs when using only docker-compose.dev.yaml
# The dev file is an OVERRIDE file, not standalone
# ❌ Wrong (only starts 3 services):
docker compose -f docker-compose.dev.yaml up -d
# ✅ Correct (starts all 6 services):
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -dProblem: "Port already in use" errors
# Find process using port
netstat -tuln | grep 3000
lsof -i :3000
# Solution: Stop conflicting service or change port
docker compose down
# Edit docker-compose.yaml to use different ports if neededProblem: Nmap errors or scanning failures
# Check scanner logs
docker logs sirius-engine | grep -i nmap
# Test Nmap directly
docker exec sirius-engine nmap --version
docker exec sirius-engine nmap -p 80 127.0.0.1
# Common fixes
docker restart sirius-engine
docker exec sirius-engine which nmap # Verify Nmap installationProblem: "Duplicate port specification" warnings
# This is resolved in current version, but if you see it:
docker exec sirius-engine grep -r "port.*specification" /app-scanner-src/
# Should show corrected port ranges like "1-1000,3389"Problem: Database connection failures
# Check PostgreSQL status
docker exec sirius-postgres pg_isready
docker logs sirius-postgres
# Test connection
docker exec sirius-postgres psql -U postgres -d sirius -c "SELECT version();"
# Reset database if needed
docker compose down
docker volume rm sirius_postgres_data
docker compose up -dProblem: RabbitMQ connectivity issues
# Check RabbitMQ status
docker exec sirius-rabbitmq rabbitmqctl status
# View queue status
docker exec sirius-rabbitmq rabbitmqctl list_queues
# Access management interface
open http://localhost:15672Problem: RabbitMQ schema integrity check failed
# This occurs when RabbitMQ has old data from an incompatible version
# Solution: Remove old volumes and restart fresh
docker compose down -v # For standard setup
# Or for development:
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml down -v
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -dProblem: Services can't communicate
# Test internal network
docker exec sirius-ui ping sirius-api
docker exec sirius-api ping sirius-postgres
# Check network configuration
docker network ls
docker network inspect siriusProblem: External access issues
# Verify port mapping
docker port sirius-ui
docker port sirius-api
# Check firewall (Linux)
sudo ufw status
sudo iptables -L
# Check firewall (macOS)
sudo pfctl -s allComplete System Reset:
# Stop all services
docker compose down
# Remove all data (⚠️ This deletes all scan data!)
docker compose down -v
# Clean Docker system
docker system prune -a -f
# Recreate .env using installer (required after reset)
docker compose -f docker-compose.installer.yaml run --rm sirius-installer --non-interactive --no-print-secrets
# Fresh start without shell variable shadowing
env -u SIRIUS_API_KEY -u POSTGRES_PASSWORD -u NEXTAUTH_SECRET -u INITIAL_ADMIN_PASSWORD \
SIRIUS_IMAGE_PULL_POLICY=never docker compose up -d --build
# Verify auth contract before interacting with UI
bash scripts/verify-runtime-auth-contract.shBackup Current Data:
# Backup database
docker exec sirius-postgres pg_dump -U postgres sirius > backup.sql
# Backup scan results directory
docker cp sirius-engine:/opt/sirius/ ./sirius-backup/Essential Security Steps:
- Change Default Credentials:
# Generate secure values with the installer
docker compose -f docker-compose.installer.yaml run --rm sirius-installer --force
# Or set explicit values in .env if needed
# POSTGRES_PASSWORD=your_secure_password
# NEXTAUTH_SECRET=your_long_random_secret
# SIRIUS_API_KEY=your_long_random_api_key
# INITIAL_ADMIN_PASSWORD=your_strong_admin_password- Network Security:
# Use internal networks for service communication
# Expose only necessary ports (3000 for UI)
# Configure firewall rules
sudo ufw allow 3000/tcp
sudo ufw deny 5432/tcp # Don't expose database- SSL/TLS Configuration:
# Use reverse proxy with SSL (nginx/traefik)
# Enable HTTPS for web interface
# Secure API endpoints with proper certificates- Data Protection:
# Encrypt database backups
# Secure volume mounts
# Regular security updates
docker compose pull # Update images regularly- Network Isolation: Run scans from isolated networks when possible
- Permission Management: Use least-privilege principles for scan accounts
- Scan Scheduling: Perform intensive scans during maintenance windows
- Data Retention: Implement appropriate data lifecycle policies
- Audit Logging: Enable comprehensive logging for compliance
- 📘 Installation Guide - Detailed setup instructions
- 🎯 Quick Start Guide - Get scanning in 5 minutes
- 🎪 Interface Tour - Complete UI walkthrough
- 🔧 Configuration Guide - Advanced configuration options
- 🛡️ Security Guide - Production security best practices
- 🚀 API Reference - Complete API documentation
- 📦 Go SDK - Go integration library
- 🐳 Docker Guide - Comprehensive Docker documentation
- 🏗️ Architecture Guide - System architecture deep-dive
- 🔄 CI/CD Guide - Deployment automation
- 🔍 Scanning Guide - Advanced scanning techniques
- 🎯 Vulnerability Management - Managing discovered vulnerabilities
- 🌐 Environment Management - Infrastructure assessment
- 🖥️ Host Management - Individual host analysis
- 💻 Terminal Guide - Advanced PowerShell operations
- ❓ FAQ - Frequently asked questions
- 🐛 GitHub Issues - Bug reports and feature requests
- 💬 Discord Community - Real-time community support
- 🤝 Contributing Guide - How to contribute to Sirius
- 📧 Support Contact - Direct technical support
| Use Case | CPU | RAM | Storage | Network |
|---|---|---|---|---|
| Personal Lab | 2 cores | 4GB | 20GB | Basic |
| Small Business | 4 cores | 8GB | 100GB | Dedicated |
| Enterprise | 8+ cores | 16GB+ | 500GB+ | High-speed |
| MSP/Large Scale | 16+ cores | 32GB+ | 1TB+ | Enterprise |
# Monitor resource usage
docker stats
# Optimize for large environments
# Edit docker-compose.yaml and add:
services:
sirius-engine:
deploy:
resources:
limits:
cpus: '4.0'
memory: 8G
reservations:
cpus: '2.0'
memory: 4G- ✅ Fixed Nmap Configuration: Resolved duplicate port specification warnings
- ✅ Enhanced Development Mode: Improved volume mounting for local development
- ✅ Better Error Handling: Enhanced debugging and logging capabilities
- ✅ Performance Improvements: Optimized container startup and resource usage
- ✅ Security Enhancements: Updated default configurations and security practices
- 🔄 Advanced Reporting: Enhanced PDF and dashboard reporting
- 🎯 AI-Powered Analysis: Automated vulnerability risk assessment
- 📱 Mobile Support: Mobile-responsive interface improvements
- 🔌 Plugin System: Extensible scanning module architecture
- ☁️ Cloud Integration: Native cloud platform scanning support
This project is licensed under the terms specified in the LICENSE file.
🚀 Ready to start scanning? Follow our Quick Start Guide and have Sirius running in under 5 minutes!
💡 Need help? Join our Discord community for real-time support and discussion.
🐛 Found a bug? Report it on GitHub Issues - we respond quickly!
For production deployments, always change default credentials and review our Security Guide for best practices.
![@blacksmith-sh[bot]](https://avatars.githubusercontent.com/in/807020?s=64&v=4){kind=small}