Thank you for your interest in contributing to Sirius Scan! This guide will help you get started with contributing to our open-source vulnerability scanning platform.
Sirius is an open-source general purpose vulnerability scanner that leverages community-driven security intelligence. The project combines:
Sirius consists of several microservices:
| Service | Description | Port |
|---|---|---|
| sirius-ui | Web interface (Next.js) | 3000 |
| sirius-api | Backend API service | 9001 |
| sirius-engine | Scanning engine | 5174 |
| sirius-rabbitmq | Message broker | 5672/15672 |
| sirius-postgres | Database | 5432 |
| sirius-valkey | Key-value store | 6379 |
Before you begin contributing, ensure you have:
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius
Only clone the components you plan to develop:
# Create development directory structure
mkdir -p ../minor-projects && cd ../minor-projects
# Clone 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
git clone https://github.com/SiriusScan/app-system-monitor.git # System monitor
git clone https://github.com/SiriusScan/app-administrator.git # Administrator service
cd ../Sirius
Edit docker-compose.dev.yaml and uncomment volume mounts for components you're developing:
services:
sirius-engine:
volumes:
# Uncomment ONLY for repositories you have cloned:
# - ../minor-projects/app-agent:/app-agent-src # Agent development
# - ../minor-projects/app-scanner:/app-scanner-src # Scanner development
# - ../minor-projects/app-terminal:/app-terminal-src # Terminal development
# - ../minor-projects/go-api:/go-api # API development
# - ../minor-projects/app-system-monitor:/system-monitor # Monitor development
# - ../minor-projects/app-administrator:/app-administrator # Admin development
# Development mode requires BOTH config files
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build
# Or for a clean start
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
⚠️ Important: The docker-compose.dev.yaml file is an override file, not a standalone configuration. You must specify both the base configuration (docker-compose.yaml) and the development overrides (docker-compose.dev.yaml) when starting services in development mode.
# 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 (development mode)
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d --build
# Stop development environment
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml down
# Clean restart (removes volumes)
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
# Access the container
docker exec -it sirius-engine bash
# Run tests
go test ./...
# Build manually
go build -o binary main.go
# Check dependencies
go mod tidy
# Access the UI container
docker exec -it sirius-ui bash
# Install dependencies
npm install
# Run development server
npm run dev
# Build production
npm run build
Before starting work:
Use descriptive branch names:
feature/description - New featuresfix/description - Bug fixesdocs/description - Documentationrefactor/description - Code improvementstest/description - Test additionsWrite clear commit messages:
Add host discovery feature
- Implement ARP scanning
- Add subnet range support
- Include rate limiting option
Fixes #123
Guidelines:
gofmt for formatting# Run comprehensive test suite
cd testing
make test-all
# Run specific test categories
make test-build # Container build tests
make test-health # Health check tests
make test-integration # Integration tests
# Run documentation validation
make lint-docs # Full documentation linting
make lint-docs-quick # Quick documentation checks
make lint-index # Index completeness check
# Test scanner functionality
docker exec sirius-engine nmap --version
docker exec sirius-engine nmap -p 80 127.0.0.1
# Test API endpoints
curl http://localhost:9001/health
curl http://localhost:9001/api/v1/system/health
# Test database connection
docker exec sirius-postgres pg_isready
docker exec sirius-postgres psql -U postgres -d sirius -c "SELECT version();"
# Test RabbitMQ
docker exec sirius-rabbitmq rabbitmqctl status
docker exec sirius-rabbitmq rabbitmqctl list_queues
Before committing code, always run:
# Run all validation checks
cd testing
make validate-all
# Or use the pre-commit hook (automatically runs on commit)
git commit -m "your commit message"
The pre-commit hook automatically runs:
Service fails to start
docker compose logs <service-name>netstat -tulnDatabase connection issues
docker compose ps sirius-postgresMessage queue problems
We value all contributions and recognize them through:
Thank you for contributing to Sirius Scan! Your efforts help make security scanning accessible to everyone.