<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Container Image Scanning — API Reference

## Trivy CLI

### Vulnerability Scanning

```bash
# Basic image scan
trivy image TARGET_IMAGE

# Scan with severity filter
trivy image --severity HIGH,CRITICAL TARGET_IMAGE

# JSON output
trivy image --format json --output results.json TARGET_IMAGE

# Ignore unfixed
trivy image --ignore-unfixed TARGET_IMAGE

# Scan from tar archive
trivy image --input image.tar

# Scan with custom policy
trivy image --policy /path/to/policy.rego TARGET_IMAGE
```

### Secret Scanning

```bash
# Scan for secrets in image
trivy image --scanners secret TARGET_IMAGE

# Scan filesystem
trivy fs --scanners secret /path/to/project
```

### Configuration Scanning

```bash
# Scan Dockerfile
trivy config Dockerfile

# Scan Kubernetes manifests
trivy config -f json k8s-deployment.yaml
```

## Grype CLI

```bash
# Basic scan
grype TARGET_IMAGE

# JSON output
grype TARGET_IMAGE --output json

# Only show fixed vulnerabilities
grype TARGET_IMAGE --only-fixed

# Scan from SBOM
grype sbom:sbom.json

# Scan directory
grype dir:/path/to/project
```

## Syft CLI (SBOM)

```bash
# Generate SPDX SBOM
syft TARGET_IMAGE -o spdx-json > sbom.json

# CycloneDX format
syft TARGET_IMAGE -o cyclonedx-json > bom.json

# Table output
syft TARGET_IMAGE -o table
```

## Cosign CLI

```bash
# Generate key pair
cosign generate-key-pair

# Sign image
cosign sign --key cosign.key REGISTRY/IMAGE:TAG

# Verify signature
cosign verify --key cosign.pub REGISTRY/IMAGE:TAG

# Keyless signing (Sigstore)
cosign sign REGISTRY/IMAGE:TAG

# Attach SBOM to image
cosign attach sbom --sbom sbom.json REGISTRY/IMAGE:TAG
```

## Hadolint (Dockerfile Linting)

```bash
# Lint Dockerfile
hadolint Dockerfile

# JSON output
hadolint --format json Dockerfile

# Ignore specific rules
hadolint --ignore DL3008 --ignore DL3009 Dockerfile
```

## Key Trivy JSON Fields

| Field | Description |
|-------|-------------|
| `Results[].Target` | Scanned target (OS, language file) |
| `Results[].Vulnerabilities[].VulnerabilityID` | CVE identifier |
| `Results[].Vulnerabilities[].PkgName` | Affected package |
| `Results[].Vulnerabilities[].InstalledVersion` | Current version |
| `Results[].Vulnerabilities[].FixedVersion` | Patched version |
| `Results[].Vulnerabilities[].Severity` | CRITICAL/HIGH/MEDIUM/LOW |
| `Results[].Vulnerabilities[].CVSS` | CVSS score details |

## Key Grype JSON Fields

| Field | Description |
|-------|-------------|
| `matches[].vulnerability.id` | CVE identifier |
| `matches[].vulnerability.severity` | Severity level |
| `matches[].artifact.name` | Package name |
| `matches[].artifact.version` | Installed version |
| `matches[].vulnerability.fix.versions` | Available fix versions |

## CI/CD Integration

### GitHub Actions

```yaml
- uses: aquasecurity/trivy-action@master
  with:
    image-ref: ${{ env.IMAGE }}
    format: sarif
    severity: HIGH,CRITICAL
    exit-code: 1
```

### GitLab CI

```yaml
trivy_scan:
  image: aquasec/trivy:latest
  script:
    - trivy image --exit-code 1 --severity HIGH,CRITICAL $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
```
