scanorama

module
v0.12.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 17, 2025 License: MIT

README

Scanorama

CI Security Go Report Card codecov

A network scanning and discovery tool built on nmap with database persistence, REST API, and automated scheduling capabilities.

Quick Start

Running Tests
# Start test database and run all tests
make test

# Run only unit tests (no database needed)
make test-unit

# Generate coverage report
make coverage

# Start database manually (for development)
make db-up

# Stop database
make db-down
Database Management

The test database runs in Docker and is managed automatically:

  • make test - Starts DB, runs tests, stops DB
  • make db-up - Start test database
  • make db-down - Stop test database
  • make db-reset - Reset database (down + up)
  • make db-shell - Connect with psql
Development
# Format code
make fmt

# Run linter
make lint

# Build binary
make build

# See all targets
make help

Features

  • Network Discovery: Host discovery and port scanning using nmap
  • Multiple Scan Types: Connect, SYN, version detection, aggressive, stealth
  • Database Integration: PostgreSQL persistence with automatic migrations
  • REST API: RESTful API with Swagger documentation
  • Scheduling: Automated scan jobs with cron-like scheduling
  • Monitoring: Structured logging, metrics, and health checks
  • Docker Support: Containerized deployment ready

Requirements

  • Go 1.25.3+
  • nmap 7.0+ (required)
  • PostgreSQL (for persistence)

Quick Start

git clone https://github.com/anstrom/scanorama.git
cd scanorama
make setup-dev-db   # Initialize database
make build          # Build binary

Usage

# Discover hosts on a network
./scanorama discover 192.168.1.0/24

# Scan specific targets
./scanorama scan --targets localhost --ports 80,443,8080
./scanorama scan --targets 192.168.1.1 --type aggressive

# View discovered hosts
./scanorama hosts

# Run as daemon with API server
./scanorama daemon
Scan Types
  • connect - TCP connect scanning (default)
  • syn - SYN stealth scanning (requires privileges)
  • version - Service version detection
  • comprehensive - Full port range scanning
  • aggressive - OS detection + version scanning + scripts
  • stealth - Slow, evasive scanning

API

Start the daemon and access the REST API:

./scanorama daemon
# API available at http://localhost:8080
# Swagger docs at http://localhost:8080/swagger/

Configuration

Create config.yaml:

database:
  host: localhost
  port: 5432
  name: scanorama
  user: scanorama
  password: your_password

api:
  host: 0.0.0.0
  port: 8080

logging:
  level: info
  format: json

Development

make setup-hooks     # Set up Git hooks
make ci              # Run full CI pipeline
make test            # Run tests
make coverage        # Generate coverage reports
make lint            # Run linter

Docker

docker run -p 8080:8080 ghcr.io/anstrom/scanorama:latest

Contributing

  1. Fork and clone the repository
  2. Run make setup-hooks to install Git hooks
  3. Run make setup-dev-db to set up development database
  4. Make your changes with tests
  5. Run make ci to ensure quality checks pass
  6. Create a pull request

See Contributing Guidelines for more details.

License

MIT License - see LICENSE file for details.

Directories

Path Synopsis
cmd
cli
Package cli provides command-line interface commands for the Scanorama network scanner.
 Package cli provides command-line interface commands for the Scanorama network scanner.
scanorama command
Package main provides the entry point for the Scanorama network scanning application.
 Package main provides the entry point for the Scanorama network scanning application.
Package docs provides Swagger documentation for the Scanorama API.
 Package docs provides Swagger documentation for the Scanorama API.
swagger
Package swagger Code generated by swaggo/swag.
 Package swagger Code generated by swaggo/swag.
internal
api
Package api provides HTTP REST API functionality for the Scanorama network scanner.
 Package api provides HTTP REST API functionality for the Scanorama network scanner.
api/handlers
Package handlers provides HTTP request handlers for the Scanorama API.
 Package handlers provides HTTP request handlers for the Scanorama API.
api/middleware
Package middleware provides HTTP middleware functions for the Scanorama API server.
 Package middleware provides HTTP middleware functions for the Scanorama API server.
auth
Package auth provides authentication utilities for the Scanorama API server.
 Package auth provides authentication utilities for the Scanorama API server.
config
Package config provides configuration management for scanorama.
 Package config provides configuration management for scanorama.
daemon
Package daemon provides the background service functionality for scanorama.
 Package daemon provides the background service functionality for scanorama.
db
Package db provides database connectivity and data models for scanorama.
 Package db provides database connectivity and data models for scanorama.
discovery
Package discovery provides network discovery functionality using nmap.
 Package discovery provides network discovery functionality using nmap.
errors
Package errors provides structured error handling for scanorama operations.
 Package errors provides structured error handling for scanorama operations.
logging
Package logging provides structured logging functionality using Go's slog package.
 Package logging provides structured logging functionality using Go's slog package.
metrics
Package metrics provides interfaces for metrics collection and monitoring.
 Package metrics provides interfaces for metrics collection and monitoring.
metrics/mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
profiles
Package profiles provides scanning profile management for scanorama.
 Package profiles provides scanning profile management for scanorama.
scanning
Package scanning provides core network scanning functionality for Scanorama.
 Package scanning provides core network scanning functionality for Scanorama.
scheduler
Package scheduler provides job scheduling and execution functionality for scanorama.
 Package scheduler provides job scheduling and execution functionality for scanorama.
services
Package services provides business logic services for Scanorama.
 Package services provides business logic services for Scanorama.
workers
Package workers provides a worker pool implementation for concurrent operations in scanorama.
 Package workers provides a worker pool implementation for concurrent operations in scanorama.
test
helpers
Package helpers provides testing utilities for database connections, environment setup, and test data management for Scanorama integration tests.
 Package helpers provides testing utilities for database connections, environment setup, and test data management for Scanorama integration tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.