Unique-AG/ai / .claude/skills/security-maintenance
security-maintenance
FlaggedTriage and fix Dependabot alerts, CodeQL findings and Trivy image scan alerts (search-proxy image CVEs, uv audit findings) in the ai repository. Use when the user asks to address security vulnerabilities, fix Dependabot alerts, resolve CodeQL or code scanning alerts, handle a failed Trivy image scan or uv audit run, or do security maintenance.
What I do
I drive the security maintenance workflow for the ai repository to keep both dashboards at zero:
- Dependabot — https://github.com/Unique-AG/ai/security/dependabot
- Code scanning — https://github.com/Unique-AG/ai/security/code-scanning. It holds CodeQL findings (code) and Trivy image scan alerts (dependency and OS package CVEs in the search-proxy image). They need different fixes, see below.
When to use me
- "fix dependabot", "security maintenance", "fix vulnerabilities", "dependabot alerts", "CodeQL findings", "code scanning alert", "Trivy image scan failed", "uv audit"
- Periodic security maintenance sessions
- After Dependabot auto-opens
uvPRs (we do not merge those directly)
Release model — read first
Versions and changelogs are fully owned by release-please (config: release-please-config.json, manifest: .release-please-manifest.json). CI enforces this via .github/scripts/check-no-manual-release.sh, which fails any PR that modifies:
- any
CHANGELOG.md .release-please-manifest.json- the
version = "..."line in anypyproject.toml
Because of that:
- Never edit
CHANGELOG.mdor bumpversionby hand. Do not use therelease-processskill to justify manual edits in security PRs — that skill documents automation, not hand bumps. - Drive the next release entries through conventional commit subjects (see
git-conventional-commits). For Dependabot/CodeQL fixes usefix(<scope>): ...so release-please groups them under "Bug Fixes". Usechore(deps): ...only for risk-free dep bumps you don't want to surface in user-facing notes (it's hidden in the changelog). - One commit per PR is fine; release-please derives bumps per workspace package from the commit subject + changed paths.
Dependabot workflow
Never merge Dependabot uv auto-PRs. Use constraint-dependencies in the root pyproject.toml instead. The docker and github-actions group PRs are different: review and merge them normally. The docker entry in .github/dependabot.yml ignores python minor bumps and this repo's own image tags (release-please owns those).
- List alerts — see gh commands reference. Always paginate (
gh api --paginate); the Dependabot endpoint is cursor-paged and a singleper_page=100call silently caps at 100. - Find fix version from the alert JSON.
- Add/bump
constraint-dependenciesin rootpyproject.tomlwith"<package>>=<fixed-version>". - Handle
exclude-newerconflicts — if the fix version is within the 3-day rolling window, add anexclude-newer-packagetimestamp (day after latest PyPI upload). See exclude-newer reference. - Prune stale
exclude-newer-packageentries — remove any timestamp older than 3 days (redundant, global window already covers it). Keep= falseentries. - Relock —
uv lock --refresh, with a uv that satisfiesrequired-versionin the root[tool.uv](it refuses to run otherwise; upgrade withbrew upgrade uv). If resolution fails, bump the timestamp and retry. - Branch and commit — branch
fix/dependabot-<pkg>-<ver>(single CVE) orfix/security-<date>(batch). Subject:fix(deps): bump <pkg> to >=<ver> (GHSA-xxxx)orfix(security): batch dependabot fixes <date>. Do not touchCHANGELOG.mdor anyversion = ...field — release-please will pick the commit up on the next standing Release PR. - Open PR, then close Dependabot auto-PRs after merge (they won't auto-close because we ship via constraints, not by merging their lockfile bump).
CodeQL workflow
- List findings — see gh commands reference. Paginate the same way.
- Read the rule and flagged code in context.
- Fix the code — see common CodeQL patterns.
- Branch and PR — same shape as Dependabot. Use
fix(<package-or-area>): <what was hardened> (CodeQL <rule-id>). Again: no manual changelog/version edits.
Trivy image alerts (code scanning)
These alerts sit next to CodeQL in the code scanning dashboard but are not code issues, so do not use the CodeQL workflow. Recognise them by tool.name == "Trivy" and a category like trivy-image/search_proxy (a fresh build of main) or trivy-image-release/search_proxy (a published image). They come from the [Security] Trivy Image Scan workflow, which runs every Monday at 06:00 UTC and on demand, and fails on any fixable CRITICAL or HIGH finding.
- List and read: see gh commands reference. The alert message has the package, installed version and fixed version.
- Route by
location.path:app/.venv/lib/python3.12/site-packages/<pkg>-<version>.dist-info/METADATAis a Python dependency, often transitive. Fix it with the Dependabot workflow steps 3 to 8: bumpconstraint-dependenciesto the fixed version, relock,fix(security): ...PR.usr/local/lib/python*/site-packages/<pkg>...(for examplepip) would be a Python package from the base image, outside the virtual environment. Do not add a constraint, andapt-get upgradedoes not update it. Bump the base image digest in the Dockerfile.- A
location.paththat is just the image name (for exampleunique-ag/ai/search-proxy) is a Debian package in the image, and the message names it (zlib1g, ...). Do not add a constraint. A rebuild picks it up throughapt-get upgradein the runtime stage of the Dockerfile; if that is not enough, bump the base image digest.
- No manual dismiss. The alert closes when the next scan on
mainwith the same category no longer reports it. After the fix merges, re-run the scan onmain(see the gh commands reference) or wait for Monday. That closestrivy-image/alerts only. Atrivy-image-release/alert stays open until a fixed image is published and thesource=releasescan runs. - Released images. The scan summary shows the days until the next scheduled release. Use the
hotfix-backportskill only when that is more than about 3 days away, and a person decides.
uv audit
[Security] uv Audit runs uv audit on the root uv.lock every Monday and on PRs that touch the lock (report only on PRs). Locally: uv audit --preview-features audit-command --frozen. It finds lock vulnerabilities that Dependabot may not have raised yet. Fix them with the Dependabot workflow.
Batch session
- List all Dependabot alerts, CodeQL findings and Trivy image alerts (paginated), and run
uv audit. - Prune stale
exclude-newer-packageentries. - Fix Dependabot alerts, Trivy alerts on Python packages and
uv auditfindings (mechanical: constraints + relock). - Fix CodeQL findings (code changes).
- Single branch for related fixes, separate branches for unrelated areas.
- Commit with
fix(...)subjects so release-please attributes bumps to the right workspace package(s) on the next Release PR. - Create PR(s), let CI run
check-no-manual-release.sh, then close any resolved Dependabotuvauto-PRs after merge. Re-run the Trivy image scan onmainto closetrivy-image/alerts;trivy-image-release/alerts need a release scan after the fix ships.
Tips
- Never merge Dependabot
uvauto-PRs —constraint-dependenciespersists across relocks; auto-PRs only edituv.lock. - Never touch
CHANGELOG.md,.release-please-manifest.json, orversion = ...—check-no-manual-release.shwill block the PR. - Use
fix(...)notchore(deps): ...when you want the fix to appear in user-facing release notes;choreis hidden by the changelog config. - Round timestamps up — day after latest artifact upload (
uvuses strict<on individual wheel upload times). - Batch when possible — one PR reduces noise; release-please still attributes per workspace package.
- Prune stale timestamps — entries older than the 3-day window are redundant.
- Check both dashboards — Dependabot and code scanning are independent, and code scanning holds both CodeQL and Trivy alerts.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |