ci(security): supply-chain hardening — SHA-pin Actions, least-privilege perms, Dependabot

Cordyceps-class workflow hardening following the malicious-PR / supply-chain
disclosure. The high-risk vectors were already absent (no pull_request_target,
no untrusted input in shell, no PR->publish artifact flow); this closes the rest:

- Pin every third-party Action to an immutable commit SHA (with version comments).
- Least-privilege: top-level `permissions: contents: read`; only publish escalates
  (id-token: write for OIDC). audit.yml is pull_request-triggered, so it stays
  non-privileged by design.
- Add .github/dependabot.yml (pip + github-actions) for dependency + Action-pin
  monitoring.
- SECURITY.md: add "How We Secure Our Own Build Pipeline" — a verifiable,
  customer-facing statement of the posture (Trusted Publishing, attestations,
  SHA-pinned Actions, least-privilege, hash-pinned deps).

Already in place: PyPI Trusted Publishing (OIDC), Sigstore attestations,
hash-pinned requirements.lock + pip-audit --require-hashes --strict.

Author: Oracles Technologies LLC

.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+
+# Automated dependency + Action monitoring for the public Guardian SDK. Treat
+# high-severity alerts as blocking. The github-actions updater also bumps the
+# commit-SHA pins in the workflows so they stay current without losing
+# immutability.
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels: ["dependencies", "security"]
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels: ["dependencies", "security"]

.github/workflows/audit.yml

@@ -13,16 +13,22 @@ on:
     - cron: "0 9 * * 1"   # every Monday at 09:00 UTC
   workflow_dispatch:
 
+# Read-only — this workflow only audits + uploads a report artifact. Note it is
+# also pull_request-triggered, so it MUST stay non-privileged (no secrets, no
+# write perms, no consumption of its artifact by a privileged workflow).
+permissions:
+  contents: read
+
 jobs:
   audit:
     name: pip-audit
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: "3.11"
 
@@ -53,7 +59,7 @@ jobs:
 
       - name: Upload audit report
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
         with:
           name: audit-report
           path: audit-report.md

.github/workflows/publish.yml

@@ -6,6 +6,10 @@ on:
       - "v*"          # trigger on any version tag, e.g. v1.8.1
   workflow_dispatch:  # allow manual trigger from the Actions tab
 
+# Least-privilege default; only the publish job escalates (OIDC id-token).
+permissions:
+  contents: read
+
 jobs:
   # ──────────────────────────────────────────────────────────────────────────
   # Build the source distribution and wheel in an isolated environment.
@@ -17,12 +21,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           fetch-depth: 0   # full history so setuptools-scm / version attrs work
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
         with:
           python-version: "3.11"
 
@@ -37,7 +41,7 @@ jobs:
         run: python -m build
 
       - name: Upload dist artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
         with:
           name: dist
           path: dist/
@@ -48,6 +52,9 @@ jobs:
   # stored as a secret.  The id-token: write permission is required for GitHub
   # to mint the OIDC token that Sigstore uses to attest the release.
   #
+  # Enable a required-reviewer protection rule on the `pypi` environment so a
+  # human approves every publish even if CI is compromised.
+  #
   # Sigstore attestations are generated automatically by pypa/gh-action-pypi-publish
   # when attestations: true is set.  Users can verify with:
   #   pip install pypi-attestations
@@ -67,12 +74,12 @@ jobs:
 
     steps:
       - name: Download dist artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
         with:
           name: dist
           path: dist/
 
       - name: Publish to PyPI (with Sigstore attestations)
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1
         with:
           attestations: true

SECURITY.md

@@ -176,18 +176,28 @@ within 48 hours and coordinate a responsible disclosure timeline.
 
 ---
 
-## Existing Supply Chain Protections
+## How We Secure Our Own Build Pipeline
 
-| Protection | Status |
+Guardian is a security product, so compromising a Guardian release would compromise
+every downstream deployment. We therefore hold our own CI/CD to the standard we ask
+of customers. Every release is built by an immutable, least-privilege pipeline whose
+provenance you can verify independently (see *Verify Sigstore attestation*, above).
+
+| Control | Status |
 |---|---|
-| PyPI package hashes published | ✅ |
-| Sigstore / SLSA attestations | ✅ |
-| Hash-pinned `requirements.lock` | ✅ |
-| Continuous `pip-audit` on wheel builds | ✅ |
-| Typosquatting stubs on PyPI | ✅ (4 variants monitored) |
-| SDK self-integrity check (`guardian verify`) | ✅ v2.6.0+ |
-| AI-mediated supply chain detection | ✅ API tier v2.6.0+ |
+| **PyPI Trusted Publishing (OIDC)** — no long-lived API tokens in CI | ✅ |
+| **Sigstore / SLSA build attestations** on every release | ✅ |
+| **Third-party Actions pinned to commit SHAs** (immutable; no mutable tags) | ✅ |
+| **Least-privilege workflows** — `permissions: contents: read` default, scoped per job | ✅ |
+| **No `pull_request_target`**, no untrusted input in shell, no PR→publish artifact flow | ✅ |
+| **Hash-pinned `requirements.lock`** + `pip-audit --require-hashes --strict` (release-blocking) | ✅ |
+| **Dependabot** monitoring (`pip` + `github-actions`) | ✅ |
+| **PyPI package hashes published** + SDK self-integrity (`guardian verify`) | ✅ |
+| **Typosquatting stubs** on PyPI (4 variants monitored) | ✅ |
+| **AI-mediated supply chain detection** (`supplyChainDependencyInjection`, API tier) | ✅ |
 
 ---
 
-*Last updated: 2026-05-18 — Guardian SDK v2.6.0*
+*Last updated: 2026-06-23 — supply-chain hardening pass (Trusted Publishing,
+SHA-pinned Actions, least-privilege workflows, Dependabot) following the Cordyceps
+malicious-PR disclosure.*