Skip to content

Quick Start

Jump to bottom
homelabforge edited this page Apr 5, 2026 · 3 revisions

Quick Start

Get VulnForge running in 5 minutes.

Prerequisites

  • Docker with Docker Compose
  • Access to Docker socket (via socket proxy recommended)
  • 1GB RAM minimum
  • Linux/macOS/Windows with WSL2

Installation

1. Create Directory Structure

mkdir -p /srv/vulnforge/{data,config}
cd /srv/vulnforge

2. Create docker-compose.yml

version: "3.8"

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy:latest
    container_name: socket-proxy-ro
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1
      IMAGES: 1
      INFO: 1
      NETWORKS: 1
      VOLUMES: 1
    networks:
      - vulnforge
    restart: unless-stopped

  trivy:
    image: aquasec/trivy:latest
    container_name: trivy
    command: server --listen 0.0.0.0:8080
    volumes:
      - trivy-cache:/root/.cache
    networks:
      - vulnforge
    restart: unless-stopped

  vulnforge:
    image: ghcr.io/homelabforge/vulnforge:latest
    container_name: vulnforge
    ports:
      - "8787:8787"
    volumes:
      - ./data:/data
    environment:
      DOCKER_SOCKET_PROXY: tcp://socket-proxy-ro:2375
      TRIVY_CONTAINER_NAME: trivy
      SCAN_SCHEDULE: "0 2 * * *"  # Daily at 2 AM
    networks:
      - vulnforge
    depends_on:
      - socket-proxy
      - trivy
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

volumes:
  trivy-cache:

networks:
  vulnforge:
    name: vulnforge

3. Start VulnForge

docker compose up -d

4. Access the Dashboard

Open your browser to http://localhost:8787

5. Create Admin Account

On first access, enter the bootstrap token from container logs and create your admin account:

docker logs vulnforge | grep "SETUP TOKEN"

First Steps

1. Discover Containers

  1. Navigate to the Containers page
  2. Click "Discover Containers" to detect all running and stopped containers
  3. Review the discovered containers

2. Run Initial Scan

  1. Click "Scan All" to perform vulnerability assessment on all containers
  2. Monitor real-time progress in the Scans page
  3. Review findings in the Vulnerabilities page

3. Configure Settings (Optional)

  1. Navigate to Settings
  2. Configure:
    • Scan schedule (default: daily at 2 AM)
    • Notification thresholds
    • Secret scanning toggle
    • Data retention policies

Next Steps

Common Issues

Docker Permission Denied

If you see "Docker daemon permission denied":

# Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker

Containers Not Detected

Ensure the socket proxy has correct permissions:

environment:
  CONTAINERS: 1
  IMAGES: 1
  INFO: 1

Trivy Database Update Failed

If scans fail due to database issues, check Trivy logs:

docker logs trivy

The scanner will automatically retry with stale database if fresh update fails.

Need Help?

Clone this wiki locally