base on # 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 ```bash # 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: ```bash 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: ```bash 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: ```bash git clone https://github.com/SiriusScan/Sirius.git cd Sirius docker compose -f docker-compose.production.yaml up -d ``` ### ✅ Verify Installation ```bash # 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: ```bash 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 1. **Clone Component Repositories** (Optional - for component development): ```bash # 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: ```yaml # 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**: ```bash 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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**: ```bash # 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**: ```bash # 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**: 1. **Change Default Credentials**: ```bash # 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**: ```bash # 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**: ```bash # Use reverse proxy with SSL (nginx/traefik) # Enable HTTPS for web interface # Secure API endpoints with proper certificates ``` 4. **Data Protection**: ```bash # 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](https://sirius.publickey.io/docs/getting-started/installation) - Detailed setup instructions - [🎯 Quick Start Guide](https://sirius.publickey.io/docs/getting-started/quick-start) - Get scanning in 5 minutes - [🎪 Interface Tour](https://sirius.publickey.io/docs/getting-started/interface-tour) - Complete UI walkthrough - [🔧 Configuration Guide](https://sirius.publickey.io/docs/guides/configuration) - Advanced configuration options - [🛡️ Security Guide](https://sirius.publickey.io/docs/guides/security) - Production security best practices ### 🔌 Technical Documentation - [🚀 API Reference](https://sirius.publickey.io/docs/api/rest/authentication) - Complete API documentation - [📦 Go SDK](https://sirius.publickey.io/docs/api/sdk/go) - Go integration library - [🐳 Docker Guide](./documentation/DOCKER-IMPLEMENTATION-DOCUMENTATION.md) - Comprehensive Docker documentation - [🏗️ Architecture Guide](./documentation/README.architecture.md) - System architecture deep-dive - [🔄 CI/CD Guide](./documentation/README.cicd.md) - Deployment automation ### 🎓 User Guides - [🔍 Scanning Guide](https://sirius.publickey.io/docs/guides/scanning) - Advanced scanning techniques - [🎯 Vulnerability Management](https://sirius.publickey.io/docs/guides/vulnerabilities) - Managing discovered vulnerabilities - [🌐 Environment Management](https://sirius.publickey.io/docs/guides/environment) - Infrastructure assessment - [🖥️ Host Management](https://sirius.publickey.io/docs/guides/hosts) - Individual host analysis - [💻 Terminal Guide](https://sirius.publickey.io/docs/guides/terminal) - Advanced PowerShell operations ### 🤝 Community & Support - [❓ FAQ](https://sirius.publickey.io/docs/community/faq) - Frequently asked questions - [🐛 GitHub Issues](https://github.com/SiriusScan/Sirius/issues) - Bug reports and feature requests - [💬 Discord Community](https://sirius.publickey.io/community) - Real-time community support - [🤝 Contributing Guide](https://sirius.publickey.io/docs/community/contributing) - How to contribute to Sirius - [📧 Support Contact](mailto:[email protected]) - 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 ```bash # 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](./LICENSE) file. --- **🚀 Ready to start scanning?** Follow our [Quick Start Guide](https://sirius.publickey.io/docs/getting-started/quick-start) and have Sirius running in under 5 minutes! **💡 Need help?** Join our [Discord community](https://sirius.publickey.io/community) for real-time support and discussion. **🐛 Found a bug?** Report it on [GitHub Issues](https://github.com/SiriusScan/Sirius/issues) - we respond quickly! --- _For production deployments, always change default credentials and review our [Security Guide](https://sirius.publickey.io/docs/guides/security) for best practices._ ", Assign "at most 3 tags" to the expected json: {"id":"14287","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"