Socket Badge CI

Follow @SocketSecurity

CLI for Socket.dev security analysis

pnpm install -g socket
socket --help

• socket npm [args...] / socket npx [args...] - Wrap npm/npx with security scanning
• socket pnpm [args...] / socket yarn [args...] - Wrap pnpm/yarn with security scanning
• socket pip [args...] - Wrap pip with security scanning
• socket scan - Create and manage security scans
• socket package <name> - Analyze package security scores
• socket fix - Fix CVEs in dependencies
• socket optimize - Optimize dependencies with @socketregistry overrides
• socket cdxgen [command] - Run cdxgen for SBOM generation

• socket organization (alias: org) - Manage organization settings
• socket repository (alias: repo) - Manage repositories
• socket dependencies (alias: deps) - View organization dependencies
• socket audit-log (alias: audit) - View audit logs
• socket analytics - View organization analytics
• socket threat-feed (alias: feed) - View threat intelligence

• socket login - Authenticate with Socket.dev
• socket logout - Remove authentication
• socket whoami - Show authenticated user
• socket config - Manage CLI configuration

All aliases support the flags and arguments of the commands they alias.

• socket ci - Alias for socket scan create --report (creates report and exits with error if unhealthy)
• socket org - Alias for socket organization
• socket repo - Alias for socket repository
• socket pkg - Alias for socket package
• socket deps - Alias for socket dependencies
• socket audit - Alias for socket audit-log
• socket feed - Alias for socket threat-feed

• --json - Output as JSON
• --markdown - Output as Markdown

• --dry-run - Run without uploading
• --debug - Show debug output
• --help - Show help
• --max-old-space-size - Set Node.js memory limit
• --max-semi-space-size - Set Node.js heap size
• --version - Show version

Socket CLI reads socket.yml configuration files. Supports version 2 format with projectIgnorePaths for excluding files from reports.

• SOCKET_CLI_API_TOKEN - Socket API token
• SOCKET_CLI_CONFIG - JSON configuration object
• SOCKET_CLI_GITHUB_API_URL - GitHub API base URL
• SOCKET_CLI_GIT_USER_EMAIL - Git user email (default: 94589996+socket-bot@users.noreply.github.com)
• SOCKET_CLI_GIT_USER_NAME - Git user name (default: Socket Bot)
• SOCKET_CLI_GITHUB_TOKEN - GitHub token with repo access (alias: GITHUB_TOKEN)
• SOCKET_CLI_NO_API_TOKEN - Disable default API token
• SOCKET_CLI_NPM_PATH - Path to npm directory
• SOCKET_CLI_ORG_SLUG - Socket organization slug
• SOCKET_CLI_ACCEPT_RISKS - Accept npm/npx risks
• SOCKET_CLI_VIEW_ALL_RISKS - Show all npm/npx risks

Run locally:

pnpm install
pnpm run build
pnpm exec socket

• SOCKET_CLI_API_BASE_URL - API base URL (default: https://api.socket.dev/v0/)
• SOCKET_CLI_API_PROXY - Proxy for API requests (aliases: HTTPS_PROXY, https_proxy, HTTP_PROXY, http_proxy)
• SOCKET_CLI_API_TIMEOUT - API request timeout in milliseconds
• SOCKET_CLI_CACHE_ENABLED - Enable API response caching (default: false)
• SOCKET_CLI_CACHE_TTL - Cache TTL in milliseconds (default: 300000 = 5 minutes)
• SOCKET_CLI_DEBUG - Enable debug logging
• DEBUG - Enable debug package logging

The CLI supports granular debug logging via the DEBUG environment variable:

Default categories (shown with SOCKET_CLI_DEBUG=1):

• error - Critical errors that prevent operation
• warn - Important warnings that may affect behavior
• notice - Notable events and state changes
• silly - Very verbose debugging info

Opt-in categories (require explicit DEBUG='category'):

• cache - Cache hit/miss operations
• network - HTTP requests with timing
• command - External command execution
• auth - Authentication flow
• perf - Performance timing
• spinner - Spinner state changes
• inspect - Detailed object inspection
• stdio - Command execution logs

Examples:

DEBUG=cache socket scan # Cache debugging only
DEBUG=network,cache socket scan # Multiple categories
DEBUG=* socket scan # All categories
SOCKET_CLI_DEBUG=1 socket scan # Default categories

Track long-running operations with visual progress bars:

import { startSpinner, updateSpinnerProgress } from './src/utils/spinner.mts'
const stop = startSpinner('Processing files')
for (let i = 0; i < files.length; i++) {
 updateSpinnerProgress(i + 1, files.length, 'files')
 await processFile(files[i])
}
stop()
// Output: ⠋ Processing files ████████████░░░░░░░░ 60% (12/20 files)

Display structured data with professional table formatting:

import { formatTable, formatSimpleTable } from './src/utils/output-formatting.mts'
import colors from 'yoctocolors-cjs'
// Bordered table with box-drawing characters
const data = [
 { name: 'lodash', version: '4.17.21', issues: 0 },
 { name: 'react', version: '18.2.0', issues: 2 }
]
const columns = [
 { key: 'name', header: 'Package' },
 { key: 'version', header: 'Version', align: 'center' },
 {
 key: 'issues',
 header: 'Issues',
 align: 'right',
 color: (v) => v === '0' ? colors.green(v) : colors.red(v)
 }
]
console.log(formatTable(data, columns))
// Output:
// ┌─────────┬─────────┬────────┐
// │ Package │ Version │ Issues │
// ├─────────┼─────────┼────────┤
// │ lodash │ 4.17.21 │ 0 │
// │ react │ 18.2.0 │ 2 │
// └─────────┴─────────┴────────┘
// Simple table without borders
console.log(formatSimpleTable(data, columns))
// Output:
// Package Version Issues
// ─────── ─────── ──────
// lodash 4.17.21 0
// react 18.2.0 2

Track and optimize CLI performance with comprehensive monitoring utilities:

import { perfTimer, measure, perfCheckpoint, printPerformanceSummary } from './src/utils/performance.mts'
// Simple operation timing
const stop = perfTimer('fetch-packages')
await fetchPackages()
stop({ count: 50 })
// Function measurement
const { result, duration } = await measure('parse-manifest', async () => {
 return parseManifest(file)
})
console.log(`Parsed in ${duration}ms`)
// Track complex operation progress
perfCheckpoint('start-scan')
perfCheckpoint('analyze-dependencies', { count: 100 })
perfCheckpoint('detect-issues', { issueCount: 5 })
perfCheckpoint('end-scan')
// Print performance summary
printPerformanceSummary()
// Performance Summary:
// fetch-packages: 1 calls, avg 234ms (min 234ms, max 234ms, total 234ms)
// parse-manifest: 5 calls, avg 12ms (min 8ms, max 20ms, total 60ms)

Enable with: DEBUG=perf socket <command>

Optimize API performance with smart caching based on data volatility:

import { getCacheStrategy, getRecommendedTtl, warmCaches } from './src/utils/cache-strategies.mts'
// Get recommended TTL for an endpoint
const ttl = getRecommendedTtl('/npm/lodash/4.17.21/score')
// Returns: 900000 (15 minutes for stable package info)
// Check cache strategy
const strategy = getCacheStrategy('/scans/abc123')
// Returns: { ttl: 120000, volatile: true } (2 minutes for active scans)
// Warm critical caches on startup
await warmCaches(sdk, [
 '/users/me',
 '/organizations/my-org/settings'
])

Built-in strategies:

• Package info: 15min (stable data)
• Package issues: 5min (moderate volatility)
• Scan results: 2min (high volatility)
• Org settings: 30min (very stable)
• User info: 1hr (most stable)

Handle errors with actionable recovery suggestions:

import { InputError, AuthError, getRecoverySuggestions } from './src/utils/errors.mts'
// Throw errors with recovery suggestions
throw new InputError('Invalid package name', 'Must be in format: @scope/name', [
 'Use npm package naming conventions',
 'Check for typos in the package name'
])
throw new AuthError('Token expired', [
 'Run `socket login` to re-authenticate',
 'Generate a new token at https://socket.dev/dashboard'
])
// Extract and display recovery suggestions
try {
 await operation()
} catch (error) {
 const suggestions = getRecoverySuggestions(error)
 if (suggestions.length > 0) {
 console.error('How to fix:')
 suggestions.forEach(s => console.error(` - ${s}`))
 }
}

• Socket API Reference
• Socket GitHub App
• @socketsecurity/sdk