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

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

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/...
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

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
TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/your-webhook-url
NOTIFY_ON_HIGH_SEVERITY=true
CLEANUP_OLD_SCANS_DAYS=60
HEALTH_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

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)

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

1. Clone the repository:

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

2. Install dependencies:

npm install

3. 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.

4. Start the development server:

npm run dev

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.

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

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

The platform employs several innovative approaches to vulnerability data visualization:

• 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)

• 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

• 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

• 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

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

• 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

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

Harbor Guard provides REST API endpoints for programmatic access:

• GET /api/image/[name]/scan/[scanId]/[reportType] - Download individual tool reports
• GET /api/image/[name]/scan/[scanId]/download - Download complete scan package
• GET /api/scans - List all scans
• POST /api/scans/start - Initiate new scan

• GET /api/docker/images - List local Docker images
• GET /api/docker/search - Search Docker Hub
• GET /api/docker/info - Docker daemon information

Harbor Guard is built with modern web technologies:

• Frontend: React 19 + Next.js 15 with App Router
• Styling: Tailwind CSS + shadcn/ui components
• Database: PostgreSQL with Prisma ORM
• Charts: Recharts for data visualization
• Icons: Tabler Icons + Lucide React
• State Management: React Context + Custom hooks

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite: npm test
6. Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

• 🐛 Report Issues
• 💬 Discussions
• 📧 Email Support

Special thanks to the maintainers of the integrated security tools:

• Aqua Security (Trivy)
• Anchore (Grype, Syft)
• goodwithtech (Dockle)
• Google (OSV Scanner)
• wagoodman (Dive)

---