socketsecurity 2.2.77__tar.gz → 2.2.79__tar.gz

{socketsecurity-2.2.77 → socketsecurity-2.2.79}/.github/workflows/e2e-test.yml

@@ -4,9 +4,11 @@ on:
   push:
     branches: [main]
   pull_request:
+  workflow_dispatch:
 
 jobs:
   e2e-scan:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871
@@ -48,6 +50,7 @@ jobs:
           fi
 
   e2e-sarif:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871
@@ -63,15 +66,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 }}
@@ -96,6 +90,7 @@ jobs:
           "
 
   e2e-reachability:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871
@@ -164,10 +159,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 +172,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.77 → socketsecurity-2.2.79}/.github/workflows/pr-preview.yml

@@ -5,6 +5,7 @@ on:
 
 jobs:
   preview:
+    if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -37,6 +38,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 +158,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.77 → socketsecurity-2.2.79}/.github/workflows/python-tests.yml

@@ -50,3 +50,23 @@ jobs:
           uv sync --extra test
       - name: 🧪 run tests
         run: uv run pytest -q tests/unit/ tests/core/
+
+  unsupported-python-install:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+      - name: 🐍 setup python
+        uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3
+        with:
+          python-version: "3.10"
+      - name: 🚫 verify install is rejected on unsupported python
+        run: |
+          python -m pip install --upgrade pip
+          if pip install .; then
+            echo "Expected pip install . to fail on Python 3.10"
+            exit 1
+          fi

{socketsecurity-2.2.77 → socketsecurity-2.2.79}/.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
@@ -40,7 +42,7 @@ jobs:
 
       - name: Manage PR Comment
         uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea
-        if: always()
+        if: always() && github.event.pull_request.head.repo.full_name == github.repository
         env:
           MAIN_VERSION: ${{ env.MAIN_VERSION }}
           PR_VERSION: ${{ env.PR_VERSION }}
@@ -87,4 +89,4 @@ jobs:
                 issue_number: prNumber,
                 body: `❌ **Version Check Failed**\n\nPlease increment...`
               });
-            }
+            }

{socketsecurity-2.2.77 → socketsecurity-2.2.79}/.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.79/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: socketsecurity
+Version: 2.2.79
+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.11
+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.79/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)