Harbor Guard

A comprehensive container security scanning platform that provides an intuitive web interface for managing and visualizing security assessments of Docker images.

Installation

Docker (Recommended)

Run Harbor Guard using Docker with a single command:

docker run -p 3000:3000 ghcr.io/harborguard/harborguard:latest

To give Harbor Guard access to your local images:

docker run -p 3000:3000 -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/harborguard/harborguard:latest

To use with an external PostgreSQL database:

docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/harborguard" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/harborguard/harborguard:latest

Access the application at http://localhost:3000

Environment Variables

Harbor Guard supports comprehensive configuration through environment variables. All variables have sensible defaults and proper validation.

Variable	Description	Default	Valid Values	Example
Scanner Configuration
MAX_CONCURRENT_SCANS	Limits concurrent scanner execution to prevent resource exhaustion	3	1-20	MAX_CONCURRENT_SCANS=5
SCAN_TIMEOUT_MINUTES	Maximum time allowed for individual scanner execution	30	5-180	SCAN_TIMEOUT_MINUTES=60
ENABLED_SCANNERS	Comma-separated list of enabled scanners	trivy,grype,syft,dockle,osv,dive	Any combination of: trivy, grype, syft, dockle, osv, dive	ENABLED_SCANNERS=trivy,grype
Logging & Debugging
LOG_LEVEL	Controls application log verbosity	info	debug, info, warn, error	LOG_LEVEL=debug
Database & Maintenance
DATABASE_URL	PostgreSQL database connection string	Bundled PostgreSQL	External PostgreSQL: postgresql://user:pass@host:port/db	DATABASE_URL="postgresql://user:pass@localhost:5432/harborguard"
CLEANUP_OLD_SCANS_DAYS	Automatically delete scans older than specified days	30	1-365	CLEANUP_OLD_SCANS_DAYS=90
Network & Deployment
PORT	Server listening port	3000	1000-65535	PORT=8080
HOSTNAME	Server bind address	0.0.0.0	Valid IP address	HOSTNAME=127.0.0.1
Notifications
TEAMS_WEBHOOK_URL	Microsoft Teams webhook URL for notifications	none	Valid HTTPS URL	TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/...
SLACK_WEBHOOK_URL	Slack webhook URL for notifications	none	Valid HTTPS URL	SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
GOTIFY_SERVER_URL	Gotify server URL for self-hosted notifications	none	Valid HTTP/HTTPS URL	GOTIFY_SERVER_URL=https://gotify.example.com
GOTIFY_APP_TOKEN	Gotify application token for authentication	none	Valid token string	GOTIFY_APP_TOKEN=AC5X0f7ISmwz-zJ
APPRISE_API_URL	Apprise API URL for multi-service notifications	none	Valid HTTP/HTTPS URL	APPRISE_API_URL=https://apprise.example.com
APPRISE_CONFIG_KEY	Apprise configuration key (optional)	none	Configuration key string	APPRISE_CONFIG_KEY=harborguard
APPRISE_URLS	Direct Apprise notification URLs (comma-separated)	none	Comma-separated service URLs	APPRISE_URLS=mailto://user:pass@gmail.com,discord://webhook/...
NOTIFY_ON_HIGH_SEVERITY	Send notifications only for high/critical findings	true	true, false	NOTIFY_ON_HIGH_SEVERITY=false
Monitoring & Health Checks
HEALTH_CHECK_ENABLED	Enable /api/health and /api/ready endpoints	true	true, false	HEALTH_CHECK_ENABLED=false
VERSION_CHECK_ENABLED	Enable automatic version checking for updates	true	true, false	VERSION_CHECK_ENABLED=false

Advanced Environment Variables

These variables are typically used for internal configuration or advanced deployments:

