| Name | socketsecurity JSON |
| Version |
2.2.11
JSON |
| download |
| home_page | None |
| Summary | Socket Security CLI for CI/CD |
| upload_time | 2025-09-12 19:30:48 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| 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. |
| keywords |
oss
sca
security
socket.dev
socketsecurity
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Socket Security CLI
The Socket Security CLI was created to enable integrations with other tools like GitHub Actions, GitLab, BitBucket, local use cases and more. The tool will get the head scan for the provided repo from Socket, create a new one, and then report any new alerts detected. If there are new alerts against the Socket security policy it'll exit with a non-Zero exit code.
## Quick Start
The CLI now features automatic detection of git repository information, making it much simpler to use in CI/CD environments. Most parameters are now optional and will be detected automatically from your git repository.
### Minimal Usage Examples
**GitHub Actions:**
```bash
socketcli --target-path $GITHUB_WORKSPACE --scm github --pr-number $PR_NUMBER
```
**GitLab CI:**
```bash
socketcli --target-path $CI_PROJECT_DIR --scm gitlab --pr-number ${CI_MERGE_REQUEST_IID:-0}
```
**Local Development:**
```bash
socketcli --target-path ./my-project
```
The CLI will automatically detect:
- Repository name from git remote
- Branch name from git
- Commit SHA and message from git
- Committer information from git
- Default branch status from git and CI environment
- Changed files from git commit history
## CI/CD Workflow Examples
Pre-configured workflow examples are available in the [`workflows/`](workflows/) directory:
- **[GitHub Actions](workflows/github-actions.yml)** - Complete workflow with concurrency control and automatic PR detection
- **[GitLab CI](workflows/gitlab-ci.yml)** - Pipeline configuration with caching and environment variable handling
- **[Bitbucket Pipelines](workflows/bitbucket-pipelines.yml)** - Basic pipeline setup with optional path filtering
These examples are production-ready and include best practices for each platform.
## Monorepo Workspace Support
The Socket CLI supports scanning specific workspaces within monorepo structures while preserving git context from the repository root. This is useful for organizations that maintain multiple applications or services in a single repository.
### Key Features
- **Multiple Sub-paths**: Specify multiple `--sub-path` options to scan different directories within your monorepo
- **Combined Workspace**: All sub-paths are scanned together as a single workspace in Socket
- **Git Context Preserved**: Repository metadata (commits, branches, etc.) comes from the main target-path
- **Workspace Naming**: Use `--workspace-name` to differentiate scans from different parts of your monorepo
### Usage Examples
**Scan multiple frontend and backend workspaces:**
```bash
socketcli --target-path /path/to/monorepo \
--sub-path frontend \
--sub-path backend \
--sub-path services/api \
--workspace-name main-app
```
**GitHub Actions for monorepo workspace:**
```bash
socketcli --target-path $GITHUB_WORKSPACE \
--sub-path packages/web \
--sub-path packages/mobile \
--workspace-name mobile-web \
--scm github \
--pr-number $PR_NUMBER
```
This will:
- Scan manifest files in `./packages/web/` and `./packages/mobile/`
- Combine them into a single workspace scan
- Create a repository in Socket named like `my-repo-mobile-web`
- Preserve git context (commits, branch info) from the repository root
### Requirements
- Both `--sub-path` and `--workspace-name` must be specified together
- `--sub-path` can be used multiple times to include multiple directories
- All specified sub-paths must exist within the target-path
## 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 ...]]
[--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] [--version]
````
If you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_KEY`
### Parameters
#### Authentication
| Parameter | Required | Default | Description |
|:------------|:---------|:--------|:--------------------------------------------------------------------------------|
| --api-token | False | | Socket Security API token (can also be set via SOCKET_SECURITY_API_KEY env var) |
#### Repository
| Parameter | Required | Default | Description |
|:-----------------|:---------|:--------|:------------------------------------------------------------------------|
| --repo | False | *auto* | Repository name in owner/repo format (auto-detected from git remote) |
| --repo-is-public | False | False | If set, flags a new repository creation as public. Defaults to false. |
| --integration | False | api | Integration type (api, github, gitlab, azure, bitbucket) |
| --owner | False | | Name of the integration owner, defaults to the socket organization slug |
| --branch | False | *auto* | Branch name (auto-detected from git) |
| --committers | False | *auto* | Committer(s) to filter by (auto-detected from git commit) |
#### Pull Request and Commit
| Parameter | Required | Default | Description |
|:-----------------|:---------|:--------|:-----------------------------------------------|
| --pr-number | False | "0" | Pull request number |
| --commit-message | False | *auto* | Commit message (auto-detected from git) |
| --commit-sha | False | *auto* | Commit SHA (auto-detected from git) |
#### Path and File
| Parameter | Required | Default | Description |
|:----------------------------|:---------|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| --target-path | False | ./ | Target path for analysis |
| --sbom-file | False | | SBOM file path |
| --license-file-name | False | `license_output.json` | Name of the file to save the license details to if enabled |
| --save-submitted-files-list | False | | Save list of submitted file names to JSON file for debugging purposes |
| --save-manifest-tar | False | | Save all manifest files to a compressed tar.gz archive with original directory structure |
| --files | False | *auto* | Files to analyze (JSON array string). Auto-detected from git commit changes when not specified |
| --sub-path | False | | Sub-path within target-path for manifest file scanning (can be specified multiple times). All sub-paths are combined into a single workspace scan while preserving git context from target-path. Must be used with --workspace-name |
| --workspace-name | False | | Workspace name suffix to append to repository name (repo-name-workspace_name). Must be used with --sub-path |
| --excluded-ecosystems | False | [] | List of ecosystems to exclude from analysis (JSON array string). You can get supported files from the [Supported Files API](https://docs.socket.dev/reference/getsupportedfiles) |
#### Branch and Scan Configuration
| Parameter | Required | Default | Description |
|:-------------------------|:---------|:--------|:------------------------------------------------------------------------------------------------------|
| --default-branch | False | *auto* | Make this branch the default branch (auto-detected from git and CI environment when not specified) |
| --pending-head | False | *auto* | If true, the new scan will be set as the branch's head scan (automatically synced with default-branch) |
| --include-module-folders | False | False | If enabled will include manifest files from folders like node_modules |
#### Output Configuration
| Parameter | Required | Default | Description |
|:--------------------------|:---------|:--------|:----------------------------------------------------------------------------------|
| --generate-license | False | False | Generate license information |
| --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 |
| --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 |
#### Security Configuration
| Parameter | Required | Default | Description |
|:-------------------------|:---------|:--------|:------------------------------|
| --allow-unverified | False | False | Allow unverified packages |
| --disable-security-issue | False | False | Disable security issue checks |
#### Advanced Configuration
| Parameter | Required | Default | Description |
|:-------------------------|:---------|:--------|:----------------------------------------------------------------------|
| --ignore-commit-files | False | False | Ignore commit files |
| --disable-blocking | False | False | Disable blocking mode |
| --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 |
#### Plugins
The Python CLI currently Supports the following plugins:
- Jira
- Slack
##### Jira
| Environment Variable | Required | Default | Description |
|:------------------------|:---------|:--------|:-----------------------------------|
| SOCKET_JIRA_ENABLED | False | false | Enables/Disables the Jira Plugin |
| SOCKET_JIRA_CONFIG_JSON | True | None | Required if the Plugin is enabled. |
Example `SOCKET_JIRA_CONFIG_JSON` value
````json
{"url": "https://REPLACE_ME.atlassian.net", "email": "example@example.com", "api_token": "REPLACE_ME", "project": "REPLACE_ME" }
````
##### Slack
| Environment Variable | Required | Default | Description |
|:-------------------------|:---------|:--------|:-----------------------------------|
| SOCKET_SLACK_ENABLED | False | false | Enables/Disables the Slack Plugin |
| SOCKET_SLACK_CONFIG_JSON | True | None | Required if the Plugin is enabled. |
Example `SOCKET_SLACK_CONFIG_JSON` value
````json
{"url": "https://REPLACE_ME_WEBHOOK"}
````
## Automatic Git Detection
The CLI now automatically detects repository information from your git environment, significantly simplifying usage in CI/CD pipelines:
### Auto-Detected Information
- **Repository name**: Extracted from git remote origin URL
- **Branch name**: Current git branch or CI environment variables
- **Commit SHA**: Latest commit hash or CI-provided commit SHA
- **Commit message**: Latest commit message
- **Committer information**: Git commit author details
- **Default branch status**: Determined from git repository and CI environment
- **Changed files**: Files modified in the current commit (for differential scanning)
### Default Branch Detection
The CLI uses intelligent default branch detection with the following priority:
1. **Explicit `--default-branch` flag**: Takes highest priority when specified
2. **CI environment detection**: Uses CI platform variables (GitHub Actions, GitLab CI)
3. **Git repository analysis**: Compares current branch with repository's default branch
4. **Fallback**: Defaults to `false` if none of the above methods succeed
Both `--default-branch` and `--pending-head` parameters are automatically synchronized to ensure consistent behavior.
## GitLab Token Configuration
The CLI supports GitLab integration with automatic authentication pattern detection for different token types.
### Supported Token Types
GitLab API supports two authentication methods, and the CLI automatically detects which one to use:
1. **Bearer Token Authentication** (`Authorization: Bearer <token>`)
- GitLab CI Job Tokens (`$CI_JOB_TOKEN`)
- Personal Access Tokens with `glpat-` prefix
- OAuth 2.0 tokens (long alphanumeric tokens)
2. **Private Token Authentication** (`PRIVATE-TOKEN: <token>`)
- Legacy personal access tokens
- Custom tokens that don't match Bearer patterns
### Token Detection Logic
The CLI automatically determines the authentication method using this logic:
```
if token == $CI_JOB_TOKEN:
use Bearer authentication
elif token starts with "glpat-":
use Bearer authentication
elif token is long (>40 chars) and alphanumeric:
use Bearer authentication
else:
use PRIVATE-TOKEN authentication
```
### Automatic Fallback
If the initial authentication method fails with a 401 error, the CLI automatically retries with the alternative method:
- **Bearer → PRIVATE-TOKEN**: If Bearer authentication fails, retry with PRIVATE-TOKEN
- **PRIVATE-TOKEN → Bearer**: If PRIVATE-TOKEN fails, retry with Bearer authentication
This ensures maximum compatibility across different GitLab configurations and token types.
### Environment Variables
| Variable | Description | Example |
|:---------|:------------|:--------|
| `GITLAB_TOKEN` | GitLab API token (required for GitLab integration) | `glpat-xxxxxxxxxxxxxxxxxxxx` |
| `CI_JOB_TOKEN` | GitLab CI job token (automatically used in GitLab CI) | Automatically provided by GitLab CI |
### Usage Examples
**GitLab CI with job token (recommended):**
```yaml
variables:
GITLAB_TOKEN: $CI_JOB_TOKEN
```
**GitLab CI with personal access token:**
```yaml
variables:
GITLAB_TOKEN: $GITLAB_PERSONAL_ACCESS_TOKEN # Set in GitLab project/group variables
```
**Local development:**
```bash
export GITLAB_TOKEN="glpat-your-personal-access-token"
socketcli --integration gitlab --repo owner/repo --pr-number 123
```
### Scan Behavior
The CLI determines scanning behavior intelligently:
- **Manifest files changed**: Performs differential scan with PR/MR comments when supported
- **No manifest files changed**: Creates full repository scan report without waiting for diff results
- **Force API mode**: When no supported manifest files are detected, automatically enables non-blocking mode
## File Selection Behavior
The CLI determines which files to scan based on the following logic:
1. **Git Commit Files (Default)**: The CLI automatically checks files changed in the current git commit. If any of these files match supported manifest patterns (like package.json, requirements.txt, etc.), a scan is triggered.
2. **`--files` Parameter Override**: When specified, this parameter takes precedence over git commit detection. It accepts a JSON array of file paths to check for manifest files.
3. **`--ignore-commit-files` Flag**: When set, git commit files are ignored completely, and the CLI will scan all manifest files in the target directory regardless of what changed.
4. **Automatic Fallback**: If no manifest files are found in git commit changes and no `--files` are specified, the CLI automatically switches to "API mode" and performs a full repository scan.
> **Important**: The CLI doesn't scan only the specified files - it uses them to determine whether a scan should be performed and what type of scan to run. When triggered, it searches the entire `--target-path` for all supported manifest files.
### Scanning Modes
- **Differential Mode**: When manifest files are detected in changes, performs a diff scan with PR/MR comment integration
- **API Mode**: When no manifest files are in changes, creates a full scan report without PR comments but still scans the entire repository
- **Force Mode**: With `--ignore-commit-files`, always performs a full scan regardless of changes
- **Forced Diff Mode**: With `--enable-diff`, forces differential mode even when using `--integration api` (without SCM integration)
### Examples
- **Commit with manifest file**: If your commit includes changes to `package.json`, a differential scan will be triggered automatically with PR comment integration.
- **Commit without manifest files**: If your commit only changes non-manifest files (like `.github/workflows/socket.yaml`), the CLI automatically switches to API mode and performs a full repository scan.
- **Using `--files`**: If you specify `--files '["package.json"]'`, the CLI will check if this file exists and is a manifest file before determining scan type.
- **Using `--ignore-commit-files`**: This forces a full scan of all manifest files in the target path, regardless of what's in your commit.
- **Using `--enable-diff`**: Forces diff mode without SCM integration - useful when you want differential scanning but are using `--integration api`. For example: `socketcli --integration api --enable-diff --target-path /path/to/repo`
- **Auto-detection**: Most CI/CD scenarios now work with just `socketcli --target-path /path/to/repo --scm github --pr-number $PR_NUM`
## Debugging and Troubleshooting
### Saving Submitted Files List
The CLI provides a debugging option to save the list of files that were submitted for scanning:
```bash
socketcli --save-submitted-files-list submitted_files.json
```
This will create a JSON file containing:
- Timestamp of when the scan was performed
- Total number of files submitted
- Total size of all files (in bytes and human-readable format)
- Complete list of file paths that were found and submitted for scanning
Example output file:
```json
{
"timestamp": "2025-01-22 10:30:45 UTC",
"total_files": 3,
"total_size_bytes": 2048,
"total_size_human": "2.00 KB",
"files": [
"./package.json",
"./requirements.txt",
"./Pipfile"
]
}
```
This feature is useful for:
- **Debugging**: Understanding which files the CLI found and submitted
- **Verification**: Confirming that expected manifest files are being detected
- **Size Analysis**: Understanding the total size of manifest files being uploaded
- **Troubleshooting**: Identifying why certain files might not be included in scans or if size limits are being hit
> **Note**: This option works with both differential scans (when git commits are detected) and full scans (API mode).
### Saving Manifest Files Archive
For backup, sharing, or analysis purposes, you can save all manifest files to a compressed tar.gz archive:
```bash
socketcli --save-manifest-tar manifest_files.tar.gz
```
This will create a compressed archive containing all the manifest files that were found and submitted for scanning, preserving their original directory structure relative to the scanned directory.
Example usage with other options:
```bash
# Save both files list and archive
socketcli --save-submitted-files-list files.json --save-manifest-tar backup.tar.gz
# Use with specific target path
socketcli --target-path ./my-project --save-manifest-tar my-project-manifests.tar.gz
```
The manifest archive feature is useful for:
- **Backup**: Creating portable backups of all dependency manifest files
- **Sharing**: Sending the exact files being analyzed to colleagues or support
- **Analysis**: Examining the dependency files offline or with other tools
- **Debugging**: Verifying file discovery and content issues
- **Compliance**: Maintaining records of scanned dependency files
> **Note**: The tar.gz archive preserves the original directory structure, making it easy to extract and examine the files in their proper context.
## Development
This project uses `pyproject.toml` as the primary dependency specification.
### Development Workflows
The following Make targets provide streamlined workflows for common development tasks:
#### Initial Setup (Choose One)
1. Standard Setup (using PyPI packages):
```bash
pyenv local 3.11 # Ensure correct Python version
make first-time-setup
```
2. Local Development Setup (for SDK development):
```bash
pyenv local 3.11 # Ensure correct Python version
SOCKET_SDK_PATH=~/path/to/socketdev make first-time-local-setup
```
The default SDK path is `../socketdev` if not specified.
#### Ongoing Development Tasks
After changing dependencies in pyproject.toml:
```bash
make update-deps
```
After pulling changes:
```bash
make sync-all
```
### Available Make targets:
High-level workflows:
- `make first-time-setup`: Complete setup using PyPI packages
- `make first-time-local-setup`: Complete setup for local SDK development
- `make update-lock`: Update uv.lock file after changing pyproject.toml
- `make sync-all`: Sync dependencies after pulling changes
- `make dev-setup`: Setup for local development (included in first-time-local-setup)
Implementation targets:
- `make local-dev`: Installs dependencies needed for local development
- `make setup`: Creates virtual environment and installs dependencies from uv.lock
- `make sync`: Installs exact versions from uv.lock
- `make clean`: Removes virtual environment and cache files
- `make test`: Runs pytest suite using uv run
- `make lint`: Runs ruff for code formatting and linting using uv run
### Environment Variables
#### Core Configuration
- `SOCKET_SECURITY_API_KEY`: Socket Security API token (alternative to --api-token parameter)
- `SOCKET_SDK_PATH`: Path to local socketdev repository (default: ../socketdev)
#### GitLab Integration
- `GITLAB_TOKEN`: GitLab API token for GitLab integration (supports both Bearer and PRIVATE-TOKEN authentication)
- `CI_JOB_TOKEN`: GitLab CI job token (automatically provided in GitLab CI environments)
Raw data
{
"_id": null,
"home_page": null,
"name": "socketsecurity",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Douglas Coburn <douglas@socket.dev>",
"keywords": "oss, sca, security, socket.dev, socketsecurity",
"author": null,
"author_email": "Douglas Coburn <douglas@socket.dev>",
"download_url": "https://files.pythonhosted.org/packages/90/6f/66814483f8325893f8e5e2350f97541918497f3e94a8eca00247a077045f/socketsecurity-2.2.11.tar.gz",
"platform": null,
"description": "# Socket Security CLI\n\nThe Socket Security CLI was created to enable integrations with other tools like GitHub Actions, GitLab, BitBucket, local use cases and more. The tool will get the head scan for the provided repo from Socket, create a new one, and then report any new alerts detected. If there are new alerts against the Socket security policy it'll exit with a non-Zero exit code.\n\n## Quick Start\n\nThe CLI now features automatic detection of git repository information, making it much simpler to use in CI/CD environments. Most parameters are now optional and will be detected automatically from your git repository.\n\n### Minimal Usage Examples\n\n**GitHub Actions:**\n```bash\nsocketcli --target-path $GITHUB_WORKSPACE --scm github --pr-number $PR_NUMBER\n```\n\n**GitLab CI:**\n```bash\nsocketcli --target-path $CI_PROJECT_DIR --scm gitlab --pr-number ${CI_MERGE_REQUEST_IID:-0}\n```\n\n**Local Development:**\n```bash\nsocketcli --target-path ./my-project\n```\n\nThe CLI will automatically detect:\n- Repository name from git remote\n- Branch name from git\n- Commit SHA and message from git\n- Committer information from git\n- Default branch status from git and CI environment\n- Changed files from git commit history\n\n## CI/CD Workflow Examples\n\nPre-configured workflow examples are available in the [`workflows/`](workflows/) directory:\n\n- **[GitHub Actions](workflows/github-actions.yml)** - Complete workflow with concurrency control and automatic PR detection\n- **[GitLab CI](workflows/gitlab-ci.yml)** - Pipeline configuration with caching and environment variable handling \n- **[Bitbucket Pipelines](workflows/bitbucket-pipelines.yml)** - Basic pipeline setup with optional path filtering\n\nThese examples are production-ready and include best practices for each platform.\n\n## Monorepo Workspace Support\n\nThe Socket CLI supports scanning specific workspaces within monorepo structures while preserving git context from the repository root. This is useful for organizations that maintain multiple applications or services in a single repository.\n\n### Key Features\n\n- **Multiple Sub-paths**: Specify multiple `--sub-path` options to scan different directories within your monorepo\n- **Combined Workspace**: All sub-paths are scanned together as a single workspace in Socket\n- **Git Context Preserved**: Repository metadata (commits, branches, etc.) comes from the main target-path\n- **Workspace Naming**: Use `--workspace-name` to differentiate scans from different parts of your monorepo\n\n### Usage Examples\n\n**Scan multiple frontend and backend workspaces:**\n```bash\nsocketcli --target-path /path/to/monorepo \\\n --sub-path frontend \\\n --sub-path backend \\\n --sub-path services/api \\\n --workspace-name main-app\n```\n\n**GitHub Actions for monorepo workspace:**\n```bash\nsocketcli --target-path $GITHUB_WORKSPACE \\\n --sub-path packages/web \\\n --sub-path packages/mobile \\\n --workspace-name mobile-web \\\n --scm github \\\n --pr-number $PR_NUMBER\n```\n\nThis will:\n- Scan manifest files in `./packages/web/` and `./packages/mobile/`\n- Combine them into a single workspace scan\n- Create a repository in Socket named like `my-repo-mobile-web`\n- Preserve git context (commits, branch info) from the repository root\n\n### Requirements\n\n- Both `--sub-path` and `--workspace-name` must be specified together\n- `--sub-path` can be used multiple times to include multiple directories\n- All specified sub-paths must exist within the target-path\n\n## Usage\n\n```` shell\nsocketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branch BRANCH] [--integration {api,github,gitlab,azure,bitbucket}] \n [--owner OWNER] [--pr-number PR_NUMBER] [--commit-message COMMIT_MESSAGE] [--commit-sha COMMIT_SHA] [--committers [COMMITTERS ...]] \n [--target-path TARGET_PATH] [--sbom-file SBOM_FILE] [--license-file-name LICENSE_FILE_NAME] [--save-submitted-files-list SAVE_SUBMITTED_FILES_LIST]\n [--save-manifest-tar SAVE_MANIFEST_TAR] [--files FILES] [--sub-path SUB_PATH] [--workspace-name WORKSPACE_NAME] \n [--excluded-ecosystems EXCLUDED_ECOSYSTEMS] [--default-branch] [--pending-head] [--generate-license] [--enable-debug] \n [--enable-json] [--enable-sarif] [--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue] \n [--ignore-commit-files] [--disable-blocking] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders] [--version]\n````\n\nIf you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_KEY`\n\n### Parameters\n\n#### Authentication\n| Parameter | Required | Default | Description |\n|:------------|:---------|:--------|:--------------------------------------------------------------------------------|\n| --api-token | False | | Socket Security API token (can also be set via SOCKET_SECURITY_API_KEY env var) |\n\n#### Repository\n| Parameter | Required | Default | Description |\n|:-----------------|:---------|:--------|:------------------------------------------------------------------------|\n| --repo | False | *auto* | Repository name in owner/repo format (auto-detected from git remote) |\n| --repo-is-public | False | False | If set, flags a new repository creation as public. Defaults to false. |\n| --integration | False | api | Integration type (api, github, gitlab, azure, bitbucket) |\n| --owner | False | | Name of the integration owner, defaults to the socket organization slug |\n| --branch | False | *auto* | Branch name (auto-detected from git) |\n| --committers | False | *auto* | Committer(s) to filter by (auto-detected from git commit) |\n\n#### Pull Request and Commit\n| Parameter | Required | Default | Description |\n|:-----------------|:---------|:--------|:-----------------------------------------------|\n| --pr-number | False | \"0\" | Pull request number |\n| --commit-message | False | *auto* | Commit message (auto-detected from git) |\n| --commit-sha | False | *auto* | Commit SHA (auto-detected from git) |\n\n#### Path and File\n| Parameter | Required | Default | Description |\n|:----------------------------|:---------|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| --target-path | False | ./ | Target path for analysis |\n| --sbom-file | False | | SBOM file path |\n| --license-file-name | False | `license_output.json` | Name of the file to save the license details to if enabled |\n| --save-submitted-files-list | False | | Save list of submitted file names to JSON file for debugging purposes |\n| --save-manifest-tar | False | | Save all manifest files to a compressed tar.gz archive with original directory structure |\n| --files | False | *auto* | Files to analyze (JSON array string). Auto-detected from git commit changes when not specified |\n| --sub-path | False | | Sub-path within target-path for manifest file scanning (can be specified multiple times). All sub-paths are combined into a single workspace scan while preserving git context from target-path. Must be used with --workspace-name |\n| --workspace-name | False | | Workspace name suffix to append to repository name (repo-name-workspace_name). Must be used with --sub-path |\n| --excluded-ecosystems | False | [] | List of ecosystems to exclude from analysis (JSON array string). You can get supported files from the [Supported Files API](https://docs.socket.dev/reference/getsupportedfiles) |\n\n#### Branch and Scan Configuration\n| Parameter | Required | Default | Description |\n|:-------------------------|:---------|:--------|:------------------------------------------------------------------------------------------------------|\n| --default-branch | False | *auto* | Make this branch the default branch (auto-detected from git and CI environment when not specified) |\n| --pending-head | False | *auto* | If true, the new scan will be set as the branch's head scan (automatically synced with default-branch) |\n| --include-module-folders | False | False | If enabled will include manifest files from folders like node_modules |\n\n#### Output Configuration\n| Parameter | Required | Default | Description |\n|:--------------------------|:---------|:--------|:----------------------------------------------------------------------------------|\n| --generate-license | False | False | Generate license information |\n| --enable-debug | False | False | Enable debug logging |\n| --enable-json | False | False | Output in JSON format |\n| --enable-sarif | False | False | Enable SARIF output of results instead of table or JSON format |\n| --disable-overview | False | False | Disable overview output |\n| --exclude-license-details | False | False | Exclude license details from the diff report (boosts performance for large repos) |\n| --version | False | False | Show program's version number and exit |\n\n#### Security Configuration\n| Parameter | Required | Default | Description |\n|:-------------------------|:---------|:--------|:------------------------------|\n| --allow-unverified | False | False | Allow unverified packages |\n| --disable-security-issue | False | False | Disable security issue checks |\n\n#### Advanced Configuration\n| Parameter | Required | Default | Description |\n|:-------------------------|:---------|:--------|:----------------------------------------------------------------------|\n| --ignore-commit-files | False | False | Ignore commit files |\n| --disable-blocking | False | False | Disable blocking mode |\n| --enable-diff | False | False | Enable diff mode even when using --integration api (forces diff mode without SCM integration) |\n| --scm | False | api | Source control management type |\n| --timeout | False | | Timeout in seconds for API requests |\n\n#### Plugins\n\nThe Python CLI currently Supports the following plugins:\n\n- Jira\n- Slack\n\n##### Jira\n\n| Environment Variable | Required | Default | Description |\n|:------------------------|:---------|:--------|:-----------------------------------|\n| SOCKET_JIRA_ENABLED | False | false | Enables/Disables the Jira Plugin |\n| SOCKET_JIRA_CONFIG_JSON | True | None | Required if the Plugin is enabled. |\n\nExample `SOCKET_JIRA_CONFIG_JSON` value\n\n````json\n{\"url\": \"https://REPLACE_ME.atlassian.net\", \"email\": \"example@example.com\", \"api_token\": \"REPLACE_ME\", \"project\": \"REPLACE_ME\" }\n````\n\n##### Slack\n\n| Environment Variable | Required | Default | Description |\n|:-------------------------|:---------|:--------|:-----------------------------------|\n| SOCKET_SLACK_ENABLED | False | false | Enables/Disables the Slack Plugin |\n| SOCKET_SLACK_CONFIG_JSON | True | None | Required if the Plugin is enabled. |\n\nExample `SOCKET_SLACK_CONFIG_JSON` value\n\n````json\n{\"url\": \"https://REPLACE_ME_WEBHOOK\"}\n````\n\n## Automatic Git Detection\n\nThe CLI now automatically detects repository information from your git environment, significantly simplifying usage in CI/CD pipelines:\n\n### Auto-Detected Information\n\n- **Repository name**: Extracted from git remote origin URL\n- **Branch name**: Current git branch or CI environment variables\n- **Commit SHA**: Latest commit hash or CI-provided commit SHA\n- **Commit message**: Latest commit message\n- **Committer information**: Git commit author details\n- **Default branch status**: Determined from git repository and CI environment\n- **Changed files**: Files modified in the current commit (for differential scanning)\n\n### Default Branch Detection\n\nThe CLI uses intelligent default branch detection with the following priority:\n\n1. **Explicit `--default-branch` flag**: Takes highest priority when specified\n2. **CI environment detection**: Uses CI platform variables (GitHub Actions, GitLab CI)\n3. **Git repository analysis**: Compares current branch with repository's default branch\n4. **Fallback**: Defaults to `false` if none of the above methods succeed\n\nBoth `--default-branch` and `--pending-head` parameters are automatically synchronized to ensure consistent behavior.\n\n## GitLab Token Configuration\n\nThe CLI supports GitLab integration with automatic authentication pattern detection for different token types.\n\n### Supported Token Types\n\nGitLab API supports two authentication methods, and the CLI automatically detects which one to use:\n\n1. **Bearer Token Authentication** (`Authorization: Bearer <token>`)\n - GitLab CI Job Tokens (`$CI_JOB_TOKEN`)\n - Personal Access Tokens with `glpat-` prefix\n - OAuth 2.0 tokens (long alphanumeric tokens)\n\n2. **Private Token Authentication** (`PRIVATE-TOKEN: <token>`)\n - Legacy personal access tokens\n - Custom tokens that don't match Bearer patterns\n\n### Token Detection Logic\n\nThe CLI automatically determines the authentication method using this logic:\n\n```\nif token == $CI_JOB_TOKEN:\n use Bearer authentication\nelif token starts with \"glpat-\":\n use Bearer authentication \nelif token is long (>40 chars) and alphanumeric:\n use Bearer authentication\nelse:\n use PRIVATE-TOKEN authentication\n```\n\n### Automatic Fallback\n\nIf the initial authentication method fails with a 401 error, the CLI automatically retries with the alternative method:\n\n- **Bearer \u2192 PRIVATE-TOKEN**: If Bearer authentication fails, retry with PRIVATE-TOKEN\n- **PRIVATE-TOKEN \u2192 Bearer**: If PRIVATE-TOKEN fails, retry with Bearer authentication\n\nThis ensures maximum compatibility across different GitLab configurations and token types.\n\n### Environment Variables\n\n| Variable | Description | Example |\n|:---------|:------------|:--------|\n| `GITLAB_TOKEN` | GitLab API token (required for GitLab integration) | `glpat-xxxxxxxxxxxxxxxxxxxx` |\n| `CI_JOB_TOKEN` | GitLab CI job token (automatically used in GitLab CI) | Automatically provided by GitLab CI |\n\n### Usage Examples\n\n**GitLab CI with job token (recommended):**\n```yaml\nvariables:\n GITLAB_TOKEN: $CI_JOB_TOKEN\n```\n\n**GitLab CI with personal access token:**\n```yaml\nvariables:\n GITLAB_TOKEN: $GITLAB_PERSONAL_ACCESS_TOKEN # Set in GitLab project/group variables\n```\n\n**Local development:**\n```bash\nexport GITLAB_TOKEN=\"glpat-your-personal-access-token\"\nsocketcli --integration gitlab --repo owner/repo --pr-number 123\n```\n\n### Scan Behavior\n\nThe CLI determines scanning behavior intelligently:\n\n- **Manifest files changed**: Performs differential scan with PR/MR comments when supported\n- **No manifest files changed**: Creates full repository scan report without waiting for diff results\n- **Force API mode**: When no supported manifest files are detected, automatically enables non-blocking mode\n\n## File Selection Behavior\n\nThe CLI determines which files to scan based on the following logic:\n\n1. **Git Commit Files (Default)**: The CLI automatically checks files changed in the current git commit. If any of these files match supported manifest patterns (like package.json, requirements.txt, etc.), a scan is triggered.\n\n2. **`--files` Parameter Override**: When specified, this parameter takes precedence over git commit detection. It accepts a JSON array of file paths to check for manifest files.\n\n3. **`--ignore-commit-files` Flag**: When set, git commit files are ignored completely, and the CLI will scan all manifest files in the target directory regardless of what changed.\n\n4. **Automatic Fallback**: If no manifest files are found in git commit changes and no `--files` are specified, the CLI automatically switches to \"API mode\" and performs a full repository scan.\n\n> **Important**: The CLI doesn't scan only the specified files - it uses them to determine whether a scan should be performed and what type of scan to run. When triggered, it searches the entire `--target-path` for all supported manifest files.\n\n### Scanning Modes\n\n- **Differential Mode**: When manifest files are detected in changes, performs a diff scan with PR/MR comment integration\n- **API Mode**: When no manifest files are in changes, creates a full scan report without PR comments but still scans the entire repository\n- **Force Mode**: With `--ignore-commit-files`, always performs a full scan regardless of changes\n- **Forced Diff Mode**: With `--enable-diff`, forces differential mode even when using `--integration api` (without SCM integration)\n\n### Examples\n\n- **Commit with manifest file**: If your commit includes changes to `package.json`, a differential scan will be triggered automatically with PR comment integration.\n- **Commit without manifest files**: If your commit only changes non-manifest files (like `.github/workflows/socket.yaml`), the CLI automatically switches to API mode and performs a full repository scan.\n- **Using `--files`**: If you specify `--files '[\"package.json\"]'`, the CLI will check if this file exists and is a manifest file before determining scan type.\n- **Using `--ignore-commit-files`**: This forces a full scan of all manifest files in the target path, regardless of what's in your commit.\n- **Using `--enable-diff`**: Forces diff mode without SCM integration - useful when you want differential scanning but are using `--integration api`. For example: `socketcli --integration api --enable-diff --target-path /path/to/repo`\n- **Auto-detection**: Most CI/CD scenarios now work with just `socketcli --target-path /path/to/repo --scm github --pr-number $PR_NUM`\n\n## Debugging and Troubleshooting\n\n### Saving Submitted Files List\n\nThe CLI provides a debugging option to save the list of files that were submitted for scanning:\n\n```bash\nsocketcli --save-submitted-files-list submitted_files.json\n```\n\nThis will create a JSON file containing:\n- Timestamp of when the scan was performed\n- Total number of files submitted\n- Total size of all files (in bytes and human-readable format)\n- Complete list of file paths that were found and submitted for scanning\n\nExample output file:\n```json\n{\n \"timestamp\": \"2025-01-22 10:30:45 UTC\",\n \"total_files\": 3,\n \"total_size_bytes\": 2048,\n \"total_size_human\": \"2.00 KB\",\n \"files\": [\n \"./package.json\",\n \"./requirements.txt\",\n \"./Pipfile\"\n ]\n}\n```\n\nThis feature is useful for:\n- **Debugging**: Understanding which files the CLI found and submitted\n- **Verification**: Confirming that expected manifest files are being detected\n- **Size Analysis**: Understanding the total size of manifest files being uploaded\n- **Troubleshooting**: Identifying why certain files might not be included in scans or if size limits are being hit\n\n> **Note**: This option works with both differential scans (when git commits are detected) and full scans (API mode).\n\n### Saving Manifest Files Archive\n\nFor backup, sharing, or analysis purposes, you can save all manifest files to a compressed tar.gz archive:\n\n```bash\nsocketcli --save-manifest-tar manifest_files.tar.gz\n```\n\nThis will create a compressed archive containing all the manifest files that were found and submitted for scanning, preserving their original directory structure relative to the scanned directory.\n\nExample usage with other options:\n```bash\n# Save both files list and archive\nsocketcli --save-submitted-files-list files.json --save-manifest-tar backup.tar.gz\n\n# Use with specific target path\nsocketcli --target-path ./my-project --save-manifest-tar my-project-manifests.tar.gz\n```\n\nThe manifest archive feature is useful for:\n- **Backup**: Creating portable backups of all dependency manifest files\n- **Sharing**: Sending the exact files being analyzed to colleagues or support\n- **Analysis**: Examining the dependency files offline or with other tools\n- **Debugging**: Verifying file discovery and content issues\n- **Compliance**: Maintaining records of scanned dependency files\n\n> **Note**: The tar.gz archive preserves the original directory structure, making it easy to extract and examine the files in their proper context.\n\n## Development\n\nThis project uses `pyproject.toml` as the primary dependency specification.\n\n### Development Workflows\n\nThe following Make targets provide streamlined workflows for common development tasks:\n\n#### Initial Setup (Choose One)\n\n1. Standard Setup (using PyPI packages):\n```bash\npyenv local 3.11 # Ensure correct Python version\nmake first-time-setup\n```\n\n2. Local Development Setup (for SDK development):\n```bash\npyenv local 3.11 # Ensure correct Python version\nSOCKET_SDK_PATH=~/path/to/socketdev make first-time-local-setup\n```\nThe default SDK path is `../socketdev` if not specified.\n\n#### Ongoing Development Tasks\n\nAfter changing dependencies in pyproject.toml:\n```bash\nmake update-deps\n```\n\nAfter pulling changes:\n```bash\nmake sync-all\n```\n\n### Available Make targets:\n\nHigh-level workflows:\n- `make first-time-setup`: Complete setup using PyPI packages\n- `make first-time-local-setup`: Complete setup for local SDK development\n- `make update-lock`: Update uv.lock file after changing pyproject.toml\n- `make sync-all`: Sync dependencies after pulling changes\n- `make dev-setup`: Setup for local development (included in first-time-local-setup)\n\nImplementation targets:\n- `make local-dev`: Installs dependencies needed for local development\n- `make setup`: Creates virtual environment and installs dependencies from uv.lock\n- `make sync`: Installs exact versions from uv.lock\n- `make clean`: Removes virtual environment and cache files\n- `make test`: Runs pytest suite using uv run\n- `make lint`: Runs ruff for code formatting and linting using uv run\n\n### Environment Variables\n\n#### Core Configuration\n- `SOCKET_SECURITY_API_KEY`: Socket Security API token (alternative to --api-token parameter)\n- `SOCKET_SDK_PATH`: Path to local socketdev repository (default: ../socketdev)\n\n#### GitLab Integration\n- `GITLAB_TOKEN`: GitLab API token for GitLab integration (supports both Bearer and PRIVATE-TOKEN authentication)\n- `CI_JOB_TOKEN`: GitLab CI job token (automatically provided in GitLab CI environments)\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2022 Socket Inc\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Socket Security CLI for CI/CD",
"version": "2.2.11",
"project_urls": {
"Homepage": "https://socket.dev"
},
"split_keywords": [
"oss",
" sca",
" security",
" socket.dev",
" socketsecurity"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4895397bf7dea8281370a823b5d4e83fa6d75521ffe122cdfb9f9b66e06e3d0a",
"md5": "8a53d0b9f3125055da0ce30d3f4e13c5",
"sha256": "36ae101a5d520c66523450407754edf33b5a142be80239870fbcc46d4ce4cb06"
},
"downloads": -1,
"filename": "socketsecurity-2.2.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8a53d0b9f3125055da0ce30d3f4e13c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 75225,
"upload_time": "2025-09-12T19:30:46",
"upload_time_iso_8601": "2025-09-12T19:30:46.522223Z",
"url": "https://files.pythonhosted.org/packages/48/95/397bf7dea8281370a823b5d4e83fa6d75521ffe122cdfb9f9b66e06e3d0a/socketsecurity-2.2.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "906f66814483f8325893f8e5e2350f97541918497f3e94a8eca00247a077045f",
"md5": "b71b39dc55edeed5d0334b658e114aba",
"sha256": "6b66231c359c3b360597c34996e5a56a6477d1270a22e8288d7e235eec20eabe"
},
"downloads": -1,
"filename": "socketsecurity-2.2.11.tar.gz",
"has_sig": false,
"md5_digest": "b71b39dc55edeed5d0334b658e114aba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 740824,
"upload_time": "2025-09-12T19:30:48",
"upload_time_iso_8601": "2025-09-12T19:30:48.149940Z",
"url": "https://files.pythonhosted.org/packages/90/6f/66814483f8325893f8e5e2350f97541918497f3e94a8eca00247a077045f/socketsecurity-2.2.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 19:30:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "socketsecurity"
}
