Add agent-executable workflow docs for CVE fixes

CVE workflow docs and commit templates for AI agents and human devs.

Signed-off-by: Daniel Farrell <[email protected]>

Author: dfarrell07

.agents/commit-templates.md

@@ -0,0 +1,62 @@
+# Commit Message Templates
+
+## Rules
+
+- Imperative mood (Add, Fix, Update, not Added/Fixed/Updated)
+- Subject ≤50 chars, body lines ≤72 chars
+- Always sign-off: `git commit -s`
+
+## Version Bumps
+
+```text
+Bump <package> from <old-version> to <new-version>
+```
+
+## CVE Fixes
+
+**Single CVE:**
+```text
+Bump <abbreviated-package> for <CVE-ID>
+
+Full package: <full-package-path>
+```
+
+**Multiple CVEs (one package update):**
+
+Use "for CVEs" in subject to stay ≤50 chars, list all in body.
+
+```text
+Bump <abbreviated-package> for CVEs
+
+Full package: <full-package-path>
+Fixes: <CVE-ID-1>, <CVE-ID-2>
+```
+
+**Package abbreviations:**
+- `github.com/docker/docker` → `docker/docker`
+- `golang.org/x/oauth2` → `x/oauth2`
+- `helm.sh/helm/v3` → `helm/v3`
+- Keep `k8s.io/` prefix
+
+**Examples:**
+```text
+Bump docker/docker for GHSA-4vq8-7jfc-9cvp
+
+Full package: github.com/docker/docker
+```
+
+```text
+Bump helm/v3 for CVEs
+
+Full package: helm.sh/helm/v3
+Fixes: GHSA-f9f8-9pmf-xv68, GHSA-9h84-qmv7-982p
+```
+
+## Code Changes
+
+```text
+Add <feature>
+Fix <bug>
+Update <component>
+Remove <deprecated-feature>
+```

.agents/workflows/cve-fix.md

