<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# Container Image Scanning — API Reference

## Trivy Image Commands

```bash
# Scan image
trivy image myapp:latest --format json --severity CRITICAL,HIGH

# Scan with SBOM
trivy image myapp:latest --format spdx-json --output sbom.json

# Scan tar archive
trivy image --input myapp.tar --format json

# Scan OCI directory
trivy image --input oci:myapp --format json

# Ignore unfixed
trivy image myapp:latest --ignore-unfixed

# Scan specific layers
trivy image myapp:latest --list-all-pkgs
```

## Grype Image Commands

```bash
# Scan image
grype myapp:latest --output json

# Fail on severity
grype myapp:latest --fail-on critical

# Scan from registry
grype registry:ghcr.io/org/app:v1.0 --output json
```

## Cosign Commands

```bash
# Sign image (keyless)
cosign sign --yes ghcr.io/org/app:v1.0

# Sign with key
cosign sign --key cosign.key ghcr.io/org/app:v1.0

# Verify signature
cosign verify ghcr.io/org/app:v1.0 --certificate-identity-regexp=".*"

# Attach SBOM
cosign attach sbom --sbom sbom.spdx.json ghcr.io/org/app:v1.0

# Verify attestation
cosign verify-attestation ghcr.io/org/app:v1.0 --type spdxjson
```

## Dockerfile Best Practices

| Practice | Description |
|----------|-------------|
| Pin base image digest | `FROM python:3.12@sha256:abc...` |
| Non-root user | `USER 1001` |
| Multi-stage builds | Separate build and runtime |
| No secrets in ENV/ARG | Use runtime mounts |
| Minimal base image | distroless, alpine, scratch |
| `--no-install-recommends` | Reduce package bloat |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | No vulnerabilities found |
| 1 | Vulnerabilities detected |
| 2 | Scan error |
