Skip to content

First Time Setup

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

First-Time Setup

Complete walkthrough for configuring VulnForge after installation.

Table of Contents

Initial Access

1. Access the Dashboard

Open your browser to:

  • Local: http://localhost:8787
  • Network: http://<server-ip>:8787
  • Domain: https://vulnforge.yourdomain.com (if using reverse proxy)

2. Create Admin Account

On first access, VulnForge displays a setup page requiring a bootstrap token:

  1. Get the token from container logs: 
    docker logs vulnforge | grep "SETUP TOKEN"
  2. Enter the token in the Setup Token field
  3. Create your admin credentials (username, email, password)
  4. Click Create Admin Account

The bootstrap token is generated once on first startup. It prevents unauthorized admin account creation on internet-exposed instances.

3. Verify Health

Check that all services are running:

docker ps

# You should see:
# - vulnforge
# - trivy
# - socket-proxy-ro (if using socket proxy)

Container Discovery

Discover Containers

  1. Navigate to Containers page
  2. Click "Discover Containers" button
  3. VulnForge will scan Docker for all containers (running and stopped)

What gets discovered:

  • Container name
  • Image name and tag
  • Image ID
  • Running status
  • Last seen timestamp

Excluded from discovery:

  • Ephemeral scanner containers (e.g., docker/docker-bench-security if present)

Review Discovered Containers

  • Total: All containers found
  • Scanned: Containers with at least one scan
  • Never Scanned: Containers discovered but not yet scanned

Initial Scan

Run Your First Scan

Option 1: Scan All Containers

  1. Navigate to Containers page
  2. Click "Scan All" button
  3. Monitor progress in Scans page

Option 2: Scan Individual Container

  1. Navigate to Containers page
  2. Find the container you want to scan
  3. Click "Scan" button next to container

Monitor Scan Progress

Navigate to Scans page to see:

  • Real-time progress via Server-Sent Events (SSE)
  • Current scan status (queued, running, completed, failed)
  • Scan duration
  • Vulnerability counts

What Gets Scanned

Each scan includes:

  • Vulnerability Scan (Trivy)
    • OS packages
    • Language-specific dependencies
    • KEV matching (if enabled)
    • CVSS scoring
  • Secret Scan (Trivy - if enabled)
    • API keys
    • Passwords
    • Tokens
    • Certificates

Note: Compliance scans (VulnForge Checker, Dive) are separate and can be run from the Compliance page.

Configure Settings

Navigate to Settings page to configure:

System Settings

  • Timezone: Set your local timezone for scheduling (default: UTC)
  • Log Level: Choose verbosity (DEBUG, INFO, WARNING, ERROR)

Scan Settings

  • Scan Schedule: Cron expression for automatic scans (default: 0 2 * * * - daily at 2 AM)
  • Scan Timeout: Maximum time per container scan in seconds (default: 300)
  • Parallel Scans: Number of concurrent scans (default: 3)
  • Enable Secret Scanning: Toggle secret detection (default: enabled)

Notification Settings

  • ntfy Enabled: Enable/disable notifications
  • ntfy URL: Your ntfy server URL
  • ntfy Topic: Topic name for notifications
  • ntfy Token: Optional authentication token
  • Notify on Scan Complete: Get notified when scans finish
  • Notify on Critical: Alert when critical vulnerabilities found
  • Critical Threshold: Minimum critical CVEs to trigger alert (default: 1)
  • High Threshold: Minimum high CVEs to trigger alert (default: 10)

Data Retention

  • Keep Scan History: Days to retain historical scans (default: 90)

UI Preferences

  • Default Severity Filter: Initial filter on Vulnerabilities page (all, critical, high, medium, low)
  • Default Show Fixable Only: Start with fixable vulnerabilities filter enabled

Compliance Settings

  • Compliance Scan Enabled: Enable scheduled compliance scans
  • Compliance Scan Schedule: Cron for VulnForge Checker/Dive scans (default: 0 3 * * 0 - weekly Sunday at 3 AM)
  • Notify on Compliance Scan: Get notified when compliance scans complete
  • Notify on Failures: Alert when compliance checks fail

