docs: cleanup docs guidance, additional workflow hardening

.github/PULL_REQUEST_TEMPLATE.md

@@ -21,9 +21,9 @@
 
 <!-- Only fill this out if this PR is cutting a new release (e.g. v2.1.0). -->
 
+- [ ] `pyproject.toml` `version:` field updated to new version
+- [ ] `python3 scripts/sync_release_version.py --write` run after updating `pyproject.toml`
 - [ ] `socket_basics/version.py` updated to new version
-- [ ] `pyproject.toml` `version:` field updated to match
-- [ ] `action.yml` `image:` ref updated to `docker://ghcr.io/socketdev/socket-basics:<new-version>` *(auto-updated by `publish-docker.yml`
+- [ ] `socket_basics/__init__.py` updated to the same version
+- [ ] `action.yml` `image:` ref updated to `docker://ghcr.io/socketdev/socket-basics:<new-version>`
 - [ ] `CHANGELOG.md` `[Unreleased]` section reviewed
-
-> See [docs/releasing.md](../docs/releasing.md) for the full release process.

.github/dependabot.yml

@@ -9,6 +9,12 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    open-pull-requests-limit: 5
+    allow:
+      - dependency-name: "python"
+      - dependency-name: "ghcr.io/astral-sh/uv"
+      - dependency-name: "trufflesecurity/trufflehog"
+      - dependency-name: "aquasec/trivy"
     labels:
       - "dependencies"
       - "docker"
@@ -23,6 +29,13 @@ updates:
     directory: "/app_tests"
     schedule:
       interval: "weekly"
+    open-pull-requests-limit: 2
+    allow:
+      - dependency-name: "python"
+      - dependency-name: "golang"
+      - dependency-name: "securego/gosec"
+      - dependency-name: "trufflesecurity/trufflehog"
+      - dependency-name: "aquasec/trivy"
     labels:
       - "dependencies"
       - "docker"
@@ -37,6 +50,14 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    open-pull-requests-limit: 4
+    groups:
+      github-actions-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
     labels:
       - "dependencies"
       - "github-actions"

.github/workflows/_docker-pipeline.yml

@@ -66,6 +66,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
       - name: 🔨 Set up Docker Buildx
         uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

.github/workflows/dependabot-review.yml

@@ -0,0 +1,104 @@
+name: dependabot-review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: dependabot-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  inspect:
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    outputs:
+      root_docker_changed: ${{ steps.diff.outputs.root_docker_changed }}
+      app_tests_docker_changed: ${{ steps.diff.outputs.app_tests_docker_changed }}
+      workflow_or_action_changed: ${{ steps.diff.outputs.workflow_or_action_changed }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Inspect changed files
+        id: diff
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          CHANGED_FILES="$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")"
+
+          echo "Changed files:" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          printf '%s\n' "$CHANGED_FILES" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+
+          has_file() {
+            local pattern="$1"
+            if printf '%s\n' "$CHANGED_FILES" | grep -Eq "$pattern"; then
+              echo "true"
+            else
+              echo "false"
+            fi
+          }
+
+          echo "root_docker_changed=$(has_file '^Dockerfile$')" >> "$GITHUB_OUTPUT"
+          echo "app_tests_docker_changed=$(has_file '^app_tests/Dockerfile$')" >> "$GITHUB_OUTPUT"
+          echo "workflow_or_action_changed=$(has_file '^\\.github/workflows/|^action\\.yml$|^\\.github/dependabot\\.yml$')" >> "$GITHUB_OUTPUT"
+
+      - name: Summarize review expectations
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+        run: |
+          {
+            echo "## Dependabot Review Checklist"
+            echo "- PR: $PR_URL"
+            echo "- Confirm upstream release notes before merge"
+            echo "- Confirm Docker/toolchain changes match the files in this PR"
+            echo "- Do not treat a Dependabot PR as trusted solely because of the actor"
+            echo "- This workflow runs in pull_request context only; no publish secrets are exposed"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  docker-smoke-main:
+    needs: inspect
+    if: github.event.pull_request.user.login == 'dependabot[bot]' && needs.inspect.outputs.root_docker_changed == 'true'
+    uses: ./.github/workflows/_docker-pipeline.yml
+    permissions:
+      contents: read
+    with:
+      name: socket-basics
+      dockerfile: Dockerfile
+      context: .
+      check_set: main
+      push: false
+
+  docker-smoke-app-tests:
+    needs: inspect
+    if: github.event.pull_request.user.login == 'dependabot[bot]' && needs.inspect.outputs.app_tests_docker_changed == 'true'
+    uses: ./.github/workflows/_docker-pipeline.yml
+    permissions:
+      contents: read
+    with:
+      name: socket-basics-app-tests
+      dockerfile: app_tests/Dockerfile
+      context: .
+      check_set: app-tests
+      push: false
+
+  workflow-notice:
+    needs: inspect
+    if: github.event.pull_request.user.login == 'dependabot[bot]' && needs.inspect.outputs.workflow_or_action_changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Flag workflow-sensitive updates
+        run: |
+          {
+            echo "## Sensitive File Notice"
+            echo "This Dependabot PR changes workflow or action metadata files."
+            echo "Require explicit human review before merge."
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/publish-docker.yml

@@ -42,6 +42,7 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
+          persist-credentials: false
 
       - name: 🏷️ Resolve version
         id: version
@@ -97,6 +98,7 @@ jobs:
         with:
           ref: main
           fetch-depth: 0
+          persist-credentials: false
 
       - name: 🤖 Generate socket-release-bot token
         id: bot
@@ -129,25 +131,13 @@ jobs:
             --version "$VERSION" \
             --date "$DATE"
 
-      - name: 🔀 Commit CHANGELOG + action.yml back to main
+      - name: 🔀 Commit CHANGELOG back to main
         env:
           BOT_TOKEN: ${{ steps.bot.outputs.token }}
-          REF_NAME: ${{ github.ref_name }}
         run: |
           git config user.name "socket-release-bot[bot]"
           git config user.email "socket-release-bot[bot]@users.noreply.github.com"
           git remote set-url origin "https://x-access-token:${BOT_TOKEN}@github.com/SocketDev/socket-basics.git"
-
-          # Auto-update action.yml image ref to the new version.
-          # No-op if action.yml still uses `image: "Dockerfile"` (handles the
-          # chicken-and-egg on the initial v2.0.0 release).
-          if grep -q 'docker://ghcr.io/socketdev/socket-basics:' action.yml; then
-            sed -i "s|docker://ghcr.io/socketdev/socket-basics:[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*|docker://ghcr.io/socketdev/socket-basics:${VERSION}|" action.yml
-            echo "Updated action.yml image ref to ${VERSION}"
-          else
-            echo "action.yml not yet using pre-built image — skipping version update"
-          fi
-
-          git add CHANGELOG.md action.yml
-          git diff --cached --quiet || git commit -m "chore: release ${REF_NAME} — update CHANGELOG and action.yml [skip ci]"
+          git add CHANGELOG.md
+          git diff --cached --quiet || git commit -m "chore: release ${github.ref_name} — update CHANGELOG [skip ci]"
           git push origin HEAD:main

.github/workflows/python-tests.yml

@@ -45,34 +45,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
-      - name: 🔒 Assert version files in sync
-        run: |
-          V_PY=$(python -c "from socket_basics.version import __version__; print(__version__)")
-          V_TOML=$(python -c "import tomllib; print(tomllib.loads(open('pyproject.toml').read())['project']['version'])")
-          [ "$V_PY" = "$V_TOML" ] || (echo "Version mismatch: version.py=$V_PY pyproject.toml=$V_TOML" && exit 1)
-          echo "Version in sync: $V_PY"
-
-      - name: 🔒 Assert action.yml image ref matches version (once switched to pre-built)
-        run: |
-          python3 - <<'EOF'
-          import re, sys, tomllib
-          from pathlib import Path
-
-          action = Path("action.yml").read_text()
-          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
-
-          match = re.search(r'image:\s*["\']docker://[^:]+:([^"\']+)["\']', action)
-          if not match:
-              print(f"SKIP: action.yml still uses Dockerfile — check will activate once switched to pre-built image")
-              sys.exit(0)
-
-          action_version = match.group(1)
-          if action_version != version:
-              print(f"FAIL: action.yml refs {action_version} but version is {version}")
-              print(f"      Update action.yml image ref to docker://ghcr.io/socketdev/socket-basics:{version}")
-              sys.exit(1)
-
-          print(f"OK: action.yml image ref matches version {version}")
-          EOF
+      - name: 🔒 Assert release version metadata is in sync
+        run: python3 scripts/sync_release_version.py --check
       - name: 🧪 Run tests
         run: pytest -q tests/

README.md

@@ -43,7 +43,8 @@ jobs:
           socket_security_api_key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
 ```
 
-> **Why pin to a SHA?** Socket Basics is a security tool — its own supply-chain
+> [!NOTE]
+> Why pin to a SHA? Socket Basics is a security tool, so its own supply-chain
 > integrity matters. Version tags can be force-pushed or deleted; a commit SHA is
 > immutable. Dependabot manages the upgrade automatically so you still get updates
 > with a review gate. See [docs/github-action.md](docs/github-action.md#pinning-strategies)
@@ -54,7 +55,7 @@ jobs:
 ### What You Get
 
 - ✅ **Zero Configuration Required** — Configure scanning policies in the Socket Dashboard
-- ✅ **All Scanners Included** — SAST, secrets, containers, and dependency analysis
+- ✅ **Unified Scanning** — SAST, secrets, dependency analysis, and native container scanning support
 - ✅ **PR Comments** — Automated security findings on pull requests
 - ✅ **Centralized Management** — Update policies across all repos from one place
 
@@ -64,6 +65,16 @@ jobs:
 
 Socket Basics can also run locally or in other CI/CD environments:
 
+> [!NOTE]
+> Container and Dockerfile scanning remain part of Socket Basics, but the current
+> GitHub Action and pre-built image paths have Trivy-backed support temporarily
+> disabled while we complete additional security review of the underlying scanner
+> dependency path. If container or Dockerfile scanning is a near-term
+> requirement, the [native installation path](docs/local-installation.md) remains
+> available as a temporary workaround while the pre-built path is under
+> additional review. Review the upstream install path and artifacts carefully
+> before adopting it in production CI.
+
 - **[Pre-Commit Hook](docs/pre-commit-hook.md)** — Catch issues before they're committed
 - **[Local Docker Installation](docs/local-install-docker.md)** — Run in Docker with no tool installation required
 - **[Local Installation](docs/local-installation.md)** — Install security tools natively on your machine
@@ -73,7 +84,7 @@ Socket Basics can also run locally or in other CI/CD environments:
 **Built-in Security Scanners:**
 - 🔍 **SAST** — Static analysis for 15+ languages (Python, JavaScript, Go, Java, Ruby, C#, and more)
 - 🔐 **Secret Scanning** — Detect leaked credentials and API keys with TruffleHog
-- 🐳 **Container Scanning** — Vulnerability scanning for Docker images and Dockerfiles with Trivy
+- 🐳 **Container Scanning** — Trivy-backed image and Dockerfile scanning for native installs
 - 📦 **Dependency Analysis** — Socket Tier 1 reachability analysis for supply chain security
 
 **Enterprise Features** (requires [Socket Enterprise](https://socket.dev/enterprise)):
@@ -108,8 +119,7 @@ Every feature is customizable via GitHub Actions inputs, CLI flags, or environme
 - [PR Comment Guide](docs/github-pr-comment-guide.md) — Detailed guide to PR comment customization
 - [Pre-Commit Hook Setup](docs/pre-commit-hook.md) — Two installation methods (Docker vs native)
 - [Local Docker Installation](docs/local-install-docker.md) — Run with Docker, no tools to install
-- [Local Installation](docs/local-installation.md) — Install Socket CLI, Trivy, and other tools natively
-- [Releasing](docs/releasing.md) — Maintainer guide: How to cut a release for Socket Basics
+- [Local Installation](docs/local-installation.md) — Install Socket CLI and other tools natively with version pinning guidance
 
 ### Configuration
 All configuration can be managed through:
@@ -153,16 +163,18 @@ 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 socketdev/socket-basics:1.1.3
+docker pull ghcr.io/socketdev/socket-basics:2.0.2
 
 # Run scan
-docker run --rm -v "$PWD:/workspace" socketdev/socket-basics:1.1.3 \
+docker run --rm -v "$PWD:/workspace" ghcr.io/socketdev/socket-basics:2.0.2 \
   --workspace /workspace \
   --python-sast-enabled \
   --secret-scanning-enabled \
   --console-tabular-enabled
 ```
 
+The pre-built image is versioned and intended to be pinned exactly. Avoid floating tags like `:latest` in CI.
+
 📖 **[View Docker Installation Guide](docs/local-install-docker.md)**
 
 ### CLI
@@ -175,12 +187,12 @@ socket-basics --python --secrets --containers --verbose
 
 ## 🔧 Requirements
 
-**For GitHub Actions & Docker:** No installation needed — all tools are bundled in the container.
+**For GitHub Actions & Docker:** No local installation needed for the supported bundled scanners.
 
 **For Local Installation:**
 - Python 3.10+
 - [Socket CLI](https://docs.socket.dev/docs/cli) (for dependency analysis)
-- [Trivy](https://github.com/aquasecurity/trivy) (for container scanning)
+- [Trivy](https://github.com/aquasecurity/trivy) (for native container scanning)
 - [OpenGrep/Semgrep](https://semgrep.dev/) (for SAST)
 - [TruffleHog](https://github.com/trufflesecurity/trufflehog) (for secret scanning)
 
@@ -258,7 +270,6 @@ We welcome contributions! To add new features:
 2. **New Notifiers:** Implement under `socket_basics/core/notification/`
 3. **Configuration:** Add entries to `socket_basics/connectors.yaml` or `socket_basics/notifications.yaml`
 4. **Testing:** See [Testing](#-testing) section below
-5. **Releasing:** See [docs/releasing.md](docs/releasing.md) for the maintainer release process
 
 ## 🧪 Testing
 

action.yml

@@ -76,6 +76,7 @@ runs:
     INPUT_SWIFT_DISABLED_RULES: ${{ inputs.swift_disabled_rules }}
     INPUT_SWIFT_ENABLED_RULES: ${{ inputs.swift_enabled_rules }}
     INPUT_SWIFT_SAST_ENABLED: ${{ inputs.swift_sast_enabled }}
+    # Trivy-backed scanning is temporarily disabled in the pre-built GitHub Action image.
     INPUT_TRIVY_DISABLED_RULES: ${{ inputs.trivy_disabled_rules }}
     INPUT_TRIVY_IMAGE_SCANNING_DISABLED: ${{ inputs.trivy_image_scanning_disabled }}
     INPUT_TRIVY_NOTIFICATION_METHOD: ${{ inputs.trivy_notification_method }}
@@ -383,19 +384,19 @@ inputs:
     required: false
     default: "false"
   trivy_disabled_rules:
-    description: "Comma-separated list of Trivy rules to disable"
+    description: "Comma-separated list of Trivy rules to disable. Trivy-backed scanning is temporarily unavailable in the pre-built GitHub Action image."
     required: false
     default: ""
   trivy_image_scanning_disabled:
-    description: "Disable Trivy image scanning"
+    description: "Disable Trivy image scanning. Trivy-backed scanning is temporarily unavailable in the pre-built GitHub Action image."
     required: false
     default: "false"
   trivy_notification_method:
-    description: "Notification method for Trivy (e.g., console, slack)"
+    description: "Notification method for Trivy (e.g., console, slack). Trivy-backed scanning is temporarily unavailable in the pre-built GitHub Action image."
     required: false
     default: ""
   trivy_vuln_enabled:
-    description: "Enable Trivy vulnerability scanning for all supported language ecosystems"
+    description: "Enable Trivy vulnerability scanning for all supported language ecosystems. Trivy-backed scanning is temporarily unavailable in the pre-built GitHub Action image."
     required: false
     default: "false"
   trufflehog_exclude_dir: