cto-ai-cli 3.0.2 → 3.2.0

package/DOCS.md

@@ -5,6 +5,7 @@
 ## Table of Contents
 
 - [CLI Commands](#cli-commands)
+- [Security Audit](#security-audit---audit)
 - [MCP Server](#mcp-server)
 - [API Server](#api-server)
 - [Programmatic API](#programmatic-api)
@@ -83,6 +84,156 @@ cto2 policy validate
 cto2 policy init
 ```
 
+### `npx cto-ai-cli` (zero-install CLI)
+
+The default binary. All flags work with zero install via `npx`.
+
+```bash
+npx cto-ai-cli                           # Score your project
+npx cto-ai-cli ./path                    # Score a specific project
+npx cto-ai-cli --fix                     # Auto-generate .cto/context.md, config.json, .cteignore
+npx cto-ai-cli --context "your task"     # Task-specific context with file contents
+npx cto-ai-cli --audit                   # Security audit: detect secrets & PII
+npx cto-ai-cli --report                  # Shareable markdown report + shields.io badge
+npx cto-ai-cli --compare                 # Compare your score vs popular open source projects
+npx cto-ai-cli --benchmark              # CTO vs naive vs random comparison
+npx cto-ai-cli --json                    # Machine-readable JSON output
+npx cto-ai-cli --help                    # Show all options
+```
+
+Flags can be combined: `npx cto-ai-cli --fix --audit --report --compare`
+
+---
+
+## Security Audit (`--audit`)
+
+Full-project secret and PII detection. Scans all source files for hardcoded credentials, tokens, keys, passwords, connection strings, and personally identifiable information.
+
+### Usage
+
+```bash
+npx cto-ai-cli --audit                   # Full audit with terminal output
+npx cto-ai-cli --audit --fix             # Audit + auto-generate context files
+CI=true npx cto-ai-cli --audit           # CI mode: exit code 1 on critical/high findings
+```
+
+### Detection engine
+
+CTO uses a **dual-strategy** detection approach:
+
+**1. Pattern matching (30+ patterns)**
+
+| Type | Pattern examples | Severity |
+|------|-----------------|----------|
+| `api-key` | OpenAI `sk-*`, Anthropic `sk-ant-*`, Stripe `sk_live_*`, Google `AIza*`, SendGrid `SG.*.*` | Critical |
+| `aws-key` | `AKIA*` (Access Key ID), `aws_secret_access_key=*` | Critical |
+| `token` | GitHub `ghp_*`/`gho_*`, GitLab `glpat-*`, Slack `xoxb-*`/`xoxp-*`, npm `npm_*`, JWT `eyJ*.*.*` | Critical/High |
+| `private-key` | `-----BEGIN RSA PRIVATE KEY-----`, `-----BEGIN OPENSSH PRIVATE KEY-----` | Critical |
+| `connection-string` | `mongodb://user:pass@host`, `postgres://`, `DATABASE_URL=` | Critical |
+| `password` | `password=`, `DB_PASSWORD=`, `MYSQL_PASSWORD=` | High |
+| `env-variable` | `SECRET_KEY=`, `PRIVATE_TOKEN=`, `ENCRYPTION_PASS=` | High |
+| `pii` | Email addresses, possible SSNs | Medium |
+
+**2. Shannon entropy analysis**
+
+For strings that don't match a known pattern but look like secrets:
+- Scans all quoted strings ≥40 characters
+- Calculates Shannon entropy (randomness measure)
+- Flags strings with entropy ≥5.0 bits (very random = likely a secret)
+- Automatically skips: hex hashes, camelCase identifiers, base64 padding, integrity hashes, comments, test files
+
+### Smart filtering (false positive reduction)
+
+The scanner skips:
+- **Placeholders**: `${API_KEY}`, `{{SECRET}}`, `YOUR_KEY_HERE`, `CHANGE_ME`, `example`, `TODO`, `dummy`, `sample`
+- **Test files**: `*.test.ts`, `*.spec.ts`, `__tests__/*` (entropy analysis only — patterns still apply)
+- **Declaration files**: `*.d.ts` (entropy analysis only)
+- **Comments**: Lines starting with `//`, `#`, `*`
+
+### Output artifacts
+
+| File | Format | Purpose |
+|------|--------|---------|
+| `.cto/audit/YYYY-MM-DD.jsonl` | JSON Lines (append-only) | Audit log — one entry per run. Run daily to build history. |
+| `.cto/audit/report.md` | Markdown | Full report with findings table — share with team or compliance. |
+| `.cto/.env.example` | Text | Auto-generated `.env` template with all detected variable names. |
+
+### Audit log format (`.jsonl`)
+
+Each line is a JSON object:
+
+```json
+{
+  "timestamp": "2026-02-24T23:38:00.000Z",
+  "version": "3.2.0",
+  "summary": {
+    "filesScanned": 179,
+    "filesWithSecrets": 12,
+    "totalFindings": 51,
+    "bySeverity": { "critical": 34, "high": 5, "medium": 12, "low": 0 },
+    "byType": { "api-key": 21, "private-key": 5, "aws-key": 4, "token": 4, "connection-string": 3, "password": 2, "pii": 12 }
+  },
+  "findings": [
+    { "type": "api-key", "file": "src/config/stripe.ts", "line": 8, "severity": "critical", "redacted": "sk_l********************yZ" }
+  ]
+}
+```
+
+### Programmatic API
+
+```typescript
+import { auditProject, scanContentForSecrets, scanContentForHighEntropy } from 'cto-ai-cli/govern';
+
+// Full project audit
+const result = await auditProject('/path/to/project', filePaths, {
+  customPatterns: ['MY_INTERNAL_TOKEN=[a-z0-9]+'],  // optional extra patterns
+  entropyThreshold: 5.0,                            // default: 5.0
+  includePII: true,                                 // default: true
+});
+
+console.log(result.summary);          // { totalFindings, bySeverity, byType, ... }
+console.log(result.findings);         // SecretFinding[]
+console.log(result.recommendations);  // string[]
+
+// Scan a single string
+const findings = scanContentForSecrets(code, 'file.ts');
+
+// Entropy-only scan
+const entropyFindings = scanContentForHighEntropy(code, 'file.ts', 5.0);
+```
+
+### CI/CD integration
+
+When `CI=true` is set, `--audit` exits with code 1 if any critical or high-severity findings are detected. Use this in:
+
+**GitHub Actions:**
+```yaml
+- name: CTO Security Audit
+  run: npx cto-ai-cli --audit
+  env:
+    CI: true
+```
+
+**Pre-commit hook (`.husky/pre-commit`):**
+```bash
+CI=true npx cto-ai-cli --audit
+```
+
+### Recommendations engine
+
+Based on findings, CTO generates actionable recommendations:
+
+| Finding type | Recommendation |
+|-------------|----------------|
+| Any critical | "Rotate all detected credentials immediately" |
+| `password` | "Move passwords to environment variables or a secrets manager" |
+| `api-key` / `aws-key` | "Use environment variables. Never commit to source control" |
+| `connection-string` | "Database connection strings should use environment variables" |
+| `private-key` | "Private keys should NEVER be in source code. Use a key management service" |
+| `pii` | "Review for GDPR/CCPA compliance. Consider data anonymization" |
+| `high-entropy` | "High-entropy strings detected. Review manually" |
+| Any finding | "Add .gitignore entry for .env files" + "Run --audit regularly or add to CI" |
+
 ---
 
 ## MCP Server

package/README.md

@@ -3,7 +3,7 @@
 > **Early access** — This is a test version. We'd love your feedback.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-433_passing-brightgreen.svg)](#)
+[![Tests](https://img.shields.io/badge/tests-449_passing-brightgreen.svg)](#)
 
 ## Try it now (zero install)
 
@@ -77,10 +77,15 @@ Without type definitions, the AI invents interfaces — wrong property names, wr
 ### Option 1: Quick score (no install)
 
 ```bash
-npx cto-ai-cli                 # Score your project
-npx cto-ai-cli ./my-project    # Score a specific project
-npx cto-ai-cli --benchmark     # Compare CTO vs naive vs random
-npx cto-ai-cli --json          # Machine-readable output (for CI)
+npx cto-ai-cli                           # Score your project
+npx cto-ai-cli ./my-project              # Score a specific project
+npx cto-ai-cli --fix                     # Auto-generate optimized context files
+npx cto-ai-cli --context "your task"     # Task-specific context for AI prompts
+npx cto-ai-cli --audit                   # Security audit: detect secrets & PII
+npx cto-ai-cli --report                  # Shareable report + README badge
+npx cto-ai-cli --compare                 # Compare your score vs popular projects
+npx cto-ai-cli --benchmark               # CTO vs naive vs random comparison
+npx cto-ai-cli --json                    # Machine-readable output (for CI)
 ```
 
 ### Option 2: Full install
@@ -197,17 +202,119 @@ Without these files, the AI has to guess the shape of `AnalyzedFile`, `ContextSe
 
 ---
 
+## 🔒 Security Audit — detect secrets before AI sees them
+
+Every time you send code to an AI, there's a risk: **API keys, tokens, passwords, and PII hiding in your codebase.**
+
+CTO now scans your entire project for secrets — before they end up in an AI prompt.
+
+```bash
+npx cto-ai-cli --audit
+```
+
+```
+  🔍 Running security audit...
+
+  ╔══════════════════════════════════════════════════╗
+  ║                                                  ║
+  ║   🔴 Security Audit: CRITICAL ISSUES FOUND       ║
+  ║                                                  ║
+  ║   Files scanned:  179                            ║
+  ║   Files affected: 12                             ║
+  ║   Total findings: 51                             ║
+  ║                                                  ║
+  ╠══════════════════════════════════════════════════╣
+  ║                                                  ║
+  ║   🔴 Critical: 34                                ║
+  ║   🟠 High:     5                                 ║
+  ║   🟡 Medium:   12                                ║
+  ║                                                  ║
+  ╚══════════════════════════════════════════════════╝
+
+  Findings:
+
+  🔴 CRITICAL src/config/stripe.ts:8
+             api-key: sk_l********************yZ
+  🔴 CRITICAL src/config/database.ts:14
+             connection-string: post********************db
+  🟠 HIGH     src/utils/email.ts:22
+             pii: admi**********om
+
+  Recommendations:
+
+  🚨 CRITICAL: Rotate all detected credentials immediately.
+  💡 Use environment variables for API keys.
+  💡 Add a .gitignore entry for .env files.
+
+  📁 Audit artifacts:
+  📋 .cto/audit/2026-02-24.jsonl   Audit log (append-only)
+  📊 .cto/audit/report.md          Full report
+  📝 .cto/.env.example             Template for environment variables
+```
+
+### What it detects
+
+| Category | Examples | Severity |
+|----------|----------|----------|
+| **API Keys** | OpenAI, Anthropic, Stripe, Google, SendGrid, Azure | 🔴 Critical |
+| **Cloud credentials** | AWS Access Keys, AWS Secrets | 🔴 Critical |
+| **Tokens** | GitHub, GitLab, Slack, npm, JWT | 🔴 Critical |
+| **Private keys** | RSA, SSH, EC private keys | 🔴 Critical |
+| **Database** | Connection strings (Postgres, MongoDB, Redis, MySQL) | 🔴 Critical |
+| **Passwords** | Hardcoded passwords, DB passwords | 🟠 High |
+| **PII** | Email addresses, possible SSNs | 🟡 Medium |
+| **High-entropy strings** | Random strings that look like secrets (Shannon entropy analysis) | 🟡 Medium |
+
+### How it works
+
+1. **30+ regex patterns** — battle-tested patterns for known secret formats (AWS, Stripe, Slack, GitHub, etc.)
+2. **Shannon entropy analysis** — detects random-looking strings that may be secrets, even if they don't match a known pattern
+3. **Smart filtering** — skips placeholders (`${API_KEY}`), test files, comments, and common false positives
+4. **Auto-redaction** — secrets are NEVER shown in full. All output uses redacted values (`sk_l**********yZ`)
+
+### What it generates
+
+| File | Purpose |
+|------|---------|
+| `.cto/audit/YYYY-MM-DD.jsonl` | Append-only audit log (run it daily, keep history) |
+| `.cto/audit/report.md` | Full markdown report — share with your team or compliance |
+| `.cto/.env.example` | Auto-generated template with all detected env variable names |
+
+### CI/CD integration
+
+Set `CI=true` and the audit will **exit with code 1** if critical or high-severity secrets are found:
+
+```bash
+CI=true npx cto-ai-cli --audit
+```
+
+Perfect for pre-commit hooks or CI pipelines — block PRs that contain secrets before they reach production or an AI prompt.
+
+### Why this matters
+
+Every day, developers accidentally send secrets to AI tools:
+- Copilot autocompletes with your `.env` values in context
+- You paste a file into ChatGPT that has a hardcoded API key
+- Cursor reads your database config with connection strings
+
+**CTO catches these before they leave your machine.** Zero external calls. Everything runs locally.
+
+---
+
 ## What you can do with CTO
 
 | Use case | How |
 |----------|-----|
 | **Score your project** | `npx cto-ai-cli` |
-| **Compare strategies** | `npx cto-ai-cli --benchmark` |
-| **Get optimized context for a task** | `cto2 interact "your task"` |
-| **PR-focused context** | `cto2 interact --pr "review this PR"` |
+| **Auto-optimize context** | `npx cto-ai-cli --fix` → generates `.cto/context.md` to paste into AI |
+| **Task-specific context** | `npx cto-ai-cli --context "refactor auth"` → optimized for your task |
+| **Security audit** | `npx cto-ai-cli --audit` → detect secrets & PII before AI sees them |
+| **Shareable report** | `npx cto-ai-cli --report` → markdown report + README badge |
+| **Compare vs open source** | `npx cto-ai-cli --compare` → your score vs Zod, Next.js, Express |
+| **Compare strategies** | `npx cto-ai-cli --benchmark` → CTO vs naive vs random |
+| **Get context for a task** | `cto2 interact "your task"` |
 | **Use in your AI editor** | Add MCP server (see setup above) |
-| **Use in CI/CD** | GitHub Action posts score on every PR |
-| **Use as an API** | `cto2-api` starts an HTTP server |
+| **Block secrets in CI** | `CI=true npx cto-ai-cli --audit` |
 | **JSON output (scripting)** | `npx cto-ai-cli --json` |
 
 ---
@@ -226,10 +333,12 @@ This is an early test version. Here's what we know:
 ## What's next
 
 We're working on:
-- **More language support** — deeper analysis for Python and Go
-- **VS Code extension** — see risk scores and context suggestions inline
-- **Model-specific optimization** — different context for GPT-4 vs Claude vs Gemini
-- **Team features** — share learned patterns across your team
+- **Context Gateway** — proxy between your team and any AI, with automatic context optimization and cost tracking
+- **Monorepo intelligence** — package-aware selection for large monorepos (60-80% more token savings)
+- **CI Quality Gate** — GitHub Action that posts context score and secret audit on every PR
+- **VS Code extension** — live score, risk indicators, and context suggestions inline
+- **Learning mode** — CTO improves based on which AI suggestions you accept/reject
+- **More language support** — deeper analysis for Python, Go, and Rust
 - **Your feedback** — [open an issue](https://github.com/cto-ai/cto-ai-cli/issues) or reach out
 
 ---
@@ -241,7 +350,7 @@ git clone <repo-url>
 cd cto
 npm install
 npm run build
-npm test          # 433 tests
+npm test          # 449 tests
 npm run typecheck # strict TypeScript
 ```
 

package/dist/action/index.js

@@ -24324,7 +24324,29 @@ var BUILTIN_PATTERNS = [
   { type: "connection-string", source: `(?:mongodb(?:\\+srv)?|postgres(?:ql)?|mysql|redis|amqp):\\/\\/[^\\s'"]+:[^\\s'"]+@[^\\s'"]+`, flags: "gi", severity: "critical", description: "Database Connection String" },
   { type: "connection-string", source: `(?:DATABASE_URL|REDIS_URL|MONGODB_URI)\\s*[:=]\\s*['"]?([^\\s'"]{10,})['"]?`, flags: "gi", severity: "high", description: "Database URL" },
   // Environment variables with secrets
-  { type: "env-variable", source: `(?:SECRET|PRIVATE|ENCRYPTION)[_-]?(?:KEY|TOKEN|PASS)\\s*[:=]\\s*['"]?([^\\s'"]{8,})['"]?`, flags: "gi", severity: "high", description: "Secret Environment Variable" }
+  { type: "env-variable", source: `(?:SECRET|PRIVATE|ENCRYPTION)[_-]?(?:KEY|TOKEN|PASS)\\s*[:=]\\s*['"]?([^\\s'"]{8,})['"]?`, flags: "gi", severity: "high", description: "Secret Environment Variable" },
+  // Stripe
+  { type: "api-key", source: "sk_live_[a-zA-Z0-9]{24,}", flags: "g", severity: "critical", description: "Stripe Live Secret Key" },
+  { type: "api-key", source: "pk_live_[a-zA-Z0-9]{24,}", flags: "g", severity: "high", description: "Stripe Live Publishable Key" },
+  { type: "api-key", source: "rk_live_[a-zA-Z0-9]{24,}", flags: "g", severity: "critical", description: "Stripe Restricted Key" },
+  // Slack
+  { type: "token", source: "xoxb-[0-9]{10,}-[0-9]{10,}-[a-zA-Z0-9]{24,}", flags: "g", severity: "critical", description: "Slack Bot Token" },
+  { type: "token", source: "xoxp-[0-9]{10,}-[0-9]{10,}-[a-zA-Z0-9]{24,}", flags: "g", severity: "critical", description: "Slack User Token" },
+  { type: "api-key", source: "https://hooks\\.slack\\.com/services/T[a-zA-Z0-9_]+/B[a-zA-Z0-9_]+/[a-zA-Z0-9_]+", flags: "g", severity: "high", description: "Slack Webhook URL" },
+  // Google
+  { type: "api-key", source: "AIza[0-9A-Za-z_-]{35}", flags: "g", severity: "high", description: "Google API Key" },
+  { type: "token", source: "ya29\\.[0-9A-Za-z_-]+", flags: "g", severity: "high", description: "Google OAuth Token" },
+  // Azure
+  { type: "api-key", source: "(?:AccountKey|SharedAccessKey)\\s*=\\s*[a-zA-Z0-9+/=]{40,}", flags: "g", severity: "critical", description: "Azure Storage Key" },
+  // Twilio
+  { type: "api-key", source: "AC[a-f0-9]{32}", flags: "g", severity: "high", description: "Twilio Account SID" },
+  // SendGrid
+  { type: "api-key", source: "SG\\.[a-zA-Z0-9_-]{22}\\.[a-zA-Z0-9_-]{43}", flags: "g", severity: "critical", description: "SendGrid API Key" },
+  // JWT
+  { type: "token", source: "eyJ[a-zA-Z0-9_-]{10,}\\.eyJ[a-zA-Z0-9_-]{10,}\\.[a-zA-Z0-9_-]{10,}", flags: "g", severity: "high", description: "JSON Web Token" },
+  // PII
+  { type: "pii", source: "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b", flags: "g", severity: "medium", description: "Email Address (PII)" },
+  { type: "pii", source: "\\b\\d{3}[-.]?\\d{2}[-.]?\\d{4}\\b", flags: "g", severity: "high", description: "Possible SSN (PII)" }
 ];
 function buildPatterns(customPatterns = []) {
   const patterns = BUILTIN_PATTERNS.map((def) => ({

package/dist/api/dashboard.js

@@ -829,7 +829,29 @@ var BUILTIN_PATTERNS = [
   { type: "connection-string", source: `(?:mongodb(?:\\+srv)?|postgres(?:ql)?|mysql|redis|amqp):\\/\\/[^\\s'"]+:[^\\s'"]+@[^\\s'"]+`, flags: "gi", severity: "critical", description: "Database Connection String" },
   { type: "connection-string", source: `(?:DATABASE_URL|REDIS_URL|MONGODB_URI)\\s*[:=]\\s*['"]?([^\\s'"]{10,})['"]?`, flags: "gi", severity: "high", description: "Database URL" },
   // Environment variables with secrets
-  { type: "env-variable", source: `(?:SECRET|PRIVATE|ENCRYPTION)[_-]?(?:KEY|TOKEN|PASS)\\s*[:=]\\s*['"]?([^\\s'"]{8,})['"]?`, flags: "gi", severity: "high", description: "Secret Environment Variable" }
+  { type: "env-variable", source: `(?:SECRET|PRIVATE|ENCRYPTION)[_-]?(?:KEY|TOKEN|PASS)\\s*[:=]\\s*['"]?([^\\s'"]{8,})['"]?`, flags: "gi", severity: "high", description: "Secret Environment Variable" },
+  // Stripe
+  { type: "api-key", source: "sk_live_[a-zA-Z0-9]{24,}", flags: "g", severity: "critical", description: "Stripe Live Secret Key" },
+  { type: "api-key", source: "pk_live_[a-zA-Z0-9]{24,}", flags: "g", severity: "high", description: "Stripe Live Publishable Key" },
+  { type: "api-key", source: "rk_live_[a-zA-Z0-9]{24,}", flags: "g", severity: "critical", description: "Stripe Restricted Key" },
+  // Slack
+  { type: "token", source: "xoxb-[0-9]{10,}-[0-9]{10,}-[a-zA-Z0-9]{24,}", flags: "g", severity: "critical", description: "Slack Bot Token" },
+  { type: "token", source: "xoxp-[0-9]{10,}-[0-9]{10,}-[a-zA-Z0-9]{24,}", flags: "g", severity: "critical", description: "Slack User Token" },
+  { type: "api-key", source: "https://hooks\\.slack\\.com/services/T[a-zA-Z0-9_]+/B[a-zA-Z0-9_]+/[a-zA-Z0-9_]+", flags: "g", severity: "high", description: "Slack Webhook URL" },
+  // Google
+  { type: "api-key", source: "AIza[0-9A-Za-z_-]{35}", flags: "g", severity: "high", description: "Google API Key" },
+  { type: "token", source: "ya29\\.[0-9A-Za-z_-]+", flags: "g", severity: "high", description: "Google OAuth Token" },
+  // Azure
+  { type: "api-key", source: "(?:AccountKey|SharedAccessKey)\\s*=\\s*[a-zA-Z0-9+/=]{40,}", flags: "g", severity: "critical", description: "Azure Storage Key" },
+  // Twilio
+  { type: "api-key", source: "AC[a-f0-9]{32}", flags: "g", severity: "high", description: "Twilio Account SID" },
+  // SendGrid
+  { type: "api-key", source: "SG\\.[a-zA-Z0-9_-]{22}\\.[a-zA-Z0-9_-]{43}", flags: "g", severity: "critical", description: "SendGrid API Key" },
+  // JWT
+  { type: "token", source: "eyJ[a-zA-Z0-9_-]{10,}\\.eyJ[a-zA-Z0-9_-]{10,}\\.[a-zA-Z0-9_-]{10,}", flags: "g", severity: "high", description: "JSON Web Token" },
+  // PII
+  { type: "pii", source: "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b", flags: "g", severity: "medium", description: "Email Address (PII)" },
+  { type: "pii", source: "\\b\\d{3}[-.]?\\d{2}[-.]?\\d{4}\\b", flags: "g", severity: "high", description: "Possible SSN (PII)" }
 ];
 function buildPatterns(customPatterns = []) {
   const patterns = BUILTIN_PATTERNS.map((def) => ({