fix: address security scanners follow-up items (#180)

.github/workflows/security-scanners.yml

@@ -304,7 +304,7 @@ jobs:
     runs-on: ubuntu-latest
     services:
       clamav:
-        image: clamav/clamav@sha256:bf876a415b7ff77b9305b1de087e6d16833d170931581b01404e8761cb0dc87c
+        image: clamav/clamav@sha256:60ef5fee072ff46f91ca63ba09f36597e41693977600902d21df9d0d97f640e4
         ports:
           - 127.0.0.1:3310:3310
         options: >-
@@ -319,7 +319,7 @@ jobs:
       - name: Install clamdscan client
         run: |
           sudo apt-get update || true
-          sudo rm -f /var/lib/man-db/auto-update
+          sudo rm -f /var/lib/man-db/auto-update  # prevent man-db auto-update from blocking apt-get
           sudo apt-get install -y --no-install-recommends clamdscan
           sudo mkdir -p /etc/clamav
           cat << EOF | sudo tee /etc/clamav/clamd.conf

docs/ADMINISTRATIVE_GUIDE.md

@@ -246,7 +246,7 @@ flowchart TD
 | **Triggers**    | `push` to `main`, `push` tags `v*`, `pull_request` to `main` (label-gated, path-filtered), `workflow_dispatch` (dispatched by `tag-on-merge.yml` or manual — select a tag in the UI to trigger a release build) |
 | **Environment** | `codebuild` (protected, manual approval)                                                                                                                                                                        |
 | **Runner**      | `ubuntu-latest`                                                                                                                                                                                                 |
-| **Concurrency** | Groups by `{workflow}-{ref}`, cancels in-progress                                                                                                                                                               |
+| **Concurrency** | Groups by `{workflow}-{event_name}-{ref}`, cancels in-progress                                                                                                                                                  |
 
 **Purpose:** Runs an AWS CodeBuild project, downloads primary and secondary artifacts from S3, caches them in GitHub Actions cache, uploads them as workflow artifacts, and (when triggered from a `v*` tag) attaches them to the GitHub Release.
 
@@ -351,7 +351,7 @@ This job runs when the `rules` label is applied, immediately removing the remind
 | **Triggers**    | `pull_request_target` to `main` (edited, labeled, opened, ready_for_review, reopened, synchronize, unlabeled); `merge_group` (checks_requested) |
 | **Environment** | *(none)*                                                                                                                                        |
 | **Runner**      | `ubuntu-latest`                                                                                                                                 |
-| **Concurrency** | Groups by `{workflow}-{ref}`, cancels in-progress                                                                                               |
+| **Concurrency** | Groups by `{workflow}-{event_name}-{ref}`, cancels in-progress                                                                                  |
 
 **Purpose:** Validates pull requests before merge. Enforces conventional commit PR titles, the contributor acknowledgment statement, merge-halt controls, and a do-not-merge label gate. Also runs as a merge queue check.
 
@@ -422,7 +422,7 @@ Only runs for `pull_request` and `pull_request_target` events. Skipped for bot a
 | **Triggers**    | `push` to `main`, `pull_request` to `main`, `schedule` (daily 03:47 UTC), `workflow_dispatch`  |
 | **Environment** | *(none)*                                                                                       |
 | **Runner**      | `ubuntu-latest`                                                                                |
-| **Concurrency** | Groups by `{workflow}-{ref}`, cancels in-progress                                              |
+| **Concurrency** | Groups by `{workflow}-{event_name}-{ref}`, cancels in-progress                                 |
 
 **Purpose:** Runs six independent security scanners in parallel to detect secrets, vulnerabilities, misconfigurations, and malware. All HIGH and CRITICAL findings must be remediated or have a documented risk acceptance before merge (see [Security Finding Requirements](#security-finding-requirements)).
 
@@ -665,13 +665,63 @@ These rules are used by `git-cliff --bumped-version` when auto-determining the n
 
 All scanner tools, GitHub Actions, and container images in the workflow files are pinned to specific versions or commit SHAs. This prevents supply-chain attacks and ensures reproducible builds, but requires periodic maintenance to stay current with security patches and new features.
 
-Pinned versions should be reviewed and updated **at least quarterly**.
+Pinned versions should be reviewed and updated **at least quarterly**, with the exception of the ClamAV container image which should be updated **monthly** (see below).
 
-<!-- TODO: Add step-by-step instructions for updating pinned versions, including:
-  - How to check for latest versions of each scanner tool (PyPI, GitHub releases, Docker Hub)
-  - How to look up commit SHAs for GitHub Actions (gh api repos/OWNER/REPO/git/ref/tags/TAG)
-  - How to look up Docker image digests (docker manifest inspect)
-  - How to verify the update works (run the workflow on a feature branch)
-  - How to handle breaking changes in scanner tool upgrades
-  - Consider automating this with Dependabot or Renovate
--->
+### Update cadence
+
+| Component                     | Cadence   | Reason                                                                                        |
+| ----------------------------- | --------- | --------------------------------------------------------------------------------------------- |
+| GitHub Actions (SHA-pinned)   | Quarterly | Security patches and new features; low churn                                                  |
+| Scanner tool versions         | Quarterly | New rules and bug fixes; breaking changes are rare                                            |
+| ClamAV container image digest | Monthly   | Pinning the digest also freezes the malware signature database; stale signatures miss threats |
+
+### How to update GitHub Actions
+
+Look up the commit SHA for a new tag:
+
+```bash
+gh api repos/OWNER/REPO/git/ref/tags/TAG --jq '.object.sha'
+```
+
+For tags pointing to annotated tag objects (not commits directly), dereference:
+
+```bash
+gh api repos/OWNER/REPO/git/ref/tags/TAG --jq '.object.sha' | xargs -I{} gh api repos/OWNER/REPO/git/tags/{} --jq '.object.sha'
+```
+
+Update the SHA in the workflow file and keep the version comment in sync (e.g., `# v6.0.2`).
+
+### How to update the ClamAV image digest
+
+The ClamAV service container in `security-scanners.yml` is pinned to a `sha256` digest for supply-chain safety. This also freezes the virus signature database, so the digest should be updated **monthly**.
+
+Get the current `linux/amd64` digest:
+
+```bash
+docker buildx imagetools inspect clamav/clamav:latest
+```
+
+Look for the `linux/amd64` manifest digest (starts with `sha256:`). Update the `image:` line in the `clamav` service definition:
+
+```yaml
+image: clamav/clamav@sha256:<new-digest>
+```
+
+### How to update scanner tool versions
+
+Check latest versions from their respective sources:
+
+- **Bandit**: `pip index versions bandit` or [PyPI](https://pypi.org/project/bandit/)
+- **Semgrep**: `pip index versions semgrep` or [PyPI](https://pypi.org/project/semgrep/)
+- **Grype**: [GitHub releases](https://github.com/anchore/grype/releases)
+- **Gitleaks**: [GitHub releases](https://github.com/gitleaks/gitleaks/releases)
+- **Checkov**: `pip index versions checkov` or [PyPI](https://pypi.org/project/checkov/)
+
+### Verification
+
+After updating any pinned version:
+
+1. Push the change to a feature branch
+2. Verify the `security-scanners.yml` workflow runs successfully
+3. Check that scanner output (SARIF uploads, artifacts) is produced correctly
+4. Watch for new findings that may be introduced by updated rule sets