socketsecurity 2.2.76__tar.gz → 2.2.78__tar.gz

{socketsecurity-2.2.76 → socketsecurity-2.2.78}/.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,10 +155,12 @@ 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: |
@@ -175,12 +168,15 @@ jobs:
             --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:

{socketsecurity-2.2.76 → socketsecurity-2.2.78}/.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

{socketsecurity-2.2.76 → socketsecurity-2.2.78}/.github/workflows/python-tests.yml

@@ -9,6 +9,7 @@ on:
     paths:
       - "socketsecurity/**/*.py"
       - "tests/unit/**/*.py"
+      - "tests/core/**/*.py"
       - "pyproject.toml"
       - "uv.lock"
       - ".github/workflows/python-tests.yml"
@@ -16,6 +17,7 @@ on:
     paths:
       - "socketsecurity/**/*.py"
       - "tests/unit/**/*.py"
+      - "tests/core/**/*.py"
       - "pyproject.toml"
       - "uv.lock"
       - ".github/workflows/python-tests.yml"
@@ -47,4 +49,4 @@ jobs:
           pip install uv
           uv sync --extra test
       - name: 🧪 run tests
-        run: uv run pytest -q tests/unit/
+        run: uv run pytest -q tests/unit/ tests/core/

{socketsecurity-2.2.76 → socketsecurity-2.2.78}/.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...`
               });
-            }
+            }

{socketsecurity-2.2.76 → socketsecurity-2.2.78}/.gitignore

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

socketsecurity-2.2.78/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: socketsecurity
+Version: 2.2.78
+Summary: Socket Security CLI for CI/CD
+Project-URL: Homepage, https://socket.dev
+Author-email: Douglas Coburn <douglas@socket.dev>
+Maintainer-email: Douglas Coburn <douglas@socket.dev>
+License: MIT License
+        
+        Copyright (c) 2022 Socket Inc
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: oss,sca,security,socket.dev,socketsecurity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: bs4>=0.0.2
+Requires-Dist: gitpython
+Requires-Dist: markdown>=3.10
+Requires-Dist: mdutils
+Requires-Dist: packaging
+Requires-Dist: prettytable
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: socketdev<4.0.0,>=3.0.32
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: uv>=0.1.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'test'
+Requires-Dist: pytest-watch>=4.2.0; extra == 'test'
+Requires-Dist: pytest>=7.4.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Socket Security CLI
+
+Socket Python CLI for Socket scans, diff reporting, reachability analysis, and SARIF/GitLab exports.
+
+Comprehensive docs are available in [`docs/`](docs/) for full flag reference, CI/CD-specific guidance, and contributor setup.
+
+## Quick start
+
+### 1) Install
+
+```bash
+pip install socketsecurity
+```
+
+### 2) Authenticate
+
+```bash
+export SOCKET_SECURITY_API_TOKEN="<token>"
+```
+
+### 3) Run a basic scan
+
+```bash
+socketcli --target-path .
+```
+
+## Common use cases
+
+This section covers the paved path/common workflows.
+For advanced options and exhaustive details, see [`docs/cli-reference.md`](docs/cli-reference.md).
+For CI/CD-specific guidance, see [`docs/ci-cd.md`](docs/ci-cd.md).
+
+### Basic policy scan (no SARIF)
+
+```bash
+socketcli --target-path .
+```
+
+### GitLab dependency-scanning report
+
+```bash
+socketcli --enable-gitlab-security --gitlab-security-file gl-dependency-scanning-report.json
+```
+
+## SARIF use cases
+
+### Full-scope reachable SARIF (grouped alerts)
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope full \
+  --sarif-grouping alert \
+  --sarif-reachability reachable \
+  --disable-blocking
+```
+
+### Diff-scope reachable SARIF (PR/CI gating)
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope diff \
+  --sarif-reachability reachable \
+  --strict-blocking
+```
+
+### Full-scope SARIF (instance-level detail)
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope full \
+  --sarif-grouping instance \
+  --sarif-reachability all \
+  --disable-blocking
+```
+
+## Choose your mode
+
+| Use case | Recommended mode | Key flags |
+|:--|:--|:--|
+| Basic policy enforcement in CI | Diff-based policy check | `--strict-blocking` |
+| Reachable-focused SARIF for reporting | Full-scope grouped SARIF | `--reach --sarif-scope full --sarif-grouping alert --sarif-reachability reachable --sarif-file <path>` |
+| Detailed reachability export for investigations | Full-scope instance SARIF | `--reach --sarif-scope full --sarif-grouping instance --sarif-reachability all --sarif-file <path>` |
+| Net-new PR findings only | Diff-scope SARIF | `--reach --sarif-scope diff --sarif-reachability reachable --sarif-file <path>` |
+
+Dashboard parity note:
+- Full-scope SARIF is the closest match for dashboard-style filtering.
+- Exact result counts can still differ from the dashboard due to backend/API consolidation differences and grouping semantics.
+- See [`docs/troubleshooting.md#dashboard-vs-cli-result-counts`](docs/troubleshooting.md#dashboard-vs-cli-result-counts).
+
+## Config files (`--config`)
+
+Use `--config <path>` with `.toml` or `.json` to avoid long command lines.
+
+Precedence order:
+
+`CLI flags` > `environment variables` > `config file` > `built-in defaults`
+
+Example:
+
+```toml
+[socketcli]
+repo = "example-repo"
+reach = true
+sarif_scope = "full"
+sarif_grouping = "alert"
+sarif_reachability = "reachable"
+sarif_file = "reachable.sarif"
+```
+
+Equivalent JSON:
+
+```json
+{
+  "socketcli": {
+    "repo": "example-repo",
+    "reach": true,
+    "sarif_scope": "full",
+    "sarif_grouping": "alert",
+    "sarif_reachability": "reachable",
+    "sarif_file": "reachable.sarif"
+  }
+}
+```
+
+Run:
+
+```bash
+socketcli --config .socketcli.toml --target-path .
+```
+
+Reference sample configs:
+
+TOML:
+- [`examples/config/sarif-dashboard-parity.toml`](examples/config/sarif-dashboard-parity.toml)
+- [`examples/config/sarif-instance-detail.toml`](examples/config/sarif-instance-detail.toml)
+- [`examples/config/sarif-diff-ci-cd.toml`](examples/config/sarif-diff-ci-cd.toml)
+
+JSON:
+- [`examples/config/sarif-dashboard-parity.json`](examples/config/sarif-dashboard-parity.json)
+- [`examples/config/sarif-instance-detail.json`](examples/config/sarif-instance-detail.json)
+- [`examples/config/sarif-diff-ci-cd.json`](examples/config/sarif-diff-ci-cd.json)
+
+## CI/CD examples
+
+Prebuilt workflow examples:
+
+- [GitHub Actions](workflows/github-actions.yml)
+- [Buildkite](workflows/buildkite.yml)
+- [GitLab CI](workflows/gitlab-ci.yml)
+- [Bitbucket Pipelines](workflows/bitbucket-pipelines.yml)
+
+Minimal pattern:
+
+```yaml
+- name: Run Socket CLI
+  run: socketcli --config .socketcli.toml --target-path .
+  env:
+    SOCKET_SECURITY_API_TOKEN: ${{ secrets.SOCKET_SECURITY_API_TOKEN }}
+```
+
+## Common gotchas
+
+See [`docs/troubleshooting.md`](docs/troubleshooting.md#common-gotchas).
+
+## Quick verification checks
+
+After generating SARIF files, validate shape/count quickly:
+
+```bash
+jq '.runs[0].results | length' results.sarif
+jq -r '.runs[0].results[]?.properties.reachability' results.sarif | sort -u
+```
+
+For side-by-side comparisons:
+
+```bash
+jq '.runs[0].results | length' sarif-dashboard-parity-reachable.sarif
+jq '.runs[0].results | length' sarif-full-instance-all.sarif
+jq '.runs[0].results | length' sarif-diff-reachable.sarif
+```
+
+## Documentation reference
+
+- Full CLI reference: [`docs/cli-reference.md`](docs/cli-reference.md)
+- CI/CD guide: [`docs/ci-cd.md`](docs/ci-cd.md)
+- Troubleshooting guide: [`docs/troubleshooting.md`](docs/troubleshooting.md)
+- Development guide: [`docs/development.md`](docs/development.md)

socketsecurity-2.2.78/README.md

@@ -0,0 +1,193 @@
+# Socket Security CLI
+
+Socket Python CLI for Socket scans, diff reporting, reachability analysis, and SARIF/GitLab exports.
+
+Comprehensive docs are available in [`docs/`](docs/) for full flag reference, CI/CD-specific guidance, and contributor setup.
+
+## Quick start
+
+### 1) Install
+
+```bash
+pip install socketsecurity
+```
+
+### 2) Authenticate
+
+```bash
+export SOCKET_SECURITY_API_TOKEN="<token>"
+```
+
+### 3) Run a basic scan
+
+```bash
+socketcli --target-path .
+```
+
+## Common use cases
+
+This section covers the paved path/common workflows.
+For advanced options and exhaustive details, see [`docs/cli-reference.md`](docs/cli-reference.md).
+For CI/CD-specific guidance, see [`docs/ci-cd.md`](docs/ci-cd.md).
+
+### Basic policy scan (no SARIF)
+
+```bash
+socketcli --target-path .
+```
+
+### GitLab dependency-scanning report
+
+```bash
+socketcli --enable-gitlab-security --gitlab-security-file gl-dependency-scanning-report.json
+```
+
+## SARIF use cases
+
+### Full-scope reachable SARIF (grouped alerts)
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope full \
+  --sarif-grouping alert \
+  --sarif-reachability reachable \
+  --disable-blocking
+```
+
+### Diff-scope reachable SARIF (PR/CI gating)
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope diff \
+  --sarif-reachability reachable \
+  --strict-blocking
+```
+
+### Full-scope SARIF (instance-level detail)
+
+```bash
+socketcli \
+  --reach \
+  --sarif-file results.sarif \
+  --sarif-scope full \
+  --sarif-grouping instance \
+  --sarif-reachability all \
+  --disable-blocking
+```
+
+## Choose your mode
+
+| Use case | Recommended mode | Key flags |
+|:--|:--|:--|
+| Basic policy enforcement in CI | Diff-based policy check | `--strict-blocking` |
+| Reachable-focused SARIF for reporting | Full-scope grouped SARIF | `--reach --sarif-scope full --sarif-grouping alert --sarif-reachability reachable --sarif-file <path>` |
+| Detailed reachability export for investigations | Full-scope instance SARIF | `--reach --sarif-scope full --sarif-grouping instance --sarif-reachability all --sarif-file <path>` |
+| Net-new PR findings only | Diff-scope SARIF | `--reach --sarif-scope diff --sarif-reachability reachable --sarif-file <path>` |
+
+Dashboard parity note:
+- Full-scope SARIF is the closest match for dashboard-style filtering.
+- Exact result counts can still differ from the dashboard due to backend/API consolidation differences and grouping semantics.
+- See [`docs/troubleshooting.md#dashboard-vs-cli-result-counts`](docs/troubleshooting.md#dashboard-vs-cli-result-counts).
+
+## Config files (`--config`)
+
+Use `--config <path>` with `.toml` or `.json` to avoid long command lines.
+
+Precedence order:
+
+`CLI flags` > `environment variables` > `config file` > `built-in defaults`
+
+Example:
+
+```toml
+[socketcli]
+repo = "example-repo"
+reach = true
+sarif_scope = "full"
+sarif_grouping = "alert"
+sarif_reachability = "reachable"
+sarif_file = "reachable.sarif"
+```
+
+Equivalent JSON:
+
+```json
+{
+  "socketcli": {
+    "repo": "example-repo",
+    "reach": true,
+    "sarif_scope": "full",
+    "sarif_grouping": "alert",
+    "sarif_reachability": "reachable",
+    "sarif_file": "reachable.sarif"
+  }
+}
+```
+
+Run:
+
+```bash
+socketcli --config .socketcli.toml --target-path .
+```
+
+Reference sample configs:
+
+TOML:
+- [`examples/config/sarif-dashboard-parity.toml`](examples/config/sarif-dashboard-parity.toml)
+- [`examples/config/sarif-instance-detail.toml`](examples/config/sarif-instance-detail.toml)
+- [`examples/config/sarif-diff-ci-cd.toml`](examples/config/sarif-diff-ci-cd.toml)
+
+JSON:
+- [`examples/config/sarif-dashboard-parity.json`](examples/config/sarif-dashboard-parity.json)
+- [`examples/config/sarif-instance-detail.json`](examples/config/sarif-instance-detail.json)
+- [`examples/config/sarif-diff-ci-cd.json`](examples/config/sarif-diff-ci-cd.json)
+
+## CI/CD examples
+
+Prebuilt workflow examples:
+
+- [GitHub Actions](workflows/github-actions.yml)
+- [Buildkite](workflows/buildkite.yml)
+- [GitLab CI](workflows/gitlab-ci.yml)
+- [Bitbucket Pipelines](workflows/bitbucket-pipelines.yml)
+
+Minimal pattern:
+
+```yaml
+- name: Run Socket CLI
+  run: socketcli --config .socketcli.toml --target-path .
+  env:
+    SOCKET_SECURITY_API_TOKEN: ${{ secrets.SOCKET_SECURITY_API_TOKEN }}
+```
+
+## Common gotchas
+
+See [`docs/troubleshooting.md`](docs/troubleshooting.md#common-gotchas).
+
+## Quick verification checks
+
+After generating SARIF files, validate shape/count quickly:
+
+```bash
+jq '.runs[0].results | length' results.sarif
+jq -r '.runs[0].results[]?.properties.reachability' results.sarif | sort -u
+```
+
+For side-by-side comparisons:
+
+```bash
+jq '.runs[0].results | length' sarif-dashboard-parity-reachable.sarif
+jq '.runs[0].results | length' sarif-full-instance-all.sarif
+jq '.runs[0].results | length' sarif-diff-reachable.sarif
+```
+
+## Documentation reference
+
+- Full CLI reference: [`docs/cli-reference.md`](docs/cli-reference.md)
+- CI/CD guide: [`docs/ci-cd.md`](docs/ci-cd.md)
+- Troubleshooting guide: [`docs/troubleshooting.md`](docs/troubleshooting.md)
+- Development guide: [`docs/development.md`](docs/development.md)

socketsecurity-2.2.78/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.