socketsecurity 2.2.65__tar.gz → 2.2.68__tar.gz

{socketsecurity-2.2.65 → socketsecurity-2.2.68}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socketsecurity
-Version: 2.2.65
+Version: 2.2.68
 Summary: Socket Security CLI for CI/CD
 Project-URL: Homepage, https://socket.dev
 Author-email: Douglas Coburn <douglas@socket.dev>
@@ -137,6 +137,32 @@ This will:
 - Create a repository in Socket named like `my-repo-mobile-web`
 - Preserve git context (commits, branch info) from the repository root
 
+**Generate GitLab Security Dashboard report:**
+```bash
+socketcli --enable-gitlab-security \
+          --repo owner/repo \
+          --target-path .
+```
+
+This will:
+- Scan all manifest files in the current directory
+- Generate a GitLab-compatible Dependency Scanning report
+- Save to `gl-dependency-scanning-report.json`
+- Include all actionable security alerts (error/warn level)
+
+**Multiple output formats:**
+```bash
+socketcli --enable-json \
+          --enable-sarif \
+          --enable-gitlab-security \
+          --repo owner/repo
+```
+
+This will simultaneously generate:
+- JSON output to console
+- SARIF format to console
+- GitLab Security Dashboard report to file
+
 ### Requirements
 
 - Both `--sub-path` and `--workspace-name` must be specified together
@@ -146,14 +172,15 @@ This will:
 ## Usage
 
 ```` shell
-socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branch BRANCH] [--integration {api,github,gitlab,azure,bitbucket}] 
-          [--owner OWNER] [--pr-number PR_NUMBER] [--commit-message COMMIT_MESSAGE] [--commit-sha COMMIT_SHA] [--committers [COMMITTERS ...]] 
+socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branch BRANCH] [--integration {api,github,gitlab,azure,bitbucket}]
+          [--owner OWNER] [--pr-number PR_NUMBER] [--commit-message COMMIT_MESSAGE] [--commit-sha COMMIT_SHA] [--committers [COMMITTERS ...]]
           [--target-path TARGET_PATH] [--sbom-file SBOM_FILE] [--license-file-name LICENSE_FILE_NAME] [--save-submitted-files-list SAVE_SUBMITTED_FILES_LIST]
-          [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME] 
-          [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug] 
-          [--enable-json] [--enable-sarif] [--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue] 
-          [--ignore-commit-files] [--disable-blocking] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders] 
-          [--reach] [--reach-version REACH_VERSION] [--reach-analysis-timeout REACH_ANALYSIS_TIMEOUT] 
+          [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME]
+          [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug]
+          [--enable-json] [--enable-sarif] [--enable-gitlab-security] [--gitlab-security-file <path>]
+          [--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue]
+          [--ignore-commit-files] [--disable-blocking] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders]
+          [--reach] [--reach-version REACH_VERSION] [--reach-analysis-timeout REACH_ANALYSIS_TIMEOUT]
           [--reach-analysis-memory-limit REACH_ANALYSIS_MEMORY_LIMIT] [--reach-ecosystems REACH_ECOSYSTEMS] [--reach-exclude-paths REACH_EXCLUDE_PATHS]
           [--reach-min-severity {low,medium,high,critical}] [--reach-skip-cache] [--reach-disable-analytics] [--reach-output-file REACH_OUTPUT_FILE]
           [--only-facts-file] [--version]
@@ -212,6 +239,8 @@ If you don't want to provide the Socket API Token every time then you can use th
 | --enable-debug            | False    | False   | Enable debug logging                                                              |
 | --enable-json             | False    | False   | Output in JSON format                                                             |
 | --enable-sarif            | False    | False   | Enable SARIF output of results instead of table or JSON format                    |
+| --enable-gitlab-security  | False    | False   | Enable GitLab Security Dashboard output format (Dependency Scanning report)       |
+| --gitlab-security-file    | False    | gl-dependency-scanning-report.json | Output file path for GitLab Security report                |
 | --disable-overview        | False    | False   | Disable overview output                                                           |
 | --exclude-license-details | False    | False   | Exclude license details from the diff report (boosts performance for large repos) |
 | --version                 | False    | False   | Show program's version number and exit                                            |
