Skip to content

Vulnerability Scanning

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

Vulnerability Scanning

Comprehensive guide to scanning, triaging, and remediating container vulnerabilities.

Table of Contents

How Scanning Works

Trivy Integration

VulnForge uses Trivy (Aqua Security) for vulnerability scanning:

  1. Image Analysis: Trivy examines container images layer-by-layer
  2. Package Detection: Identifies OS packages and language dependencies
  3. Database Matching: Compares against vulnerability databases
  4. CVSS Scoring: Assigns severity based on Common Vulnerability Scoring System
  5. KEV Matching: Checks against CISA Known Exploited Vulnerabilities

What Gets Scanned

Operating System Packages:

  • Alpine APK packages
  • Debian/Ubuntu APT packages
  • Red Hat/CentOS RPM packages
  • Amazon Linux packages

Language Dependencies:

  • Node.js (package.json, package-lock.json)
  • Python (requirements.txt, Pipfile, poetry.lock)
  • Go (go.mod, go.sum)
  • Rust (Cargo.toml, Cargo.lock)
  • PHP (composer.json, composer.lock)
  • Ruby (Gemfile, Gemfile.lock)
  • Java (pom.xml, build.gradle)

Secret Detection (if enabled):

  • API keys
  • Passwords
  • Tokens
  • Private keys
  • AWS credentials
  • Database connection strings

Running Scans

Manual Scans

Scan All Containers

  1. Navigate to Containers page
  2. Click "Scan All" button
  3. Monitor progress in Scans page
# Via API
curl -X POST http://localhost:8787/api/scan/all

Scan Individual Container

  1. Navigate to Containers page
  2. Find container in list
  3. Click "Scan" button
# Via API
curl -X POST http://localhost:8787/api/scan/container/123

Scheduled Scans

Configure automatic scanning in Settings → Scan Settings:

Scan Schedule: Cron expression

  • 0 2 * * * - Daily at 2 AM
  • 0 2 * * 0 - Weekly on Sunday at 2 AM
  • 0 2 1 * * - Monthly on 1st at 2 AM

Scan Parameters:

  • Scan Timeout: Maximum time per container (default: 300s)
  • Parallel Scans: Concurrent scans (default: 3)

Real-Time Progress

Monitor scans via Server-Sent Events (SSE):

Navigate to Scans page to see:

  • Current scan status (queued, running, completed, failed)
  • Progress percentage
  • Vulnerabilities discovered
  • Scan duration
  • Real-time updates (no refresh needed)

Understanding Results

Vulnerability Details

Each vulnerability includes:

Field Description
CVE ID Common Vulnerabilities and Exposures identifier
Severity Critical, High, Medium, Low (CVSS-based)
CVSS Score Numeric score (0.0-10.0)
Package Name Affected package or library
Installed Version Current version in container
Fixed Version Version with patch (if available)
Is Fixable Whether patch exists
Title Brief vulnerability description
KEV CISA Known Exploited Vulnerability indicator

Severity Breakdown

Critical (CVSS 9.0-10.0):

  • Remote code execution
  • Privilege escalation
  • Authentication bypass
  • Action: Patch immediately

High (CVSS 7.0-8.9):

  • SQL injection
  • Cross-site scripting (XSS)
  • Denial of service (DoS)
  • Action: Patch within days

Medium (CVSS 4.0-6.9):

  • Information disclosure
  • Partial DoS
  • Low-impact XSS
  • Action: Plan remediation

Low (CVSS 0.1-3.9):

  • Minor information leaks
  • Unlikely attack vectors
  • Action: Monitor and review

Container Vulnerability Summary

View per-container metrics:

  • Total vulnerabilities
  • Fixable count
  • Severity distribution (Critical, High, Medium, Low)
  • Last scan timestamp
  • KEV matches

Vulnerability Triage

Triage Workflow

  1. Review - Assess vulnerability impact
  2. Classify - Determine actual risk to your environment
  3. Mark Status - Apply triage label
  4. Document - Add notes for future reference

Triage States

Open (default):

  • Newly discovered vulnerability
  • Requires review

Accepted:

  • Risk acknowledged
  • Remediation planned or in progress
  • Not a false positive

False Positive:

  • Vulnerability doesn't apply to your environment
  • Scanner incorrectly identified issue
  • Package not actually used

Ignored:

  • Low priority or low impact
  • Accepted risk (documented reason)
  • Won't fix (end-of-life software)

How to Triage

  1. Navigate to Vulnerabilities page
  2. Click on vulnerability to view details
  3. Select triage status dropdown
  4. Choose status: Open, Accepted, False Positive, Ignored
  5. Add notes (optional but recommended)
  6. Save

Bulk Triage:

  • Select multiple vulnerabilities
  • Apply same status to all selected
  • Useful for false positive patterns

KEV Tracking

CISA Known Exploited Vulnerabilities

What is KEV?

  • Catalog maintained by CISA (Cybersecurity and Infrastructure Security Agency)
  • Lists CVEs with confirmed active exploitation
  • Highest priority for remediation

Enabling KEV Checking

Navigate to Settings → KEV Settings:

  • KEV Checking Enabled: Toggle on
  • KEV Cache Hours: How long to cache KEV data (default: 12 hours)

KEV Indicators

🚨 KEV Badge appears on:

  • Dashboard metrics
  • Vulnerability lists
  • Container summaries
  • Scan results

KEV Alerts

Configure in Settings → Notifications:

  • Alert immediately when KEV detected
  • Higher priority than severity thresholds

Remediation

Remediation Strategies

1. Update Base Image

Most effective approach:

# Before
FROM node:18-alpine

# After (patch CVE-2024-12345)
FROM node:18.20.1-alpine

Steps:

  1. Check for newer image version
  2. Update Dockerfile
  3. Rebuild image
  4. Test thoroughly
  5. Deploy updated container
  6. Re-scan to verify

2. Update Package

For language dependencies:

// Before (package.json)
{
  "dependencies": {
    "axios": "0.21.0"  // CVE-2021-3749
  }
}

// After
{
  "dependencies": {
    "axios": "0.21.2"  // Patched version
  }
}

Steps:

  1. Identify fixed version from vulnerability details
  2. Update package manifest
  3. Rebuild image
  4. Test compatibility
  5. Deploy and re-scan

3. Pin to Fixed Version

For OS packages (Alpine example):

# Before
RUN apk add --no-cache curl

# After (pin to patched version)
RUN apk add --no-cache curl=8.5.0-r0

4. Mitigation (No Fix Available)

When patch doesn't exist:

  1. Isolate: Network segmentation
  2. Monitor: Enhanced logging
  3. Compensate: WAF rules or runtime protection
  4. Accept Risk: Document decision
  5. Mark as Accepted in VulnForge

Grouped Remediation

VulnForge groups vulnerabilities by package for efficient remediation:

Example:

Package: openssl
Installed: 1.1.1k
Fixed: 1.1.1w

Vulnerabilities Fixed (12):
- CVE-2024-0001 (Critical)
- CVE-2024-0002 (High)
- CVE-2024-0003 (High)
...

Action: Update openssl to 1.1.1w

Single package update resolves multiple CVEs.

Scan History

View Past Scans

Navigate to Scans page:

  • All historical scans
  • Filter by container
  • Filter by date range
  • Filter by status (completed, failed)

Scan Details

Click on scan to view:

  • Scan ID
  • Container name
  • Start/finish timestamp
  • Duration
  • Total vulnerabilities found
  • Severity breakdown
  • Scan logs (if failed)

Compare Scans

Compare two scans to see:

  • New vulnerabilities discovered
  • Vulnerabilities remediated
  • Net change in security posture

Data Retention

Configure in Settings → Data Retention:

  • Keep Scan History Days: How long to retain scan records (default: 90 days)

Older scans are automatically purged to save disk space.

Advanced Features

False Positive Patterns

Create regex patterns to auto-mark false positives:

Navigate to Settings → Advanced → False Positive Patterns:

Example:

CVE Pattern: CVE-2024-.*
Package: libfoo
Reason: Package not exposed to network

Future scans automatically apply this pattern.

Scanner Offline Resilience

Handle network outages gracefully:

Settings → Scanner Offline Resilience:

  • Scanner DB Max Age: Max hours before forcing update (default: 24)
  • Allow Stale DB: Continue scanning with outdated database
  • Stale DB Warning: Hours before warning (default: 72)

Ensures scans continue even if Trivy DB update fails.

API Integration

Automate vulnerability scanning:

# Scan all containers
curl -X POST http://localhost:8787/api/scan/all

# Scan specific container
curl -X POST http://localhost:8787/api/scan/container/123

# Get vulnerabilities
curl http://localhost:8787/api/vulnerabilities

# Filter by severity
curl "http://localhost:8787/api/vulnerabilities?severity=critical"

# Filter by container
curl "http://localhost:8787/api/vulnerabilities?container_id=123"

See API Reference for complete documentation.

Best Practices

Scanning Strategy

  1. Scan frequently: Daily or after every deployment
  2. Prioritize: Focus on running containers first
  3. Automate: Use scheduled scans
  4. Monitor: Set up notifications for critical findings

Triage Discipline

  1. Review new vulnerabilities within 24 hours
  2. Document decisions with notes
  3. Revisit ignored vulnerabilities quarterly
  4. Update patterns for recurring false positives

Remediation Workflow

  1. Critical/High KEVs: Immediate action (hours)
  2. Critical non-KEVs: Within 1 week
  3. High: Within 2 weeks
  4. Medium: Within 30 days
  5. Low: Quarterly review

Troubleshooting

Scans Failing

Check Trivy logs:

docker logs trivy

Common issues:

  • Trivy DB update failed (network issue)
  • Scanner timeout (increase SCAN_TIMEOUT)
  • Image not pullable (credentials required)
  • Disk space exhausted

No Vulnerabilities Found

  • Image may be truly clean (rare)
  • Trivy DB may be outdated
  • Scanner may not support image OS

High False Positive Rate

  • Create false positive patterns
  • Check Trivy version (newer is better)
  • Review scanner configuration

Next Steps

Clone this wiki locally