Sirius Scan v1.0.0

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.

🚀 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 (uses prebuilt images from GitHub Container Registry)
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
docker compose up -d

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

Note: By default, Sirius uses prebuilt container images from GitHub Container Registry for fast deployments (5-8 minutes). For local development with source code changes, use docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d.

Login Credentials:

• Username: admin
• Password: password

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

🆕 What's New in v1.0.0

System Monitoring & Observability

• 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

Enhanced Reliability

• 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

🔧 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 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

🛠️ Standard Setup

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

🤝 Contributing

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: - Development Setup - Testing Guide - Code Standards - GitHub Issues

Join our community and help make security scanning accessible to everyone!

🔌 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: 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 -d

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

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

🌐 Network & Connectivity

Problem: Services can