diff --git a/README.md b/README.md index 9edf6fd..5f41bdd 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,142 @@ # Socket Patch CLI -CLI tool for applying security patches to dependencies. +Apply security patches to npm dependencies without waiting for upstream fixes. -## Setup +## Installation ```bash -# Install dependencies -npm install +npx @socketsecurity/socket-patch +``` + +Or install globally: -# Build the project -npm run build +```bash +npm install -g @socketsecurity/socket-patch ``` -## Usage +## Commands + +### `apply` + +Apply security patches from manifest. +**Usage:** ```bash -# Apply patches from manifest (default: .socket/manifest.json) -socket-patch apply +npx @socketsecurity/socket-patch apply [options] +``` -# Apply patches with custom manifest path -socket-patch apply --manifest-path /path/to/manifest.json +**Options:** +- `--cwd` - Working directory (default: current directory) +- `-d, --dry-run` - Verify patches without modifying files +- `-s, --silent` - Only output errors +- `-m, --manifest-path` - Path to manifest (default: `.socket/manifest.json`) -# Dry run (verify patches can be applied without modifying files) -socket-patch apply --dry-run +**Examples:** +```bash +# Apply patches +npx @socketsecurity/socket-patch apply -# Silent mode (only output errors) -socket-patch apply --silent +# Dry run +npx @socketsecurity/socket-patch apply --dry-run -# Custom working directory -socket-patch apply --cwd /path/to/project +# Custom manifest +npx @socketsecurity/socket-patch apply -m /path/to/manifest.json ``` -## Development +### `download` +Download patch from Socket API. + +**Usage:** ```bash -# Watch mode for development -npm run dev +npx @socketsecurity/socket-patch download --uuid --org [options] ``` -## Project Structure +**Options:** +- `--uuid` - Patch UUID (required) +- `--org` - Organization slug (required) +- `--api-token` - API token (or use `SOCKET_API_TOKEN` env var) +- `--api-url` - API URL (default: `https://api.socket.dev`) +- `--cwd` - Working directory +- `-m, --manifest-path` - Path to manifest + +**Examples:** +```bash +# Download patch +export SOCKET_API_TOKEN="your-token" +npx @socketsecurity/socket-patch download --uuid "550e8400-e29b-41d4-a716-446655440000" --org "my-org" +# With explicit token +npx @socketsecurity/socket-patch download --uuid "..." --org "my-org" --api-token "token" ``` -src/ -├── cli.ts # Main CLI entry point -├── commands/ -│ └── apply.ts # Apply patch command -├── schema/ -│ └── manifest-schema.ts # Patch manifest schema (Zod) -├── hash/ -│ └── git-sha256.ts # Git-compatible SHA256 hashing -├── patch/ -│ ├── file-hash.ts # File hashing utilities -│ └── apply.ts # Core patch application logic -├── types.ts # TypeScript type definitions -├── utils.ts # Utility functions -└── index.ts # Library exports + +### `list` + +List patches in manifest. + +**Usage:** +```bash +npx @socketsecurity/socket-patch list [options] ``` -## Commands +**Options:** +- `--cwd` - Working directory +- `-m, --manifest-path` - Path to manifest +- `--json` - Output as JSON + +**Examples:** +```bash +# List patches +npx @socketsecurity/socket-patch list -### apply +# JSON output +npx @socketsecurity/socket-patch list --json +``` + +**Sample Output:** +``` +Found 2 patch(es): + +Package: pkg:npm/lodash@4.17.20 + UUID: 550e8400-e29b-41d4-a716-446655440000 + Tier: free + License: MIT + Vulnerabilities (1): + - GHSA-xxxx-yyyy-zzzz (CVE-2024-12345) + Severity: high + Summary: Prototype pollution in lodash + Files patched (1): + - lodash.js +``` + +### `remove` -Apply security patches to dependencies from a manifest file. +Remove patch from manifest. + +**Usage:** +```bash +npx @socketsecurity/socket-patch remove [options] +``` + +**Arguments:** +- `identifier` - Package PURL (e.g., `pkg:npm/package@version`) or patch UUID **Options:** -- `--cwd` - Working directory (default: current directory) -- `-d, --dry-run` - Verify patches can be applied without modifying files -- `-s, --silent` - Only output errors -- `-m, --manifest-path` - Path to patch manifest file (default: `.socket/manifest.json`) -- `-h, --help` - Show help -- `-v, --version` - Show version +- `--cwd` - Working directory +- `-m, --manifest-path` - Path to manifest -**Exit Codes:** -- `0` - Success (patches applied or already applied) -- `1` - Error (manifest not found, verification failed, or patch application failed) +**Examples:** +```bash +# Remove by PURL +npx @socketsecurity/socket-patch remove "pkg:npm/lodash@4.17.20" + +# Remove by UUID +npx @socketsecurity/socket-patch remove "550e8400-e29b-41d4-a716-446655440000" +``` ## Manifest Format -The manifest file (`.socket/manifest.json`) contains patch definitions: +Downloaded patches are stored in `.socket/manifest.json`: ```json { @@ -98,43 +157,10 @@ The manifest file (`.socket/manifest.json`) contains patch definitions: "severity": "high", "description": "Detailed description" } - }, - "description": "Patch description", - "license": "MIT", - "tier": "free" + } } } } ``` -Patched file contents are stored in `.socket/blobs/` directory, named by their Git-compatible SHA256 hash. - -## Library Usage - -The socket-patch CLI can also be used as a library: - -```typescript -import { - PatchManifest, - PatchManifestSchema, - computeGitSHA256FromBuffer, - computeGitSHA256FromChunks, - applyPackagePatch, - findNodeModules, -} from '@socketsecurity/socket-patch-cli' - -// Validate manifest -const manifest = PatchManifestSchema.parse(manifestData) - -// Compute file hashes -const hash = computeGitSHA256FromBuffer(fileBuffer) - -// Apply patches programmatically -const result = await applyPackagePatch( - packageKey, - packagePath, - files, - blobsPath, - dryRun, -) -``` +Patched file contents are in `.socket/blobs/` (named by git SHA256 hash). diff --git a/package.json b/package.json index f1e9a26..8a254de 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "@socketsecurity/socket-patch-cli", + "name": "@socketsecurity/socket-patch", "version": "0.1.0", "description": "CLI tool for applying security patches to dependencies", "main": "dist/index.js",