# First-Time Setup

Complete walkthrough for configuring VulnForge after installation.

---

## Table of Contents

- [Initial Access](#initial-access)
- [Container Discovery](#container-discovery)
- [Initial Scan](#initial-scan)
- [Configure Settings](#configure-settings)
- [Set Up Authentication](#set-up-authentication)
- [Configure Notifications](#configure-notifications)
- [Understanding Results](#understanding-results)

---

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

```bash
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](Authentication)** for detailed setup guides.

### Recommended Setup

For homelab use with reverse proxy:

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

```bash
# Self-hosted ntfy
docker run -d --name ntfy \
  -p 8080:80 \
  -v ntfy-cache:/var/cache/ntfy \
  binwiederhier/ntfy serve
```

2. 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)

3. 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](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](Vulnerability-Scanning)** - Learn about triage and remediation
2. **[Compliance Monitoring](Compliance-Monitoring)** - Run compliance checks and Dive
3. **[Advanced Configuration](Advanced-Configuration)** - False positive patterns and KEV tracking
4. **[API Reference](API-Reference)** - Integrate with automation

---

## Troubleshooting

### Scans Failing

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

**Check VulnForge logs**:
```bash
docker logs vulnforge
```

### Notifications Not Working

**Test connectivity**:
```bash
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?

- **[FAQ](FAQ)** - Frequently asked questions
- **[Troubleshooting](Troubleshooting)** - Comprehensive problem-solving
- **[GitHub Issues](https://github.com/homelabforge/vulnforge/issues)** - Report bugs