# Frequently Asked Questions

Common questions about VulnForge organized by topic.

---

## Table of Contents

- [General](#general)
- [Installation](#installation)
- [Scanning](#scanning)
- [Vulnerabilities](#vulnerabilities)
- [Authentication](#authentication)
- [Notifications](#notifications)
- [Performance](#performance)
- [Troubleshooting](#troubleshooting)

---

## 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](Installation.md#nas-deployment)**.

### 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](Installation)** for alternatives.

###  How do I upgrade VulnForge?

```bash
# Pull latest image
docker compose pull vulnforge

# Restart container
docker compose up -d vulnforge
```

See **[Upgrading Guide](Upgrading)** 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](Troubleshooting.md#scans-failing)**.

### 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:

```bash
# 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:

```dockerfile
# 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](Authentication)**.

### 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**:
```bash
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**:
```yaml
environment:
  CONTAINERS: 1
  IMAGES: 1
  INFO: 1
```

**Verify Docker access**:
```bash
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:

```bash
# Restart VulnForge
docker restart vulnforge

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

### High memory usage

**Trivy cache growing**:
```bash
# 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?

- **[Troubleshooting Guide](Troubleshooting)** - Comprehensive problem-solving
- **[GitHub Issues](https://github.com/homelabforge/vulnforge/issues)** - Report bugs
- **[GitHub Discussions](https://github.com/homelabforge/vulnforge/discussions)** - Ask questions
- **[Installation Guide](Installation)** - Deployment help
- **[Authentication Guide](Authentication)** - Security setup