Max Severity + Grype Vulnerability Scanner Collector
Enforce Max Severity using data collected by Grype Vulnerability Scanner Collector. Automatically check security and compliance standards on every PR.
How Grype Vulnerability Scanner Collector Powers This Guardrail
The Grype Vulnerability Scanner Collector gathers metadata from your security systems. This data flows into Lunar's Component JSON, where the Max Severity guardrail evaluates it against your standards.
When enabled, this check runs automatically on every PR and in AI coding workflows, providing real-time enforcement with actionable feedback.
Quick Start Configuration
Add both the collector and policy to your lunar-config.yml to enable this guardrail.
# Step 1: Enable the Grype Vulnerability Scanner Collector
collectors:
- uses: github://earthly/lunar-lib/collectors/grype@v1.0.5
# with: ...
# Step 2: Enable the SCA Guardrails
policies:
- uses: github://earthly/lunar-lib/policies/sca@v1.0.5
include: [max-severity]
# with: ...What Grype Vulnerability Scanner Collector Collects
This collector gathers the following data that the Max Severity guardrail evaluates.
auto
Auto-scans the repository filesystem for dependency vulnerabilities using Grype. Writes normalized findings to .sca with severity counts, CVE IDs, affected packages, and fix versions.
rescan
Re-runs the dependency (SCA) scan on a schedule and overwrites .sca so
the SCA policy re-evaluates against CVEs published since the commit was
first scanned — closing the gap where a branch passes at scan time but a
dependency picks up a new CVE later. Runs the same scan as the auto
collector (the sibling auto.sh) in the Grype collector image, and stamps
.sca.source.integration="cron" (vs "code" for the on-push scan) so it's
clear the data came from a scheduled re-scan.
Opt-in scan history: with scan_history_size > 0 the re-scan first snapshots the current .sca (counts + summary + source, including the scan timestamp) into a bounded .sca.history[] array before overwriting .sca, preserving point-in-time scan results for audit. The SCA policy keeps reading the current .sca and behaves identically whether history is on or off. Default 0 keeps today's overwrite-only behavior — no history, no schema change for existing consumers.
cicd
Detects Grype executions in CI pipelines. Captures the command,
version, and input arguments for audit and compliance tracking.
Routes results by scan target: an image scan (grype <image-ref>) is
normalized to .container_scan, while a directory or SBOM scan
(grype dir:., grype sbom:...) stays in .sca — so a container scan
already running in your pipeline is collected automatically with no
extra configuration.
container-rescan
Re-scans the most recently shipped container image on a schedule. Resolves
the image from what the component actually pushed — the most recent
docker push (or --push build) in the docker collector's recorded
commands (.containers.native.docker.cicd.cmds[]), read via lunar component get-json. That's already-persisted data, so no collector dependency is
required. Pulls the image, scans it with Grype, and overwrites
.container_scan so a shipped image is re-evaluated against CVEs published
after it was built. Override with the container_image input. No code
clone needed; runs in the Grype collector image, so the baked-in
vulnerability DB is reused.
Example Data Flow
Here's an example of the data that Grype Vulnerability Scanner Collector writes to the Component JSON, which Max Severity then evaluates.
{
"sca": {
"source": {
"tool": "grype",
"version": "0.74.0",
"integration": "cron",
"collected_at": "2026-07-08T02:00:07Z"
},
"vulnerabilities": {
"critical": 0,
"high": 2,
"medium": 5,
"low": 3,
"total": 10
},
"findings": [
{
"severity": "high",
"package": "golang.org/x/net",
"version": "0.7.0",
"ecosystem": "go-module",
"cve": "CVE-2023-44487",
"title": "HTTP/2 Rapid Reset Attack",
"fix_version": "0.17.0",
"fixable": true
}
],
"summary": {
"has_critical": false,
"has_high": true,
"all_fixable": true
},
"history": [
{
"source": {"tool": "grype", "version": "0.74.0", "integration": "code", "collected_at": "2026-07-01T02:00:11Z"},
"vulnerabilities": {"critical": 0, "high": 1, "medium": 5, "low": 3, "total": 9},
"summary": {"has_critical": false, "has_high": true, "all_fixable": true}
},
{
"source": {"tool": "grype", "version": "0.74.0", "integration": "cron", "collected_at": "2026-07-05T02:00:09Z"},
"vulnerabilities": {"critical": 0, "high": 2, "medium": 5, "low": 3, "total": 10},
"summary": {"has_critical": false, "has_high": true, "all_fixable": true}
}
],
"rescan_count": 2,
"native": {
"grype": {
"cicd": {
"cmds": [
{"cmd": "grype dir:. -o json", "version": "0.74.0"}
]
},
"matches": [
{
"vulnerability": {
"id": "CVE-2023-44487",
"severity": "High",
"fix": {"versions": ["0.17.0"], "state": "fixed"},
"dataSource": "https://nvd.nist.gov/vuln/detail/CVE-2023-44487",
"cvss": [{"metrics": {"baseScore": 7.5}}]
},
"artifact": {
"name": "golang.org/x/net",
"version": "0.7.0",
"type": "go-module",
"language": "go",
"purl": "pkg:golang/golang.org/x/net@0.7.0"
}
}
]
}
}
},
"container_scan": {
"source": {
"tool": "grype",
"version": "0.74.0",
"integration": "ci"
},
"image": "myregistry.io/app:v1.2.3",
"os": {
"family": "alpine",
"version": "3.19"
},
"vulnerabilities": {
"critical": 0,
"high": 1,
"medium": 4,
"low": 7,
"total": 12
},
"findings": [
{
"severity": "high",
"package": "libssl3",
"version": "3.1.4-r5",
"ecosystem": "apk",
"cve": "CVE-2024-2511",
"title": "OpenSSL unbounded memory growth in TLSv1.3 session handling",
"fix_version": "3.1.4-r6",
"fixable": true
}
],
"summary": {
"has_critical": false,
"has_high": true,
"all_fixable": true
},
"native": {
"grype": {
"matches": [
{
"vulnerability": {
"id": "CVE-2024-2511",
"severity": "High",
"fix": {"versions": ["3.1.4-r6"], "state": "fixed"}
},
"artifact": {
"name": "libssl3",
"version": "3.1.4-r5",
"type": "apk",
"purl": "pkg:apk/alpine/libssl3@3.1.4-r5"
}
}
]
}
}
}
}Configuration Options
Grype Vulnerability Scanner Collector Inputs
| Input | Required | Default | Description |
|---|---|---|---|
scan_history_size |
Optional |
0
|
Maximum number of prior SCA scans to retain in .sca.history[] on each cron re-scan. Snapshots are ordered oldest-first and the current scan stays in the main .sca fields, so the SCA policy is unaffected. Each entry carries its own source (integration + collected_at), so the release-time scan is identifiable as the integration="code" entry — that's .sca.history[0] when history is enabled from the component's first scan (the intended setup for release-time audit). Enabling it later on a component that has already been re-scanned captures the current .sca as the oldest entry, since the release-time scan was already overwritten. 0 (default) disables history entirely — .sca is overwritten each run exactly as today and no .sca.history is written, so existing consumers see no change. When the cap is reached the oldest entry (index 0) is preserved and the second-oldest is dropped. Only the rescan (cron) sub-collector maintains history; the on-push auto scan ignores this. |
max_rescans |
Optional |
0
|
Stop re-scanning a component after this many scheduled re-scans; 0 (default) means unlimited. Counted independently via .sca.rescan_count (a monotonic tally of completed re-scans), so it stands alone and does not depend on scan_history_size — scan_history_size bounds how many scans you KEEP, max_rescans bounds how many you RUN. Once the limit is reached the cron skips the component, keeping the last scan and its history. |
db_auto_update |
Optional |
false
|
Download the latest Grype vulnerability database at scan time so scans pick up CVEs published since the collector image was built. Disabled by default for now: enabling it fetches a runtime DB that decompresses to ~1.7GB, which needs the size: large profile the auto/rescan collectors declare — and that only helps on a Hub that honors size (ENG-983), so it's kept off until size-aware Hub builds ship everywhere. Set to "true" on a size-aware Hub to scan the fresh DB; left "false" it scans the lighter image-baked DB, whose freshness tracks the image rebuild cadence. |
container_image |
Required | — | Override the image reference the container-rescan cron scans. By default the cron derives the image from the component's most recent .containers.builds[] entry (populated by the docker collector). Set this to pin a specific image, e.g. "ghcr.io/acme/app:latest". |
SCA Guardrails Inputs
| Input | Required | Default | Description |
|---|---|---|---|
min_severity |
Optional |
high
|
Minimum severity to fail on (critical, high, medium, low) |
max_total_threshold |
Required | — | Maximum total findings allowed (must be configured) |
alert_url |
Required | — | Optional webhook URL. When set, a failing max-severity check also POSTs a JSON payload describing the findings at or above min_severity. Leave empty to disable alerting (default). |
alert_timeout_sec |
Optional |
2
|
Webhook POST timeout in seconds. Best-effort — a slow or dead endpoint never changes the check result. |
Ready to Automate Your Standards?
See how Lunar can turn your AGENTS.md, engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 200+ built-in guardrails.
AI agent rules & prompt files
Post-mortem action items
Security & compliance policies
Testing & quality requirements