@@ -251,6 +280,7 @@ The CLI will automatically install @coana-tech/cli if not present. Use `--reach`
 |:-------------------------|:---------|:--------|:----------------------------------------------------------------------|
 | --ignore-commit-files    | False    | False   | Ignore commit files                                                   |
 | --disable-blocking       | False    | False   | Disable blocking mode                                                 |
+| --strict-blocking        | False    | False   | Fail on ANY security policy violations (blocking severity), not just new ones. Only works in diff mode. See [Strict Blocking Mode](#strict-blocking-mode) for details. |
 | --enable-diff            | False    | False   | Enable diff mode even when using --integration api (forces diff mode without SCM integration) |
 | --scm                    | False    | api     | Source control management type                                        |
 | --timeout                | False    |         | Timeout in seconds for API requests                                   |
@@ -386,6 +416,99 @@ Bot mode (`bot_configs` array items):
 - `alert_types` (array, optional): Only send specific alert types
 - `reachability_alerts_only` (boolean, default: false): Only send reachable vulnerabilities when using `--reach`
 
+## Strict Blocking Mode
+
+The `--strict-blocking` flag enforces a zero-tolerance security policy by failing builds when **ANY** security violations with blocking severity exist, not just new ones introduced in the current changes.
+
+### Standard vs Strict Blocking Behavior
+
+**Standard Behavior (Default)**:
+- ✅ Passes if no NEW violations are introduced
+- ❌ Fails only on NEW violations from your changes
+- 🟡 Existing violations are ignored
+
+**Strict Blocking Behavior (`--strict-blocking`)**:
+- ✅ Passes only if NO violations exist (new or existing)
+- ❌ Fails on ANY violation (new OR existing)
+- 🔴 Enforces zero-tolerance policy
+
+### Usage Examples
+
+**Basic strict blocking:**
+```bash
+socketcli --target-path ./my-project --strict-blocking
+```
+
+**In GitLab CI:**
+```bash
+socketcli --target-path $CI_PROJECT_DIR --scm gitlab --pr-number ${CI_MERGE_REQUEST_IID:-0} --strict-blocking
+```
+
+**In GitHub Actions:**
+```bash
+socketcli --target-path $GITHUB_WORKSPACE --scm github --pr-number $PR_NUMBER --strict-blocking
+```
+
+### Output Differences
+
+**Standard scan output:**
+```
+Security issues detected by Socket Security:
+  - NEW blocking issues: 2
+  - NEW warning issues: 1
+```
+
+**Strict blocking scan output:**
+```
+Security issues detected by Socket Security:
+  - NEW blocking issues: 2
+  - NEW warning issues: 1
+  - EXISTING blocking issues: 5 (causing failure due to --strict-blocking)
+  - EXISTING warning issues: 3
+```
+
+### Use Cases
+
+1. **Zero-Tolerance Security Policy**: Enforce that no security violations exist in your codebase at any time
+2. **Gradual Security Improvement**: Use alongside standard scans to monitor existing violations while blocking new ones
+3. **Protected Branch Enforcement**: Require all violations to be resolved before merging to main/production
+4. **Security Audits**: Scheduled scans that fail if any violations accumulate
+
+### Important Notes
+
+- **Diff Mode Only**: The flag only works in diff mode (with SCM integration). In API mode, a warning is logged.
+- **Error-Level Only**: Only fails on `error=True` alerts (blocking severity), not warnings.
+- **Priority**: `--disable-blocking` takes precedence - if both flags are set, the build will always pass.
+- **First Scan**: On the very first scan of a repository, there are no "existing" violations, so behavior is identical to standard mode.
+
+### Flag Combinations
+
+**Strict blocking with debugging:**
+```bash
+socketcli --strict-blocking --enable-debug
+```
+
+**Strict blocking with JSON output:**
+```bash
+socketcli --strict-blocking --enable-json > security-report.json
+```
+
+**Override for testing** (passes even with violations):
+```bash
+socketcli --strict-blocking --disable-blocking
+```
+
+### Migration Strategy
+
+**Phase 1: Assessment** - Add strict scan with `allow_failure: true` in CI
+**Phase 2: Remediation** - Fix or triage all violations
+**Phase 3: Enforcement** - Set `allow_failure: false` to block merges
+
+For complete GitLab CI/CD examples, see:
+- [`.gitlab-ci-strict-blocking-demo.yml`](.gitlab-ci-strict-blocking-demo.yml) - Comprehensive demo
+- [`.gitlab-ci-strict-blocking-production.yml`](.gitlab-ci-strict-blocking-production.yml) - Production-ready template
+- [`STRICT-BLOCKING-GITLAB-CI.md`](STRICT-BLOCKING-GITLAB-CI.md) - Full documentation
+
 ## Automatic Git Detection
 
 The CLI now automatically detects repository information from your git environment, significantly simplifying usage in CI/CD pipelines:
@@ -588,9 +711,136 @@ The manifest archive feature is useful for:
 
 ### Differential scan skipped on octopus merge
 
-When your repo uses an **octopus merge** (3+ parents), the CLI may not detect all changed files.  
+When your repo uses an **octopus merge** (3+ parents), the CLI may not detect all changed files.
 This is expected Git behavior: the default diff only compares the merge result to the first parent.
 
+## GitLab Security Dashboard Integration
+
+Socket CLI can generate reports compatible with GitLab's Security Dashboard, allowing vulnerability information to be displayed directly in merge requests and security dashboards. This feature complements the existing [Socket GitLab integration](https://docs.socket.dev/docs/gitlab) by providing standardized dependency scanning reports.
+
+### Generating GitLab Security Reports
+
+To generate a GitLab-compatible security report:
+
+```bash
+socketcli --enable-gitlab-security --repo owner/repo
+```
+
+This creates a `gl-dependency-scanning-report.json` file following GitLab's Dependency Scanning report schema.
+
+### GitLab CI/CD Integration
+
+Add Socket Security scanning to your GitLab CI pipeline to generate Security Dashboard reports:
+
+```yaml
+# .gitlab-ci.yml
+socket_security_scan:
+  stage: security
+  image: python:3.11
+  before_script:
+    - pip install socketsecurity
+  script:
+    - socketcli
+        --api-token $SOCKET_API_TOKEN
+        --repo $CI_PROJECT_PATH
+        --branch $CI_COMMIT_REF_NAME
+        --commit-sha $CI_COMMIT_SHA
+        --enable-gitlab-security
+  artifacts:
+    reports:
+      dependency_scanning: gl-dependency-scanning-report.json
+    paths:
+      - gl-dependency-scanning-report.json
+    expire_in: 1 week
+  only:
+    - merge_requests
+    - main
+```
+
+**Note**: This Security Dashboard integration can be used alongside the [Socket GitLab App](https://docs.socket.dev/docs/gitlab) for comprehensive protection:
+- **Socket GitLab App**: Real-time PR comments, policy enforcement, and blocking
+- **Security Dashboard**: Centralized vulnerability tracking and reporting in GitLab's native interface
+
+### Custom Output Path
+
+Specify a custom output path for the GitLab security report:
+
+```bash
+socketcli --enable-gitlab-security --gitlab-security-file custom-path.json
+```
+
+### Multiple Output Formats
+
+GitLab security reports can be generated alongside other output formats:
+
+```bash
+socketcli --enable-json --enable-gitlab-security --enable-sarif
+```
+
+This command will:
+- Output JSON format to console
+- Save GitLab Security Dashboard report to `gl-dependency-scanning-report.json`
+- Save SARIF report (if configured)
+
+### Security Dashboard Features
+
+The GitLab Security Dashboard will display:
+- **Vulnerability Severity**: Critical, High, Medium, Low levels
+- **Affected Packages**: Package name, version, and ecosystem
+- **CVE Identifiers**: Direct links to CVE databases when available
+- **Dependency Chains**: Distinction between direct and transitive dependencies
+- **Remediation Suggestions**: Fix recommendations from Socket Security
+- **Alert Categories**: Supply chain risks, malware, vulnerabilities, and more
+
+### Alert Filtering
+
+The GitLab report includes **actionable security alerts** based on your Socket policy configuration:
+
+**Included Alerts** ✅:
+- **Error-level alerts** (`error: true`) - Security policy violations that block merges
+- **Warning-level alerts** (`warn: true`) - Important security concerns requiring attention
+
+**Excluded Alerts** ❌:
+- **Ignored alerts** (`ignore: true`) - Alerts explicitly ignored in your policy
+- **Monitor-only alerts** (`monitor: true` without error/warn) - Tracked but not actionable
+
+**Socket Alert Types Detected**:
+- Supply chain risks (malware, typosquatting, suspicious behavior)
+- Security vulnerabilities (CVEs, unsafe code patterns)
+- Risky permissions (network access, filesystem access, shell access)
+- License policy violations
+
+All alert types are included in the GitLab report if they're marked as `error` or `warn` by your Socket Security policy, ensuring the Security Dashboard shows only actionable findings.
+
+### Report Schema
+
+Socket CLI generates reports compliant with [GitLab Dependency Scanning schema version 15.0.0](https://docs.gitlab.com/ee/development/integrations/secure.html). The reports include:
+
+- **Scan metadata**: Analyzer and scanner information
+- **Vulnerabilities**: Detailed vulnerability data with:
+  - Unique deterministic UUIDs for tracking
+  - Package location and dependency information
+  - Severity levels mapped from Socket's analysis
+  - Socket-specific alert types and CVE identifiers
+  - Links to Socket.dev for detailed analysis
+
+### Requirements
+
+- **GitLab Version**: GitLab 12.0 or later (for Security Dashboard support)
+- **Socket API Token**: Set via `$SOCKET_API_TOKEN` environment variable or `--api-token` parameter
+- **CI/CD Artifacts**: Reports must be uploaded as `dependency_scanning` artifacts
+
+### Troubleshooting
+
+**Report not appearing in Security Dashboard:**
+- Verify the artifact is correctly configured in `.gitlab-ci.yml`
+- Check that the job succeeded and artifacts were uploaded
+- Ensure the report file follows the correct schema format
+
+**Empty vulnerabilities array:**
+- This is normal if no new security issues were detected
+- Check Socket.dev dashboard for full analysis details
+
 ## Development
 
 This project uses `pyproject.toml` as the primary dependency specification.

{socketsecurity-2.2.65 → socketsecurity-2.2.68}/README.md

@@ -79,6 +79,32 @@ This will:
 - Create a repository in Socket named like `my-repo-mobile-web`
 - Preserve git context (commits, branch info) from the repository root
 
+**Generate GitLab Security Dashboard report:**
+```bash
+socketcli --enable-gitlab-security \
+          --repo owner/repo \
+          --target-path .
+```
+
+This will:
+- Scan all manifest files in the current directory
+- Generate a GitLab-compatible Dependency Scanning report
+- Save to `gl-dependency-scanning-report.json`
+- Include all actionable security alerts (error/warn level)
+
+**Multiple output formats:**
+```bash
+socketcli --enable-json \
+          --enable-sarif \
+          --enable-gitlab-security \
+          --repo owner/repo
+```
+
+This will simultaneously generate:
+- JSON output to console
+- SARIF format to console
+- GitLab Security Dashboard report to file
+
 ### Requirements
 
 - Both `--sub-path` and `--workspace-name` must be specified together
@@ -88,14 +114,15 @@ This will:
 ## Usage
 
 ```` shell
-socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branch BRANCH] [--integration {api,github,gitlab,azure,bitbucket}] 
-          [--owner OWNER] [--pr-number PR_NUMBER] [--commit-message COMMIT_MESSAGE] [--commit-sha COMMIT_SHA] [--committers [COMMITTERS ...]] 
+socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branch BRANCH] [--integration {api,github,gitlab,azure,bitbucket}]
+          [--owner OWNER] [--pr-number PR_NUMBER] [--commit-message COMMIT_MESSAGE] [--commit-sha COMMIT_SHA] [--committers [COMMITTERS ...]]
           [--target-path TARGET_PATH] [--sbom-file SBOM_FILE] [--license-file-name LICENSE_FILE_NAME] [--save-submitted-files-list SAVE_SUBMITTED_FILES_LIST]
-          [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME] 
-          [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug] 
-          [--enable-json] [--enable-sarif] [--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue] 
-          [--ignore-commit-files] [--disable-blocking] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders] 
-          [--reach] [--reach-version REACH_VERSION] [--reach-analysis-timeout REACH_ANALYSIS_TIMEOUT] 
+          [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME]
+          [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug]
+          [--enable-json] [--enable-sarif] [--enable-gitlab-security] [--gitlab-security-file <path>]
+          [--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue]
+          [--ignore-commit-files] [--disable-blocking] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders]
+          [--reach] [--reach-version REACH_VERSION] [--reach-analysis-timeout REACH_ANALYSIS_TIMEOUT]
           [--reach-analysis-memory-limit REACH_ANALYSIS_MEMORY_LIMIT] [--reach-ecosystems REACH_ECOSYSTEMS] [--reach-exclude-paths REACH_EXCLUDE_PATHS]
           [--reach-min-severity {low,medium,high,critical}] [--reach-skip-cache] [--reach-disable-analytics] [--reach-output-file REACH_OUTPUT_FILE]
           [--only-facts-file] [--version]
