diff --git a/README.md b/README.md index ae6a6f8..79c15a2 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ pip install cryptoserve ## Common Commands ```bash -cryptoserve scan . # Scan project (6 languages, 80+ algorithms) +cryptoserve scan . # Scan project (6 languages, 130+ algorithms) cryptoserve scan . --binary # Include binary signature detection cryptoserve pqc # Post-quantum readiness assessment cryptoserve cbom --format cyclonedx # Generate CBOM @@ -131,7 +131,7 @@ import { encrypt, decrypt } from 'cryptoserve/lib/local-crypto.mjs'; See the [Node.js SDK README](sdk/javascript/README.md). -### Python SDK v1.4.2 (server-connected) +### Python SDK v1.4.3 (server-connected) The Python SDK adds managed key management and context-aware algorithm selection when connected to a CryptoServe server: diff --git a/docs/cli.md b/docs/cli.md index 4ce0bf1..e76f835 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,6 +1,6 @@ # CLI Reference -CryptoServe ships a single `cryptoserve` CLI with scanning, encryption, certificate, and server management commands. Many commands work offline with no server required. +CryptoServe ships a single `cryptoserve` CLI with scanning, encryption, and secret management commands. All commands work offline with no server required (except `login`). ## Installation @@ -14,173 +14,67 @@ pip install cryptoserve --- -## Scanning Tools (no server required) - -Scanner binaries are downloaded automatically on first use and cached in `~/.cryptoserve/bin/`. +## Scanning Tools ### `scan` — Cryptographic Scanner -Scans files and directories for 90+ cryptographic patterns. Generates output in text, JSON, SARIF, or CycloneDX CBOM format. - -```bash -cryptoserve scan . # Scan current directory -cryptoserve scan ./src --format sarif -o results.sarif # SARIF output -cryptoserve scan . --push # Scan + upload to dashboard -cryptoserve scan . --python-only # Built-in lightweight scanner -cryptoserve scan . --update # Force binary re-download -``` - -Example output: - -``` -CRYPTOSERVE > scan - - Directory /path/to/project - Files scanned 55 - -Crypto Libraries - Library Version Risk Algorithms - node:crypto builtin high AES, ChaCha20, SHA-256, RS256 - -Hardcoded Secrets - x [CRIT] AWS Access Key - src/config.js - * Use $AWS_ACCESS_KEY_ID instead - -Weak Crypto Patterns - ! MD5 is cryptographically broken - lib/hash.js - x DES has 56-bit keys (use AES) - lib/legacy.js -``` - -| Flag | Description | -|------|-------------| -| `--push` | Upload results to CryptoServe dashboard | -| `--python-only` | Use built-in Python scanner instead of CryptoScan binary | -| `--update` | Force re-download of CryptoScan binary | -| `--format ` / `-f` | Output format: `json`, `sarif`, `cyclonedx` | -| `--output ` / `-o` | Write output to file | - -Any unrecognized flags are passed through to the CryptoScan binary. - -### `deps` — Dependency Analysis - -Analyzes the dependency tree for cryptographic usage. Supports CBOM generation and reachability analysis. +Scans files and directories for 130+ cryptographic patterns across 6 languages. ```bash -cryptoserve deps . # Analyze dependencies -cryptoserve deps . --push # Analyze + upload -cryptoserve deps . --format json -o deps.json # JSON output -cryptoserve deps . --update # Force binary re-download +cryptoserve scan . # Scan current directory +cryptoserve scan . --format sarif # SARIF output for CI/IDE +cryptoserve scan . --binary # Include binary signature detection +cryptoserve scan . --verbose # Detailed output ``` | Flag | Description | |------|-------------| -| `--push` | Upload results to CryptoServe dashboard | -| `--update` | Force re-download of CryptoDeps binary | -| `--format ` / `-f` | Output format: `json`, `sarif`, `cyclonedx` | -| `--output ` / `-o` | Write output to file | - -Any unrecognized flags are passed through to the CryptoDeps binary. - -### `push` — Upload Results - -Uploads JSON results from CryptoScan, CryptoDeps, or CycloneDX CBOM to the dashboard. - -```bash -cryptoserve push scan-results.json -cryptoserve push cbom.json -``` - ---- - -## Security Tools +| `--format ` | Output format: `text` (default), `json`, `sarif` | +| `--binary` | Include binary file scanning (ELF, PE, Mach-O, .class, .NET) | +| `--verbose` | Show detailed progress and findings | ### `cbom` — CBOM Generation Generates a Cryptographic Bill of Materials in multiple formats. ```bash -cryptoserve cbom # Default JSON output -cryptoserve cbom --format cyclonedx -o cbom.json # CycloneDX format -cryptoserve cbom --format spdx -o sbom.spdx # SPDX format -cryptoserve cbom --local-only # Skip upload +cryptoserve cbom # Default JSON output +cryptoserve cbom --format cyclonedx -o cbom.json # CycloneDX format +cryptoserve cbom --format spdx # SPDX format ``` | Flag | Description | |------|-------------| -| `--format ` / `-f` | Output format: `json`, `cyclonedx`, `spdx` | +| `--format ` | Output format: `json` (default), `cyclonedx`, `spdx` | | `--output ` / `-o` | Write output to file | -| `--name ` / `-n` | Scan name for platform upload | -| `--local-only` | Generate without uploading | -| `--no-upload` | Disable automatic upload | ### `pqc` — PQC Migration Recommendations Analyzes cryptographic exposure and provides post-quantum readiness assessment. ```bash -cryptoserve pqc # General profile -cryptoserve pqc --profile healthcare # HIPAA-focused -cryptoserve pqc --profile financial # PCI-DSS-focused -``` - -Example output: - -``` -CRYPTOSERVE > pqc - -Data Profile - Profile Personal Data / General - Protection needed 10 years - Urgency MEDIUM - -Quantum Readiness - 40/100 (high confidence -- 14 algorithms found) - Migration urgency IMMEDIATE - Risk breakdown x 3 critical / ! 7 high / 1 low / + 3 safe - -SNDL Risk Assessment - Risk level critical - Risk window 3 years - -KEM Recommendations - Algorithm FIPS Level Score - ML-KEM-768 FIPS 203 NIST Level 3 100% +cryptoserve pqc # General profile +cryptoserve pqc --profile healthcare # HIPAA-focused +cryptoserve pqc --profile financial # PCI-DSS-focused +cryptoserve pqc --verbose # Detailed breakdown ``` | Flag | Description | |------|-------------| -| `--profile

