From c52aed69ba339492012409ed3264ecfb3516c761 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Wed, 12 Aug 2026 17:38:15 -0700
Subject: [PATCH 1/5] docs(changelog): draft 3.1.0 entry for the bundled
 release

Covers #97, #98, #104, #105 and #106. Internal-only changes (#104, #106)
are collapsed into a short section; customer-facing changes keep the
detail needed to plan an upgrade, including the behavioral change where
an unresolvable changed_files scope now fails instead of scanning.
---
 CHANGELOG.md | 92 ++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 64 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3cf1f08..69516cc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,36 +8,72 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-### Fixed
-- `changed_files` diff-only mode always resolved to zero files in the pre-built
-  Docker GitHub Action: the container runs as root while the checkout is owned
-  by the runner user, so git's ownership check refused every diff lookup, the
-  scope silently resolved to nothing, and the scanners skipped with a green
-  run. Git subprocesses now mark the scan workspace as `safe.directory` via
-  command-scope `GIT_CONFIG_*` environment entries. No config files are
-  touched, and caller-provided `GIT_CONFIG_*` entries (including the previously
-  documented workaround) are preserved. The same mismatch broke git-based
-  repository/branch/commit and default-branch discovery in local Docker runs;
-  those lookups are covered by the same change.
-- A failed `changed_files` diff resolution is no longer indistinguishable from
-  an empty diff. Git errors are captured and logged instead of discarded, and
-  when the scope cannot be resolved — unreadable repository, unresolvable base
-  ref, or `pr` mode with no base ref — Socket Basics now **fails with a
-  configuration error** rather than reporting a green run that scanned nothing.
-  Shallow checkouts get a more specific error naming `fetch-depth: 0`. A
-  genuinely empty diff (e.g. a delete-only PR) is a successful resolution and
-  still skips the scanners as before.
-
 ### Added
