Sirius Scan

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.

🚀 Quick Start Guide

Prerequisites

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)

⚡ One-Command Setup

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

🔧 Installation Options

Option 1: Standard Setup (Recommended for Most Users)

The default configuration provides a complete scanning environment:

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

Option 2: User-Focused Setup (Simplified)

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

Option 3: Production Deployment

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

✅ Verify Installation

# 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

🎯 What Can Sirius Do?

Core Capabilities

🔍 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

Supported Scan Types

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

🏗️ System Architecture

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

📡 Service Communication Flow

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)

🗄️ Data Storage

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

📱 Interface Overview

📊 Dashboard

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

🔍 Scanning Interface

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

🎯 Vulnerability Navigator

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

🌐 Environment Overview

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

🖥️ Host Details

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

💻 Terminal Interface

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

🛠️ Development & Customization

🎯 End User Setup (Recommended)

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

🔧 Developer Setup (Advanced)

For developers contributing to Sirius or building custom integrations:

Prerequisites for Development

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

Setup Development Environment

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

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

Start Development Environment:

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

Development Features

🔥 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

Development Commands

# 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

🧪 Testing & Quality Assurance

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

🔌 API & Integration

Sirius provides comprehensive APIs for integration with existing security workflows:

REST API Endpoints

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

WebSocket APIs

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

Integration Examples

# 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

🔧 Troubleshooting

Common Issues & Solutions

🐳 Container Issues

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

🔍 Scanner Issues

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"

🗄️ Database Issues

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

🐰 Message Queue Issues

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

🌐 Network & Connectivity

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

🚨 Emergency Recovery

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/

🔒 Security Best Practices

🏭 Production Deployment

Essential Security Steps:

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

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

🛡️ Security Scanning Best Practices

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

📚 Documentation & Resources

📖 Essential Documentation

📘 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

🔌 Technical Documentation

🚀 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

🎓 User Guides

🔍 Scanning Guide - Advanced scanning techniques
🎯 Vulnerability Management - Managing discovered vulnerabilities
🌐 Environment Management - Infrastructure assessment
🖥️ Host Management - Individual host analysis
💻 Terminal Guide - Advanced PowerShell operations

🤝 Community & Support

❓ 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

📊 Performance & Scaling

📈 System Requirements by Use Case

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

⚡ Performance Optimization

# 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

🆕 What's New

Recent Updates

✅ 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

Upcoming Features

🔄 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

📄 License

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.

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.cursor		.cursor
.github/workflows		.github/workflows
documentation		documentation
environments		environments
rabbitmq		rabbitmq
scripts		scripts
sirius-api		sirius-api
sirius-engine		sirius-engine
sirius-ui		sirius-ui
tasks		tasks
.DS_Store		.DS_Store
.dockerignore		.dockerignore
.gitignore		.gitignore
LICENSE		LICENSE
README-DEVELOPMENT.md		README-DEVELOPMENT.md
README.deployment.md		README.deployment.md
README.md		README.md
cookies.txt		cookies.txt
docker-compose.local.example.yaml		docker-compose.local.example.yaml
docker-compose.override.yaml		docker-compose.override.yaml
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.production.yaml		docker-compose.production.yaml
docker-compose.staging.yaml		docker-compose.staging.yaml
docker-compose.user.yaml		docker-compose.user.yaml
docker-compose.yaml		docker-compose.yaml

License

SiriusScan/Sirius

Folders and files

Latest commit

History

Repository files navigation