Variable	Description	Default	Example
SCANNER_WORKDIR	Working directory for scanner operations	/workspace	SCANNER_WORKDIR=/tmp/scanners
NEXT_PUBLIC_DEMO_MODE	Enable demo mode with limited functionality	false	NEXT_PUBLIC_DEMO_MODE=true
NEXT_PUBLIC_APP_URL	Public application URL (for OpenAPI spec)	http://localhost:3000	NEXT_PUBLIC_APP_URL=https://harborguard.example.com
NEXT_PUBLIC_API_URL	Public API URL (for OpenAPI spec)	auto-detected	NEXT_PUBLIC_API_URL=https://api.harborguard.example.com
PGDATA	PostgreSQL data directory (bundled PostgreSQL only)	/var/lib/postgresql/data	PGDATA=/data/postgres
POSTGRES_USER	PostgreSQL username (bundled PostgreSQL only)	harborguard	POSTGRES_USER=admin
POSTGRES_PASSWORD	PostgreSQL password (bundled PostgreSQL only)	harborguard	POSTGRES_PASSWORD=secure_password
POSTGRES_DB	PostgreSQL database name (bundled PostgreSQL only)	harborguard	POSTGRES_DB=harborguard_prod

Quick Configuration Examples

Development Setup:

# Minimal development configuration
PORT=3000
LOG_LEVEL=debug
HEALTH_CHECK_ENABLED=true

Production Setup:

# Production configuration with PostgreSQL and notifications
DATABASE_URL="postgresql://user:password@db:5432/harborguard"
PORT=8080
LOG_LEVEL=warn
MAX_CONCURRENT_SCANS=10
SCAN_TIMEOUT_MINUTES=60
ENABLED_SCANNERS=trivy,grype,syft

# Choose your notification service(s):
# Option 1: Microsoft Teams
TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/your-webhook-url

# Option 2: Slack
# SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your-webhook

# Option 3: Self-hosted Gotify
# GOTIFY_SERVER_URL=https://gotify.example.com
# GOTIFY_APP_TOKEN=your-app-token

# Option 4: Apprise (supports 80+ notification services)
# APPRISE_API_URL=https://apprise.example.com
# APPRISE_URLS=discord://webhook/...,mailto://user:pass@gmail.com

NOTIFY_ON_HIGH_SEVERITY=true
CLEANUP_OLD_SCANS_DAYS=60
HEALTH_CHECK_ENABLED=true
VERSION_CHECK_ENABLED=true

Resource-Constrained Environment:

# Optimized for low-resource environments
MAX_CONCURRENT_SCANS=1
SCAN_TIMEOUT_MINUTES=15
ENABLED_SCANNERS=trivy,grype
LOG_LEVEL=error
CLEANUP_OLD_SCANS_DAYS=7

Docker Deployment:

docker run -p 8080:8080 \
  -e PORT=8080 \
  -e MAX_CONCURRENT_SCANS=5 \
  -e LOG_LEVEL=info \
  -e TEAMS_WEBHOOK_URL=https://your-webhook-url \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/harborguard/harborguard:latest

Health Check Endpoints

When HEALTH_CHECK_ENABLED=true (default), Harbor Guard provides monitoring endpoints:

• GET /api/health - Comprehensive health status including database connectivity, scanner configuration, and cleanup statistics
• GET /api/ready - Kubernetes-style readiness probe for load balancers
• HEAD /api/health - Lightweight health check (returns HTTP status only)
• HEAD /api/ready - Lightweight readiness check (returns HTTP status only)

Docker Health Check

The Harbor Guard Docker image includes a built-in HEALTHCHECK instruction that automatically monitors container health:

• Interval: 30 seconds between health checks
• Timeout: 10 seconds for each health check request
• Start Period: 40 seconds grace period during container startup
• Retries: 3 consecutive failures before marking container as unhealthy

The health check uses the /api/health endpoint to verify: - Application is responding to HTTP requests - Database connectivity is working - Critical services are operational

Docker and orchestration platforms (like Docker Compose, Kubernetes, etc.) will automatically use this health check to: - Monitor container health status - Restart unhealthy containers (if configured) - Route traffic only to healthy instances in load-balanced setups