@@ -0,0 +1,267 @@
+#### Fixing CVEs
+
+**Before starting, user must:**
+
+Install/update grype:
+```bash
+grype version || curl -sSfL https://get.anchore.io/grype | sudo sh -s -- -b /usr/local/bin
+```
+
+Fetch latest changes:
+```bash
+git fetch
+```
+
+##### 0. Update Vulnerability Database
+
+```bash
+grype db update
+```
+
+##### 1. Update Branch and Create Fix Branch
+
+```bash
+# Switch to target branch and update to latest
+git checkout release-0.X
+git merge --ff-only origin/release-0.X
+
+# Create fix branch (add -v2, -v3 etc if branch exists; don't delete old versions)
+git checkout -b fix-0.X-cves-YYYY-MM-DD
+```
+
+Replace `0.X`: `release-0.21` → `0.21`, `devel` → `devel`.
+
+One commit per package (may fix multiple CVEs), one PR total.
+
+##### 2. Scan
+
+```bash
+grype . --config .grype.yaml -o table
+```
+
+Ignore warning "no explicit name and version provided".
+
+For each CVE, note:
+- Package (**NAME**)
+- Version (**FIXED-IN**)
+- CVE ID (**VULNERABILITY**)
+
+**Note**: Same package may appear multiple times with different versions (e.g., quic-go v0.48.2 in coredns, v0.54.0 in main). Treat each as separate fix.
+
+##### 3. Locate Package
+
+```bash
+grep -Fl [package] go.mod coredns/go.mod tools/go.mod 2>/dev/null
+```
+
+**Check for replace directives**:
+```bash
+grep "replace.*$(basename [package])" go.mod coredns/go.mod tools/go.mod 2>/dev/null
+```
+
+If found, check git history why it was added. If obsolete, remove now. Otherwise update to safe version in Step 4:
+```bash
+# Check history
+git log -p --all -S "replace.*$(basename [package])" -- [module]/go.mod | head -50
+
+# Remove if obsolete
+sed -i '/replace.*[package]/d; /Fixes CVE-/d' [module]/go.mod
+```
+
+**Check for parent-child dependencies:**
+
+If multiple packages in the same module have CVEs, check if one depends on another: `cd [module] && go mod graph | grep [package]`. If parent (e.g., CoreDNS depends on quic-go) also has CVE, fix parent first. Parent upgrade often brings newer child, eliminating separate fix.
+
+##### 4. Update
+
+**If Step 3 found package in single module:**
+
+```bash
+# coredns/go.mod only
+cd coredns && go get [package]@v[version] && go mod tidy && cd ..
+
+# tools/go.mod only
+cd tools && go get [package]@v[version] && go mod tidy && cd ..
+
+# go.mod only
+go get [package]@v[version] && go mod tidy
+```
+
+If multiple CVEs have different FIXED-IN versions, use the highest.
+
+**If Step 3 found package in multiple modules:**
+
+Multi-module packages require verification between updates to avoid downgrades.
+
+1. If package in main go.mod (and maybe submodules too):
+   ```bash
+   go get [package]@v[version] && go mod tidy
+   ```
+   Then proceed to Step 5, Step 6. If Step 6 shows CVE still present, update one submodule at a time, repeating Steps 5-6 after each update.
+
+2. If package only in submodules (e.g., both coredns and tools):
+   ```bash
+   cd coredns && go get [package]@v[version] && go mod tidy && cd ..
+   ```
+   Then proceed to Step 5, Step 6. If Step 6 shows CVE still present, update next submodule (tools), repeating Steps 5-6.
+
+Submodules may have different (non-vulnerable) versions. Check `git diff` for unexpected downgrades (e.g., CoreDNS version changes).
+
+**On stable release branches, if `go get` upgrades:**
+- Go minor version (1.X => 1.Y)
+- K8s minor version (v0.A => v0.B)
+
+Revert changes. Low/Medium CVEs: skip to Step 9. High/Critical: consult team.
+
+Remove `toolchain` lines and extra blank lines added by `go mod tidy`:
+
+```bash
+sed -i '/^toolchain/d' go.mod coredns/go.mod tools/go.mod
+sed -i '/^$/{N;/^\n$/s/\n//;}' go.mod coredns/go.mod tools/go.mod
+```
+
+Verify changes:
+
+```bash
+git diff
+```
+
+Expected: Dependency file updates only.
+
+##### 5. Clean Binaries
+
+```bash
+make clean-generated
+```
+
+Removes build artifacts to avoid false positives.
+
+Network errors: see Common Issues.
+
+##### 6. Verify
+
+```bash
+grype . --config .grype.yaml -o table
+```
+
+CVE(s) for this package should no longer appear.
+
+**If CVE persists**: Double-check you used the correct version from Step 2 FIXED-IN column. If version is correct but CVE persists, the replace directive should have been caught in Step 3 - recheck Step 3.
+
+##### 7. Verify Build
+
+```bash
+make unit
+```
+
+**Note**: When fixing multiple packages, skip this step for each package and run once at end.
+
+Build errors may indicate incompatible dependency versions for this branch.
+
+##### 8. Commit
+
+```bash
+# Stage dependency files
+git add go.mod go.sum coredns/go.mod coredns/go.sum tools/go.mod tools/go.sum
+
+# Verify what will be committed
+git diff --staged --stat
+```
+
+Expected: Only go.mod/go.sum files (for modules that changed).
+
+Follow commit templates in @.agents/commit-templates.md (CVE Fixes section). Use "in /[module]" format if only coredns or tools files changed.
+
+After each commit, rescan to check for newly introduced CVEs:
+```bash
+grype . --config .grype.yaml -o table
+```
+
+Repeat steps 3-8 for each remaining package with CVEs.
+
+##### 9. When to Ignore CVEs
+
+If fix requires breaking changes (Go version, K8s major version, incompatible APIs), consider:
+- CVE severity (Low/Medium vs High/Critical)
+- Cost/risk of breaking stable branch dependencies
+
+Add to `.grype.yaml`:
+```yaml
+# Update requires [incompatibility]. [Severity] doesn't justify breaking changes.
+- vulnerability: GHSA-xxxx-xxxx-xxxx
+  package:
+    name: package.name/path
+```
+
+Commit:
+```bash
+git commit -s -m "$(cat <<'EOF'
+Ignore [package] CVEs incompatible with release-X.Y
+
+[Package] CVEs require versions with [incompatible dependency]
+incompatible with this branch's [current dependency].
+EOF
+)"
+```
+
+##### 10. Final Verification
+
+After fixing all packages:
+
+```bash
+# Verify no vulnerabilities remain
+grype . --config .grype.yaml -o table
+
+# Run build tests if not done in step 7
+make unit
+
+# Review commits
+git log origin/release-0.X..HEAD
+
+# Verify no unexpected changes
+git diff
+```
+
+Expected: "No vulnerabilities found", tests pass, commits follow @.agents/commit-templates.md, and no output from diff.
+
+##### 11. Create Pull Request (Optional)
+
+Agent generates ready-to-run PR command. User reviews commits, then copies and runs command if desired:
+
+```bash
+# Auto-generate gh pr create command
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+BASE_BRANCH=$(echo $CURRENT_BRANCH | sed 's/fix-\([0-9.]*\)-.*/release-\1/')
+COMMIT_COUNT=$(git log ${BASE_BRANCH}..HEAD --oneline | wc -l)
+PLURAL=$([[ $COMMIT_COUNT -eq 1 ]] && echo "" || echo "s")
+CVE_PLURAL=$([[ $COMMIT_COUNT -eq 1 ]] && echo "CVE" || echo "CVEs")
+
+# Find fork remote (non-submariner-io remote)
+FORK_REMOTE=$(git remote -v | grep -v 'submariner-io' | grep '(push)' | head -1 | awk '{print $1}')
+FORK_USER=$(git remote get-url ${FORK_REMOTE} 2>/dev/null | sed 's/.*github.com[:/]\([^/]*\).*/\1/')
+
+cat <<EOF
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Copy and run these commands to create PR:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+git push ${FORK_REMOTE} ${CURRENT_BRANCH}
+
+gh pr create \\
+  --title "Fix ${CVE_PLURAL} in ${BASE_BRANCH}" \\
+  --body "See commit message${PLURAL} for details." \\
+  --base "${BASE_BRANCH}" \\
+  --head "${FORK_USER}:${CURRENT_BRANCH}" \\
+  --assignee "@me"
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EOF
+```
+
+##### Common Issues
+
+- **CVE persists after update**: Verify you used correct FIXED-IN version; replace directives should have been caught in Step 3
+- **New CVE appears after fix**: Dependency downgrades can introduce CVEs; fix immediately (Step 8 rescan catches these)
+- **Tests fail**: Try different version; check CI logs
+- **make unit "no route to host"**: User must run `sudo systemctl restart docker` (agent can't use sudo)

CLAUDE.md

@@ -0,0 +1,27 @@
+# lighthouse
+
+Development guidelines for the lighthouse repository.
+
+## Commit Messages
+
+@.agents/commit-templates.md
+
+## Workflows
+
+### Testing
+
+#### Markdown
+
+Run after editing any `.md` file, before committing:
+
+```bash
+make markdownlint
+```
+
+### CVE Fixes
+
+@.agents/workflows/cve-fix.md
+
+### Konflux Builds
+
+(future - planned for separate effort)