-- The resolved `changed_files` scope is now logged on every scoped run: file
-  count at INFO, the full file list at DEBUG — so an empty diff and a failed
-  lookup are visible and distinguishable in run logs.
-- `scan_all` is now a declared action input and doubles as the fail-open escape
+- `pr_comment_enabled` (default `true`): set to `false` to run scans without
+  posting or updating the pull request comment. Findings still reach the Socket
+  dashboard, since the facts upload runs before any notifier. (#97)
+- `pr_comment_collapse_all` (default `false`): starts the collapsible OpenGrep
+  (SAST) and Socket Tier 1 sections collapsed, including critical findings.
+  Flat-table outputs (TruffleHog, Trivy Dockerfile) are unaffected. (#97)
+- Negative `--no-*` forms for every default-true boolean CLI flag, e.g.
+  `--no-pr-comment`. (#97)
+- The resolved `changed_files` scope is logged on every scoped run — file count
+  at INFO, full list at DEBUG — so an empty diff and a failed lookup are
+  distinguishable in run logs. (#105)
+- `scan_all` is now a declared action input, and doubles as the fail-open escape
   hatch for `changed_files`: when the scope cannot be resolved, widen to a
-  full-repo scan with a warning instead of failing. Every enabled scanner
-  widens consistently on that failure path. A successfully resolved scope
-  remains authoritative, including a genuinely empty diff, which still skips
-  scoped scanners.
+  full-repo scan with a warning instead of failing. Every enabled scanner widens
+  consistently on that path. (#98, #105)
+
+### Changed
+- **Behavioral:** a `changed_files` scope that cannot be resolved (unreadable
+  repository, missing base ref, shallow checkout with no base) now **fails the
+  run** with a configuration error instead of scanning. Previously this exited
+  green having scanned nothing. Pipelines with a broken diff-only setup will
+  start failing on the first run after upgrading — read the error, which names
+  the underlying git problem. Set `scan_all` to widen instead of failing.
+  (#98, #105)
+- A successfully resolved `changed_files` scope is now authoritative over
+  `scan_all`, which previously overrode it. `scan_all` applies only on the
+  failure path. A genuinely empty diff (e.g. a delete-only PR) still skips the
+  scoped scanners. (#98)
+- Notifier parameters from `notifications.yaml` now take CLI overrides through
+  the same path as connector parameters, fixing flags that parsed but never
+  reached the effective config. Absent boolean flags resolve to "unset" rather
+  than `false`, so CLI defaults no longer clobber environment, JSON, or
+  dashboard config. (#97)
+
+### Fixed
+- `changed_files` diff-only mode resolved to zero files on every run of the
+  pre-built Docker action, so scans exited green having scanned nothing: the
+  container runs as root over a runner-owned checkout, and git refuses to read a
+  repository it does not own. Git subprocesses now mark the workspace
+  `safe.directory` via command-scope `GIT_CONFIG_*` entries, and any
+  caller-supplied `GIT_CONFIG_*` entries are preserved. The same mismatch broke
+  git-based repository, branch, and commit discovery in local Docker runs. (#105)
+- `changed_files` was only resolved for CLI-built configs, so environment, JSON,
+  and dashboard configs silently scanned the whole repository, and a literal
+  `"auto"` was iterated character by character into an empty scope. Every config
+  source now runs through one resolver. (#98)
+- Pull request base detection falls back to `pull_request.base.sha`/`.ref` from
+  the event payload when `GITHUB_BASE_REF` is unset, covering
+  `pull_request_target`, `pull_request_review` and `pull_request_review_comment`.
+  `issue_comment` carries no usable base and now warns to pass `GITHUB_BASE_REF`
+  from the workflow. (#98)
+- TruffleHog and Trivy no longer substitute their own staged-file scope when an
+  explicit `changed_files` request is in effect. Trivy's Dockerfile scan skips
+  when no Dockerfile changed, and TruffleHog drops changed paths that no longer
+  exist on disk. (#98)
+
+### Internal
+- core-tool-watch reconciles one canonical `core-tool-drift` issue on `main`
+  pushes, tracks the Socket Python and npm CLIs plus `Dockerfile.heavy`, and
+  reads Trivy releases from `ghcr.io/socketdev/trivy`. The npm `socket` CLI is
+  pinned in every image, and Docker publish no longer authors a GitHub
+  Release. (#104)
+- Release prep keeps action and image references in README and `docs/**` in sync
+  with the release version; 73 stale `2.0.3` references normalized. (#106)
+- Dependency updates: pyyaml (#107), docker/setup-buildx-action (#108).
 
 ## [3.0.0] - 2026-08-06
 

From 1306abbe3901a6109a686b464a3206e5a8d92f03 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Wed, 2 Sep 2026 18:59:39 -0400
Subject: [PATCH 2/5] chore(deps): refresh Socket-owned tool pins

Socket npm CLI 1.1.154 -> 1.1.165 across all three images, matching the
current npm release. Socket Python CLI 2.6.3 -> 2.7.0 in the heavy and
app-tests images.

2.7.0 is NOT published to PyPI yet (latest is 2.6.11), so this is
scaffolding: the heavy and app-tests image builds and core-tool-watch
both fail until it lands. Keep this commit separate so it can be dropped
or held if the CLI release slips.

The socketdev Python SDK is already current at 3.5.0, so no change.
---
 CHANGELOG.md         | 3 +++
 Dockerfile           | 2 +-
 Dockerfile.heavy     | 4 ++--
 app_tests/Dockerfile | 4 ++--
 4 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 69516cc..961a363 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `scan_all`, which previously overrode it. `scan_all` applies only on the
   failure path. A genuinely empty diff (e.g. a delete-only PR) still skips the
   scoped scanners. (#98)
+- Socket toolchain refresh: Socket npm CLI 1.1.154 → 1.1.165 in every image,
+  and Socket Python CLI 2.6.3 → 2.7.0 in the heavy and app-tests images. The
+  socketdev Python SDK is already current at 3.5.0.
 - Notifier parameters from `notifications.yaml` now take CLI overrides through
   the same path as connector parameters, fixing flags that parsed but never
   reached the effective config. Absent boolean flags resolve to "unset" rather
diff --git a/Dockerfile b/Dockerfile
index 337d515..967c5f9 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -9,7 +9,7 @@ ARG UV_VERSION=0.12.1
 #
 # NOT Dependabot-trackable (no official Docker image with a stable binary path):
 ARG OPENGREP_VERSION=v1.26.0
-ARG SOCKET_NPM_CLI_VERSION=1.1.154
+ARG SOCKET_NPM_CLI_VERSION=1.1.165
 #
 # NOT Dependabot-trackable — Socket-built Trivy, rebuilt from unmodified upstream
 # source and published by Socket's own release pipeline. Pinned by digest; both
diff --git a/Dockerfile.heavy b/Dockerfile.heavy
index 9f76e44..ff3bdd3 100644
--- a/Dockerfile.heavy
+++ b/Dockerfile.heavy
@@ -3,8 +3,8 @@ ARG PYTHON_VERSION=3.12
 ARG TRUFFLEHOG_VERSION=3.96.0
 ARG UV_VERSION=0.12.1
 ARG OPENGREP_VERSION=v1.26.0
-ARG SOCKET_NPM_CLI_VERSION=1.1.154
-ARG SOCKET_PYTHON_CLI_VERSION=2.6.3
+ARG SOCKET_NPM_CLI_VERSION=1.1.165
+ARG SOCKET_PYTHON_CLI_VERSION=2.7.0
 # Socket-built Trivy, pinned by digest — see the note in ./Dockerfile.
 ARG TRIVY_IMAGE=ghcr.io/socketdev/trivy:0.73.0@sha256:e3d9d5f10250cb73b0ea9446ae1191c0f2da2f5e6173eac08a840b1812f02e0b
 
diff --git a/app_tests/Dockerfile b/app_tests/Dockerfile
index 04d0be7..9764ce2 100644
--- a/app_tests/Dockerfile
+++ b/app_tests/Dockerfile
@@ -12,8 +12,8 @@ ARG UV_VERSION=0.12.1
 # NOT Dependabot-trackable (no official Docker image with a stable binary path):
 ARG GOSEC_VERSION=v2.28.0
 ARG OPENGREP_VERSION=v1.26.0
-ARG SOCKET_NPM_CLI_VERSION=1.1.154
-ARG SOCKET_PYTHON_CLI_VERSION=2.6.3
+ARG SOCKET_NPM_CLI_VERSION=1.1.165
+ARG SOCKET_PYTHON_CLI_VERSION=2.7.0
 #
 # NOT Dependabot-trackable — Socket-built Trivy, pinned by digest; updated by
 # Socket's trivy-dist release process. See the note in the root ./Dockerfile.

From 3f0ed2a9e71b3cc82e5d37e250dc2c295c2f556b Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Wed, 2 Sep 2026 19:00:30 -0400
Subject: [PATCH 3/5] chore(release): 3.1.0

Version metadata, uv.lock, CHANGELOG date stamp, and 74 current-release
documentation references, via scripts/prep_release.py --version 3.1.0.
---
 CHANGELOG.md                    |  2 +
 README.md                       |  6 +--
 action.yml                      |  2 +-
 docs/github-action.md           | 56 +++++++++++-----------
 docs/github-pr-comment-guide.md |  2 +-
 docs/local-install-docker.md    | 82 ++++++++++++++++-----------------
 docs/pre-commit-hook.md         |  2 +-
 pyproject.toml                  |  2 +-
 socket_basics/__init__.py       |  2 +-
 socket_basics/version.py        |  2 +-
 uv.lock                         |  4 +-
 11 files changed, 82 insertions(+), 80 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 961a363..bea2408 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-09-02
+
 ### Added
 - `pr_comment_enabled` (default `true`): set to `false` to run scans without
   posting or updating the pull request comment. Findings still reach the Socket
diff --git a/README.md b/README.md
index ff1897f..3327b92 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ jobs:
       - name: Run Socket Basics
         # Pin to a commit SHA for supply-chain safety.
         # Dependabot will keep this up to date automatically — see docs/github-action.md.
-        uses: SocketDev/socket-basics@<sha>  # v3.0.0
+        uses: SocketDev/socket-basics@<sha>  # v3.1.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -179,10 +179,10 @@ For GitHub Actions, see the [Quick Start](#-quick-start---github-actions) above
 
 ```bash
 # Pull the pre-built image (recommended — no build step required)
-docker pull ghcr.io/socketdev/socket-basics:3.0.0
+docker pull ghcr.io/socketdev/socket-basics:3.1.0
 
 # Run scan
-docker run --rm -v "$PWD:/workspace" ghcr.io/socketdev/socket-basics:3.0.0 \
+docker run --rm -v "$PWD:/workspace" ghcr.io/socketdev/socket-basics:3.1.0 \
   --workspace /workspace \
   --python-sast-enabled \
   --secret-scanning-enabled \
diff --git a/action.yml b/action.yml
index ff8ee9c..d200ae2 100644
--- a/action.yml
+++ b/action.yml
@@ -4,7 +4,7 @@ author: "Socket"
 
 runs:
   using: "docker"
-  image: "docker://ghcr.io/socketdev/socket-basics:3.0.0"
+  image: "docker://ghcr.io/socketdev/socket-basics:3.1.0"
   env:
     # Core GitHub variables (these are automatically available, but we explicitly pass GITHUB_TOKEN)
     GITHUB_TOKEN: ${{ inputs.github_token }}
diff --git a/docs/github-action.md b/docs/github-action.md
index 13efb31..db7165e 100644
--- a/docs/github-action.md
+++ b/docs/github-action.md
@@ -43,7 +43,7 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v3.0.0
+        uses: SocketDev/socket-basics@v3.1.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -57,7 +57,7 @@ With just your `SOCKET_SECURITY_API_KEY`, all scanning configurations are manage
 
 ### How the action is currently built
 
-When you reference `uses: SocketDev/socket-basics@v3.0.0`, GitHub Actions pulls the
+When you reference `uses: SocketDev/socket-basics@v3.1.0`, GitHub Actions pulls the
 pre-built image referenced by [`action.yml`](../action.yml). The historical multi-stage
 Docker build still matters for maintainers because it determines what lands in the
 published image:
@@ -75,7 +75,7 @@ Socket Basics from source in every workflow run.
 ### Pre-built image
 
 Starting with v2, the action pulls a pre-built image from GHCR rather than
-building from source on every run. Pinning to a specific version tag (e.g. `@v3.0.0`)
+building from source on every run. Pinning to a specific version tag (e.g. `@v3.1.0`)
 means the action starts in seconds — the image is built, integration-tested, and
 published before the release tag is ever created.
 
@@ -85,7 +85,7 @@ If you run socket-basics in other CI systems (Jenkins, GitLab, CircleCI, etc.) o
 as a standalone `docker run`, pull the pre-built image directly:
 
 ```bash
-docker pull ghcr.io/socketdev/socket-basics:3.0.0
+docker pull ghcr.io/socketdev/socket-basics:3.1.0
 ```
 
 See [Local Docker Installation](local-install-docker.md) for usage examples.
@@ -101,7 +101,7 @@ is immediately affected. We've seen this happen across the ecosystem:
   publish `:latest`/`:latest-heavy` Docker aliases as an onboarding
   convenience, but treat them as exactly that — production pipelines should
   pin an exact version or digest.)
-- **Version tags** (`@v3.0.0`) are better, but tags are mutable by default.
+- **Version tags** (`@v3.1.0`) are better, but tags are mutable by default.
   A tag can be deleted and recreated pointing at a different commit. There are
   documented cases of this happening — maliciously and accidentally.
 - **Commit SHAs** are the only truly immutable reference. A SHA cannot be
@@ -126,14 +126,14 @@ The only truly immutable reference. Dependabot keeps it current automatically.
 ```yaml
 - name: Run Socket Basics
   # Dependabot keeps this SHA up to date — see .github/dependabot.yml setup below.
-  uses: SocketDev/socket-basics@<sha>  # v3.0.0
+  uses: SocketDev/socket-basics@<sha>  # v3.1.0
   with:
     socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
 ```
 
 Get the SHA for any release:
 ```bash
-git ls-remote https://github.com/SocketDev/socket-basics refs/tags/v3.0.0
+git ls-remote https://github.com/SocketDev/socket-basics refs/tags/v3.1.0
 ```
 
 ---
@@ -145,7 +145,7 @@ enforces tag protection rules). SHA pinning is still preferable for defence
 in depth.
 
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
 ```
@@ -166,7 +166,7 @@ updates:
 ```
 
 Dependabot opens a PR for each new release, updating the SHA or version tag
-and keeping the `# v3.0.0` comment in sync. You review, approve, and merge
+and keeping the `# v3.1.0` comment in sync. You review, approve, and merge
 on your own schedule — automated upgrades with a human gate.
 
 ---
@@ -176,7 +176,7 @@ on your own schedule — automated upgrades with a human gate.
 | Strategy | Immutable? | Auto-updates | Review gate |
 |---|---|---|---|
 | `@v2` floating tag | ❌ (not published) | — | — |
-| `@v3.0.0` + Dependabot | ✅ (tag protection enforced) | Yes (weekly PR) | Yes |
+| `@v3.1.0` + Dependabot | ✅ (tag protection enforced) | Yes (weekly PR) | Yes |
 | `@<sha>` + Dependabot | ✅ always | Yes (weekly PR) | Yes |
 
 ## Basic Configuration
@@ -204,7 +204,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 
 **SAST (Static Analysis):**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     # Enable SAST for specific languages
@@ -218,7 +218,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 
 **Secret Scanning:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     secret_scanning_enabled: 'true'
@@ -230,7 +230,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 
 **Container Scanning:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     # The supported pre-built GitHub Action path currently ships without
@@ -252,7 +252,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 
 **Socket Tier 1 Reachability:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_tier_1_enabled: 'true'
@@ -261,7 +261,7 @@ Include these in your workflow's `jobs.<job_id>.permissions` section.
 ### Output Configuration
 
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     python_sast_enabled: 'true'
@@ -299,7 +299,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run Socket Basics (changed files only)
-        uses: SocketDev/socket-basics@v3.0.0
+        uses: SocketDev/socket-basics@v3.1.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
         with:
@@ -425,7 +425,7 @@ Configure Socket Basics centrally from the [Socket Dashboard](https://socket.dev
 
 **Enable in workflow:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   env:
     GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
   with:
@@ -438,7 +438,7 @@ Configure Socket Basics centrally from the [Socket Dashboard](https://socket.dev
 > [!NOTE]
 > You can also pass credentials using environment variables instead of the `with:` section:
 > ```yaml
-> - uses: SocketDev/socket-basics@v3.0.0
+> - uses: SocketDev/socket-basics@v3.1.0
 >   env:
 >     SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_SECURITY_API_KEY }}
 >   with:
@@ -456,7 +456,7 @@ All notification integrations require Socket Enterprise.
 
 **Slack Notifications:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -468,7 +468,7 @@ All notification integrations require Socket Enterprise.
 
 **Jira Issue Creation:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -483,7 +483,7 @@ All notification integrations require Socket Enterprise.
 
 **Microsoft Teams:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -495,7 +495,7 @@ All notification integrations require Socket Enterprise.
 
 **Generic Webhook:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -507,7 +507,7 @@ All notification integrations require Socket Enterprise.
 
 **SIEM Integration:**
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     github_token: ${{ secrets.GITHUB_TOKEN }}
     socket_org: ${{ secrets.SOCKET_ORG }}
@@ -543,7 +543,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v3.0.0
+        uses: SocketDev/socket-basics@v3.1.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -586,7 +586,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       
       - name: Run Full Security Scan
-        uses: SocketDev/socket-basics@v3.0.0
+        uses: SocketDev/socket-basics@v3.1.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -711,7 +711,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v3.0.0
+        uses: SocketDev/socket-basics@v3.1.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -768,7 +768,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       
       - name: Run Socket Basics
-        uses: SocketDev/socket-basics@v3.0.0
+        uses: SocketDev/socket-basics@v3.1.0
         env:
           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
         with:
@@ -897,7 +897,7 @@ env:
 ```yaml
 steps:
   - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - Must be first
-  - uses: SocketDev/socket-basics@v3.0.0
+  - uses: SocketDev/socket-basics@v3.1.0
 ```
 
 ### PR Comments Not Appearing
diff --git a/docs/github-pr-comment-guide.md b/docs/github-pr-comment-guide.md
index f5d07a4..ed55d67 100644
--- a/docs/github-pr-comment-guide.md
+++ b/docs/github-pr-comment-guide.md
@@ -315,7 +315,7 @@ PR. This is for teams who want to review finding quality in the Socket dashboard
 first, without every PR growing a comment that developers have to scroll past.
 
 ```yaml
-- uses: SocketDev/socket-basics@v3.0.0
+- uses: SocketDev/socket-basics@v3.1.0
   with:
     socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
     github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/docs/local-install-docker.md b/docs/local-install-docker.md
index 05fd132..a0e54e7 100644
--- a/docs/local-install-docker.md
+++ b/docs/local-install-docker.md
@@ -16,7 +16,7 @@ Run Socket Basics locally using Docker without installing security tools on your
 
 ```bash
 # 1. Pull a pinned release from GHCR (no build step required)
-docker pull ghcr.io/socketdev/socket-basics:3.0.0
+docker pull ghcr.io/socketdev/socket-basics:3.1.0
 
 # 2. Create .env file with your credentials
 cat > .env << 'EOF'
@@ -28,14 +28,14 @@ EOF
 docker run --rm \
   -v "$PWD:/workspace" \
   --env-file .env \
-  ghcr.io/socketdev/socket-basics:3.0.0 \
+  ghcr.io/socketdev/socket-basics:3.1.0 \
   --workspace /workspace \
   --python \
   --secrets \
   --console-tabular-enabled
 ```
 
-The Docker image should always be pinned to an exact version such as `3.0.0`. Avoid
+The Docker image should always be pinned to an exact version such as `3.1.0`. Avoid
 floating tags like `:latest` in CI/CD.
 
 ## Using Pre-built Images
@@ -45,12 +45,12 @@ The baked-in security tool versions are recorded in the image labels so you can
 inspect exactly what's inside:
 
 ```bash
-docker inspect ghcr.io/socketdev/socket-basics:3.0.0 \
+docker inspect ghcr.io/socketdev/socket-basics:3.1.0 \
   | jq '.[0].Config.Labels'
 # {
 #   "com.socket.trufflehog-version": "3.93.8",
 #   "com.socket.opengrep-version": "v1.16.5",
-#   "org.opencontainers.image.version": "3.0.0",
+#   "org.opencontainers.image.version": "3.1.0",
 #   ...
 # }
 ```
@@ -81,7 +81,7 @@ docker inspect ghcr.io/socketdev/socket-basics:3.0.0 \
       -v "$GITHUB_WORKSPACE:/workspace" \
       -e SOCKET_SECURITY_API_KEY=${{ secrets.SOCKET_API_KEY }} \
       -e SOCKET_ORG=${{ secrets.SOCKET_ORG }} \
-      ghcr.io/socketdev/socket-basics:3.0.0 \
+      ghcr.io/socketdev/socket-basics:3.1.0 \
       --workspace /workspace \
       --all-languages \
       --secrets \
@@ -92,7 +92,7 @@ docker inspect ghcr.io/socketdev/socket-basics:3.0.0 \
 
 ```yaml
 security-scan:
-  image: ghcr.io/socketdev/socket-basics:3.0.0
+  image: ghcr.io/socketdev/socket-basics:3.1.0
   stage: test
   script:
     - socket-basics
@@ -109,7 +109,7 @@ security-scan:
 
 ```dockerfile
 # Pin socket-basics and let Dependabot send upgrade PRs automatically
-FROM ghcr.io/socketdev/socket-basics:3.0.0
+FROM ghcr.io/socketdev/socket-basics:3.1.0
 ```
 
 ### Staying Up to Date with Dependabot
@@ -127,7 +127,7 @@ updates:
       interval: "weekly"
 ```
 
-Dependabot will detect the `FROM ghcr.io/socketdev/socket-basics:3.0.0` reference
+Dependabot will detect the `FROM ghcr.io/socketdev/socket-basics:3.1.0` reference
 and open a PR with the version bump when a new release is available.
 
 ## Building the Docker Image
@@ -138,10 +138,10 @@ Pull a specific release without building locally:
 
 ```bash
 # GHCR (preferred)
-docker pull ghcr.io/socketdev/socket-basics:3.0.0
+docker pull ghcr.io/socketdev/socket-basics:3.1.0
 
 # Docker Hub
-docker pull socketdev/socket-basics:3.0.0
+docker pull socketdev/socket-basics:3.1.0
 ```
 
 ### Build from Source
@@ -154,7 +154,7 @@ git clone https://github.com/SocketDev/socket-basics.git
 cd socket-basics
 
 # Build with version tag (multi-stage; first build is slower, subsequent ones are fast)
-docker build -t socket-basics:3.0.0 .
+docker build -t socket-basics:3.1.0 .
 
 # Verify the build
 docker images | grep socket-basics
@@ -163,7 +163,7 @@ docker images | grep socket-basics
 ### Build for a Specific Platform (M1/M2 Macs)
 
 ```bash
-docker build --platform linux/amd64 -t socket-basics:3.0.0 .
+docker build --platform linux/amd64 -t socket-basics:3.1.0 .
 ```
 
 ### Build with Custom Tool Versions
@@ -174,7 +174,7 @@ The image pins the bundled tools to specific versions. You can override them at
 docker build \
   --build-arg TRUFFLEHOG_VERSION=3.93.8 \
   --build-arg OPENGREP_VERSION=v1.16.5 \
-  -t socket-basics:3.0.0 .
+  -t socket-basics:3.1.0 .
 ```
 
 Trivy comes from a Socket-built image pinned by digest via the `TRIVY_IMAGE`
@@ -187,10 +187,10 @@ tests image, build from the `app_tests` directory and use the same build args.
 
 ```bash
 # Check that all tools are available in the container
-docker run --rm socket-basics:3.0.0 socket-basics --version
-docker run --rm socket-basics:3.0.0 socket --version
-docker run --rm socket-basics:3.0.0 opengrep --version
-docker run --rm socket-basics:3.0.0 trufflehog --version
+docker run --rm socket-basics:3.1.0 socket-basics --version
+docker run --rm socket-basics:3.1.0 socket --version
+docker run --rm socket-basics:3.1.0 opengrep --version
+docker run --rm socket-basics:3.1.0 trufflehog --version
 ```
 
 ### Smoke Test
@@ -225,7 +225,7 @@ Mount your project directory into the container:
 # Scan current directory
 docker run --rm \
   -v "$PWD:/workspace" \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --python \
   --secrets \
@@ -242,7 +242,7 @@ docker run --rm \
 # Scan a specific project directory
 docker run --rm \
   -v "/path/to/your/project:/workspace" \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --javascript \
   --secrets
@@ -253,7 +253,7 @@ docker run --rm \
 ```bash
 docker run --rm \
   -v "$PWD:/workspace" \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --all-languages \
   --secrets \
@@ -301,7 +301,7 @@ VERBOSE=false
 docker run --rm \
   -v "$PWD:/workspace" \
   --env-file .env \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --python \
   --secrets
@@ -316,7 +316,7 @@ docker run --rm \
   -v "$PWD:/workspace" \
   -e "SOCKET_SECURITY_API_KEY=scrt_your_api_key" \
   -e "SOCKET_ORG=your-org-slug" \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --python \
   --secrets \
@@ -338,7 +338,7 @@ docker run --rm \
   --env-file .env.socket \
   --env-file .env.notifiers \
   --env-file .env.scanning \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --all-languages
 ```
@@ -357,7 +357,7 @@ docker run --rm \
   -v "$PWD:/workspace" \
   -e "SOCKET_SECURITY_API_KEY=$SOCKET_SECURITY_API_KEY" \
   -e "SOCKET_ORG=$SOCKET_ORG" \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --python
 ```
@@ -385,7 +385,7 @@ docker run --rm \
   -v "$PWD:/workspace" \
   -v "$PWD/scan-results:/results" \
   --env-file .env \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --python \
   --secrets \
@@ -402,7 +402,7 @@ docker run --rm -it \
   -v "$PWD:/workspace" \
   --env-file .env \
   --entrypoint /bin/bash \
-  socket-basics:3.0.0
+  socket-basics:3.1.0
 
 # Inside container, run commands manually:
 # cd /workspace
@@ -431,7 +431,7 @@ docker run --rm \
   -v "$PWD:/workspace" \
   -v "$PWD/socket-config.json:/config.json" \
   --env-file .env \
-  socket-basics:3.0.0 \
+  socket-basics:3.1.0 \
   --workspace /workspace \
   --config /config.json
 ```
@@ -455,7 +455,7 @@ for PROJECT in "${PROJECTS[@]}"; do
   docker run --rm \
     -v "$PROJECT:/workspace" \
     --env-file .env \
-    socket-basics:3.0.0 \
+    socket-basics:3.1.0 \
     --workspace /workspace \
     --all-languages \
     --secrets \
@@ -479,7 +479,7 @@ pipeline {
         stage('Security Scan') {
             steps {
                 script {
-                    docker.image('ghcr.io/socketdev/socket-basics:3.0.0').inside(
+                    docker.image('ghcr.io/socketdev/socket-basics:3.1.0').inside(
                         "-v ${WORKSPACE}:/workspace --env-file .env"
                     ) {
                         sh '''
@@ -501,7 +501,7 @@ pipeline {
 
 ```yaml
 security-scan:
-  image: ghcr.io/socketdev/socket-basics:3.0.0
+  image: ghcr.io/socketdev/socket-basics:3.1.0
   stage: test
   script:
     - socket-basics
@@ -527,7 +527,7 @@ security-scan:
    docker run --rm \
      -v "$PWD:/workspace" \
      --user "$(id -u):$(id -g)" \
-     socket-basics:3.0.0 \
+     socket-basics:3.1.0 \
      --workspace /workspace
    ```
 
@@ -546,14 +546,14 @@ security-scan:
    ```bash
    docker run --rm \
      -v "$(pwd):/workspace" \  # Use $(pwd) instead of $PWD
-     socket-basics:3.0.0
+     socket-basics:3.1.0
    ```
 
 2. Verify mount:
    ```bash
    docker run --rm \
      -v "$PWD:/workspace" \
-     socket-basics:3.0.0 \
+     socket-basics:3.1.0 \
      ls -la /workspace
    ```
 
@@ -583,7 +583,7 @@ security-scan:
    docker run --rm \
      -v "$PWD:/workspace" \
      --env-file "$(pwd)/.env" \
-     socket-basics:3.0.0
+     socket-basics:3.1.0
    ```
 
 ### Container Image Too Large
@@ -614,7 +614,7 @@ security-scan:
    ```bash
    docker run --rm \
      -v "$PWD:/workspace" \
-     socket-basics:3.0.0 \
+     socket-basics:3.1.0 \
      --workspace /workspace \
      --python \
      --secrets \
@@ -635,7 +635,7 @@ security-scan:
    ```bash
    docker run --rm \
      -v "$PWD:/workspace" \
-     socket-basics:3.0.0 \
+     socket-basics:3.1.0 \
      --workspace /workspace \
      --output /workspace/results.json  # Save to mounted directory
    ```
@@ -646,7 +646,7 @@ security-scan:
    docker run --rm \
      -v "$PWD:/workspace" \
      -v "$PWD/results:/results" \
-     socket-basics:3.0.0 \
+     socket-basics:3.1.0 \
      --workspace /workspace \
      --output /results/scan.json
    ```
@@ -657,7 +657,7 @@ Add these to your `~/.bashrc` or `~/.zshrc` for quick access:
 
 ```bash
 # Socket Basics Docker aliases
-alias sb-docker='docker run --rm -v "$PWD:/workspace" --env-file .env ghcr.io/socketdev/socket-basics:3.0.0 --workspace /workspace'
+alias sb-docker='docker run --rm -v "$PWD:/workspace" --env-file .env ghcr.io/socketdev/socket-basics:3.1.0 --workspace /workspace'
 alias sb-quick='sb-docker --secrets --console-tabular-enabled'
 alias sb-python='sb-docker --python --secrets --console-tabular-enabled'
 alias sb-js='sb-docker --javascript --secrets --console-tabular-enabled'
@@ -682,7 +682,7 @@ sb-all
 ## Best Practices
 
 1. **Use pre-built images** — Pull `ghcr.io/socketdev/socket-basics:<version>` instead of building locally
-2. **Pin to a specific version** — Avoid `:latest` in production CI; pin to `3.0.0` and upgrade deliberately
+2. **Pin to a specific version** — Avoid `:latest` in production CI; pin to `3.1.0` and upgrade deliberately
 3. **Use Dependabot** — Reference the image in your Dockerfile/Compose to get automatic upgrade PRs
 4. **Inspect baked-in labels** — Run `docker inspect <image> | jq '.[0].Config.Labels'` to verify tool versions
 5. **Use .env files** — Keep credentials out of command history
@@ -701,7 +701,7 @@ set -e
 # Configuration
 PROJECT_DIR="$(pwd)"
 RESULTS_DIR="./scan-results"
-IMAGE_NAME="socket-basics:3.0.0"
+IMAGE_NAME="socket-basics:3.1.0"
 ENV_FILE=".env"
 
 # Create results directory
diff --git a/docs/pre-commit-hook.md b/docs/pre-commit-hook.md
index 03d682b..1965954 100644
--- a/docs/pre-commit-hook.md
+++ b/docs/pre-commit-hook.md
@@ -35,7 +35,7 @@ Best for: Teams wanting consistent environments without installing security tool
 
 ```bash
 # Pull the pre-built image (no build step required)
-docker pull ghcr.io/socketdev/socket-basics:3.0.0
+docker pull ghcr.io/socketdev/socket-basics:3.1.0
 ```
 
 **2. Create pre-commit hook:**
diff --git a/pyproject.toml b/pyproject.toml
index a6c7359..2962d3f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "socket_basics"
-version = "3.0.0"
+version = "3.1.0"
 description = "Socket Basics with integrated SAST, secret scanning, and container analysis"
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/socket_basics/__init__.py b/socket_basics/__init__.py
index b9800c0..3cb2d14 100644
--- a/socket_basics/__init__.py
+++ b/socket_basics/__init__.py
@@ -12,7 +12,7 @@
 from .socket_basics import SecurityScanner, main
 from .core.config import load_config_from_env, Config
 
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 __author__ = "Socket.dev"
 __email__ = "support@socket.dev"
 
diff --git a/socket_basics/version.py b/socket_basics/version.py
index 528787c..f5f41e5 100644
--- a/socket_basics/version.py
+++ b/socket_basics/version.py
@@ -1 +1 @@
-__version__ = "3.0.0"
+__version__ = "3.1.0"
diff --git a/uv.lock b/uv.lock
index c5e524e..3d5f814 100644
--- a/uv.lock
+++ b/uv.lock
@@ -244,7 +244,7 @@ name = "exceptiongroup"
 version = "1.3.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0b/9f/a65090624ecf468cdca03533906e7c69ed7588582240cfe7cc9e770b50eb/exceptiongroup-1.3.0.tar.gz", hash = "sha256:b241f5885f560bc56a59ee63ca4c6a8bfa46ae4ad651af316d4e81817bb9fd88", size = 29749, upload-time = "2025-05-10T17:42:51.123Z" }
 wheels = [
@@ -692,7 +692,7 @@ wheels = [
 
 [[package]]
 name = "socket-basics"
-version = "3.0.0"
+version = "3.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "jsonschema" },

From 493add1a5c2e6f6a8e8a53c278faf56c4ed05c0b Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Wed, 2 Sep 2026 19:19:44 -0400
Subject: [PATCH 4/5] fix(app-tests): refresh socketsecurity index metadata on
 install

This install pins an exact version, so a stale cached uv index response
makes a freshly published release look like it does not exist. Use
--refresh-package for just this package rather than --no-cache, which
would discard the cache mount's benefit for bandit and built wheels.

Dockerfile.heavy already passes --no-cache-dir on its pip equivalent.
---
 CHANGELOG.md         | 2 ++
 app_tests/Dockerfile | 8 +++++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bea2408..470706c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -79,6 +79,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Release prep keeps action and image references in README and `docs/**` in sync
   with the release version; 73 stale `2.0.3` references normalized. (#106)
 - Dependency updates: pyyaml (#107), docker/setup-buildx-action (#108).
+- app-tests image refreshes `socketsecurity` index metadata on install, so a
+  stale cached index cannot make a freshly published pin look nonexistent.
 
 ## [3.0.0] - 2026-08-06
 
diff --git a/app_tests/Dockerfile b/app_tests/Dockerfile
index 9764ce2..15327de 100644
--- a/app_tests/Dockerfile
+++ b/app_tests/Dockerfile
@@ -98,9 +98,15 @@ RUN --mount=type=cache,target=/root/.npm \
 # Bandit + socketsecurity via uv
 ENV UV_LINK_MODE=copy
 ARG SOCKET_PYTHON_CLI_VERSION
+# --refresh-package: this install pins an exact version, so a stale cached index
+# response makes a freshly published release look like it does not exist ("no
+# version of socketsecurity==X"). Refresh metadata for this one package rather
+# than passing --no-cache, which would discard the cache mount's benefit for
+# bandit and for already-built wheels.
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv tool install bandit \
-    && uv tool install "socketsecurity==${SOCKET_PYTHON_CLI_VERSION}"
+    && uv tool install --refresh-package socketsecurity \
+        "socketsecurity==${SOCKET_PYTHON_CLI_VERSION}"
 ENV PATH="/root/.local/bin:$PATH"
 
 # NOTE: the legacy socket-security-tools runner (src/, entrypoint.sh) predates

From af893ed5c8b5c57805c44368ff7c3e84b11fa4bd Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Wed, 2 Sep 2026 19:22:41 -0400
Subject: [PATCH 5/5] test: assert the socketsecurity pin, not the RUN's
 formatting

The assertion matched an exact literal, so it broke when the install
gained a --refresh-package flag and a line continuation even though the
version pin it guards was unchanged. Collapse continuations and match the
ARG-pinned spec after 'uv tool install' instead.

Verified the guard still fails for an unpinned spec and for a hardcoded
version that bypasses the ARG.
---
 tests/test_check_core_tools.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/tests/test_check_core_tools.py b/tests/test_check_core_tools.py
index 1d1b38c..1cfada5 100644
--- a/tests/test_check_core_tools.py
+++ b/tests/test_check_core_tools.py
@@ -54,7 +54,13 @@ def test_socket_cli_installs_are_version_pinned():
             assert re.search(r"^ARG SOCKET_NPM_CLI_VERSION=\d+\.\d+\.\d+$", contents, re.MULTILINE)
 
     app_tests = (check_core_tools.REPO_ROOT / "app_tests" / "Dockerfile").read_text()
-    assert 'uv tool install "socketsecurity==${SOCKET_PYTHON_CLI_VERSION}"' in app_tests
+    # Collapse line continuations so the pin assertion is not sensitive to how
+    # the RUN is wrapped or to intervening flags (e.g. --refresh-package).
+    app_tests_joined = re.sub(r"\\\s*\n\s*", " ", app_tests)
+    assert re.search(
+        r'uv tool install [^\n]*"socketsecurity==\$\{SOCKET_PYTHON_CLI_VERSION\}"',
+        app_tests_joined,
+    )
     assert re.search(r"^ARG SOCKET_PYTHON_CLI_VERSION=\d+\.\d+\.\d+$", app_tests, re.MULTILINE)