container-image-scanner

# container-image-scanner Skill

## When to Use

Use this skill when the user wants to:
- Scan a Docker image for known CVE vulnerabilities
- Check what security findings exist in a container image
- Gate a CI/CD pipeline on critical/high CVEs
- Compare two scans to see what vulnerabilities were fixed or introduced
- Track CVE exposure across multiple images

## Prerequisites

- Node.js 20+
- pnpm 9+
- Trivy installed: `brew install trivy` or `apt-get install trivy`
- container-image-scanner server running (`pnpm --filter server dev` or Docker)
- `CIS_API_KEY` environment variable set (required for scan triggers)

## CLI Quick Reference

```
# Scan an image
container-image-scanner scan nginx:1.25-alpine

# Scan and fail CI on critical findings
container-image-scanner scan nginx:1.25-alpine --fail-on CRITICAL

# Scan with JSON output
container-image-scanner scan nginx:1.25-alpine --json

# List recent scans
container-image-scanner scans

# List scans for a specific image
container-image-scanner scans --image nginx:1.25-alpine

# Show findings for a scan
container-image-scanner findings scan_a1b2c3

# Show only HIGH and above
container-image-scanner findings scan_a1b2c3 --severity HIGH

# Show all images affected by a CVE
container-image-scanner cve CVE-2024-5535

# List scanned images
container-image-scanner images
```

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `PORT` | no | `3000` | HTTP server port |
| `DATABASE_PATH` | no | `./data/cis.db` | SQLite database path |
| `API_KEY` | yes (for write) | (none) | API key for scan triggers and deletions |
| `TRIVY_PATH` | no | `trivy` | Path to trivy binary |
| `TRIVY_TIMEOUT` | no | `10m` | Timeout per scan |
| `MAX_CONCURRENT_SCANS` | no | `1` | Max parallel scans |
| `LOG_LEVEL` | no | `info` | debug, info, warn, error |
| `CIS_API_KEY` | no | (none) | Client-side env var for CLI auth |

Boolean env vars (1=true, 0=false):

| Variable | Default | Description |
|---|---|---|
| `TRIVY_IGNORE_UNFIXED` | `0` | Hide CVEs with no fix available |
| `SKIP_DB_UPDATE` | `0` | Skip trivy CVE DB update (faster, stale) |
| `VERIFY_SSL` | `1` | Verify TLS on registry connections |

## API Routes

All write routes require `Authorization: Bearer <api-key>`.

| Method | Path | Auth | Description |
|---|---|---|---|
| `GET` | `/api/summary` | no | Global stats |
| `GET` | `/api/images` | no | List images |
| `GET` | `/api/images/:id` | no | Image + scan history |
| `POST` | `/api/scans` | yes | Trigger scan: `{ "image": "nginx:1.25-alpine" }` |
| `GET` | `/api/scans` | no | List scans |
| `GET` | `/api/scans/:id` | no | Scan detail + findings |
| `DELETE` | `/api/scans/:id` | yes | Delete scan |
| `GET` | `/api/findings` | no | Findings (filterable by severity, search) |
| `GET` | `/api/findings/cve/:cveId` | no | All findings for a CVE |
| `GET` | `/healthz` | no | Health check |

## Severity Levels

Findings are classified into five severity levels. The worst finding determines the image's overall severity:

| Severity | Score | When to Action |
|---|---|---|
| CRITICAL | 4 | Immediate -- block deployment |
| HIGH | 3 | Fix within sprint |
| MEDIUM | 2 | Fix within quarter |
| LOW | 1 | Track, fix when convenient |
| UNKNOWN | 0 | Investigate manually |

## CI/CD Integration

```bash
#!/bin/bash
# ci-scan.sh - fail the build if critical CVEs are found

set -euo pipefail

IMAGE="${1:?Usage: ci-scan.sh <image>}"

container-image-scanner scan "$IMAGE" \
  --fail-on CRITICAL \
  --json \
  --api-url "${CIS_API_URL:-http://localhost:3000}" \
  --api-key "${CIS_API_KEY}"
```

Exit codes:
- `0` - scan completed, severity threshold not breached
- `1` - scan completed, `--fail-on` threshold breached
- `2` - scan failed (trivy error, network error, invalid image)

## Trigger a Scan via REST API

```bash
# Trigger scan
curl -X POST http://localhost:3000/api/scans \
  -H "Authorization: Bearer $CIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "nginx:1.25-alpine"}'
# -> { "scan_id": "scan_a1b2c3", "status": "queued" }

# Poll status
curl http://localhost:3000/api/scans/scan_a1b2c3
# -> { "status": "done", "findings": { "CRITICAL": 2, ... } }
```

## Troubleshooting

**"trivy not found"**
Install Trivy: `brew install trivy` (macOS), `apt-get install trivy` (Debian/Ubuntu), or download from https://github.com/aquasecurity/trivy/releases

**"unauthorized"**
Set the `CIS_API_KEY` environment variable or pass `--api-key` to the CLI.

**Scan fails for a private registry image**
Ensure Docker is logged in on the server host: `docker login registry.example.com`. Trivy uses the Docker credential store.

**Scan is stuck in "running" for a long time**
The image may be very large. Check `TRIVY_TIMEOUT` is set high enough (default 10m). Verify trivy can be run manually: `trivy image --format json nginx:latest`.

**"image name is invalid"**
Image references must match the pattern `[registry/][namespace/]name[:tag][@digest]`. Shell metacharacters are rejected. Example valid refs: `nginx:1.25`, `myregistry.io/myorg/myapp:v2.1.0`.