KEV Settings

  • KEV Checking Enabled: Match CVEs against CISA KEV catalog
  • KEV Cache Hours: Hours to cache KEV data before refresh (default: 12)

Scanner Offline Resilience

  • Scanner DB Max Age: Hours before forcing Trivy DB update (default: 24)
  • Skip DB Update When Fresh: Skip update if DB is recent
  • Allow Stale DB: Continue scanning even if DB update fails
  • Stale DB Warning Hours: Hours before warning about stale database (default: 72)

Set Up Authentication

By default, VulnForge has no authentication. Secure your instance:

Choose Authentication Method

Navigate to Settings → Authentication:

  1. None (default) - No authentication required
  2. API Key - Require API key in X-API-Key header
  3. Basic Auth - Username/password authentication
  4. Authentik - SSO via Authentik forward auth
  5. Custom Headers - Custom header-based authentication

See Authentication for detailed setup guides.

Recommended Setup

For homelab use with reverse proxy:

# Authentik with Traefik forward auth
AUTH_PROVIDER=authentik
AUTH_AUTHENTIK_HEADER_USERNAME=X-authentik-username
AUTH_AUTHENTIK_HEADER_EMAIL=X-authentik-email

Configure Notifications

Set Up ntfy

  1. Deploy ntfy server or use ntfy.sh:
# Self-hosted ntfy
docker run -d --name ntfy \
  -p 8080:80 \
  -v ntfy-cache:/var/cache/ntfy \
  binwiederhier/ntfy serve

  1. Configure in Settings:

    • ntfy URL: http://ntfy:80 or https://ntfy.sh
    • ntfy Topic: vulnforge (or your chosen topic)
    • ntfy Token: (optional for private topics)

  2. Test notification:

    • Click "Test Notification" in Settings
    • Check ntfy app/web for test message

Subscribe to Notifications

Mobile App:

  1. Install ntfy from App Store/Play Store
  2. Subscribe to your topic: vulnforge

Web:

  • Visit https://ntfy.sh/vulnforge (or your self-hosted URL)

See Notifications for advanced configuration.

Understanding Results

Vulnerability Summary

After your first scan, review the Dashboard:

  • Total Containers: All discovered containers
  • Total Vulnerabilities: Sum across all containers
  • Fixable Vulnerabilities: CVEs with available patches
  • Severity Breakdown: Critical, High, Medium, Low counts
  • KEV Matches: Known Exploited Vulnerabilities

Vulnerability Details

Navigate to Vulnerabilities page:

  • Filter by Severity: Critical, High, Medium, Low
  • Filter by Fixable: Show only patchable CVEs
  • Search: Find specific CVEs or packages
  • Triage Status: Mark as accepted, false_positive, or ignored

Container Status

Navigate to Containers page:

  • Last Scan: When container was last scanned
  • Vulnerability Count: Total CVEs per container
  • Status Indicators: Never scanned, scanning, complete, failed

Next Steps

Now that VulnForge is configured:

  1. Vulnerability Scanning - Learn about triage and remediation
  2. Compliance Monitoring - Run compliance checks and Dive
  3. Advanced Configuration - False positive patterns and KEV tracking
  4. API Reference - Integrate with automation

Troubleshooting

Scans Failing

Check Trivy logs:

docker logs trivy

Common issues:

  • Trivy DB update failed (network issue)
  • Scanner timeout (increase SCAN_TIMEOUT)
  • Container image not accessible

Containers Not Discovered

Verify socket proxy permissions:

environment:
  CONTAINERS: 1
  IMAGES: 1
  INFO: 1

Check VulnForge logs:

docker logs vulnforge

Notifications Not Working

Test connectivity:

curl -d "Test message" http://ntfy:80/vulnforge

Check Settings:

  • ntfy URL is correct
  • Topic name matches subscription
  • Token is valid (if using auth)

Need Help?

Clone this wiki locally