app-scanner

README

Sirius Vulnerability Scanner

General-purpose network vulnerability scanner with sequential port discovery pipeline.

Architecture

The scanner uses a three-phase scanning pipeline:

Fingerprint (ping++) → Enumeration (Naabu) → Vulnerability (Nmap)
     ↓                       ↓                        ↓
 Host liveness         Find open ports          Scan discovered ports
 + OS detection

Key Features

• Port Discovery Pipeline - Nmap only scans ports discovered by Naabu
• Protocol Agnostic - No hardcoded protocol-specific logic
• Template-Based - Customizable scan profiles with NSE scripts
• Source Attribution - Complete audit trail of scan tools and configurations
• Parallel Execution - Worker pool for concurrent host scanning
• Fingerprint Ready - Placeholder for ping++ integration (coming soon)

Quick Start

Running a Scan

# Scanner runs automatically in sirius-engine container
docker logs -f sirius-engine

# Trigger scan via UI:
# http://localhost:3000/scanner → Select template → Start scan

Scan Types

Scan Type	Tool	Purpose
fingerprint	ping++*	Host liveness + OS detection
enumeration	Naabu	Fast port enumeration
port_scan	Naabu	Alias for enumeration
vulnerability	Nmap+NSE	Vulnerability scanning

*ping++ is currently a placeholder - full implementation coming soon.

See: SCAN-TYPES.md for detailed information.

Port Discovery Pipeline

How It Works

1. Fingerprint Phase (if enabled, placeholder):

   • ping++ performs host liveness detection
   • Determines OS family via TTL analysis
   • Skips dead hosts early

2. Enumeration Phase (if enabled):

   • Naabu performs fast port discovery
   • Example: discovers [80, 443, 445, 3389]

3. Vulnerability Phase:

   • Nmap scans ONLY discovered ports
   • Falls back to template port_range if no ports discovered
   • Skips scan if no ports and no template range

Creating Scan Templates

Recommended: With Enumeration

{
  "name": "Web Application Scan",
  "type": "custom",
  "scan_options": {
    "scan_types": ["enumeration", "vulnerability"],
    "port_range": "",
    "parallel": true
  },
  "enabled_scripts": ["http-vuln-*", "ssl-*"]
}

Benefits:

• Only scans open ports (fast!)
• No wasted time on closed ports
• Adapts to target configuration

Alternative: Without Enumeration

{
  "name": "SMB Direct Scan",
  "type": "custom",
  "scan_options": {
    "scan_types": ["vulnerability"],
    "port_range": "139,445",
    "parallel": true
  },
  "enabled_scripts": ["smb-vuln-*", "smb2-*"]
}

Use when:

• You know exact ports to scan
• Targeting specific services
• Fastest for known configurations

See: PORT-RANGE-OPTIMIZATION.md for port recommendations by protocol.

Performance

Port Pipeline vs Traditional

Approach	Ports Scanned	Scan Time
Port Pipeline (enumeration → vuln)	4 discovered ports	~1 minute
Traditional (vuln only with 1-65535)	All 65,535 ports	~30 minutes

Result: 30x faster for typical scans

Development

Project Structure

app-scanner/
├── cmd/                    # Test utilities
├── internal/
│   ├── scan/              # Core scanning logic
│   │   ├── manager.go     # Scan orchestration
│   │   ├── factory.go     # Tool factory
│   │   ├── strategies.go  # Scan strategies
│   │   ├── utils.go       # Helper functions
│   │   └── worker_pool.go # Parallel execution
│   ├── nse/               # NSE script management
│   └── templates/         # Template management
├── modules/
│   ├── nmap/              # Nmap integration
│   │   └── args/          # Script arguments
│   └── naabu/             # Naabu integration
├── documentation/
│   └── archive/           # Historical documentation
└── pkg/
    ├── models/            # Data models
    ├── queue/             # RabbitMQ integration
    └── store/             # ValKey integration

Building

# In container
docker exec sirius-engine bash -c "cd /app-scanner && go build ."

# Local (requires Go 1.21+)
cd /Users/oz/Projects/Sirius-Project/minor-projects/app-scanner
go build .

Testing

# Run specific test
go run cmd/scan-full-test/main.go

# Validate NSE scripts
go run cmd/validate-nse-fix/main.go

Configuration

Environment Variables

# RabbitMQ
RABBITMQ_HOST=sirius-rabbitmq
RABBITMQ_PORT=5672
RABBITMQ_QUEUE=scan_requests

# ValKey (Redis)
VALKEY_ADDR=sirius-valkey:6379

# API
GO_API_URL=http://sirius-go-api:8080

# Scanning
NMAP_PATH=/usr/bin/nmap
NSE_SCRIPTS_DIR=/opt/sirius/nse/sirius-nse

Troubleshooting

Scans Taking Too Long

Symptom: Scan runs for 10+ minutes
Cause: Scanning too many ports
Solution:

1. Enable enumeration scan type to find open ports first
2. Use protocol-specific port ranges (see PORT-RANGE-OPTIMIZATION.md)
3. Avoid port_range: "1-65535" unless necessary

No Ports Discovered

Symptom: "No ports discovered and no port_range - skipping"
Cause: Target has no open ports OR enumeration failed
Solution:

1. Verify target is accessible: docker exec sirius-engine ping <target>
2. Check firewall rules
3. Add fallback port_range in template

Nmap Errors

Symptom: "failed to build script flag" or "no port range specified"
Cause: Template misconfiguration
Solution:

1. Ensure template has enabled_scripts or port_range
2. Check NSE scripts are valid: go run cmd/validate-nse-fix/main.go
3. Review scanner logs: docker logs sirius-engine

Documentation

• SCAN-TYPES.md - Canonical scan types reference
• PORT-RANGE-OPTIMIZATION.md - Port range recommendations

Archived (Historical)

• documentation/archive/ARCHITECTURAL-FIX-PORT-PIPELINE.md - Historical implementation details
• documentation/archive/PORT-PIPELINE-IMPLEMENTED.md - Original pipeline implementation

Key Design Principles

1. General Purpose - No protocol-specific hardcoded logic
2. Discovery-Driven - Nmap scans discovered ports, not arbitrary ranges
3. Template-Based - Users control scan behavior via templates
4. Performance-Focused - Only scan what's necessary
5. Observable - Comprehensive logging and audit trails
6. Modular - Fingerprint phase ready for ping++ integration

---

Built with: Go, Nmap, Naabu, RabbitMQ, ValKey

Documentation

Overview

main.go