Socket Security Python SDK

3.0.32 · active · verified Fri Apr 17

The Socket Security Python SDK provides an interface to interact with the Socket API for software supply chain security scanning. It allows users to scan packages, retrieve security insights, and manage their Socket account programmatically. The current version is 3.0.32, and it follows an active release cadence with regular updates.

Common errors

```
AttributeError: 'SocketSDKClient' object has no attribute 'get_package_scorecard'
```
cause Attempting to call a method that was removed or renamed in `socketdev` v3.0.0. `get_package_scorecard` was removed.

fix This method has been deprecated and removed. For package insights, rely on the `scan_package` method and its comprehensive `ScanPackageResult` object. If specific scorecard data is needed, consult Socket's updated API documentation for alternatives.
```
socketdev.exceptions.SocketApiException: 401 Unauthorized - Invalid API key.
```
cause The API key provided is missing, incorrect, or expired.

fix Verify that your `SOCKET_API_KEY` environment variable is correctly set or that the `api_key` argument passed to `SocketSDKClient` contains a valid, active Socket API key. Regenerate the key in your Socket account if necessary.
```
TypeError: scan_package() got an unexpected keyword argument 'package_name'
```
cause Using an old parameter name (`package_name`) from `socketdev` v2.x with a v3.x client.

fix Update your `scan_package` call to use the new parameter names: `package` instead of `package_name`, `version` instead of `package_version`, and `ecosystem` instead of `package_type`.

Warnings

breaking Version 3.0.0 introduced significant breaking changes. The `scan_package` method's parameters were updated (`package_name` changed to `package`, `package_version` changed to `version`, `package_type` changed to `ecosystem`). Many methods like `get_package_scorecard` and `get_package_advisories` were removed or renamed. Return types for API calls also changed from dictionaries to Pydantic models.
Fix: Review the official documentation and migration guide for `socketdev` 3.x. Update method signatures, parameter names, and how return values are accessed (e.g., `result.status` instead of `result['status']`). If upgrading from 2.x, carefully check all API calls.
gotcha Authentication requires an API key, which can be passed directly to the `SocketSDKClient` constructor via the `api_key` argument or read from the `SOCKET_API_KEY` environment variable. Failing to provide a valid key will result in `401 Unauthorized` errors.
Fix: Ensure `os.environ['SOCKET_API_KEY']` is set before initializing the client, or explicitly pass `api_key='YOUR_API_KEY'` during client instantiation. Always protect your API key.
gotcha The `scan_package` method takes an `ecosystem` argument (e.g., 'npm', 'pypi', 'composer') instead of a generic 'package_type'. Using an incorrect or unsupported ecosystem will lead to API errors or incorrect scan results.
Fix: Refer to the Socket API documentation for the list of supported `ecosystem` values. For Python packages, use `ecosystem='pypi'`.

Install

pip install socketdev Install latest version

Imports

SocketSDKClient
wrong:
```
from socketdev.client import SocketSDKClient
```
correct:
```
from socketdev import SocketSDKClient
```
The client class is directly exposed under the top-level 'socketdev' package since v3.0.0, avoiding deeper imports.

Quickstart

Initializes the SocketSDKClient using an API key (preferably from an environment variable) and performs a basic package scan. Demonstrates handling of the returned `ScanPackageResult` object.

import os
import socketdev

# Ensure you have SOCKET_API_KEY set as an environment variable or pass api_key directly
# e.g., os.environ['SOCKET_API_KEY'] = 'your_api_key_here'

try:
    client = socketdev.SocketSDKClient(api_key=os.environ.get('SOCKET_API_KEY', ''))

    # Example: Scan a package (npm, lodash, v4.17.21)
    result = client.scan_package(
        ecosystem="npm", 
        package="lodash", 
        version="4.17.21", 
        options={"allow_insecure_versions": True}
    )
    print(f"Scan status: {result.status}")
    print(f"Issue count: {result.issues_count}")
    
    # Accessing specific issues if available
    if result.issues:
        print("First issue type:", result.issues[0].issue_type)

except socketdev.exceptions.SocketApiException as e:
    print(f"API Error: {e.status_code} - {e.message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →