@groupby/ai-dev 0.5.16 → 0.5.17

package/teams/firstspirit-caas/skills/handle-red-cve-plan/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: handle-red-cve-plan
+description: 'Use when the user gives a red/failing Bamboo build URL and asks to fix, remediate, or triage its dependency CVEs — phrases like "fix the CVEs in this Bamboo build", "handle-cve for <bamboo url>", "remediate the dependency-check findings from CI". Distinct from handle-cve: this skill is driven by a Bamboo build URL and parses the published dependency-check report artifact (the JSON report when present, falling back to the HTML report), not a user-supplied local file.'
+---
+
+# handle-red-cve-plan
+
+Input: a red Bamboo plan/build URL. Output: **normally a Bitbucket PR** that fixes or
+suppresses every active CVSS >= 7.0 finding — **except when the remediation is suppressions
+only**, in which case the output is a single **unpushed local commit on the default branch**
+for the invoker to review (no branch, no PR; see step 7). Runs fully autonomously — no
+confirmation stops. Operates on the current working directory, assumed to be the checked-out
+target repo.
+
+**Parameters:**
+- `ticket` (**required**) — the JIRA key that tracks this remediation (e.g. `PX-1234`). Drives
+  the fix branch (step 4): the skill reuses an existing branch for this ticket in the repo, or
+  creates `bugfix/<ticket>-handle-weekly-cves`. **Invoked without a ticket → hard stop and ask
+  for one** (see Hard stops). The orchestrator `handle-weekly-cve-plans` always supplies it.
+- `useSonatype` (optional flag) — when the user specifies it (e.g. "fix the CVEs …
+  useSonatype"), the verify step (step 6) runs `./gradlew dependencyCheckAggregate
+  -DuseSonatype`; when omitted, it runs `./gradlew dependencyCheckAggregate` without the
+  flag. This mirrors how the Bamboo plan itself was configured (the weekly Sonatype-OSS
+  build passes it) so local verification matches CI.
+
+## When NOT to use
+
+- A local JSON dependency-check report is already in hand and no PR/push is wanted — use
+  `handle-cve` (read-only, never invokes Gradle or Git).
+- Single ad-hoc CVE with no scanner/Bamboo context.
+
+## Constraints (non-negotiable)
+
+- Act only on **active** findings with **CVSS >= 7.0** (exclude the report's suppressed
+  vulnerabilities — both `parse_json_report.py` and `parse_report.py` already do this: the JSON
+  parser reads only the `vulnerabilities` array and never `suppressedVulnerabilities`, the HTML
+  parser keeps only entries that still carry a suppress button).
+- **Only update an existing dependency declaration.** Never add a new entry for a
+  transitive dependency.
+- Suppression file is **auto-discovered, never created**. If suppression is needed and no
+  file is found → **STOP and report**.
+- Each CVE is suppressed **at most once** across the whole file — one block per CVE, listing
+  every affected `<packageUrl>`. Never emit the same `<cve>` in two blocks.
+- Suppression type: **when in doubt, temporary** (default 2 months). Permanent only
+  for a confident false positive across all affected artifacts; mixed fate → temporary.
+- **Suppressions-only remediation** (the only change is the suppression file, no bumps) **on a
+  freshly-created step-4 branch** → **no branch and no PR**: a single commit directly on the
+  latest default branch, **never pushed automatically** and **with no ticket number in the
+  message**, handed back to the invoker as the skill's output (see step 7, Path A). If step 4
+  reused an existing ticket branch, suppressions-only takes Path B instead (never bypass an
+  existing branch).
+
+## Workflow
+
+### 1. Resolve the build
+Parse the URL to a plan/build key. If it ends in `/latest` or is a bare plan key,
+normalize to `{PLAN}-latest` and call `mcp__plugin_planetexpress_jira-tools__get_bamboo_build`
+to get the concrete build number. Confirm the build is Failed/red before proceeding. Auth or
+resolution failure → hard stop.
+
+### 2. Fetch the report
+The report artifact's **name and layout vary by plan** — do not hardcode either. Some plans
+publish it as `owasp dependency check report` with the report files under `reports/`; others
+(e.g. haupia / `SMASE-WDCS`) publish `Report DependencyCheckAggregate` with the files at the
+artifact root. Resolve by the **file**, not the artifact name.
+
+**Prefer the JSON report; fall back to HTML.** The JSON (`dependency-check-report.json`) is the
+richer, structured source and is parsed without regex; the HTML is the backup for plans whose
+CI run has not yet started publishing JSON.
+
+- `mcp__plugin_planetexpress_jira-tools__list_bamboo_artifacts <build_key>` → across all
+  directory artifacts, look for a file whose relative name ends in
+  `dependency-check-report.json`. If present, take its `path`; that is the report to fetch and
+  the parse in step 3 is JSON. If **no** `.json` is present, fall back to the file whose name
+  ends in `dependency-check-report.html` (prefer it over the `.xml`/`.csv`/`.sarif` siblings)
+  and the step-3 parse is HTML.
+- `mcp__plugin_planetexpress_jira-tools__get_bamboo_artifact` with the `build_key` positional
+  argument and `href=<that path>`. It returns as `localPath`. If **neither** a
+  `dependency-check-report.json` nor a `dependency-check-report.html` file is present in any
+  artifact → hard stop (report the artifacts found).
+
+### 3. Parse
+Pick the parser to match the file fetched in step 2:
+- **JSON** → `python "<plugin-root>/scripts/parse_json_report.py" <localPath> --out /tmp/cve-worklist.json`
+- **HTML** → `python "<plugin-root>/scripts/parse_report.py" <localPath> --out /tmp/cve-worklist.json`
+
+Both emit the **same worklist schema** (`findings` + `unparsed`), so the rest of the workflow
+is identical regardless of source. Read the worklist. `findings` empty **and** `unparsed` empty
+→ nothing to do; report and stop. Non-empty `unparsed` → hard stop (see Hard stops below)
+regardless of `findings`.
+
+Each finding carries the report's own advisory data — use it, don't discard it:
+- `description` — the advisory prose; often names the fixed release and the affected range
+  in words (e.g. "5.4.2 and earlier").
+- `affectedVersions` — the "Vulnerable Software & Versions" entries, e.g.
+  `cpe:...:httpcomponents_core:* versions up to (including) 5.4.2` — the affected boundary.
+- `references` — advisory URLs (NVD, vendor lists, and the Sonatype guide page, which
+  states the exact fixed version). Fetch these only if the description/affectedVersions
+  don't already answer the fixed-version question.
+- `includedBy` — **JSON parse only** (the HTML parser cannot supply it): the package URLs
+  that pull this dependency in. For a transitive finding this is the ancestor chain step 5.2
+  needs, so when it is present the `dependencyInsight` call there becomes a confirmation of a
+  known ancestor rather than a discovery. Absent (empty) on HTML-sourced worklists — fall back
+  to `dependencyInsight` as before.
+
+### 4. Prepare the fix branch (ticket-driven)
+Do this **before** editing anything — every bump, suppression, and the verify happen on this
+branch. The branch is chosen from the `ticket` parameter: reuse the ticket's existing branch if
+one is already in the repo, otherwise create a fresh one off the **latest default branch**.
+
+- **Determine the default branch:** do not assume `master`. Derive it from the remote:
+  `git symbolic-ref refs/remotes/origin/HEAD` (or `git remote show origin` if unset). Call it
+  `<default>`.
+- `git fetch origin`, then look for an **existing branch for this ticket** — local or remote —
+  matching the ticket key: `git branch -a --list "*<ticket>*"` (e.g. `*PX-1234*`). Resolve by
+  how many match:
+  - **Exactly one** → **reuse it as-is.** `git switch <branch>` (tracking the remote if it is
+    remote-only). Do **not** reset it onto `<default>` — commit on top of whatever work it
+    already carries. Record that the branch was **reused** (step 7 needs this).
+  - **None** → **create it off the latest tip:**
+    `git switch -c bugfix/<ticket>-handle-weekly-cves origin/<default>`. Record that the branch
+    was **newly created**.
+  - **More than one** → **hard stop** and report the candidates; do not guess which is the
+    ticket's branch.
+- If the working tree has unrelated uncommitted changes that would be carried across or block
+  the switch, STOP and report rather than discarding them.
+- This branch is the working base for fixing + verifying. Suppressions-only remediation goes to
+  Path A **only when this branch was newly created** — see step 7.
+
+### 5. Fix each finding (grouped by dependency)
+Detect the repo's declaration mechanism: version catalog (`gradle/libs.versions.toml`),
+direct `dependencies {}`, `constraints {}`, or `platform()`/BOM. **A bump is the preferred
+fix — but only when the latest available version actually clears the CVE.** Get the affected
+range / fixed version **from the report first** (the finding's `affectedVersions`,
+`description`, and `references` from step 3) — that is the first place to look; **web-search
+only when the report doesn't state it.** Then check the latest available version against that
+range: if the latest is outside the affected range (i.e. a fixed release exists), bump to it;
+if the latest version *still contains* the vulnerability, a bump is pointless — do not bump,
+fall through to suppression. Suppression is the last resort. Try the fixes in this order and
+stop at the first that works:
+
+1. **Direct dependency with an existing entry** — if the vulnerable dependency (or its GAV)
+   is itself declared and the **latest available version clears the CVE**, bump that entry to
+   the latest version. (Take the latest, not merely the lowest fixed release — but only if
+   the latest is in fact a fixed, non-affected version.)
+2. **Transitive dependency → bump the direct ancestor that pulls it in.** A vulnerable dep
+   with no direct declaration is often fixable without adding a new entry: find the
+   direct/parent dependency that brings it in and bump *that* existing declaration to its
+   latest available version — **provided that bump resolves the transitive dep to a version
+   that clears the CVE.**
+   - Identify the ancestor from the OWASP report's "included by" / `includedBy` data and
+     confirm with `./gradlew dependencyInsight --dependency <group:artifact>` (add
+     `--configuration <name>` if needed). This shows the resolution path from a declared
+     dependency down to the vulnerable one.
+   - Bump the declared ancestor, then re-run `dependencyInsight` (or rely on step 6's
+     verify) to confirm the transitive version is now a CVE-clearing one. If the ancestor's
+     latest still pulls the vulnerable version, this path does not clear it — fall through.
+3. **Existing constraint / BOM / platform entry** — if the repo already pins the version via
+   a `constraints {}` block or a `platform()`/BOM, and a CVE-clearing version exists, update
+   that existing pin to the latest available (clearing) version. (Only update an entry that
+   already exists — see the hard rule below.)
+4. **Suppress — only when no existing declaration can be bumped to a CVE-clearing version**
+   (nothing to update, no released version clears the CVE, or the only available fix would
+   require a new entry). A **false positive** is also fixed by a bump when the latest version
+   makes the finding go away; suppress a false positive only when no clearing bump exists.
+   - Discover the suppression file per `references/suppression.md`. Not found → STOP.
+   - **One block per CVE.** Before writing, check whether the CVE is already suppressed (in
+     the file or in a block you've added this run). If so, add the new affected `<packageUrl>`
+     to that existing block instead of creating a second one — never emit the same `<cve>`
+     twice. The same CVE across several artifacts (e.g. `httpcore` 4.x and `httpcore5`) is one
+     block with repeated `--pkgurl`.
+   - **When in doubt between permanent and temporary, choose temporary** (default, 2 months).
+     Pass `--permanent` only for a confident false positive across *all* affected artifacts;
+     if a CVE is FP for one artifact but real-yet-unfixable for another, the single block is
+     temporary.
+   - Generate the block with `python "<plugin-root>/scripts/gen_suppression.py"` (repeat
+     `--pkgurl` for each affected artifact; `--permanent` only per the rule above, else the
+     temporary default) and insert it into the file's `<suppressions>` root.
+
+**Hard rule:** never *add* a brand-new direct declaration (or a new constraint) for a
+transitive dependency just to pin it. Only *update entries that already exist*. If the only
+way to pin the fixed version would be a new entry, that path is unavailable — fall through to
+suppression (step 5.4).
+
+After any bump, remove any now-obsolete `<suppress>` entry for a CVE no longer reported.
+
+**Compile check after bumps.** A latest-version bump can break the build. After applying all
+bumps (and before the step-6 verify), confirm the project still **compiles — main and test
+sources**: `./gradlew classes testClasses` (this compiles both without running tests). Fix
+any compilation errors the bump introduced (API changes, moved packages, renamed methods).
+**Do not run the tests** — CI runs them later; you only guarantee it compiles. If compilation
+cannot be made to pass, STOP and report (hard stop) rather than pushing a broken build.
+
+Read `references/suppression.md` before writing any suppression.
+
+### 6. Verify
+Run `./gradlew dependencyCheckAggregate` in the repo — append `-DuseSonatype` if the
+`useSonatype` parameter was specified (`./gradlew dependencyCheckAggregate -DuseSonatype`),
+otherwise run it without the flag. Locate the freshly written report under `build/reports/`
+and re-parse it with the matching parser: **prefer `dependency-check-report.json` via
+`parse_json_report.py`**, falling back to `dependency-check-report.html` via `parse_report.py`
+only if the project does not emit JSON locally. Confirm **0** findings
+>= 7.0 remain **and** `unparsed` is empty. If residuals remain, loop back to step 5. Non-empty
+`unparsed` at this step is also a hard stop — never treat it as convergence. If it cannot
+converge or Gradle fails → STOP and report; do not push. Dependency-check's own validation of
+the suppression file (it fails the build on malformed suppression XML) is the guardrail
+against a corrupt suppression file reaching this step.
+
+### 7. Commit — fork on what changed
+
+First decide which path applies by inspecting exactly what step 5 changed:
+
+**Path A — suppressions-only.** The *only* changed file is the suppression file (no
+dependency-declaration edits, no code, no other files at all) **and the step-4 branch was
+newly created** (not a reused ticket branch). Then **do not** open a branch or PR — produce a
+single local commit on the latest default branch and hand it back:
+
+- Move onto the latest default branch, carrying the suppression edit: `git switch <default>`,
+  then `git merge --ff-only origin/<default>` to bring it to the latest tip. If local
+  `<default>` cannot fast-forward (it has diverged), STOP and report — do not commit on a
+  stale or diverged base.
+- The freshly-created fix branch from step 4 has no commits; delete it:
+  `git branch -D bugfix/<ticket>-handle-weekly-cves` (use the actual branch name).
+- Stage **only** the suppression file (exact path; never `git add -A`/`-u`).
+- Commit with a message describing the suppression(s) that **contains NO ticket number** —
+  no `PX-…`, `HP-…`, or any `[A-Z]+-\d+` token anywhere in subject or body. For example:
+  `chore(security): suppress <CVE-ids> dependency-check findings`.
+- **Do not push.** Skip steps 8 (release notes) and 9 (PR).
+- **Output of the skill = this commit.** Show the invoker the commit SHA, its message, and the
+  suppression diff, and stop. Pushing is the invoker's decision.
+
+**Path B — anything else** (any dependency bump, any change beyond the suppression file, **or**
+suppressions-only on a **reused** ticket branch — never delete or bypass an existing ticket
+branch). The fix branch already exists from step 4 — commit onto it:
+
+- Stage **only** the specific files edited in step 5 — the dependency-declaration file(s)
+  (e.g. `gradle/libs.versions.toml`, `build.gradle[.kts]`) and, if touched, the suppression
+  file, by exact path: `git add <dependency-file-path> <suppression-file-path>`. **Never**
+  `git add -A` or `git add -u` — this skill pushes and opens a PR autonomously, and sweeping
+  unrelated working-tree changes into that commit is not acceptable.
+- Commit: `git commit -m "fix(<repo>): remediate CVSS>=7 dependency-check findings"`. Do
+  **not** push yet — release notes (step 8) are derived from committed changes and get
+  **amended into this same commit**, so it must not be pushed until step 8 completes.
+
+### 8. Release notes
+*(Path B only — skipped entirely in the suppressions-only Path A, which ends at step 7.)*
+
+Invoke the `write-releasenotes` skill (via the Skill tool) with **pre-approval** so it writes
+without a confirmation gate — this skill runs autonomously (e.g. "write and apply the release
+notes for this CVE remediation, no need to confirm"). `write-releasenotes` reads the **committed**
+changes on the branch (hence step 7 commits first), derives the ticket key/type **from the
+branch name** (which carries `<ticket>`), scaffolds per-language `.adoc` entries via the
+project's `create*` Gradle task when missing, and fills them in house style.
+
+- If `write-releasenotes` reports **not applicable** (no releasenotes subproject and no `create*`
+  Gradle tasks), that is a notice, not an error — proceed to step 9 and put the CVE summary
+  in the PR body instead.
+- If it wrote or updated notes: stage **only** the generated/updated `.adoc` files and any
+  version file the `create*` task bumped, by exact path (same never-`git add -A/-u` rule as
+  step 7), then **amend them into the step-7 commit**: `git commit --amend --no-edit`. This
+  keeps the remediation and its release notes as a single commit. (Safe because the branch
+  has not been pushed yet — no force-push needed.)
+
+Then push the branch (single commit).
+
+### 9. PR
+*(Path B only — the suppressions-only Path A produces a local commit and no PR.)*
+
+The Bitbucket project/repo slugs are derived from the repo's `origin` remote URL (not asked
+of the user). If no open PR exists for the branch, create one with
+`mcp__plugin_planetexpress_jira-tools__create_bitbucket_pr`, targeting the default branch
+(`<default>` from step 4). Body: a per-CVE summary — CVE id, score, and whether it was bumped
+(old→new version) or suppressed (temp until <date> / permanent, with reason).
+
+## Hard stops (abort, report, never push)
+
+| Situation | Behaviour |
+|---|---|
+| Invoked without a `ticket` | Report and ask for the JIRA key before doing anything |
+| More than one existing branch matches the ticket key (step 4) | Report the candidates and stop; do not guess the branch |
+| Bamboo auth / URL resolution failure | Report and stop before fetching anything |
+| Neither a `dependency-check-report.json` nor `.html` file in any build artifact (step 2) | Report the artifacts found and stop |
+| Suppression needed but no suppression file found | Report and stop; never create one |
+| Bumps break compilation (`classes`/`testClasses`) and can't be fixed | Report and stop; do not push a build that doesn't compile |
+| Gradle verify fails or residual >= 7.0 findings remain | Report and stop; do not push |
+| Either parser returns any non-empty `unparsed` entries (initial parse or verify) | Report and stop; never silently proceed as if 0 findings |
+| Suppressions-only path (7A) but local default branch can't fast-forward to `origin/<default>` | Report and stop; don't commit on a diverged/stale base |
+
+## Known limitations
+
+- Every active finding is classified by **severity** — a numeric CVSS score, or, for scoreless
+  advisories (common for JS/NPM), the qualitative band. Both parsers apply the identical rule
+  (`parse_json_report.py` from the typed `cvssv2/v3/v4` and `severity` fields — taking the worst
+  numeric across the CVSS versions present; `parse_report.py` by scraping the HTML). Then:
+  - **below HIGH** (score < 7.0, or a low/medium/none band) → **excluded** — out of scope, does
+    not redden the build. A medium/low unscored advisory is *not* a hard stop.
+  - **at/above HIGH & a CVE id** → a normal `findings` entry (a scoreless HIGH/CRITICAL carries
+    `score: null` with the band in `severity`).
+  - **at/above HIGH & no CVE id** (e.g. a HIGH/CRITICAL `GHSA-*`) → `unparsed`. This skill only
+    remediates CVEs, so it cannot fix these — routing them to `unparsed` (a hard stop) prevents
+    converging to "0 findings" on a build that is red because of one. Such a build stops for
+    human triage rather than being reported as fixed. Identifier (`cpe`) buttons, present on
+    every dependency, are always ignored.
+- The `unparsed` bucket is a fail-safe signal, not noise: an at/above-HIGH non-CVE finding, or
+  an active finding whose severity could be determined **neither** numerically **nor** by band.
+  Treat any non-empty `unparsed` as a hard stop, identical in severity to the other hard stops
+  above — never converge or report success while it is non-empty. (`unparsed` is deduplicated by
+  advisory id + file, so the same finding on the same artifact never appears twice.)
+- Malformed suppression XML is guarded at the verify step: `dependencyCheckAggregate` itself
+  validates the suppression file and fails the build if it's invalid.
+
+## Out of scope
+
+- Creating a suppression file that doesn't exist.
+- Adding new declarations for transitive-only dependencies (suppress instead).
+- Merging the PR — open it and stop; merge is the user's call.

package/teams/firstspirit-caas/skills/handle-red-cve-plan/references/suppression.md

@@ -0,0 +1,79 @@
+# Suppression policy & syntax (dependency-check)
+
+## Finding the suppression file (auto-discover, never create)
+1. Read the repo's Gradle config for the configured path:
+   `dependencyCheck { suppressionFile "..." }` or `suppressionFiles = [...]`
+   (check `build.gradle`, `build.gradle.kts`, and any `gradle/*.gradle`).
+2. If not configured there, glob `*suppress*.xml` — repo root first, then repo-wide.
+3. **If no file is found, STOP and report.** Do not create one. Do not suppress.
+
+## When to suppress vs bump
+- Prefer a version bump of an **existing** declaration. Never add a new entry for a
+  transitive dependency.
+- Suppress only when: no existing declaration to bump, no patched version exists, or the
+  finding is a false positive.
+
+## One suppression per CVE — never suppress the same CVE twice
+- A given CVE id must appear in **at most one** `<suppress>` block across the entire file.
+  Before writing a suppression, scan the file (and any blocks you're adding this run) for the
+  CVE. If it's already covered, **do not add a second block** — extend the existing one.
+- The same CVE often affects **several declared artifacts** (e.g. `httpcore` 4.x and
+  `httpcore5` 5.x). Suppress it **once**, in a single block that lists every affected
+  `<packageUrl>` (dependency-check allows unbounded `<packageUrl>` in one `<suppress>`). Do
+  **not** emit one block per artifact for the same CVE.
+- `gen_suppression.py` takes repeated `--pkgurl` for exactly this — one block, many packages.
+
+## Permanent vs temporary
+- **When in doubt, choose temporary.** A temporary suppression expires and re-flags; a wrong
+  permanent one hides a real CVE forever. Only go permanent when it is *confidently* a pure
+  false positive across **all** affected artifacts.
+- If a CVE is a false positive for one artifact but a real-yet-unfixable finding for another
+  (mixed fate) → the single block is **temporary** (the tie-break rule above).
+- **False positive (confident, all artifacts) → permanent**: omit `until`. Notes state
+  concisely why it does not apply (e.g. CPE mismatch, unreachable code path).
+- **Otherwise → temporary**: `until="<today + 2 months>Z"` (the default; 2 months).
+- One `<suppress>` block may cover multiple `<cve>` entries under a single notes summary.
+
+## Notes content — concise technical reason only
+The `<notes>` text states **why the CVE is suppressed** and nothing else. Keep it to the
+technical fact (CPE mismatch, unreachable code path, no patched release yet, patch not yet
+scheduled). Then stop.
+
+- **Never mention a JIRA ticket** — no `PX-…`, `HP-…`, or any `[A-Z]+-\d+` key. The `ticket`
+  parameter drives the fix branch; it does **not** track the suppression, so "Tracked by PX-…"
+  is simply false.
+- **No boilerplate.** Do not append filler like "Expires; re-flags if unresolved" or "Added to
+  unblock builds" — the `until` attribute already encodes expiry; the sentence adds nothing.
+
+## Syntax
+```xml
+<suppress until="2026-09-13Z">
+    <notes><![CDATA[No patched 4.x release; HTTP/2 HPACK decoder path does not exist in the 4.x line.]]></notes>
+    <packageUrl regex="true">pkg:maven/org\.apache\.httpcomponents/httpcore@.*</packageUrl>
+    <packageUrl regex="true">pkg:maven/org\.apache\.httpcomponents\.core5/httpcore5@.*</packageUrl>
+    <cve>CVE-2026-54399</cve>
+    <cve>CVE-2026-54428</cve>
+</suppress>
+```
+
+Generate blocks with `scripts/gen_suppression.py` — it handles the purl→regex escaping and
+the today+2-months default date, and takes **repeated `--pkgurl`** to list every affected
+artifact in one block:
+
+```
+python "<plugin-root>/scripts/gen_suppression.py" \
+  --pkgurl pkg:maven/org.apache.httpcomponents/httpcore@4.4.16 \
+  --pkgurl pkg:maven/org.apache.httpcomponents.core5/httpcore5@5.4.2 \
+  --cve CVE-2026-54399 --cve CVE-2026-54428 --notes "..."
+```
+
+Insert new blocks inside the root `<suppressions>` element of the discovered file. The script
+emits `<suppress>` at column 0 with 4-space child indent; when inserting, **re-indent the whole
+block to match the surrounding blocks** (typically `<suppress>` one level in, children one level
+deeper) so the file stays consistent — dependency-check ignores the whitespace, but a mismatched
+block is noise in review. Omit `--until` for the temporary default (2 months); pass `--permanent`
+only for a confident, all-artifacts false positive.
+
+## Removing obsolete suppressions
+After a successful bump, if an existing `<suppress>` entry now targets a CVE that no
+longer appears in the report, remove that entry.

package/teams/firstspirit-caas/skills/handle-red-cve-plan/scripts/gen_suppression.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Generate an OWASP Dependency-Check <suppress> block for a finding.
+
+Temporary suppression: pass --until YYYY-MM-DD (or let the skill compute
+today + 2 months). Permanent (false positive): omit --until.
+"""
+import argparse
+import datetime
+import re
+import sys
+import textwrap
+
+NOTE_WIDTH = 100
+
+
+def pkgurl_to_regex(package_url: str) -> str:
+    """Escape a Maven purl and match any version: `...@4.4.16` -> `...@.*`.
+
+    re.escape() does not escape `/` or `:` on Python >= 3.7, so no further
+    unescaping of those characters is needed after re.escape().
+    """
+    base = package_url.split("@", 1)[0]
+    return re.escape(base) + "@.*"
+
+
+def default_until(today: datetime.date, months: int = 2) -> str:
+    month = today.month - 1 + months
+    year = today.year + month // 12
+    month = month % 12 + 1
+    day = min(today.day, 28)
+    return f"{year:04d}-{month:02d}-{day:02d}"
+
+
+def wrap_notes(notes: str) -> list:
+    """Wrap notes for readability inside the CDATA. Breaks on whitespace only
+    (break_long_words / break_on_hyphens off) so CVE ids and version strings
+    like `CVE-2026-54428` or `5.5-beta1` are never split. Caller-supplied
+    newlines are honoured as paragraph boundaries. Returns physical lines."""
+    lines = []
+    for para in notes.split("\n"):
+        if not para.strip():
+            lines.append("")
+            continue
+        lines.extend(textwrap.wrap(
+            para, width=NOTE_WIDTH,
+            break_long_words=False, break_on_hyphens=False))
+    return lines
+
+
+def suppress_block(package_urls, cves: list, notes: str, until) -> str:
+    """One <suppress> block. `package_urls` is a single purl or a list — the
+    same CVE affecting several declared artifacts is suppressed ONCE, in one
+    block listing every affected packageUrl (dependency-check allows unbounded
+    <packageUrl>). Never emit a separate block per artifact for the same CVE."""
+    if isinstance(package_urls, str):
+        package_urls = [package_urls]
+    open_tag = f'<suppress until="{until}Z">' if until else "<suppress>"
+    # One level of child indent, matching the dependency-check file's 4-space
+    # convention. The block is emitted with <suppress> at column 0; the skill
+    # re-indents the whole block by the file's base indent on insertion.
+    ind = "    "
+    pkg_lines = "\n".join(
+        f'{ind}<packageUrl regex="true">{pkgurl_to_regex(p)}</packageUrl>'
+        for p in package_urls
+    )
+    cve_lines = "\n".join(f"{ind}<cve>{c}</cve>" for c in cves)
+    # A literal "]]>" inside notes would close the CDATA section early and
+    # corrupt the XML. Split it across two CDATA sections instead.
+    safe_notes = notes.replace("]]>", "]]]]><![CDATA[>")
+    note_lines = wrap_notes(safe_notes)
+    # Short notes stay on one line; anything that wraps (or carries explicit
+    # line breaks) is laid out on its own indented lines for readability.
+    if len(note_lines) <= 1:
+        inner = note_lines[0] if note_lines else ""
+        notes_el = f"{ind}<notes><![CDATA[{inner}]]></notes>"
+    else:
+        body = "\n".join(f"{ind}{ln}".rstrip() for ln in note_lines)
+        notes_el = f"{ind}<notes><![CDATA[\n{body}\n{ind}]]></notes>"
+    return (
+        f"{open_tag}\n"
+        f"{notes_el}\n"
+        f"{pkg_lines}\n"
+        f"{cve_lines}\n"
+        f"</suppress>"
+    )
+
+
+def main(argv):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--pkgurl", action="append", required=True,
+                    help="Affected package purl; repeat to cover the same CVE across "
+                         "multiple declared artifacts in one block")
+    ap.add_argument("--cve", action="append", required=True)
+    ap.add_argument("--notes", required=True)
+    group = ap.add_mutually_exclusive_group()
+    group.add_argument("--until", help="YYYY-MM-DD; omit for the default (today + 2 months)")
+    group.add_argument("--permanent", action="store_true",
+                        help="False-positive only: permanent suppression, no 'until'")
+    ns = ap.parse_args(argv)
+
+    # Policy: false positive -> permanent (no until); everything else ->
+    # temporary (today + 2 months). Omitting --until must NEVER silently
+    # produce a permanent suppression.
+    if ns.permanent:
+        until = None
+    elif ns.until:
+        until = ns.until
+    else:
+        until = default_until(datetime.date.today())
+
+    print(suppress_block(ns.pkgurl, ns.cve, ns.notes, until))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))