Sirius is an open-source comprehensive vulnerability scanner that leverages community-driven security intelligence and automated penetration testing capabilities. Get started in minutes with our Docker-based setup.

• 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)

# Clone and start Sirius
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose up -d

# Access the web interface
open http://localhost:3000

Login Credentials:

• Username: admin
• Password: password

⚠️ Security Notice: Change these default credentials immediately in production environments.

The default configuration provides a complete scanning environment:

git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose up -d

For the cleanest experience without development tooling:

git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose -f docker-compose.user.yaml up -d

For production environments with optimized performance:

git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose -f docker-compose.production.yaml up -d

# 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/health

• 🔍 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, Air live-reload	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

User Interface (sirius-ui)
    ↓ HTTP/WebSocket
REST API (sirius-api)
    ↓ AMQP Messages
Message Queue (sirius-rabbitmq)
    ↓ Queue Processing
Scanning Engine (sirius-engine)
    ↓ SQL Queries
Database (sirius-postgres)

• 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 up -d

This configuration provides:

• ✅ Complete scanning capabilities out-of-the-box
• ✅ Pre-configured vulnerability databases
• ✅ No additional setup required
• ✅ Production-ready security scanning

For developers contributing to Sirius or building custom integrations:

• Git repositories for individual components
• Go 1.21+ for backend development
• Node.js 20+ for frontend development
• Understanding of Docker multi-stage builds

1. Clone Component Repositories (Optional - for component development):

# Create development directory structure
mkdir -p ../minor-projects && cd ../minor-projects

# Clone only the components you want to develop:
git clone https://github.com/SiriusScan/go-api.git          # REST API backend
git clone https://github.com/SiriusScan/app-scanner.git    # Scanning engine
git clone https://github.com/SiriusScan/app-terminal.git   # Terminal service
git clone https://github.com/SiriusScan/app-agent.git      # Remote agents
git clone https://github.com/SiriusScan/sirius-nse.git     # NSE scripts

2. Enable Development Mode:

Edit docker-compose.override.yaml and uncomment volume mounts for components you're developing:

# Uncomment ONLY for repositories you have cloned:
# - ../minor-projects/app-agent:/app-agent        # Agent development
# - ../minor-projects/app-scanner:/app-scanner    # Scanner development
# - ../minor-projects/app-terminal:/app-terminal  # Terminal development
# - ../minor-projects/go-api:/go-api              # API development

3. Start Development Environment:

cd Sirius
docker compose down && docker compose up -d --build

• 🔥 Hot Reload: Live code reloading with Air for Go services
• 📝 Live Editing: Frontend changes reflect immediately
• 🐛 Debug Mode: Detailed logging and error reporting
• 🔍 Development Tools: Access to Go toolchain and debugging utilities

# View real-time logs
docker compose logs -f sirius-engine

# Access development container
docker exec -it sirius-engine bash

# Check live reload status
docker exec sirius-engine ps aux | grep air

# Restart specific service
docker restart sirius-engine

# Rebuild with changes
docker compose up -d --build

# Run comprehensive test suite
./run_tests.sh --all

# Run specific test categories
./run_tests.sh --models      # Backend model tests
./run_tests.sh --ui          # Frontend UI tests
./run_tests.sh --integration # Integration tests
./run_tests.sh --security    # Security validation tests

# Manual testing commands
docker exec sirius-engine nmap --version
docker exec sirius-api go test ./...

Sirius provides comprehensive APIs for integration with existing security workflows:

• Authentication: /api/auth - JWT-based authentication
• Hosts: /api/hosts - Host management and discovery
• Scans: /api/scans - Scan management and execution
• Vulnerabilities: /api/vulnerabilities - Vulnerability data access
• Reports: /api/reports - Report generation and export

• Real-time Updates: Live scan progress and vulnerability notifications
• Agent Communication: Bidirectional agent management
• System Monitoring: Live system metrics and health status

# Start a network scan via API
curl -X POST http://localhost:9001/api/scans \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target": "192.168.1.0/24", "scan_type": "network"}'

# Get vulnerability summary
curl http://localhost:9001/api/vulnerabilities/summary \
  -H "Authorization: Bearer $TOKEN"

# Export scan results
curl http://localhost:9001/api/reports/scan/123/pdf \
  -H "Authorization: Bearer $TOKEN" \
  -o scan-report.pdf

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 down && docker compose up -d --build  # Fresh restart
docker system prune -f                               # Clean up space

Problem: "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 needed

Problem: 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 installation

Problem: "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 -d

Problem: 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:15672  # guest/guest

Problem: 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 sirius_default

Problem: 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 all

Complete 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

# Fresh start
docker compose up -d --build

Backup 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:

1. Change Default Credentials:

# Update in docker-compose.production.yaml
POSTGRES_PASSWORD=your_secure_password
RABBITMQ_DEFAULT_PASS=your_secure_password
NEXTAUTH_SECRET=your_long_random_secret

2. 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

3. SSL/TLS Configuration:

# Use reverse proxy with SSL (nginx/traefik)
# Enable HTTPS for web interface
# Secure API endpoints with proper certificates

4. 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.