Fix reachability filtering, add config file support

.github/workflows/e2e-test.yml

@@ -63,15 +63,6 @@ jobs:
           python -m pip install --upgrade pip
           pip install .
 
-      - name: Verify --sarif-reachable-only without --reach exits non-zero
-        run: |
-          if socketcli --sarif-reachable-only --api-token dummy 2>&1; then
-            echo "FAIL: Expected non-zero exit"
-            exit 1
-          else
-            echo "PASS: Exited non-zero as expected"
-          fi
-
       - name: Run Socket CLI scan with --sarif-file
         env:
           SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_CLI_API_TOKEN }}
@@ -164,23 +155,28 @@ jobs:
             --target-path tests/e2e/fixtures/simple-npm \
             --reach \
             --sarif-file /tmp/sarif-all.sarif \
+            --sarif-scope full \
+            --sarif-reachability all \
             --disable-blocking \
-            2>/dev/null || true
+            2>/dev/null
 
-      - name: Run scan with --sarif-file --sarif-reachable-only (filtered results)
+      - name: Run scan with --sarif-file --sarif-reachability reachable (filtered results)
         env:
           SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_CLI_API_TOKEN }}
         run: |
           socketcli \
             --target-path tests/e2e/fixtures/simple-npm \
             --reach \
             --sarif-file /tmp/sarif-reachable.sarif \
-            --sarif-reachable-only \
+            --sarif-scope full \
+            --sarif-reachability reachable \
             --disable-blocking \
-            2>/dev/null || true
+            2>/dev/null
 
       - name: Verify reachable-only results are a subset of all results
         run: |
+          test -f /tmp/sarif-all.sarif
+          test -f /tmp/sarif-reachable.sarif
           python3 -c "
           import json
           with open('/tmp/sarif-all.sarif') as f:

.github/workflows/pr-preview.yml

@@ -37,6 +37,17 @@ jobs:
           VERSION=$(hatch version | cut -d+ -f1)
           echo "VERSION=$VERSION" >> $GITHUB_ENV
 
+      - name: Check if version already exists on Test PyPI
+        id: version_check
+        env:
+          VERSION: ${{ env.VERSION }}
+        run: |
+          if curl -s -f https://test.pypi.org/pypi/socketsecurity/${VERSION}/json > /dev/null; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Build package
         if: steps.version_check.outputs.exists != 'true'
         run: |
@@ -146,4 +157,4 @@ jobs:
           build-args: |
             CLI_VERSION=${{ env.VERSION }}
             PIP_INDEX_URL=https://test.pypi.org/simple
-            PIP_EXTRA_INDEX_URL=https://pypi.org/simple
+            PIP_EXTRA_INDEX_URL=https://pypi.org/simple

.github/workflows/version-check.yml

@@ -18,13 +18,15 @@ jobs:
       - name: Check version increment
         id: version_check
         run: |
+          python -m pip install --upgrade pip
+          pip install packaging
+
           # Get version from current PR
           PR_VERSION=$(grep -o "__version__.*" socketsecurity/__init__.py | awk '{print $3}' | tr -d "'")
           echo "PR_VERSION=$PR_VERSION" >> $GITHUB_ENV
 
           # Get version from main branch
-          git checkout origin/main
-          MAIN_VERSION=$(grep -o "__version__.*" socketsecurity/__init__.py | awk '{print $3}' | tr -d "'")
+          MAIN_VERSION=$(git show origin/main:socketsecurity/__init__.py | grep -o "__version__.*" | awk '{print $3}' | tr -d "'")
           echo "MAIN_VERSION=$MAIN_VERSION" >> $GITHUB_ENV
 
           # Compare versions using Python
@@ -87,4 +89,4 @@ jobs:
                 issue_number: prNumber,
                 body: `❌ **Version Check Failed**\n\nPlease increment...`
               });
-            }
+            }

.gitignore

@@ -15,6 +15,7 @@ scripts/*.py
 *.json
 *.sarif
 !tests/**/*.json
+!examples/config/*.json
 markdown_overview_temp.md
 markdown_security_temp.md
 .DS_Store

docs/ci-cd.md

@@ -0,0 +1,119 @@
+# CI/CD guide
+
+Use this guide for pipeline-focused CLI usage across platforms.
+
+## Recommended patterns
+
+### Dashboard-style reachable SARIF
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope full \
+  --sarif-grouping alert \
+  --sarif-reachability reachable \
+  --disable-blocking
+```
+
+### Diff-based gating on new reachable findings
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope diff \
+  --sarif-reachability reachable \
+  --strict-blocking
+```
+
+## Config file usage in CI
+
+Use `--config .socketcli.toml` or `--config .socketcli.json` to keep pipeline commands small.
+
+Precedence order:
+
+`CLI flags` > `environment variables` > `config file` > `built-in defaults`
+
+Example:
+
+```toml
+[socketcli]
+reach = true
+sarif_scope = "full"
+sarif_grouping = "alert"
+sarif_reachability = "reachable"
+sarif_file = "results.sarif"
+```
+
+Equivalent JSON:
+
+```json
+{
+  "socketcli": {
+    "reach": true,
+    "sarif_scope": "full",
+    "sarif_grouping": "alert",
+    "sarif_reachability": "reachable",
+    "sarif_file": "results.sarif"
+  }
+}
+```
+
+## Platform examples
+
+### GitHub Actions
+
+```yaml
+- name: Run Socket CLI
+  run: socketcli --config .socketcli.toml --target-path .
+  env:
+    SOCKET_SECURITY_API_TOKEN: ${{ secrets.SOCKET_SECURITY_API_TOKEN }}
+```
+
+### Buildkite
+
+```yaml
+steps:
+  - label: "Socket scan"
+    command: "socketcli --config .socketcli.toml --target-path ."
+    env:
+      SOCKET_SECURITY_API_TOKEN: "${SOCKET_SECURITY_API_TOKEN}"
+```
+
+### GitLab CI
+
+```yaml
+socket_scan:
+  script:
+    - socketcli --config .socketcli.toml --target-path .
+  variables:
+    SOCKET_SECURITY_API_TOKEN: $SOCKET_SECURITY_API_TOKEN
+```
+
+### Bitbucket Pipelines
+
+```yaml
+pipelines:
+  default:
+    - step:
+        script:
+          - socketcli --config .socketcli.toml --target-path .
+```
+
+## Workflow templates
+
+Prebuilt examples in this repo:
+
+- [`../workflows/github-actions.yml`](../workflows/github-actions.yml)
+- [`../workflows/buildkite.yml`](../workflows/buildkite.yml)
+- [`../workflows/gitlab-ci.yml`](../workflows/gitlab-ci.yml)
+- [`../workflows/bitbucket-pipelines.yml`](../workflows/bitbucket-pipelines.yml)
+
+## CI gotchas
+
+- `--strict-blocking` enables strict diff behavior (`new + unchanged`) for blocking evaluation and diff-based output selection.
+- `--sarif-scope full` requires `--reach`.
+- `--sarif-grouping alert` currently applies to `--sarif-scope full`.
+- Diff-based SARIF can validly be empty when there are no matching net-new alerts.
+- Keep API tokens in secret stores (`SOCKET_SECURITY_API_TOKEN`), not in config files.