` / `-p` | Sensitivity profile: `general` (default), `healthcare`, `financial`, `national_security`, `short_lived` | +| `--profile

` | Sensitivity profile: `general` (default), `healthcare`, `financial`, `national_security`, `short_lived` | +| `--format ` | Output format: `text` (default), `json` | +| `--verbose` | Show detailed analysis | ### `gate` — CI/CD Policy Gate -Enforces cryptographic policy compliance in CI/CD pipelines. Returns pass/fail with violation details. +Enforces cryptographic policy compliance in CI/CD pipelines. Exits non-zero when violations are found. ```bash -cryptoserve gate . # Check current directory -cryptoserve gate . --fail-on-weak # Fail on weak algorithms (MD5, DES, RC4) -cryptoserve gate . --min-score 70 # Require minimum quantum readiness score -cryptoserve gate . --max-risk medium # Fail on algorithms above medium risk -cryptoserve gate . --format json # JSON output for CI parsing -``` - -Example output: - -``` -CRYPTOSERVE > gate - - Status x FAIL - Score 40/100 (min: 50) - Max risk high - - Violations: - x [CRITICAL] MD5 -- node:crypto@builtin - x [CRITICAL] DES -- node:crypto@builtin - x [CRITICAL] RC4 -- node:crypto@builtin - - x Score 40 is below minimum 50 +cryptoserve gate . # Check current directory +cryptoserve gate . --fail-on-weak # Fail on weak algorithms (MD5, DES, RC4) +cryptoserve gate . --min-score 70 # Require minimum quantum readiness score +cryptoserve gate . --max-risk medium # Fail on algorithms above medium risk +cryptoserve gate . --format sarif # SARIF output ``` | Flag | Description | @@ -188,23 +82,24 @@ CRYPTOSERVE > gate | `--max-risk ` | Maximum allowed risk level: `none`, `low`, `medium`, `high` (default), `critical` | | `--min-score ` | Minimum quantum readiness score (default: `50`) | | `--fail-on-weak` | Fail on weak algorithms (MD5, DES, RC4, ECB) | -| `--format ` / `-f` | Output format: `text` (default), `json`, `sarif` | +| `--format ` | Output format: `text` (default), `json`, `sarif` | +| `--verbose` | Show detailed violations | -### `census` -- Ecosystem Census +### `census` — Ecosystem Census Analyze cryptographic library adoption across package ecosystems. ```bash -cryptoserve census # Run ecosystem census (cached/offline data) -cryptoserve census --live # Fetch real-time data from npm, PyPI, crates.io -cryptoserve census --live --ecosystems npm # Query only npm -cryptoserve census --live --format json # Machine-readable JSON output +cryptoserve census # Offline census from bundled data +cryptoserve census --live # Fetch real-time data from registries +cryptoserve census --live --ecosystems npm # Query only npm +cryptoserve census --format json -o out.json # JSON output ``` | Flag | Description | |------|-------------| | `--live` | Fetch real-time download counts from package registries (npm, PyPI, crates.io) | -| `--ecosystems ` | Comma-separated list of ecosystems to query: `npm`, `pypi`, `crates` (default: all three) | +| `--ecosystems ` | Comma-separated list: `npm`, `pypi`, `crates` (default: all three) | | `--format ` | Output format: `text` (default), `json`, `html` | | `--output ` | Write output to a file | | `--no-cache` | Skip cached data | @@ -212,11 +107,11 @@ cryptoserve census --live --format json # Machine-readable JSON output --- -## Offline Crypto Tools (no server required) +## Crypto Tools ### `encrypt` — Encrypt String or File -Password-based authenticated encryption. +Password-based authenticated encryption (AES-256-GCM with PBKDF2 key derivation). ```bash cryptoserve encrypt "hello world" --password secret @@ -226,7 +121,9 @@ cryptoserve encrypt --file secret.txt -p secret -o secret.enc | Flag | Description | |------|-------------| | `--password ` / `-p` | Encryption password (prompted if omitted) | -| `--file ` / `-f` | File to encrypt | +| `--algorithm ` | Encryption algorithm (default: AES-256-GCM) | +| `--context ` | Encryption context for server-managed keys | +| `--file ` | File to encrypt | | `--output ` / `-o` | Output file path | ### `decrypt` — Decrypt String or File @@ -239,7 +136,7 @@ cryptoserve decrypt --file secret.enc -p secret -o decrypted.txt | Flag | Description | |------|-------------| | `--password ` / `-p` | Decryption password (prompted if omitted) | -| `--file ` / `-f` | Encrypted file to decrypt | +| `--file ` | Encrypted file to decrypt | | `--output ` / `-o` | Output file path | ### `hash-password` — Password Hashing @@ -247,9 +144,9 @@ cryptoserve decrypt --file secret.enc -p secret -o decrypted.txt Generates password hashes using scrypt (default) or PBKDF2. ```bash -cryptoserve hash-password # Interactive prompt -cryptoserve hash-password --password mypass # Non-interactive (CI/scripts) -cryptoserve hash-password "mypassword" +cryptoserve hash-password # Interactive prompt +cryptoserve hash-password "mypassword" # Positional argument +cryptoserve hash-password --password mypass # Non-interactive (CI/scripts) cryptoserve hash-password "mypassword" --algorithm pbkdf2 ``` @@ -258,36 +155,21 @@ cryptoserve hash-password "mypassword" --algorithm pbkdf2 | `--password ` | Password to hash (prompted if omitted) | | `--algorithm ` | Algorithm: `scrypt` (default), `pbkdf2` | -### `token` — JWT Token Creation - -Creates HS256 JWT tokens with custom payload and expiration. - -```bash -cryptoserve token --key mysecret -cryptoserve token --key mysecret --payload '{"sub":"user1"}' --expires 7200 -``` - -| Flag | Description | -|------|-------------| -| `--key ` / `-k` | Signing key (required) | -| `--payload ` | JSON payload (default: `{}`) | -| `--expires ` / `-e` | Expiration in seconds (default: 3600) | - ### `vault` — Encrypted Secret Storage Stores secrets in an encrypted vault at `~/.cryptoserve/vault.enc`. All vault commands accept `--password P` for non-interactive/CI usage. ```bash -cryptoserve vault init # Create new vault (prompts for password) -cryptoserve vault init --password mysecret # Non-interactive -cryptoserve vault set API_KEY sk-abc123 # Store a secret -cryptoserve vault get API_KEY # Retrieve a secret -cryptoserve vault list # List stored secrets -cryptoserve vault delete API_KEY # Remove a secret -cryptoserve vault run -- node server.js # Run command with secrets as env vars -cryptoserve vault import .env # Import .env file into vault -cryptoserve vault export # Export encrypted bundle -cryptoserve vault reset # Delete vault +cryptoserve vault init # Create new vault (prompts for password) +cryptoserve vault init --password mysecret # Non-interactive +cryptoserve vault set API_KEY sk-abc123 # Store a secret +cryptoserve vault get API_KEY # Retrieve a secret +cryptoserve vault list # List stored secrets +cryptoserve vault delete API_KEY # Remove a secret +cryptoserve vault run -- node server.js # Run command with secrets as env vars +cryptoserve vault import .env # Import .env file into vault +cryptoserve vault export # Export encrypted bundle +cryptoserve vault reset # Delete vault ``` | Flag | Description | @@ -296,99 +178,40 @@ cryptoserve vault reset # Delete vault --- -## Certificate Operations - -### `certs generate-csr` — Generate CSR - -```bash -cryptoserve certs generate-csr --cn "example.com" --org "Example Inc" -cryptoserve certs generate-csr --cn "example.com" --san "*.example.com" --key-type rsa --key-size 4096 -``` - -| Flag | Description | -|------|-------------| -| `--cn ` | Common Name (required) | -| `--org ` | Organization | -| `--country ` | Country code (2 letters) | -| `--key-type ` | `ec` (default), `rsa` | -| `--key-size ` | Key size (256 for EC, 2048 for RSA) | -| `--san ` | Subject Alternative Name (repeatable) | -| `--output ` | Output file prefix | - -### `certs self-signed` — Generate Self-Signed Certificate +## Setup Commands -```bash -cryptoserve certs self-signed --cn "localhost" -cryptoserve certs self-signed --cn "example.com" --days 730 --ca -``` - -| Flag | Description | -|------|-------------| -| `--cn ` | Common Name (required) | -| `--org ` | Organization | -| `--days ` | Validity period (default: 365) | -| `--ca` | Create as CA certificate | -| `--san ` | Subject Alternative Name (repeatable) | -| `--output ` | Output file prefix | - -### `certs parse` — Parse Certificate - -```bash -cryptoserve certs parse server.pem -``` - -Displays subject, issuer, expiry, extensions, and key info. +### `init` — Initialize Project -### `certs verify` — Verify Certificate +Sets up CryptoServe in a project: generates a master key and configures AI tool protection. ```bash -cryptoserve certs verify server.pem --issuer ca.pem +cryptoserve init # Interactive setup +cryptoserve init --insecure-storage # Skip keychain (not recommended) ``` -| Flag | Description | -|------|-------------| -| `--issuer ` | CA certificate for chain verification | - ---- - -## Server Commands (requires login) - -### `login` — Authenticate +### `login` — Authenticate with Server ```bash -cryptoserve login # Opens browser for OAuth -cryptoserve login --server https://your-server # Custom server -cryptoserve login --dev # Dev mode (no OAuth) -cryptoserve login --cookie # Manual session token +cryptoserve login # Login to default server +cryptoserve login --server https://crypto.company.com # Custom server ``` | Flag | Description | |------|-------------| | `--server ` / `-s` | Server URL (default: `http://localhost:8003`) | -| `--dev` | Force dev mode login | -| `--cookie ` | Set session manually | - -### `logout` — Clear Credentials - -```bash -cryptoserve logout -``` -### `configure` — Set SDK Configuration +### `context` — List Encryption Contexts ```bash -cryptoserve configure --token -cryptoserve configure --server https://your-server -cryptoserve configure --refresh-token +cryptoserve context # List all contexts +cryptoserve context --verbose # Show key versions and rotation info +cryptoserve context --format json # JSON output ``` | Flag | Description | |------|-------------| -| `--token ` / `-t` | API token | -| `--refresh-token ` / `-r` | Refresh token | -| `--server ` / `-s` | Server URL | - -Also reads from environment variables: `CRYPTOSERVE_TOKEN`, `CRYPTOSERVE_REFRESH_TOKEN`, `CRYPTOSERVE_SERVER_URL`. +| `--verbose` | Show key version details | +| `--format ` | Output format: `text` (default), `json` | ### `status` — Show Configuration @@ -398,167 +221,50 @@ cryptoserve status Displays SDK configuration, identity, and server connection status. -### `verify` — Health Check - -```bash -cryptoserve verify -``` - -Checks server connectivity and reports latency. - -### `info` — Identity Information - -```bash -cryptoserve info -``` - -Displays current identity, app name, tenants, and roles. - -### `contexts` — List Encryption Contexts - -```bash -cryptoserve contexts # List all -cryptoserve contexts "pii" # Search by keyword -cryptoserve contexts -e user-pii # Show usage example -``` - -| Flag | Description | -|------|-------------| -| `--example ` / `-e` | Show usage example for a context | - -### `promote` — Promote Application - -```bash -cryptoserve promote my-app # Check readiness -cryptoserve promote my-app --confirm # Promote -cryptoserve promote my-app --to staging # Target environment -cryptoserve promote my-app --expedite # Expedited approval -``` - -| Flag | Description | -|------|-------------| -| `--to ` / `-t` | Target environment (default: `production`) | -| `--confirm` | Proceed with promotion | -| `--expedite` / `-e` | Request expedited approval | - -### `wizard` — Interactive Context Wizard - -```bash -cryptoserve wizard -``` - -Guided walkthrough for selecting encryption contexts for your application. - --- -## Backup & Restore (requires admin) +## Exit Codes -### `backup` — Create Encrypted Backup - -```bash -cryptoserve backup -o backup.enc -cryptoserve backup -o backup.enc --audit-logs -cryptoserve backup -o backup.enc --tenant-only -``` - -| Flag | Description | -|------|-------------| -| `--output ` / `-o` | Output file path | -| `--audit-logs` | Include audit logs | -| `--tenant-only` | Backup current tenant only | - -### `restore` — Restore from Backup - -```bash -cryptoserve restore --backup backup.enc --dry-run # Preview -cryptoserve restore --backup backup.enc --execute # Restore -``` - -| Flag | Description | -|------|-------------| -| `--backup ` / `-b` | Backup file (required) | -| `--dry-run` | Preview what would be restored (default) | -| `--execute` | Perform the restore | - -### `backups` — List Backups - -```bash -cryptoserve backups -``` +| Code | Meaning | +|------|---------| +| `0` | Success (scan clean, gate passed) | +| `1` | Failure (gate failed, crypto issues found, invalid input) | --- -## Key Ceremony (requires admin) - -Enterprise master key management using Shamir's Secret Sharing. - -### `ceremony status` - -```bash -cryptoserve ceremony status -``` - -Shows current state: uninitialized, sealed, or unsealed. - -### `ceremony initialize` +## Built-in Help ```bash -cryptoserve ceremony initialize --threshold 3 --shares 5 +cryptoserve help # All commands and flags +cryptoserve scan --help # Scan-specific options +cryptoserve --version # Current version ``` -Creates master key and generates recovery shares. - -| Flag | Description | -|------|-------------| -| `--threshold ` | Shares required to unseal | -| `--shares ` | Total shares to generate | - -### `ceremony seal` +Every command supports `--help` for detailed usage. -```bash -cryptoserve ceremony seal -``` - -Clears master key from memory. Service must be unsealed to resume operation. - -### `ceremony unseal` - -```bash -cryptoserve ceremony unseal --share -cryptoserve ceremony unseal --interactive -``` - -| Flag | Description | -|------|-------------| -| `--share ` | Recovery share (hex-encoded) | -| `--interactive` | Prompt for share input | - -### `ceremony verify` - -```bash -cryptoserve ceremony verify --share -``` - -Validates a recovery share without using it. - -### `ceremony audit` - -```bash -cryptoserve ceremony audit -``` +--- -Displays audit log of ceremony operations. +## Python CLI Only ---- +The following commands are available via `pip install cryptoserve` (`python -m cryptoserve`) but not yet in the Node.js CLI (`npx cryptoserve`): -## Binary Management +### Scanning & Analysis +- **`deps`** — Dedicated dependency analysis with binary downloaders +- **`push`** — Upload scan results or CBOM to CryptoServe dashboard -The `scan` and `deps` commands use Go binaries (CryptoScan, CryptoDeps) that are managed automatically: +### Crypto Tools +- **`token`** — JWT token creation/verification +- **`certs`** — Certificate management (generate-csr, self-signed, parse, verify) -- **Cache location**: `~/.cryptoserve/bin/` -- **Auto-download**: Binaries are fetched on first use -- **Integrity**: SHA-256 checksum verification on download -- **Update**: Use `--update` to force re-download -- **Platforms**: macOS (arm64, amd64), Linux (arm64, amd64), Windows (amd64) +### Server Commands (requires login) +- **`logout`** — Clear credentials +- **`configure`** — Set SDK configuration (token, server URL) +- **`verify`** — Server health check +- **`info`** — Display identity information +- **`contexts`** — List and search encryption contexts +- **`promote`** — Promote application to production +- **`wizard`** — Interactive context selection wizard -The `--python-only` flag on `scan` bypasses the binary and uses a built-in Python scanner with fewer patterns. +### Admin Commands +- **`backup`** / **`restore`** / **`backups`** — Encrypted backup and restore +- **`ceremony`** — Enterprise key ceremony (Shamir's Secret Sharing)