Screenshots

Harbor Guard Dashboard - Container security scanning made simple

Development Setup

1. Clone the repository:

git clone https://github.com/HarborGuard/HarborGuard.git
cd HarborGuard

1. Install dependencies:

npm install

1. Set up the database:

npm run db:init

Database: Harbor Guard uses PostgreSQL. It includes a bundled PostgreSQL instance, or you can connect to an external database via DATABASE_URL. See Database Configuration Guide for detailed setup instructions.

1. Start the development server:

npm run dev

Purpose

Harbor Guard is a modern web application designed to streamline container security management by providing a unified interface for multiple scanning tools and advanced visualization capabilities.

Multi-Tool Security Scanning

Harbor Guard Dashboard - Container security scanning made simple

Harbor Guard integrates and orchestrates multiple industry-standard security scanning tools:

• Trivy - Comprehensive vulnerability scanner for containers
• Grype - Vulnerability scanner by Anchore
• Syft - Software Bill of Materials (SBOM) generator
• Dockle - Container image linter for security and best practices
• OSV Scanner - Open Source Vulnerability database scanner
• Dive - Docker image layer analysis and optimization tool

Quality of Life Improvements

Harbor Guard addresses common pain points in container security workflows:

• Unified Dashboard - Single interface for all scanning tools instead of managing multiple CLI outputs
• Historical Tracking - Persistent storage and comparison of scan results over time
• Report Export - Download individual tool reports or complete ZIP packages for compliance
• Real-time Monitoring - Live scan progress tracking with WebSocket integration
• Smart Filtering - Dynamic filtering and sorting of vulnerabilities by severity, package, or CVE
• Interactive Charts - Click-to-navigate scatter plots for vulnerability analysis

Optimized Visualization Strategy

Harbor Guard Dashboard - Container security scanning made simple

The platform employs several innovative approaches to vulnerability data visualization:

Library Vulnerability Scatterplot

• Multi-dimensional mapping - X-axis represents severity levels, Y-axis shows vulnerability counts
• Interactive filtering - Toggle visibility by severity level with real-time count updates
• Clickable exploration - Navigate directly to library-specific analysis from chart points
• Color-coded severity - Consistent color scheme across all interfaces (red/orange/yellow/blue)

Layer-by-Layer Analysis

• Horizontal tab navigation - Each Docker layer gets its own tab for focused analysis
• Dynamic sizing - Tab layout adapts to any number of layers without breaking
• File system exploration - Detailed view of files added/modified in each layer
• Size optimization insights - Visual indicators for layer sizes and optimization opportunities

Findings Management

• Severity-based grouping - Organize findings by Critical, High, Medium, Low severity
• Progress tracking - Visual indicators for scan completion and remediation status
• Export flexibility - Individual JSON reports or complete ZIP archives
• API accessibility - Public REST endpoints for programmatic access to scan data

Features

🔍 Comprehensive Scanning

• Support for 6 major container security tools
• Automatic vulnerability detection and classification
• Software Bill of Materials (SBOM) generation
• Container best practices validation
• Layer-by-layer image analysis

📊 Advanced Visualization

• Interactive vulnerability scatter plots
• Historical scan comparison charts
• Real-time progress monitoring
• Severity-based filtering and grouping
• Responsive design for all screen sizes

🚀 Developer Experience

• Modern React 19 + Next.js 15 architecture
• TypeScript for type safety
• Prisma ORM with PostgreSQL
• Automatic database fallback for reliability
• Tailwind CSS for styling
• shadcn/ui component library

📈 Enterprise Ready

• RESTful API for programmatic access
• Bulk report export capabilities
• Persistent scan history
• Scalable database design
• Docker-first deployment

API Endpoints

Harbor Guard provides REST API endpoints for programmatic access:

Scan Reports

• GET /api/image/[name]/scan/[scanId]/[reportType] - Download individual tool reports
• GET /api/image/[name]/scan/[scanId]/download - Download complete scan pa