@@ -154,6 +181,8 @@ If you don't want to provide the Socket API Token every time then you can use th
 | --enable-debug            | False    | False   | Enable debug logging                                                              |
 | --enable-json             | False    | False   | Output in JSON format                                                             |
 | --enable-sarif            | False    | False   | Enable SARIF output of results instead of table or JSON format                    |
+| --enable-gitlab-security  | False    | False   | Enable GitLab Security Dashboard output format (Dependency Scanning report)       |
+| --gitlab-security-file    | False    | gl-dependency-scanning-report.json | Output file path for GitLab Security report                |
 | --disable-overview        | False    | False   | Disable overview output                                                           |
 | --exclude-license-details | False    | False   | Exclude license details from the diff report (boosts performance for large repos) |
 | --version                 | False    | False   | Show program's version number and exit                                            |
@@ -193,6 +222,7 @@ The CLI will automatically install @coana-tech/cli if not present. Use `--reach`
 |:-------------------------|:---------|:--------|:----------------------------------------------------------------------|
 | --ignore-commit-files    | False    | False   | Ignore commit files                                                   |
 | --disable-blocking       | False    | False   | Disable blocking mode                                                 |
+| --strict-blocking        | False    | False   | Fail on ANY security policy violations (blocking severity), not just new ones. Only works in diff mode. See [Strict Blocking Mode](#strict-blocking-mode) for details. |
 | --enable-diff            | False    | False   | Enable diff mode even when using --integration api (forces diff mode without SCM integration) |
 | --scm                    | False    | api     | Source control management type                                        |
 | --timeout                | False    |         | Timeout in seconds for API requests                                   |
@@ -328,6 +358,99 @@ Bot mode (`bot_configs` array items):
 - `alert_types` (array, optional): Only send specific alert types
 - `reachability_alerts_only` (boolean, default: false): Only send reachable vulnerabilities when using `--reach`
 
+## Strict Blocking Mode
+
+The `--strict-blocking` flag enforces a zero-tolerance security policy by failing builds when **ANY** security violations with blocking severity exist, not just new ones introduced in the current changes.
+
+### Standard vs Strict Blocking Behavior
+
+**Standard Behavior (Default)**:
+- ✅ Passes if no NEW violations are introduced
+- ❌ Fails only on NEW violations from your changes
+- 🟡 Existing violations are ignored
+
+**Strict Blocking Behavior (`--strict-blocking`)**:
+- ✅ Passes only if NO violations exist (new or existing)
+- ❌ Fails on ANY violation (new OR existing)
+- 🔴 Enforces zero-tolerance policy
+
+### Usage Examples
+
+**Basic strict blocking:**
+```bash
+socketcli --target-path ./my-project --strict-blocking
+```
+
+**In GitLab CI:**
+```bash
+socketcli --target-path $CI_PROJECT_DIR --scm gitlab --pr-number ${CI_MERGE_REQUEST_IID:-0} --strict-blocking
+```
+
+**In GitHub Actions:**
+```bash
+socketcli --target-path $GITHUB_WORKSPACE --scm github --pr-number $PR_NUMBER --strict-blocking
+```
+
+### Output Differences
+
+**Standard scan output:**
+```
+Security issues detected by Socket Security:
+  - NEW blocking issues: 2
+  - NEW warning issues: 1
+```
+
+**Strict blocking scan output:**
+```
+Security issues detected by Socket Security:
+  - NEW blocking issues: 2
+  - NEW warning issues: 1
+  - EXISTING blocking issues: 5 (causing failure due to --strict-blocking)
+  - EXISTING warning issues: 3
+```
+
+### Use Cases
+
+1. **Zero-Tolerance Security Policy**: Enforce that no security violations exist in your codebase at any time
+2. **Gradual Security Improvement**: Use alongside standard scans to monitor existing violations while blocking new ones
+3. **Protected Branch Enforcement**: Require all violations to be resolved before merging to main/production
+4. **Security Audits**: Scheduled scans that fail if any violations accumulate
+
+### Important Notes
+
+- **Diff Mode Only**: The flag only works in diff mode (with SCM integration). In API mode, a warning is logged.
+- **Error-Level Only**: Only fails on `error=True` alerts (blocking severity), not warnings.
+- **Priority**: `--disable-blocking` takes precedence - if both flags are set, the build will always pass.
+- **First Scan**: On the very first scan of a repository, there are no "existing" violations, so behavior is identical to standard mode.
+
+### Flag Combinations
+
+**Strict blocking with debugging:**
+```bash
+socketcli --strict-blocking --enable-debug
+```
+
+**Strict blocking with JSON output:**
+```bash
+socketcli --strict-blocking --enable-json > security-report.json
+```
+
+**Override for testing** (passes even with violations):
+```bash
+socketcli --strict-blocking --disable-blocking
+```
+
+### Migration Strategy
+
+**Phase 1: Assessment** - Add strict scan with `allow_failure: true` in CI
+**Phase 2: Remediation** - Fix or triage all violations
+**Phase 3: Enforcement** - Set `allow_failure: false` to block merges
+
+For complete GitLab CI/CD examples, see:
+- [`.gitlab-ci-strict-blocking-demo.yml`](.gitlab-ci-strict-blocking-demo.yml) - Comprehensive demo
+- [`.gitlab-ci-strict-blocking-production.yml`](.gitlab-ci-strict-blocking-production.yml) - Production-ready template
+- [`STRICT-BLOCKING-GITLAB-CI.md`](STRICT-BLOCKING-GITLAB-CI.md) - Full documentation
+
 ## Automatic Git Detection
 
 The CLI now automatically detects repository information from your git environment, significantly simplifying usage in CI/CD pipelines:
@@ -530,9 +653,136 @@ The manifest archive feature is useful for:
 
 ### Differential scan skipped on octopus merge
 
-When your repo uses an **octopus merge** (3+ parents), the CLI may not detect all changed files.  
+When your repo uses an **octopus merge** (3+ parents), the CLI may not detect all changed files.
 This is expected Git behavior: the default diff only compares the merge result to the first parent.
 
+## GitLab Security Dashboard Integration
+
+Socket CLI can generate reports compatible with GitLab's Security Dashboard, allowing vulnerability information to be displayed directly in merge requests and security dashboards. This feature complements the existing [Socket GitLab integration](https://docs.socket.dev/docs/gitlab) by providing standardized dependency scanning reports.
+
+### Generating GitLab Security Reports
+
+To generate a GitLab-compatible security report:
+
+```bash
+socketcli --enable-gitlab-security --repo owner/repo
+```
+
+This creates a `gl-dependency-scanning-report.json` file following GitLab's Dependency Scanning report schema.
+
+### GitLab CI/CD Integration
+
+Add Socket Security scanning to your GitLab CI pipeline to generate Security Dashboard reports:
+
+```yaml
+# .gitlab-ci.yml
+socket_security_scan:
+  stage: security
+  image: python:3.11
+  before_script:
+    - pip install socketsecurity
+  script:
+    - socketcli
+        --api-token $SOCKET_API_TOKEN
+        --repo $CI_PROJECT_PATH
+        --branch $CI_COMMIT_REF_NAME
+        --commit-sha $CI_COMMIT_SHA
+        --enable-gitlab-security
+  artifacts:
+    reports:
+      dependency_scanning: gl-dependency-scanning-report.json
+    paths:
+      - gl-dependency-scanning-report.json
+    expire_in: 1 week
+  only:
+    - merge_requests
+    - main
+```
+
+**Note**: This Security Dashboard integration can be used alongside the [Socket GitLab App](https://docs.socket.dev/docs/gitlab) for comprehensive protection:
+- **Socket GitLab App**: Real-time PR comments, policy enforcement, and blocking
+- **Security Dashboard**: Centralized vulnerability tracking and reporting in GitLab's native interface
+
+### Custom Output Path
+
+Specify a custom output path for the GitLab security report:
+
+```bash
+socketcli --enable-gitlab-security --gitlab-security-file custom-path.json
+```
+
+### Multiple Output Formats
+
+GitLab security reports can be generated alongside other output formats:
+
+```bash
+socketcli --enable-json --enable-gitlab-security --enable-sarif
+```
+
+This command will:
+- Output JSON format to console
+- Save GitLab Security Dashboard report to `gl-dependency-scanning-report.json`
+- Save SARIF report (if configured)
+
+### Security Dashboard Features
+
+The GitLab Security Dashboard will display:
+- **Vulnerability Severity**: Critical, High, Medium, Low levels
+- **Affected Packages**: Package name, version, and ecosystem
+- **CVE Identifiers**: Direct links to CVE databases when available
+- **Dependency Chains**: Distinction between direct and transitive dependencies
+- **Remediation Suggestions**: Fix recommendations from Socket Security
+- **Alert Categories**: Supply chain risks, malware, vulnerabilities, and more
+
+### Alert Filtering
+
+The GitLab report includes **actionable security alerts** based on your Socket policy configuration:
+
+**Included Alerts** ✅:
+- **Error-level alerts** (`error: true`) - Security policy violations that block merges
+- **Warning-level alerts** (`warn: true`) - Important security concerns requiring attention
+
+**Excluded Alerts** ❌:
+- **Ignored alerts** (`ignore: true`) - Alerts explicitly ignored in your policy
+- **Monitor-only alerts** (`monitor: true` without error/warn) - Tracked but not actionable
+
+**Socket Alert Types Detected**:
+- Supply chain risks (malware, typosquatting, suspicious behavior)
+- Security vulnerabilities (CVEs, unsafe code patterns)
+- Risky permissions (network access, filesystem access, shell access)
+- License policy violations
+
+All alert types are included in the GitLab report if they're marked as `error` or `warn` by your Socket Security policy, ensuring the Security Dashboard shows only actionable findings.
+
+### Report Schema
+
+Socket CLI generates reports compliant with [GitLab Dependency Scanning schema version 15.0.0](https://docs.gitlab.com/ee/development/integrations/secure.html). The reports include:
+
+- **Scan metadata**: Analyzer and scanner information
+- **Vulnerabilities**: Detailed vulnerability data with:
+  - Unique deterministic UUIDs for tracking
+  - Package location and dependency information
+  - Severity levels mapped from Socket's analysis
+  - Socket-specific alert types and CVE identifiers
+  - Links to Socket.dev for detailed analysis
+
+### Requirements
+
+- **GitLab Version**: GitLab 12.0 or later (for Security Dashboard support)
+- **Socket API Token**: Set via `$SOCKET_API_TOKEN` environment variable or `--api-token` parameter
+- **CI/CD Artifacts**: Reports must be uploaded as `dependency_scanning` artifacts
+
+### Troubleshooting
+
+**Report not appearing in Security Dashboard:**
+- Verify the artifact is correctly configured in `.gitlab-ci.yml`
+- Check that the job succeeded and artifacts were uploaded
+- Ensure the report file follows the correct schema format
+
+**Empty vulnerabilities array:**
+- This is normal if no new security issues were detected
+- Check Socket.dev dashboard for full analysis details
+
 ## Development
 
 This project uses `pyproject.toml` as the primary dependency specification.

{socketsecurity-2.2.65 → socketsecurity-2.2.68}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.2.65"
+version = "2.2.68"
 requires-python = ">= 3.10"
 license = {"file" = "LICENSE"}
 dependencies = [

{socketsecurity-2.2.65 → socketsecurity-2.2.68}/socketsecurity/__init__.py

@@ -1,3 +1,3 @@
 __author__ = 'socket.dev'
-__version__ = '2.2.65'
+__version__ = '2.2.68'
 USER_AGENT = f'SocketPythonCLI/{__version__}'