Skip to content

FAQ

Jump to bottom
homelabforge edited this page Feb 8, 2026 · 3 revisions

Frequently Asked Questions

Common questions about VulnForge organized by topic.

Table of Contents

General

What is VulnForge?

VulnForge is a self-hosted container security dashboard that helps homelab operators monitor Docker container vulnerabilities, compliance, and security hygiene without relying on external SaaS services.

Is VulnForge free?

Yes, VulnForge is open-source and free to use under the MIT License.

What scanning tools does VulnForge use?

  • Trivy - Vulnerability scanning
  • VulnForge Checker - Native CIS Benchmark compliance (20 checks)
  • Dive - Image efficiency analysis and layer optimization

Do I need to send data to external services?

No. All scanning happens locally. VulnForge only connects externally to:

  • Download Trivy vulnerability database (from GitHub)
  • Fetch CISA KEV catalog (if KEV checking enabled)
  • Send notifications (if configured)

What's the difference between VulnForge and commercial container security platforms?

Feature VulnForge Commercial SaaS
Cost Free $$$-$$$$
Data Privacy 100% local Data sent to vendor
Deployment Self-hosted Cloud
Target Audience Homelabs, SMB Enterprise
Customization Full control Limited

Installation

What are the system requirements?

  • Docker with Docker Compose
  • 1GB RAM minimum (2GB recommended)
  • 10GB disk space (for Trivy cache and scan history)
  • Linux/macOS/Windows with WSL2

Can I run VulnForge on a NAS?

Yes! VulnForge works on:

  • Synology DSM (Container Manager)
  • QNAP (Container Station)
  • TrueNAS Scale
  • Unraid (Community Apps)

See Installation Guide.

Do I need a reverse proxy?

Not required, but recommended for:

  • HTTPS/TLS encryption
  • Custom domain names
  • SSO integration (Authentik, Authelia)

Can I use VulnForge without Docker Compose?

Yes, you can run VulnForge with:

  • docker run commands
  • Kubernetes (Helm chart coming soon)
  • Bare metal (Python + Bun)

See Installation Guide for alternatives.

How do I upgrade VulnForge?

# Pull latest image
docker compose pull vulnforge

# Restart container
docker compose up -d vulnforge

See Upgrading Guide for version-specific migrations.

Scanning

How often should I scan containers?

Recommended:

  • Production containers: Daily
  • Development containers: Weekly
  • Compliance scans: Weekly

Configure automatic scheduling in Settings → Scan Settings.

How long do scans take?

Typical scan times:

  • Small image (Alpine, 50MB): 10-30 seconds
  • Medium image (Node.js, 500MB): 1-2 minutes
  • Large image (Python, 1GB+): 3-5 minutes

Factors affecting speed:

  • Image size
  • Number of packages
  • Trivy DB freshness
  • Disk I/O speed

Why are my scans failing?

Common causes:

  1. Trivy DB update failed - Network issue, wait and retry
  2. Scan timeout - Increase SCAN_TIMEOUT in Settings
  3. Docker permission denied - Check socket proxy permissions
  4. Image not accessible - Image requires authentication
  5. Disk space full - Free up space

See Troubleshooting.

Can I scan images that aren't running?

Yes! VulnForge scans all discovered containers, whether running or stopped.

Can I scan images before deploying them?

Yes, via API:

# Scan image directly
curl -X POST http://localhost:8787/api/scan/image \
  -H "Content-Type: application/json" \
  -d '{"image": "nginx:latest"}'

Integrate into CI/CD pipelines to block vulnerable images.

What if Trivy database update fails?

VulnForge has offline resilience:

  1. Attempts to update Trivy DB
  2. If update fails and DB is recent (<24h), uses stale DB
  3. Warns if DB is too old (>72h)
  4. Can be configured to skip scans if DB too stale

Configure in Settings → Scanner Offline Resilience.

Vulnerabilities

What does "KEV" mean?

KEV = Known Exploited Vulnerability (CISA catalog)

These CVEs have confirmed active exploitation in the wild and require immediate remediation.

Should I fix all vulnerabilities?

Priority order:

  1. ✅ Critical KEVs - Immediate (hours)
  2. ✅ Critical non-KEVs - Within 1 week
  3. ✅ High - Within 2 weeks
  4. ⚠️ Medium - Within 30 days
  5. ⏸️ Low - Quarterly review

Not all vulnerabilities pose real risk to your environment. Use triage to mark false positives and accepted risks.

What's the difference between "Fixable" and "Non-Fixable"?

  • Fixable: Patch available, upgrade package to fixed version
  • Non-Fixable: No patch available yet, requires mitigation or risk acceptance

How do I handle false positives?

  1. Navigate to Vulnerabilities page
  2. Find the CVE
  3. Change triage status to "False Positive"
  4. Add notes explaining why

For recurring false positives, create False Positive Patterns in Settings → Advanced.

