### Start the Firewall with Docker
Source: https://docs.socket.dev/docs/registry-mode-setup-downstream
Commands to pull the firewall image and start the service using Docker Compose.
```bash
docker pull socketdev/socket-registry-firewall
docker compose up -d
```
--------------------------------
### Start Firewall Service
Source: https://docs.socket.dev/docs/registry-mode-upstream-deployment-guide
Pull the latest image, start the container, and verify the health endpoint.
```bash
docker pull socketdev/socket-registry-firewall
docker compose up -d
curl -k https://socket-firewall.internal.company.com:8443/health
```
--------------------------------
### Socket CI Command Examples
Source: https://docs.socket.dev/docs/socket-ci
Provides examples of how to use the `socket ci` command, demonstrating its basic usage and the use of the `--autoManifest` flag for including locally generated manifest files.
```bash
$ socket ci
$ socket ci --autoManifest
```
--------------------------------
### View Discovered Routes Example
Source: https://docs.socket.dev/docs/registry-mode-configuration-reference
Example output of routes automatically discovered by the firewall.
```text
/npm-public → https://registry.npmjs.org
/pypi-public → https://pypi.org
/maven-central → https://repo1.maven.org/maven2
/cargo-crates → https://index.crates.io
```
--------------------------------
### Install Socket SDK
Source: https://docs.socket.dev/docs/socket-typescript-sdk
Install the package via npm.
```bash
npm install @socketsecurity/sdk
```
--------------------------------
### Manually Install Socket Firewall on macOS
Source: https://docs.socket.dev/docs/socket-firewall-free
These commands guide the manual installation of Socket Firewall Free on macOS. It involves downloading the binary, making it executable, and moving it to a directory in the system's PATH. The `xattr` command is included to handle potential macOS security restrictions on unsigned binaries.
```bash
# Download the binary (replace with actual release URL)
curl -L -o sfw https://github.com/SocketDev/sfw-free/releases/latest/download/sfw-darwin-arm64
chmod +x sfw
sudo mv sfw /usr/local/bin/
# If needed for unsigned binaries on macOS:
xattr -dr com.apple.quarantine ./path/to/sfw
```
--------------------------------
### Docker Build, Push, and Start Commands
Source: https://docs.socket.dev/docs/installations
These bash commands are used to build the Docker image for the Socket Firewall, optionally push it to a private registry with version tagging, and then start the firewall service using Docker Compose.
```bash
# Build the image
docker compose build
# (Optional) Push to private registry
docker tag my-registry.company.com/socket-firewall:latest \
my-registry.company.com/socket-firewall:1.1.94
docker push my-registry.company.com/socket-firewall:latest
docker push my-registry.company.com/socket-firewall:1.1.94
# Start the firewall
docker compose up -d
# View logs
docker compose logs -f socket-firewall
```
--------------------------------
### Troubleshoot Package Installation
Source: https://docs.socket.dev/docs/registry-mode-setup-downstream
Commands to verify firewall connectivity and check for blocked packages.
```bash
docker compose logs socket-firewall | grep -i block # check if blocked by policy
curl -kI https://localhost:8443/health # verify firewall is up
docker compose exec socket-firewall curl -I https://registry.npmjs.org # test upstream
```
--------------------------------
### Filtering Logs Examples
Source: https://docs.socket.dev/docs/registry-mode-configuration-reference
Examples of how to filter and search through the firewall logs using `docker compose logs` and `grep`.
```APIDOC
## Filtering Logs Examples
Examples of how to filter and search through the firewall logs using `docker compose logs` and `grep`.
### Examples
```bash
# All security decisions
docker compose logs socket-firewall | grep SOCKET_DECISION
# Only blocked packages
docker compose logs socket-firewall | grep SOCKET_DECISION | grep '"decision":"blocked"'
# Decisions for a specific package
docker compose logs socket-firewall | grep SOCKET_DECISION | grep 'lodash'
# Metadata filtering decisions
docker compose logs socket-firewall | grep SOCKET_DECISION | grep '"block_source":"metadata"'
```
```
--------------------------------
### Run Package Manager Commands with Socket Firewall
Source: https://docs.socket.dev/docs/socket-firewall-free
These examples demonstrate how to prefix package manager commands with `sfw` to enable network traffic filtering. This ensures that dependencies are checked for malicious content before installation or fetching.
```bash
sfw npm install --save some-package@1.33.7
sfw cargo fetch
sfw uv pip install flask
```
--------------------------------
### Display Socket login help information
Source: https://docs.socket.dev/docs/socket-login
View usage instructions, available options, and examples for the login command.
```shell
$ socket login --help
Socket API login
Usage
$ socket login [options]
API Token Requirements
- Quota: 1 unit
Logs into the Socket API by prompting for an API key
Options
--apiBaseUrl API server to connect to for login
--apiProxy Proxy to use when making connection to API server
Examples
$ socket login
$ socket login --api-proxy=http://localhost:1234
```
--------------------------------
### Install Socket Python SDK
Source: https://docs.socket.dev/docs/socket-python-sdk
Instructions to install the Socket Python SDK by cloning the official GitHub repository. This is the first step to begin using the SDK.
```bash
git clone https://github.com/SocketDev/socket-sdk-python.git
```
--------------------------------
### Depscore Tool Parameters and Example Usage
Source: https://docs.socket.dev/docs/guide-to-socket-mcp
Demonstrates the parameters required for the `depscore` tool, which queries the Socket API for dependency scoring information. It includes an example JSON payload for analyzing multiple packages across different ecosystems and their versions.
```json
{
"packages": [
{
"ecosystem": "npm",
"depname": "express",
"version": "4.18.2"
},
{
"ecosystem": "pypi",
"depname": "fastapi",
"version": "0.100.0"
}
]
}
```
--------------------------------
### Start and Verify Socket Firewall
Source: https://docs.socket.dev/docs/installations
Commands to pull the latest firewall image, start the service in detached mode, and verify its health.
```bash
docker pull socketdev/socket-registry-firewall:latest
docker compose up -d
```
```bash
# Check health endpoint
curl -fk https://localhost:8443/health
# Expected: {"status":"healthy","version":"1.x.x"}
# View logs
docker compose logs -f socket-firewall
```
--------------------------------
### Install Basic Dependencies and Lua Libraries for Dockerfile
Source: https://docs.socket.dev/docs/installations
This Dockerfile snippet installs essential packages like curl and git, and then clones and installs several lua-resty libraries (http, openssl, redis) into the OpenResty environment. It prefers IPv4 over IPv6 for network connections.
```dockerfile
RUN apk add --no-cache curl ca-certificates git openssl bash && \
# Prefer IPv4 over IPv6 to avoid upstream IPv6 connection attempts
printf 'precedence ::ffff:0:0/96 100' >> /etc/gai.conf || true
# Install lua-resty libraries
RUN cd /tmp && \
# Install lua-resty-http
git clone https://github.com/ledgetech/lua-resty-http.git && \
cd lua-resty-http && \
cp -r lib/resty/* /usr/local/openresty/lualib/resty/ && \
cd /tmp && \
# Install lua-resty-openssl (needed for HTTPS)
git clone https://github.com/fffonion/lua-resty-openssl.git && \
cd lua-resty-openssl && \
cp -r lib/resty/* /usr/local/openresty/lualib/resty/ && \
cd /tmp && \
# Install lua-resty-redis (needed for Redis caching)
git clone https://github.com/openresty/lua-resty-redis.git && \
cd lua-resty-redis && \
cp lib/resty/redis.lua /usr/local/openresty/lualib/resty/ && \
cd / && \
rm -rf /tmp/lua-resty-http /tmp/lua-resty-openssl /tmp/lua-resty-redis
WORKDIR /app
ENTRYPOINT ["/app/entrypoint.sh"]
```
--------------------------------
### Dockerfile for Socket Firewall (Dockerfile)
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-proxy-service-setup
This Dockerfile outlines the steps to build a custom Socket Firewall Docker image. It installs necessary dependencies, downloads the firewall binary, sets up certificate directories, exposes ports, and configures the entry point to run the service.
```dockerfile
FROM debian:bullseye-slim
# netcat/curl included for healthcheck and fetching binaries
RUN apt-get update
&& apt-get install -y netcat-openbsd curl
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
RUN mkdir -p /app/certs /run/secrets
# Make sure the binary matches the host architecture
ADD https://github.com/SocketDev/firewall-release/releases/latest/download/sfw-linux-x86_64 ./sfw
RUN chmod +x ./sfw
RUN mv ./sfw /usr/local/bin/sfw
COPY ./ca.crt /app/certs/ca.crt
COPY ./ca.key /app/certs/ca.key
ENV SFW_HTTP_PORT=80
ENV SFW_HTTPS_PORT=443
EXPOSE 80
EXPOSE 443
ENTRYPOINT ["/usr/local/bin/sfw", "--service"]
```
--------------------------------
### Install Socket JavaScript SDK
Source: https://docs.socket.dev/docs/socket-javascript-sdk
Installs the Socket JavaScript SDK using npm. This is the first step to using the SDK in your project.
```bash
npm install @socketsecurity/sdk
```
--------------------------------
### Verify Firewall Integration
Source: https://docs.socket.dev/docs/nexus-configuration
Commands to test package installation and verify firewall logs.
```bash
# Developers use Nexus as normal
npm config set registry https://nexus.company.com/repository/npm-proxy/
npm install lodash
# Check firewall logs
docker compose logs socket-firewall | grep lodash
```
```bash
pip config set global.index-url https://nexus.company.com/repository/pypi-proxy/simple
pip install requests
docker compose logs socket-firewall | grep requests
```
```bash
# View discovered routes
docker compose exec socket-firewall cat /app/discovered-routes.yml
# Check logs for discovery events
docker compose logs socket-firewall | grep "Discovered.*repositories"
```
--------------------------------
### Install Socket Firewall via npm
Source: https://docs.socket.dev/docs/socket-firewall-free
This command installs the Socket Firewall Free tool globally using npm. After installation, `sfw` can be used to prefix package manager commands for security.
```bash
npm i -g sfw
# sfw can then be prefixed in front of package manager commands
sfw npm install --save dangerous-package
sfw pip install dangerous-package
```
--------------------------------
### Advanced projectIgnorePaths Example
Source: https://docs.socket.dev/docs/socket-yml
An advanced example of `projectIgnorePaths` in socket.yml, demonstrating how to ignore all package manifest files by default and then selectively unignore specific ones. This uses gitignore-like patterns, requiring double quotes for special characters.
```yaml
projectIgnorePaths:
- "/*"
- "!/package.json"
- "!/package-lock.json"
- "!/workspaces"
- "/workspaces/*"
- "!/workspaces/foo"
- "!/workspaces/bar"
```
--------------------------------
### Allowed Package with Warnings Response Headers
Source: https://docs.socket.dev/docs/registry-mode-configuration-reference
Example HTTP response headers for an allowed package that triggered warnings.
```http
HTTP/1.1 200 OK
X-Socket-Request-ID: a1b2c3d4e5f6...
X-Socket-Decision: allowed
X-Socket-Warn-Reason: protestware
```
--------------------------------
### Manually Install Socket Firewall on Linux
Source: https://docs.socket.dev/docs/socket-firewall-free
These commands outline the manual installation process for Socket Firewall Free on Linux systems. It includes downloading the appropriate binary, setting execute permissions, and placing it in the system's PATH.
```bash
# Download the binary (replace with actual release URL)
curl -L -o sfw https://github.com/SocketDev/sfw-free/releases/latest/download/sfw-linux-x86_64
chmod +x sfw
sudo mv sfw /usr/local/bin/
```
--------------------------------
### Manually Install Socket Firewall on Windows
Source: https://docs.socket.dev/docs/socket-firewall-free
This PowerShell command demonstrates the manual installation of Socket Firewall Free on Windows. It downloads the Windows executable and moves it to a common location within the user's PATH for easy access.
```powershell
# Download the binary (replace with actual release URL)
Invoke-WebRequest -Uri "https://github.com/SocketDev/sfw-free/releases/latest/download/sfw-windows-amd64.exe" -OutFile "sfw.exe"
# Move to a directory in your PATH, such as:
Move-Item sfw.exe "%USERPROFILE%\AppData\Local\Microsoft\WindowsApps\sfw.exe"
```
--------------------------------
### Configure Maven for Socket Firewall
Source: https://docs.socket.dev/docs/registry-mode-setup-downstream
Add the mirror configuration to settings.xml and run installation with insecure SSL flags.
```xml
socket-firewall
https://sfw.your_company.com:8443/maven
*
```
```bash
mvn install -Dmaven.wagon.http.ssl.insecure=true -Dmaven.wagon.http.ssl.allowall=true
```
--------------------------------
### Troubleshoot Lua Library Installation Failures
Source: https://docs.socket.dev/docs/installations
This snippet indicates a troubleshooting scenario where Lua library installation might fail during the tarball build process. No specific commands are provided, suggesting manual inspection or further investigation.
```bash
# Lua library installation fails
```
--------------------------------
### Socket.yml Configuration Example
Source: https://docs.socket.dev/docs/socket-yml
A basic example of the socket.yml configuration file, demonstrating top-level version, ignored paths, trigger paths, issue rules, and GitHub app settings. This file enables or disables features like dependency overview comments and specifies users to ignore.
```yaml
version: 2
projectIgnorePaths:
- "ignored-folder"
- "foo/bar/package.json"
# only trigger pull request alerts when these files change.
triggerPaths:
- "package.json"
- "package-lock.json"
issueRules:
unresolvedRequire: false
githubApp:
enabled: true # enable/disable the Socket.dev GitHub app entirely
dependencyOverviewEnabled: true # enable/disable GitHub app dependency overview comments in pull request alerts.
ignoreUsers: ["aBotOnGitHub"]
disableCommentsAndCheckRuns: false
```
--------------------------------
### Allowed Package Response Headers
Source: https://docs.socket.dev/docs/registry-mode-configuration-reference
Example HTTP response headers for a package that was allowed without any alerts.
```http
HTTP/1.1 200 OK
X-Socket-Request-ID: a1b2c3d4e5f6...
X-Socket-Decision: allowed
```
--------------------------------
### Install CA Certificate on macOS (Terminal)
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-proxy-client-setup
Adds the Socket Firewall CA certificate to the system keychain on macOS using the terminal. It also includes a command to verify the installation.
```bash
# Add the CA certificate to the system keychain
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/socketFirewallCa.crt
# Verify the certificate was added
security find-certificate -c "Socket Proxy CA" /Library/Keychains/System.keychain
```
--------------------------------
### Install CA Certificate on Linux (RedHat/CentOS/Fedora)
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-proxy-client-setup
Installs the Socket Firewall CA certificate on RedHat, CentOS, and Fedora systems by copying it to the appropriate directory and updating the trust store.
```bash
sudo cp /path/to/socketFirewallCa.crt /etc/pki/ca-trust/source/anchors/socketFirewallCa.crt
sudo update-ca-trust
```
--------------------------------
### Complete socket.yml Configuration Reference
Source: https://docs.socket.dev/docs/registry-mode-configuration-reference
Full configuration file example covering core settings, path routing, caching, and advanced features.
```yaml
# Core Socket settings
socket:
api_url: https://api.socket.dev
fail_open: true
outbound_proxy: http://proxy.company.com:3128
no_proxy: localhost,127.0.0.1,internal.company.com
api_ssl_verify: false
api_ssl_ca_cert: /etc/ssl/certs/corporate-ca.crt
upstream_ssl_verify: false
# Ports
ports:
http: 8080
https: 8443
# Deployment mode
config_mode: upstream
# Path-based routing with auto-discovery
path_routing:
enabled: true
domain: socket-firewall.company.com
mode: artifactory
private_registry:
api_url: https://artifactory.company.com/artifactory
api_key: ${ARTIFACTORY_API_KEY}
interval: 5m
exclude_pattern: "(tmp|test|snapshot)-.*"
# Caching
cache:
ttl: 600
redis:
enabled: true
host: redis.company.com
port: 6380
password: ${REDIS_PASSWORD}
ttl: 86400
ssl: true
ssl_verify: true
ssl_ca_cert: /etc/redis/ssl/ca-cert.pem
# Performance
nginx:
worker_processes: 8
worker_connections: 16384
proxy:
connect_timeout: 120
send_timeout: 300
read_timeout: 300
# Advanced features (v1.1.108+)
metadata_filtering:
enabled: true
filter_blocked: true
filter_warn: false
include_unchecked_versions: true
max_versions: 100
cache_ttl: 3600
batch_size: 4000
# Per-ecosystem recentlyPublished override (v1.1.134+)
# recently_published_enabled_ecosystems:
# - npm
# - pypi
splunk:
enabled: true
hec_url: https://splunk.company.com:8088/services/collector/event
hec_token: ${SPLUNK_HEC_TOKEN}
index: security
source: socket-firewall
sourcetype: socket:firewall:event
ssl_verify: true
```
--------------------------------
### Install CA Certificate on Linux (Ubuntu/Debian)
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-proxy-client-setup
Installs the Socket Firewall CA certificate on Ubuntu/Debian systems by copying it to the system's certificate directory and updating the certificate store.
```bash
sudo cp /path/to/socketFirewallCa.crt /usr/local/share/ca-certificates/socketFirewallCa.crt
sudo update-ca-certificates
```
--------------------------------
### Verify CA Certificate Installation
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-proxy-client-setup
Uses `openssl s_client` to verify that the Socket Firewall CA certificate is correctly installed and trusted by the system. Compares output with and without explicitly specifying the CA file.
```bash
openssl s_client -connect your-firewall-host:443 -prexit
openssl s_client -connect your-firewall-host:443 -prexit -CAfile ./path/to/socketFirewallCa.crt
```
--------------------------------
### Custom Rules for AI Assistant Integration
Source: https://docs.socket.dev/docs/guide-to-socket-mcp
Provides an example of custom rules that can be added to an AI assistant's configuration to guide its interaction with the Socket MCP server. This rule instructs the AI to always check dependency scores and handle low scores appropriately.
```markdown
Always check dependency scores with the depscore tool when you add a new dependency. If the score is low, consider using an alternative library or writing the code yourself. If you are unsure about the score, ask for a review from someone with more experience. When checking dependencies, make sure to also check the imports not just the pyproject.toml/package.json/dependency file.
```
--------------------------------
### Install Socket Firewall Binary
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-wrapper-mode
Instructions for downloading and setting up the Socket Firewall (sfw) binary on Linux/macOS. This involves downloading the binary, renaming it, making it executable, and adding it to the system's PATH. Special handling for macOS quarantine is also included.
```bash
chmod +x sfw
export PATH="$(pwd):$PATH"
xattr -dr com.apple.quarantine ./path/to/sfw
```
--------------------------------
### Run Socket CLI commands
Source: https://docs.socket.dev/docs/socket-cli
Examples of running various Socket CLI commands, including displaying help, checking package scores, scanning directories, and logging in.
```bash
socket --help
socket package score npm webpack@5.75.0 --markdown
socket scan create ./proj
socket login
```
--------------------------------
### Install CA Certificate on Windows (PowerShell)
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-proxy-client-setup
Imports the Socket Firewall CA certificate into the Trusted Root Certification Authorities store on Windows using PowerShell. Includes verification.
```powershell
# Import the CA certificate to the Trusted Root Certification Authorities store
Import-Certificate -FilePath "C:\path\to\socketFirewallCa.crt" -CertStoreLocation Cert:\LocalMachine\Root
# Verify the certificate was imported
Get-ChildItem -Path Cert:\LocalMachine\Root | Where-Object {$_.Subject -like "*Socket Proxy CA*"}
```
--------------------------------
### Initialize and Use Socket SDK
Source: https://docs.socket.dev/docs/socket-typescript-sdk
Initialize the client and fetch quota information using ESM or CommonJS.
```javascript
import { SocketSdk } from '@socketsecurity/sdk'
const client = new SocketSdk('yourApiKeyHere')
const res = await client.getQuota()
if (res.success) {
// Will output { quota: 123 } if the quota you have left is 123
console.log(res.data)
}
```
```javascript
const { SocketSdk } = require('@socketsecurity/sdk')
```
--------------------------------
### Install CA Certificate for Java Applications
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-proxy-client-setup
Adds the Socket Firewall CA certificate to the Java keystore, making it trusted for Java applications like Maven and Gradle. Requires the `keytool` utility.
```bash
keytool -import -trustcacerts -cacerts -noprompt \
-storepass changeit \
-alias socket-proxy-ca \
-file /usr/local/share/ca-certificates/socketFirewallCa.crt
```
--------------------------------
### Troubleshoot Container Startup Issues
Source: https://docs.socket.dev/docs/installations
This section provides bash commands to troubleshoot issues with the Socket Firewall container not starting. It includes checking logs, verifying the API token environment variable, and testing the configuration generation tool.
```bash
# Check logs
docker compose logs socket-firewall
# Verify API token is set
docker compose exec socket-firewall env | grep SOCKET_SECURITY_API_TOKEN
# Test config generation
docker compose exec socket-firewall socket-proxy-config-tool generate --config /app/socket.yml
```
--------------------------------
### Setup Python and Node.js Environments (YAML)
Source: https://docs.socket.dev/docs/socket-for-github-actions
This YAML snippet configures the necessary build environment by setting up specific versions of Python and Node.js. These steps are crucial prerequisites for installing and running the Socket CLI and its dependencies.
```yaml
steps:
- uses: actions/checkout@v4
with:
# For PRs, fetch one additional commit for proper diff analysis
fetch-depth: ${{ github.event_name == 'pull_request' && 2 || 0 }}
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- uses: actions/setup-node@v4
with:
node-version: '20'
```
--------------------------------
### View Socket Optimize Help
Source: https://docs.socket.dev/docs/socket-optimize
Displays the command-line interface help and usage instructions for the socket optimize command.
```bash
$ socket optimize --help
```
--------------------------------
### Generate CycloneDX SBOM for Gradle Projects
Source: https://docs.socket.dev/docs/gradle-setup-instructions-for-java-kotlin-and-scala
This command uses the `socket` CLI tool to generate a CycloneDX SBOM for a Gradle project. It specifies the project type as 'gradle', outputs to 'socket-gradle.cdx.json', installs dependencies, and uses the 'build' lifecycle. This is an alternative if lockfiles cannot be enabled.
```bash
socket cdxgen -t gradle -o socket-gradle.cdx.json --install-deps --lifecycle build
```
--------------------------------
### Install Socket CLI
Source: https://docs.socket.dev/docs/safe-npm-faq
Installs the Socket CLI globally using npm. This command adds the 'socket' binary to your system's PATH, allowing you to use 'socket npm install' instead of 'npm install'.
```bash
npm install -g socket
```
--------------------------------
### Deploy Custom Production Certificates
Source: https://docs.socket.dev/docs/registry-mode-configuration-reference
Prepare and set permissions for custom SSL certificates in the host directory.
```bash
mkdir -p ssl
cp /path/to/cert.pem ssl/fullchain.pem
cp /path/to/key.pem ssl/privkey.pem
chmod 644 ssl/fullchain.pem ssl/privkey.pem
```
--------------------------------
### Troubleshoot Container Issues
Source: https://docs.socket.dev/docs/registry-mode-setup-downstream
Commands to diagnose container startup failures and configuration issues.
```bash
docker compose logs socket-firewall
docker compose exec socket-firewall env | grep SOCKET
docker compose exec socket-firewall socket-proxy-config-tool generate --config /app/socket.yml
```
--------------------------------
### Generate SBOM without Automatic Dependency Installation
Source: https://docs.socket.dev/docs/socket-cdxgen
Generates an SBOM without automatically installing dependencies. This is useful when dependencies are managed manually or in environments where automatic installation is not desired or possible.
```bash
socket manifest cdxgen --no-install-deps
```
--------------------------------
### Configure NuGet for Socket Firewall
Source: https://docs.socket.dev/docs/registry-mode-setup-downstream
Add the firewall as a NuGet source.
```bash
dotnet nuget add source https://sfw.your_company.com:8443/nuget/v3/index.json -n socket-firewall
```
--------------------------------
### Webhook Event Payload Example
Source: https://docs.socket.dev/docs/registry-mode-configuration-reference
An example JSON payload for a webhook event, detailing package decision information.
```json
{
"event_type": "package_decision",
"timestamp": 1709078400.123,
"request_id": "abc123xyz",
"purl": "pkg:npm/malicious-package@1.0.0",
"decision": "blocked",
"action": "block",
"response_code": 403,
"upstream_status": null,
"block_source": "download",
"block_reason": "Known Malware",
"warn_reason": "",
"client_ip": "203.0.113.10",
"user_agent": "npm/8.19.2",
"repo": "npm-remote",
"source_path": "/repository/npm/malicious-package/-/malicious-package-1.0.0.tgz",
"upstream_host": "registry.npmjs.org",
"cached": false,
"stale": false,
"socket_api_response_code": 403,
"purl_check_latency_ms": 142,
"private_registry_request_id": "ecb06b92c7f89c93:ecb06b92c7f89c93:0000000000000000:0"
}
```
--------------------------------
### socket scan setup
Source: https://docs.socket.dev/docs/socket-scan
Initiates an interactive prompt to generate a `socket.json` file with default configurations for running scans in a target directory.
```APIDOC
## POST /api/scans/setup
### Description
Initiates an interactive prompt to generate a `socket.json` file with default configurations for running scans in a target directory. This helps prefill options like `--repo` and `--branch` for subsequent commands.
### Method
POST
### Endpoint
`/api/scans/setup`
### Parameters
#### Path Parameters
- **TARGET_DIRECTORY** (string) - Required - The directory for which to set up defaults.
### Request Example
```bash
socket scan setup ./proj
```
### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the `socket.json` file has been generated.
#### Response Example
```json
{
"message": "socket.json generated successfully."
}
```
```
--------------------------------
### Setup GitHub Actions Workflow with Socket Security
Source: https://docs.socket.dev/docs/socket-for-github-actions
This YAML workflow configures GitHub Actions to run Socket Security scans on every commit. It checks out the code, sets up Python, installs the Socket CLI, and runs the scan using environment variables for API keys. It automatically detects repository and commit information and handles different event types like push, pull_request, and issue_comment.
```yaml
# Socket Security GitHub Actions Workflow
# This workflow runs Socket Security scans on every commit to any branch
# It automatically detects git repository information and handles different event types
name: socket-security-workflow
run-name: Socket Security Github Action
on:
push:
branches: ['**'] # Run on all branches, all commits
pull_request:
types: [opened, synchronize, reopened]
issue_comment:
types: [created]
# Prevent concurrent runs for the same commit
concurrency:
group: socket-scan-${{ github.ref }}-${{ github.sha }}
cancel-in-progress: true
jobs:
socket-security:
permissions:
issues: write
contents: read
pull-requests: write
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
# For PRs, fetch one additional commit for proper diff analysis
fetch-depth: ${{ github.event_name == 'pull_request' && 2 || 0 }}
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install Socket CLI
run: pip install socketsecurity --upgrade
- name: Run Socket Security Scan
env:
SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_SECURITY_API_KEY }}
GH_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
# Determine PR number based on event type
PR_NUMBER=0
if [ "${{ github.event_name }}" == "pull_request" ]; then
PR_NUMBER=${{ github.event.pull_request.number }}
elif [ "${{ github.event_name }}" == "issue_comment" ]; then
PR_NUMBER=${{ github.event.issue.number }}
fi
# Run Socket CLI with minimal required parameters
# The CLI automatically detects:
# - Repository name from git
# - Branch name from git
# - Commit SHA from git
# - Commit message from git
# - Committer information from git
# - Default branch status from git and GitHub environment
# - Changed files from git commit
socketcli \
--target-path $GITHUB_WORKSPACE \
--scm github \
--pr-number $PR_NUMBER
```
--------------------------------
### Download Firewall Tarball and Entrypoint Script
Source: https://docs.socket.dev/docs/installations
Download the Socket Firewall tarball and the entrypoint script for your system's architecture. Make the entrypoint script executable.
```bash
# Download tarball and entrypoint for your architecture
# Replace {version} and {arch} with your values
wget https://github.com/SocketDev/socket-registry-firewall/releases/download/v{version}/socket-firewall-{version}.{arch}.tgz
wget https://github.com/SocketDev/socket-registry-firewall/blob/main/entrypoint.sh
# Make entrypoint executable
chmod +x entrypoint.sh
```
--------------------------------
### Display Socket Firewall Help Information
Source: https://docs.socket.dev/docs/socket-firewall-free
This command displays the help information for the Socket Firewall Free tool, including its usage, examples, and license information. It's useful for understanding the tool's capabilities and how to use it.
```bash
$ sfw --help
Socket Firewall Free - Network security proxy for package managers
Runs any package manager command with network traffic filtering.
Usage:
sfw ...
sfw --help
Examples:
sfw npm install
sfw pip install requests
Provided under the following license:
https://github.com/SocketDev/sfw-free/blob/main/README.md#license
```
--------------------------------
### Verify OpenSSL Installation
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-generating-keys
Checks if OpenSSL is installed and displays its version. This is a prerequisite for generating CA keys and certificates.
```bash
openssl version
```
--------------------------------
### Dotenv Configuration Example
Source: https://docs.socket.dev/docs/socket-firewall-enterprise-configuration
Example of configuration settings in dotenv format, commonly used for environment variables. These variables control API keys and hostnames for the Socket Firewall.
```shell
SOCKET_API_KEY=sktsec_your_api_key_here_api
SFW_HOSTNAME=your.proxy.hostname
```
--------------------------------
### Check System Architecture
Source: https://docs.socket.dev/docs/installations
Determine your system's architecture to select the correct Docker image. Use 'x86_64' for amd64 and 'aarch64' or 'arm64' for arm64.
```bash
uname -m
```
--------------------------------
### Install and Run Socket CLI for Security Scan (Bash)
Source: https://docs.socket.dev/docs/socket-for-github-actions
This snippet demonstrates installing the Socket CLI using npm, generating a CycloneDX SBOM for various build tools, installing the Socket Security CLI via pip, and then executing the security scan. It utilizes environment variables for API keys and automatically detects SCM details.
```bash
npm i -g socket
socket cdxgen -t gradle -t kotlin -t scala -o socket.cdx.json --install-deps --lifecycle build
pip install socketsecurity --upgrade
SOCKET_SECURITY_API_KEY=${{ secrets.SOCKET_SECURITY_API_KEY }}
GH_API_TOKEN=${{ secrets.GITHUB_TOKEN }}
# Determine PR number based on event type
PR_NUMBER=0
if [ "${{ github.event_name }}" == "pull_request" ]; then
PR_NUMBER=${{ github.event.pull_request.number }}
elif [ "${{ github.event_name }}" == "issue_comment" ]; then
PR_NUMBER=${{ github.event.issue.number }}
fi
# Run Socket CLI with minimal required parameters
# The CLI automatically detects:
# - Repository name from git
# - Branch name from git
# - Commit SHA from git
# - Commit message from git
# - Committer information from git
# - Default branch status from git and GitHub environment
# - Changed files from git commit
socketcli \
--target-path $GITHUB_WORKSPACE \
--scm github \
--pr-number $PR_NUMBER
```