---
checkId: check.scanner.vuln
plugin: stellaops.doctor.scanner
severity: warn
tags: [scanner, vulnerability, cve, database]
---
# Vulnerability Scan Health

## What It Checks
Queries the Scanner service at `/api/v1/vuln/stats` and evaluates vulnerability scanning health, focusing on database freshness:

- **Database freshness**: warn when the vulnerability database is older than 24 hours, fail when older than 72 hours.
- **Scan failure rate**: warn when scan failure rate exceeds 10%.

Evidence collected: `database_age_hours`, `last_db_update`, `total_cves`, `scans_completed`, `scan_failures`, `failure_rate`, `vulnerabilities_found`.

The check requires `Scanner:Url` or `Services:Scanner:Url` to be configured.

## Why It Matters
A stale vulnerability database means newly disclosed CVEs are not detected in scans, creating a false sense of security. Artifacts that pass policy gates with an outdated database may contain exploitable vulnerabilities that would have been caught with current data. In regulated environments, scan freshness is an auditable compliance requirement. High scan failure rates mean some artifacts are not being scanned at all.

## Common Causes
- Vulnerability database sync job failed or is not scheduled
- Feed source (NVD, OSV, vendor advisory) unavailable or rate-limited
- Network connectivity issue preventing feed downloads
- Scheduled sync delayed due to system overload
- Parsing errors on specific artifact formats
- Unsupported package ecosystem or lockfile format

## How to Fix

### Docker Compose
```bash
# Trigger an immediate database sync
stella scanner db sync

# Check sync job status
stella scanner db status

# View scanner logs for sync errors
docker compose -f docker-compose.stella-ops.yml logs scanner | grep -i "sync\|feed\|vuln"
```

Configure sync schedule in `docker-compose.stella-ops.yml`:

```yaml
services:
  scanner:
    environment:
      Scanner__VulnDb__SyncIntervalHours: "6"
      Scanner__VulnDb__FeedSources: "nvd,osv,github"
      Scanner__VulnDb__RetryCount: "3"
```

### Bare Metal / systemd
```bash
# Trigger manual sync
stella scanner db sync

# Check sync schedule
stella scanner db schedule

# View sync logs
sudo journalctl -u stellaops-scanner --since "24 hours ago" | grep -i "sync\|feed"
```

Edit `/etc/stellaops/scanner/appsettings.json`:

```json
{
  "VulnDb": {
    "SyncIntervalHours": 6,
    "FeedSources": ["nvd", "osv", "github"],
    "RetryCount": 3
  }
}
```

### Kubernetes / Helm
```bash
# Check scanner pod logs for sync status
kubectl logs -l app=stellaops-scanner --tail=100 | grep -i sync

# Verify CronJob for database sync exists and is running
kubectl get cronjobs -l app=stellaops-scanner-sync
```

Set in Helm `values.yaml`:

```yaml
scanner:
  vulnDb:
    syncIntervalHours: 6
    feedSources:
      - nvd
      - osv
      - github
    retryCount: 3
  syncCronJob:
    schedule: "0 */6 * * *"
```

## Verification
```
stella doctor run --check check.scanner.vuln
```

## Related Checks
- `check.scanner.queue` -- scan failures may originate from queue processing issues
- `check.scanner.sbom` -- vulnerability matching depends on SBOM quality
- `check.scanner.reachability` -- reachability analysis uses vulnerability data to filter findings