Why do I have vulnerabilities in base images?

Base images (Alpine, Ubuntu, Debian) receive security updates regularly. To remediate:

# Update base image tag
FROM alpine:3.18  # Old version

# To latest patch version
FROM alpine:3.18.4  # Includes security fixes

Check Docker Hub or image registry for newer tags.

Can VulnForge automatically patch vulnerabilities?

No. VulnForge is a scanning and monitoring tool, not a remediation tool.

You must manually:

  1. Update Dockerfiles
  2. Rebuild images
  3. Redeploy containers
  4. Re-scan to verify

Authentication

Is authentication required?

No, but strongly recommended for production deployments.

By default, VulnForge has no authentication. Anyone with network access can view and modify settings.

What authentication methods are supported?

VulnForge has two separate authentication systems:

User Authentication (Browser Login):

  • Local - Username/password with Argon2id hashing
  • OIDC/SSO - Single sign-on (Authentik, Keycloak, Auth0, Okta)

API Authentication (External Tools):

  • API Keys - Secure keys for TideWatch, scripts, automation

See Authentication Guide.

Can I use multiple authentication methods?

Yes! User authentication and API authentication work independently:

  • Users login via browser (local or SSO)
  • Tools use API keys for programmatic access
  • Both can be active simultaneously

How do I reset admin password?

Local User Authentication:

  1. Navigate to Settings → Security → User Account
  2. Click Change Password
  3. Enter current password and new password
  4. Click Save

OIDC/SSO:

  • Reset password in your OIDC provider (Authentik, Keycloak, etc.)
  • VulnForge will reflect changes on next login

Lost Password / Locked Out:

  1. Stop VulnForge container
  2. Delete user auth database: rm data/vulnforge.db
  3. Restart container
  4. Setup page will appear for new account creation

Notifications

What notification services are supported?

VulnForge supports 7 notification services:

  • ntfy (self-hosted or ntfy.sh)
  • Gotify
  • Pushover
  • Slack
  • Discord
  • Telegram
  • Email (SMTP)

How do I test notifications?

Navigate to Settings → Notifications and click "Test Notification".

Check your ntfy app/web interface for the test message.

Why aren't I receiving notifications?

Check:

  1. ntfy URL is correct
  2. ntfy topic matches subscription
  3. ntfy token is valid (if using auth)
  4. Notification settings are enabled
  5. Thresholds are configured correctly

Test connectivity:

curl -d "Test message" http://ntfy:80/your-topic

Can I customize notification thresholds?

Yes! Configure in Settings → Notifications:

  • Critical Threshold: Minimum critical CVEs to alert (default: 1)
  • High Threshold: Minimum high CVEs to alert (default: 10)
  • Notify on Scan Complete: Toggle all scans or only critical findings

Performance

How much disk space does VulnForge use?

Typical usage:

  • VulnForge database: 50-200 MB
  • Trivy cache: 500 MB - 2 GB
  • Scan history: 10-50 MB per 100 scans

Storage grows with:

  • Number of containers
  • Scan frequency
  • History retention period

Configure retention in Settings → Data Retention (default: 90 days).

How much RAM does VulnForge need?

  • VulnForge: 256-512 MB
  • Trivy: 512 MB - 1 GB during scans
  • Total: 1-2 GB recommended

Can I scan multiple containers in parallel?

Yes! Configure Parallel Scans in Settings → Scan Settings (default: 3).

Recommendations:

  • Low-end hardware (NAS, RPi): 1-2
  • Mid-range (homelab server): 3-5
  • High-end (dedicated server): 5-10

Does VulnForge support clustering or high availability?

Not currently. VulnForge uses:

  • SQLite database (single-node)
  • In-memory scan queue
  • Background scheduler (APScheduler)

These components are not designed for distributed deployment.

Troubleshooting

Containers not being discovered

Check socket proxy permissions:

environment:
  CONTAINERS: 1
  IMAGES: 1
  INFO: 1

Verify Docker access:

docker exec vulnforge docker ps
# Should list containers

Scans stuck in "Running" state

  1. Check Trivy logs: docker logs trivy
  2. Restart Trivy: docker restart trivy
  3. Increase scan timeout in Settings
  4. Check disk space: df -h

Dashboard shows no data

  1. Run "Discover Containers"
  2. Wait for scans to complete
  3. Check browser console for errors
  4. Verify VulnForge health: http://localhost:8787/health

"Database locked" errors

SQLite WAL mode should prevent this, but if it occurs:

# Restart VulnForge
docker restart vulnforge

# If persistent, check for stale locks
docker exec vulnforge ls -la /data

High memory usage

Trivy cache growing:

# Clear Trivy cache
docker volume rm vulnforge-trivy-cache
docker restart trivy

Scan history growing:

  • Reduce retention days in Settings
  • Manually clean old scans via Maintenance page

Still Need Help?

Clone this wiki locally