@continum/cli 0.1.0

package/README.md

@@ -0,0 +1,481 @@
+# @continum/cli
+
+Continum CLI - Pre-commit credential scanner with AI-powered pattern learning
+
+## Quick Start
+
+```bash
+# 1. Install globally
+npm install -g @continum/cli
+
+# 2. Login to Continum (opens browser)
+continum login
+
+# 3. Initialize in your project
+cd your-project
+continum init
+
+# That's it! Every commit is now scanned
+```
+
+## What It Does
+
+The Continum CLI provides two-layer protection against credential leaks:
+
+**Layer 1: Local Scanner (Instant)**
+- Regex-based pattern matching
+- Runs in milliseconds before commit
+- Works offline
+- Blocks commit immediately if violations found
+
+**Layer 2: Sandbox Audit (Background)**
+- AI-powered context analysis
+- Catches generic credentials with no known pattern
+- Fire-and-forget (doesn't block workflow)
+- Creates signals for team review
+
+## Installation
+
+### For End Users
+
+```bash
+npm install -g @continum/cli
+```
+
+### For Development
+
+See [SETUP.md](./SETUP.md) for development setup instructions.
+
+## Authentication
+
+### Login (Required First Step)
+
+```bash
+continum login
+```
+
+**What happens:**
+1. Opens browser to console.continum.dev
+2. You sign in with your Continum account
+3. Browser shows "Authentication Successful"
+4. CLI automatically receives credentials
+5. Credentials saved to `~/.continum/credentials.json`
+
+**You only need to login once per machine.**
+
+## Project Setup
+
+### Initialize in Your Project
+
+```bash
+cd your-project
+continum init
+```
+
+**Requirements:**
+- Must be in a git repository
+- Must be logged in (run `continum login` first)
+
+**What it does:**
+1. Creates `.continum.json` configuration file
+2. Installs pre-commit hook at `.git/hooks/pre-commit`
+3. Verifies connection to Continum API
+
+## Daily Usage
+
+### Making Commits
+
+Just commit normally:
+
+```bash
+git add .
+git commit -m "your changes"
+```
+
+The pre-commit hook runs automatically.
+
+### Scenario 1: Clean Commit
+
+```bash
+$ git commit -m "add user feature"
+
+Continum — scanning 3 files...
+✓ Clean
+
+[main abc1234] add user feature
+```
+
+✅ Commit goes through.
+
+### Scenario 2: Known Pattern Blocked
+
+```bash
+$ git commit -m "add config"
+
+Continum — scanning 1 file...
+
+❌  BLOCKED
+
+config.ts (line 14)
+──────────────────────────────────────────────────────
+Type:     AWS_ACCESS_KEY
+Found:    AKIA••••••••7EXAMPLE
+Severity: CRITICAL
+
+Fix these before committing.
+Override (not recommended): git commit --no-verify
+```
+
+❌ Commit blocked. Remove the credential and try again.
+
+### Scenario 3: Unknown Pattern Detected
+
+```bash
+$ git commit -m "add acme integration"
+
+Continum — scanning 1 file...
+
+⚠️  POSSIBLE CREDENTIAL DETECTED
+
+config.ts (line 14)
+──────────────────────────────────────────────────────
+Type:    UNKNOWN_PATTERN (HIGH confidence)
+Found:   acme_prod_x7k9••••••••
+Pattern: acme_prod_[a-z0-9]{16}
+
+This looks like a credential, but it's not in our pattern library.
+
+Options:
+  [b] Block this commit
+  [a] Approve pattern and block (will catch in future)
+  [i] Ignore this pattern
+  [c] Continue anyway (not recommended)
+
+Choice: a
+
+Pattern description: ACME Production API Key
+Severity level: HIGH
+
+✓ Pattern saved to your library
+✓ This pattern will now be caught locally on future commits
+
+Commit blocked. Remove the credential and try again.
+```
+
+**What happened:**
+- CLI detected a potential credential
+- You approved it as a real pattern
+- Pattern saved to Continum platform
+- All team members will now catch this pattern
+- Commit still blocked (remove the credential first)
+
+## Commands
+
+### `continum login`
+
+Authenticate with your Continum account. Opens browser for secure OAuth-style authentication.
+
+```bash
+continum login
+```
+
+**You only need to run this once per machine.**
+
+### `continum init`
+
+Initialize Continum in a project.
+
+```bash
+continum init
+```
+
+**Requirements:**
+- Must be in a git repository
+- Must be logged in first
+
+**Options:**
+- `--silent` - Non-interactive mode (for postinstall scripts)
+
+### `continum scan`
+
+Scan files for credentials and sensitive data.
+
+```bash
+# Scan specific files
+continum scan src/config.ts src/utils.ts
+
+# Scan staged files
+continum scan --staged
+
+# Scan with strict mode (block on unknown patterns)
+continum scan --staged --strict
+```
+
+**Options:**
+- `--staged` - Scan staged files (used by pre-commit hook)
+- `--hook` - Minimal output mode (for git hooks)
+- `--strict` - Block on unknown patterns without prompting
+- `--warn-only` - Show warnings but don't block commits
+
+### `continum patterns`
+
+Manage credential patterns.
+
+```bash
+# Update patterns from Continum API
+continum patterns update
+
+# List all available patterns
+continum patterns list
+```
+
+### `continum status`
+
+Check Continum configuration and API connection.
+
+```bash
+continum status
+```
+
+Shows:
+- Git repository status
+- Configuration file
+- Pre-commit hook status
+- API connection
+- Your account info
+
+### `continum uninstall`
+
+Remove Continum pre-commit hook from the repository.
+
+```bash
+continum uninstall
+```
+
+## Configuration
+
+The `.continum.json` file controls scanner behavior:
+
+```json
+{
+  "scanOnCommit": true,
+  "sandbox": "employee_confidential",
+  "block": ["CRITICAL", "HIGH"],
+  "warn": ["MEDIUM"],
+  "ignore": [
+    ".env.example",
+    "**/*.test.ts",
+    "**/fixtures/**",
+    "**/mocks/**"
+  ],
+  "patterns": {
+    "custom": [
+      "ACME-[0-9]{6}",
+      "internal-project-[a-z]+"
+    ]
+  }
+}
+```
+
+### Configuration Options
+
+- `scanOnCommit` - Enable/disable pre-commit scanning (default: true)
+- `sandbox` - Continum sandbox to use for auditing
+- `block` - Risk levels that block commits (CRITICAL, HIGH, MEDIUM, LOW)
+- `warn` - Risk levels that show warnings but allow commits
+- `ignore` - Glob patterns for files to skip
+- `patterns.custom` - Custom regex patterns to detect
+
+## Built-in Patterns
+
+The CLI ships with patterns for:
+
+**Cloud Credentials:**
+- AWS access keys (AKIA...)
+- GCP service account JSON
+- Azure connection strings
+
+**API Tokens:**
+- Stripe (sk_live_...)
+- GitHub PATs (ghp_...)
+- Anthropic (sk-ant-...)
+- OpenAI (sk-...)
+
+**Database:**
+- PostgreSQL connection strings
+- MySQL connection strings
+- MongoDB connection strings
+
+**Private Keys:**
+- PEM format RSA/EC keys
+- SSH private keys
+
+**UK PII:**
+- NHS numbers
+- National Insurance numbers
+
+**Generic:**
+- JWT tokens
+- High-entropy API keys
+
+## Team Deployment
+
+### Option 1: Manual Setup
+
+Each team member runs:
+
+```bash
+npm install -g @continum/cli
+continum login
+cd project
+continum init
+```
+
+### Option 2: Auto-Install (Recommended)
+
+Add to your project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "continum init --silent"
+  },
+  "devDependencies": {
+    "@continum/cli": "^0.1.0"
+  }
+}
+```
+
+**Team member workflow:**
+
+```bash
+# 1. Install CLI globally (one time)
+npm install -g @continum/cli
+
+# 2. Login (one time per machine)
+continum login
+
+# 3. Clone and install project
+git clone <your-repo>
+cd <your-repo>
+npm install
+# ↑ Automatically runs continum init --silent
+```
+
+## Troubleshooting
+
+### "Command not found: continum"
+
+```bash
+npm install -g @continum/cli
+```
+
+### "Not logged in to Continum"
+
+```bash
+continum login
+```
+
+### "Not in a git repository"
+
+```bash
+git init
+```
+
+### "Port 8765 already in use"
+
+```bash
+# Kill process on port 8765
+lsof -ti:8765 | xargs kill -9
+
+# Then try again
+continum login
+```
+
+### "Authentication timeout"
+
+```bash
+# Just try again
+continum login
+```
+
+### "Failed to connect to Continum API"
+
+```bash
+# Check credentials
+cat ~/.continum/credentials.json
+
+# Re-login
+continum login
+```
+
+### Commits still going through despite violations
+
+```bash
+# Verify hook is installed
+ls -la .git/hooks/pre-commit
+
+# Verify hook is executable
+chmod +x .git/hooks/pre-commit
+
+# Test manually
+continum scan --staged
+```
+
+## File Locations
+
+```bash
+# Credentials (per machine)
+~/.continum/credentials.json
+
+# Pattern cache (per machine)
+~/.continum/patterns.json
+
+# Project config (committed to repo)
+.continum.json
+
+# Git hook (per project)
+.git/hooks/pre-commit
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/security.yml
+name: Security Scan
+
+on: [push, pull_request]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      
+      - name: Install Continum CLI
+        run: npm install -g @continum/cli
+      
+      - name: Setup credentials
+        env:
+          CONTINUM_API_KEY: ${{ secrets.CONTINUM_API_KEY }}
+        run: |
+          mkdir -p ~/.continum
+          echo '{"apiUrl":"https://api.continum.dev","apiKey":"'$CONTINUM_API_KEY'"}' > ~/.continum/credentials.json
+      
+      - name: Initialize Continum
+        run: continum init --silent
+      
+      - name: Scan all files
+        run: continum scan $(git ls-files)
+```
+
+## Support
+
+- Documentation: https://docs.continum.dev/cli
+- Issues: GitHub Issues
+- Discord: https://discord.gg/continum
+- Email: support@continum.dev
+
+## License
+
+MIT