Apply Databricks Labs Repository Lockdown policy (#19)

* Add scripts/security/ action-pinning tooling

Implements the three-script workflow from the Databricks Labs Repository
Lockdown policy: list-external-actions -> resolve-action-ref -> pin-gh-actions.

- list-external-actions: emits every third-party action referenced under
  .github/ (requires yq by Mike Farah).
- resolve-action-ref: for each action, finds the most recent release tag
  published before the cutoff (2026-03-10T00:00:00Z) and resolves it to a
  commit SHA. Handles both mono-repo conventions: subpath-prefixed tags
  (databrickslabs/sandbox/acceptance -> acceptance/v0.4.4) and top-level
  shared tags (github/codeql-action/analyze -> v4.32.6, where the subpath
  is just a directory inside a repo using a unified tag series).
- pin-gh-actions: consumes resolve-action-ref output, rewrites every
  matching `uses:` under .github/ with the SHA form + tag comment, and
  stages (but does not commit) the result. Skips databricks/databrickslabs
  actions per policy. Deviates from the blueprint reference in one way:
  does not auto-create or switch branches, because GeoBrix manages
  branches manually.

README documents the typical flow and the 2026-03-10 cutoff.

Co-authored-by: Isaac

* Pin external GitHub Actions to commit SHAs (cutoff 2026-03-10)

Every third-party `uses:` under .github/workflows/ and .github/actions/ is
now pinned to the commit SHA of the most recent release published before
2026-03-10T00:00:00Z, with the release tag preserved as an inline comment
for cross-reference (the comment is informational only — reviewers must
re-verify the SHA against the upstream release). Generated by running:

  ./scripts/security/list-external-actions \
    | xargs ./scripts/security/resolve-action-ref \
    | ./scripts/security/pin-gh-actions

Resolutions (all 15 external refs, ordered; every ref was on a mutable
tag prior to this change):

  actions/cache@v4, v5            -> cdf6c1fa...  # v5.0.3
  actions/checkout@v5             -> de0fac2e...  # v6.0.2   (major bump)
  actions/deploy-pages@v4         -> d6db9016...  # v4.0.5
  actions/download-artifact@v5    -> 70fc10c6...  # v8.0.0   (major bump)
  actions/setup-java@v5           -> be666c2f...  # v5.2.0
  actions/setup-node@v4           -> 53b83947...  # v6.3.0   (major bump)
  actions/setup-python@v5         -> a309ff8b...  # v6.2.0   (major bump)
  actions/upload-artifact@v5      -> bbbca2dd...  # v7.0.0   (major bump)
  actions/upload-pages-artifact@v3-> 7b1f4a76...  # v4.0.0   (major bump)
  codecov/codecov-action@v5       -> 671740ac...  # v5.5.2
  github/codeql-action/*@v4       -> 0d579ffd...  # v4.32.6
  pypa/gh-action-pypi-publish@... -> ed0c5393...  # v1.13.0

Major-version jumps are consistent with the policy ("latest release before
the cutoff") but carry breaking-change risk — reviewers should validate
each bump against the action's CHANGELOG before merge. In particular,
upload-artifact v4+ and download-artifact v4+ changed artifact immutability
semantics; the new versions may interact with the existing upload_artifacts
composite action in ways worth exercising under CI before unblocking.

Local composite action refs (./.github/actions/*) are unaffected —
they're first-party.

Co-authored-by: Isaac

* Scope non-exempt secrets to environment: runtime; disable release workflows

Databricks Labs Repository Lockdown policy requires any workflow using a
non-exempt secret (anything other than GITHUB_TOKEN or CODECOV_TOKEN) to
run inside a single protected GitHub Environment. GeoBrix uses
REPO_ACCESS_TOKEN (PAT fallback for private-repo checkout) across most
workflows, so every job that calls actions/checkout with that token now
sets `environment: runtime`.

Changes:
- Added `permissions: contents: read` at top level where missing
  (codeql-analysis, publish-maven, release) and removed stray top-level
  `id-token: write` from build_main / build_python / build_scala /
  build_scala_by_package / codecov-scala-parallel / codecov-upload
  (none of those jobs request OIDC tokens).
- deploy-docs: moved `pages: write` and `id-token: write` from top level
  down to the deploy job only (least privilege). The build job keeps
  `environment: runtime` for its REPO_ACCESS_TOKEN checkout; the deploy
  job keeps its existing `environment: github-pages`.
- doc-tests: added `environment: runtime` on all three (currently
  disabled) jobs that perform REPO_ACCESS_TOKEN checkouts, so they are
  compliant when re-enabled.
- release.yml: changed `environment: release` -> `environment: runtime`
  to converge on the single protected env the policy expects.
- release.yml + publish-maven.yml: DISABLED via `if: false` on their
  publish jobs with a banner comment explaining the policy context and
  how to re-enable. GeoBrix is not publishing to PyPI or GitHub Packages
  from Actions today; we will coordinate with Labs before re-enabling.

Exempt secrets per policy (GITHUB_TOKEN, CODECOV_TOKEN) are untouched
and do not require the protected environment.

Co-authored-by: Isaac

* Add 7-day Dependabot cooldown; document github-actions ecosystem opt-out

Labs Repository Lockdown policy: every Dependabot ecosystem in the repo
must apply a cooldown so we are not the first adopters of a just-released
(possibly compromised) version. Applied `cooldown.default-days: 7` to both
maven and pip ecosystems.

The policy also excludes `github-actions` from Dependabot entirely — action
SHAs are refreshed manually via scripts/security/pin-gh-actions so bumps
are reviewed as part of the security workflow rather than as auto-opened
PRs. Added a comment documenting the intentional absence.

Co-authored-by: Isaac

* Pin base image digest; checksum-verify Hadoop/GDAL/Maven downloads

Databricks Labs Repository Lockdown policy requires all build-time binary
fetches to be integrity-verified and all base images to be pinned by
digest so a compromised registry/mirror cannot silently swap bytes.

Dockerfile changes:
- Pinned `FROM ubuntu:24.04` to the multi-arch manifest-list digest
  `sha256:c4a8d5503dfb2a3eb8ab5f807da5bc69a85730fb49b5cfca2330194ebcc41c7b`
  (kept `# ubuntu:24.04` comment for human readability).
- Hadoop 3.4.0 tarball: replaced `wget | tar` stream with
  download -> sha512sum -c -> extract, using the official
  HADOOP_SHA512 from downloads.apache.org/.sha512.
- GDAL 3.11.4 tarball: same pattern with a locally-computed SHA-256.
  OSGeo only publishes MD5; we MD5-verified the upstream download
  (9f4fa4b3be48fb60d5dd76fecb11a5f6) then computed and pinned SHA-256.
- Apache Maven 3.9.9: replaced the dynamic `.sha512` fetch (which reads
  the checksum from the same origin as the tarball and therefore provides
  no protection against origin compromise) with an in-Dockerfile pinned
  MAVEN_SHA512 ARG, cross-checked against archive.apache.org.

scripts/util/install_hadoop.sh:
- Not referenced by the build; kept as a manual mirror of the Dockerfile
  flow. Rewrote with `set -euo pipefail`, a pinned HADOOP_SHA512, and
  `sha512sum -c` verification. Made executable.

Each checksum has a matching comment documenting the authoritative source
and the requirement to bump it in lockstep with the underlying version.

Co-authored-by: Isaac

* Pin PDAL to commit SHA; add origin-guard banner to disabled doc-tests jobs

Addresses review feedback on PR #19:

1. Pin PDAL 2.8.2 to commit SHA 736fa0a66af4bed7105dff5fa152edf26bbb8a3a.
   Tags are mutable; switch the pdal-builder stage from `git clone -b <tag>`
   to `git fetch --depth 1 origin <SHA>` + `git checkout FETCH_HEAD`.
   New ARG PDAL_SHA is documented alongside PDAL_VERSION with the bump
   procedure, matching the Hadoop/GDAL/Maven pattern.

2. Add a SECURITY banner above the `if: false` line on each disabled job
   in doc-tests.yml (test-python-docs, test-scala-docs, validate-structure).
   These jobs now bind environment: runtime (which scopes REPO_ACCESS_TOKEN);
   combined with the workflow_run trigger and head_sha checkout used by two
   of the three jobs, naively re-enabling would expose REPO_ACCESS_TOKEN to
   fork-controlled code. Banner prescribes the required origin guard:
     if: github.event.workflow_run.head_repository.full_name == github.repository
   Banner also added to test-scala-docs since copy-paste from siblings is
   the likely re-enable path.

Co-authored-by: Isaac

* Add CODEOWNERS pointing all paths at @databrickslabs/geobrix-write

Required by the Databricks Labs Repository Lockdown policy. Combined with
branch protection, the listed team must approve every PR before merge.

Pattern matches sibling labs repos (ucx, blueprint, dqx): root-level
CODEOWNERS with a single `*` rule pointing to the per-repo write team.

Co-authored-by: Isaac

Author: mjohns-databricks

.github/actions/python_build/action.yml

@@ -12,7 +12,7 @@ runs:
   using: "composite"
   steps:
     - name: Configure python interpreter
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
       with:
         cache: 'pip'
         cache-dependency-path: '.ci-pip-cache-key'

.github/actions/scala_build/action.yml

@@ -18,7 +18,7 @@ runs:
   using: "composite"
   steps:
         - name: Configure JDK
-          uses: actions/setup-java@v5
+          uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654  # v5.2.0
           with:
             java-version: '17'
             distribution: 'zulu'
@@ -28,7 +28,7 @@ runs:
           shell: bash
           run: echo "MAVEN_OPTS=-Xmx4g -XX:+UseG1GC" >> $GITHUB_ENV
         - name: Configure python interpreter
-          uses: actions/setup-python@v5
+          uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
           with:
             cache: 'pip' # caches dependencies for faster subsequent runs
             cache-dependency-path: '.ci-pip-cache-key'

.github/actions/upload_artifacts/action.yml

@@ -4,12 +4,12 @@ runs:
   using: "composite"
   steps:
     - name: upload build artifacts
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f  # v7.0.0
       with:
         name: build-artifacts
         path: staging/build-artifacts/*
     - name: upload user artifacts
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f  # v7.0.0
       with:
         name: user-artifacts
         path: staging/user-artifacts/*

.github/dependabot.yml

@@ -7,8 +7,20 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    # Labs lockdown policy: wait 7 days after a release before opening a PR
+    # (reduces exposure to supply-chain attacks that rely on fast-propagating new versions).
+    cooldown:
+      default-days: 7
 
   - package-ecosystem: "pip"
     directory: "/python/geobrix"
     schedule:
       interval: "weekly"
+    # Labs lockdown policy: wait 7 days after a release before opening a PR
+    # (reduces exposure to supply-chain attacks that rely on fast-propagating new versions).
+    cooldown:
+      default-days: 7
+
+  # NOTE: No `github-actions` ecosystem entry: the lockdown policy disables
+  # Dependabot updates for Actions so SHA pins are not silently bumped.
+  # Action SHAs are refreshed manually via `scripts/security/pin-gh-actions`.

.github/workflows/build_main.yml

@@ -15,17 +15,19 @@ on:
   workflow_dispatch: {}
 permissions:
   contents: read
-  id-token: write
 jobs:
   # Regenerate doc-snippet-inventory and push to the PR branch (not master). Only for PRs targeting master.
   update-doc-inventory:
     runs-on: larger
     if: github.event_name == 'pull_request' && github.base_ref == 'master'
+    # Scoped to protected env so REPO_ACCESS_TOKEN is only available to approved workflow runs.
+    environment: runtime
     permissions:
+      # Needed to push the regenerated inventory back onto the PR head branch.
       contents: write
     steps:
       - name: Checkout PR head branch
-        uses: actions/checkout@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
           token: ${{ secrets.REPO_ACCESS_TOKEN || secrets.GITHUB_TOKEN }}
           ref: ${{ github.head_ref }}
@@ -41,6 +43,8 @@ jobs:
           git push origin HEAD:${{ github.head_ref }}
   build:
     runs-on: larger
+    # Checkout uses REPO_ACCESS_TOKEN (non-exempt secret), so gate behind the protected env.
+    environment: runtime
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     strategy:
@@ -52,14 +56,14 @@ jobs:
         spark: [ 4.0.0 ]
     steps:
       - name: checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
           token: ${{ secrets.REPO_ACCESS_TOKEN || secrets.GITHUB_TOKEN }}
       - name: Create pip cache key file
         run: |
           echo "${{ github.ref }}-${{ matrix.python }}-${{ matrix.numpy }}-${{ matrix.spark }}-${{ matrix.gdal }}" > .ci-pip-cache-key
       - name: Cache apt packages
-        uses: actions/cache@v5
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5.0.3
         with:
           path: .cache/apt-archives
           key: apt-${{ runner.os }}-${{ hashFiles('.github/actions/scala_build/action.yml', '.github/actions/python_build/action.yml') }}
@@ -96,7 +100,7 @@ jobs:
           fi
           ls -la coverage-reports/
       - name: Upload coverage artifacts
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f  # v7.0.0
         with:
           name: coverage-reports
           path: coverage-reports
@@ -113,12 +117,12 @@ jobs:
       contents: read
     steps:
       - name: Download coverage artifacts
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3  # v8.0.0
         with:
           name: coverage-reports
           path: coverage-reports
       - name: Upload to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de  # v5.5.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           directory: coverage-reports

.github/workflows/build_python.yml

@@ -6,10 +6,11 @@ on:
       - "python/**"
 permissions:
   contents: read
-  id-token: write
 jobs:
   build:
     runs-on: larger
+    # Checkout uses REPO_ACCESS_TOKEN (non-exempt secret), so gate behind the protected env.
+    environment: runtime
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     strategy:
@@ -21,14 +22,14 @@ jobs:
         spark: [ 4.0.0 ]
     steps:
       - name: checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
           token: ${{ secrets.REPO_ACCESS_TOKEN || secrets.GITHUB_TOKEN }}
       - name: Create pip cache key file
         run: |
           echo "${{ github.ref }}-${{ matrix.python }}-${{ matrix.numpy }}-${{ matrix.spark }}-${{ matrix.gdal }}" > .ci-pip-cache-key
       - name: Cache apt packages
-        uses: actions/cache@v4
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5.0.3
         with:
           path: .cache/apt-archives
           key: apt-${{ runner.os }}-${{ hashFiles('.github/actions/scala_build/action.yml', '.github/actions/python_build/action.yml') }}

.github/workflows/build_scala.yml

@@ -5,10 +5,11 @@ on:
       - "scala/**"
 permissions:
   contents: read
-  id-token: write
 jobs:
   build:
     runs-on: larger
+    # Checkout uses REPO_ACCESS_TOKEN (non-exempt secret), so gate behind the protected env.
+    environment: runtime
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     strategy:
@@ -20,14 +21,14 @@ jobs:
         spark: [ 4.0.0 ]
     steps:
       - name: checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
           token: ${{ secrets.REPO_ACCESS_TOKEN || secrets.GITHUB_TOKEN }}
       - name: Create pip cache key file
         run: |
           echo "${{ github.ref }}-${{ matrix.python }}-${{ matrix.numpy }}-${{ matrix.spark }}-${{ matrix.gdal }}" > .ci-pip-cache-key
       - name: Cache apt packages
-        uses: actions/cache@v5
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5.0.3
         with:
           path: .cache/apt-archives
           key: apt-${{ runner.os }}-${{ hashFiles('.github/actions/scala_build/action.yml', '.github/actions/python_build/action.yml') }}
@@ -38,7 +39,7 @@ jobs:
       - name: upload artifacts
         uses: ./.github/actions/upload_artifacts
       - name: Publish test coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de  # v5.5.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: target/scoverage.xml,target/scoverage-report/scoverage.xml

.github/workflows/build_scala_by_package.yml

@@ -9,12 +9,13 @@ on:
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
   test-package:
     name: Test ${{ matrix.package }}
     runs-on: larger
+    # Checkout uses REPO_ACCESS_TOKEN (non-exempt secret), so gate behind the protected env.
+    environment: runtime
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     strategy:
@@ -28,7 +29,7 @@ jobs:
         spark: [4.0.0]
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
           token: ${{ secrets.REPO_ACCESS_TOKEN || secrets.GITHUB_TOKEN }}
 
@@ -37,7 +38,7 @@ jobs:
           echo "${{ github.ref }}-${{ matrix.python }}-${{ matrix.numpy }}-${{ matrix.spark }}-${{ matrix.gdal }}" > .ci-pip-cache-key
 
       - name: Cache apt packages
-        uses: actions/cache@v5
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5.0.3
         with:
           path: .cache/apt-archives
           key: apt-${{ runner.os }}-${{ hashFiles('.github/actions/scala_build/action.yml') }}

.github/workflows/codecov-scala-parallel.yml

@@ -13,12 +13,13 @@ on:
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
   coverage-package:
     name: Coverage ${{ matrix.package }}
     runs-on: larger
+    # Checkout uses REPO_ACCESS_TOKEN (non-exempt secret), so gate behind the protected env.
+    environment: runtime
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     strategy:
@@ -32,7 +33,7 @@ jobs:
         spark: [4.0.0]
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
           token: ${{ secrets.REPO_ACCESS_TOKEN || secrets.GITHUB_TOKEN }}
 
@@ -41,7 +42,7 @@ jobs:
           echo "${{ github.ref }}-${{ matrix.python }}-${{ matrix.numpy }}-${{ matrix.spark }}-${{ matrix.gdal }}" > .ci-pip-cache-key
 
       - name: Cache apt packages
-        uses: actions/cache@v5
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5.0.3
         with:
           path: .cache/apt-archives
           key: apt-${{ runner.os }}-${{ hashFiles('.github/actions/scala_build/action.yml') }}
@@ -55,7 +56,7 @@ jobs:
           suite_pattern: "com.databricks.labs.gbx.${{ matrix.package }}.*"
 
       - name: Upload scoverage for package
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f  # v7.0.0
         with:
           name: scoverage-${{ matrix.package }}
           path: target/scoverage.xml
@@ -66,14 +67,16 @@ jobs:
     runs-on: larger
     needs: coverage-package
     if: always() && needs.coverage-package.result == 'success'
+    # Checkout uses REPO_ACCESS_TOKEN (non-exempt secret), so gate behind the protected env.
+    environment: runtime
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
           token: ${{ secrets.REPO_ACCESS_TOKEN || secrets.GITHUB_TOKEN }}
 
       - name: Download all package coverage artifacts
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3  # v8.0.0
         with:
           path: coverage-artifacts
           pattern: scoverage-*
@@ -97,7 +100,7 @@ jobs:
           fi
 
       - name: Upload to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de  # v5.5.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: merged/scoverage.xml

.github/workflows/codecov-upload.yml

@@ -16,12 +16,13 @@ on:
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
   coverage:
     name: Build, test with coverage, upload
     runs-on: larger
+    # Checkout uses REPO_ACCESS_TOKEN (non-exempt secret), so gate behind the protected env.
+    environment: runtime
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     strategy:
@@ -33,7 +34,7 @@ jobs:
         spark: [ 4.0.0 ]
     steps:
       - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:
           token: ${{ secrets.REPO_ACCESS_TOKEN || secrets.GITHUB_TOKEN }}
 
@@ -42,7 +43,7 @@ jobs:
           echo "${{ github.ref }}-${{ matrix.python }}-${{ matrix.numpy }}-${{ matrix.spark }}-${{ matrix.gdal }}" > .ci-pip-cache-key
 
       - name: Cache apt packages
-        uses: actions/cache@v5
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306  # v5.0.3
         with:
           path: .cache/apt-archives
           key: apt-${{ runner.os }}-${{ hashFiles('.github/actions/scala_build/action.yml', '.github/actions/python_build/action.yml') }}
@@ -60,7 +61,7 @@ jobs:
           enable_coverage: "true"
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de  # v5.5.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: target/scoverage.xml,target/scoverage-report/scoverage.xml,python/geobrix/coverage.xml