@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/security.ts

@@ -0,0 +1,1079 @@
+/**
+ * Bootspring Security Command
+ * Run security scans and store scores
+ *
+ * @package bootspring
+ * @command security
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Interfaces
+interface ConfigModule {
+  load: () => { _projectRoot: string };
+}
+
+interface UtilsModule {
+  COLORS: {
+    cyan: string;
+    bold: string;
+    reset: string;
+    dim: string;
+    green: string;
+    yellow: string;
+    red: string;
+  };
+  createSpinner: (text: string) => {
+    start: () => { succeed: (text: string) => void; fail: (text: string) => void; warn: (text: string) => void };
+    succeed: (text: string) => void;
+    fail: (text: string) => void;
+    warn: (text: string) => void;
+  };
+  createProgressBar?: (value: number, max: number, width: number) => string;
+  parseArgs: (args: string[]) => ParsedArgs;
+  print: {
+    error: (msg: string) => void;
+    success: (msg: string) => void;
+    warn: (msg: string) => void;
+    dim: (msg: string) => void;
+  };
+}
+
+interface ProjectStateModule {
+  getOrCreateState: (projectRoot: string) => ProjectState;
+  loadState: (projectRoot: string) => ProjectState | null;
+  saveState: (projectRoot: string, state: ProjectState) => void;
+}
+
+interface ParsedArgs {
+  _: string[];
+  skip?: string;
+  quiet?: boolean;
+  json?: boolean;
+  [key: string]: string | boolean | string[] | undefined;
+}
+
+interface SeveritySummary {
+  critical: number;
+  high: number;
+  moderate: number;
+  low: number;
+  info?: number;
+}
+
+interface CheckResult {
+  score: number;
+  issues: Issue[];
+  summary: SeveritySummary | HeadersSummary | EnvSummary | GitignoreSummary;
+  message?: string | undefined;
+  error?: string | undefined;
+}
+
+interface HeadersSummary {
+  missing: number;
+  configured: number;
+}
+
+interface EnvSummary {
+  warnings: number;
+  good: number;
+}
+
+interface GitignoreSummary {
+  missing: number;
+  covered: number;
+}
+
+interface Issue {
+  severity: string;
+  title: string;
+  package?: string | undefined;
+  fixAvailable?: boolean | undefined;
+  message?: string | undefined;
+  file?: string | undefined;
+  count?: number | undefined;
+  current?: string | undefined;
+  recommended?: string | undefined;
+  fix?: string | undefined;
+  recommendation?: string | undefined;
+}
+
+interface SecurityCheck {
+  name: string;
+  description: string;
+  weight: number;
+  run: (projectRoot: string) => Promise<CheckResult>;
+}
+
+interface ScanResults {
+  timestamp: string;
+  overallScore: number;
+  checks: Record<string, CheckResult>;
+  summary: SeveritySummary;
+  recommendations: Recommendation[];
+}
+
+interface Recommendation {
+  priority: string;
+  title: string;
+  action: string;
+}
+
+interface ProjectState {
+  security?: SecurityState | undefined;
+  health?: { breakdown?: { security?: number | undefined } | undefined } | undefined;
+}
+
+interface SecurityState {
+  score: number;
+  lastScan: string | null;
+  history: Array<{ score: number; date: string }>;
+  summary?: SeveritySummary | undefined;
+  checks?: Record<string, { score: number; issues: number }> | undefined;
+}
+
+interface ScanOptions {
+  skip?: string[] | undefined;
+  quiet?: boolean | undefined;
+}
+
+interface AuditMetadata {
+  vulnerabilities?: {
+    critical?: number | undefined;
+    high?: number | undefined;
+    moderate?: number | undefined;
+    low?: number | undefined;
+    info?: number | undefined;
+  } | undefined;
+}
+
+interface VulnerabilityData {
+  severity: string;
+  via?: Array<{ title?: string | undefined }> | undefined;
+  fixAvailable?: boolean | undefined;
+}
+
+interface AuditOutput {
+  metadata?: AuditMetadata | undefined;
+  vulnerabilities?: Record<string, VulnerabilityData> | undefined;
+}
+
+// Lazy load modules
+const config = require('../core/config') as ConfigModule;
+const utils = require('../core/utils') as UtilsModule;
+const projectState = require('../core/project-state') as ProjectStateModule;
+
+// ============================================================================
+// Security Check Definitions
+// ============================================================================
+
+const SECURITY_CHECKS: Record<string, SecurityCheck> = {
+  dependencies: {
+    name: 'Dependency Audit',
+    description: 'Check for vulnerable npm packages',
+    weight: 30,
+    run: runDependencyAudit
+  },
+  secrets: {
+    name: 'Secrets Detection',
+    description: 'Scan for exposed secrets and API keys',
+    weight: 25,
+    run: runSecretsDetection
+  },
+  permissions: {
+    name: 'File Permissions',
+    description: 'Check for insecure file permissions',
+    weight: 10,
+    run: runPermissionsCheck
+  },
+  headers: {
+    name: 'Security Headers',
+    description: 'Verify security headers configuration',
+    weight: 15,
+    run: runHeadersCheck
+  },
+  env: {
+    name: 'Environment Variables',
+    description: 'Check .env files for best practices',
+    weight: 10,
+    run: runEnvCheck
+  },
+  gitignore: {
+    name: 'Gitignore Coverage',
+    description: 'Verify sensitive files are ignored',
+    weight: 10,
+    run: runGitignoreCheck
+  }
+};
+
+// Severity weights for scoring
+const SEVERITY_WEIGHTS: Record<string, number> = {
+  critical: 40,
+  high: 25,
+  moderate: 10,
+  low: 5,
+  info: 1
+};
+
+// ============================================================================
+// Security Check Implementations
+// ============================================================================
+
+/**
+ * Run npm audit for dependency vulnerabilities
+ */
+async function runDependencyAudit(projectRoot: string): Promise<CheckResult> {
+  const result: CheckResult = {
+    score: 100,
+    issues: [],
+    summary: { critical: 0, high: 0, moderate: 0, low: 0, info: 0 }
+  };
+
+  try {
+    // Check if package-lock.json exists
+    const lockFile = path.join(projectRoot, 'package-lock.json');
+    if (!fs.existsSync(lockFile)) {
+      return {
+        score: 100,
+        issues: [],
+        summary: result.summary,
+        message: 'No package-lock.json found'
+      };
+    }
+
+    const output = execSync('npm audit --json 2>/dev/null || true', {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      maxBuffer: 10 * 1024 * 1024
+    });
+
+    if (output.trim()) {
+      const audit = JSON.parse(output) as AuditOutput;
+
+      if (audit.metadata?.vulnerabilities) {
+        const vulns = audit.metadata.vulnerabilities;
+        const summary = result.summary as SeveritySummary;
+        summary.critical = vulns.critical || 0;
+        summary.high = vulns.high || 0;
+        summary.moderate = vulns.moderate || 0;
+        summary.low = vulns.low || 0;
+        summary.info = vulns.info || 0;
+
+        // Calculate score based on vulnerabilities
+        const deductions =
+          (summary.critical * (SEVERITY_WEIGHTS.critical || 0)) +
+          (summary.high * (SEVERITY_WEIGHTS.high || 0)) +
+          (summary.moderate * (SEVERITY_WEIGHTS.moderate || 0)) +
+          (summary.low * (SEVERITY_WEIGHTS.low || 0));
+
+        result.score = Math.max(0, 100 - deductions);
+
+        // Add top issues
+        if (audit.vulnerabilities) {
+          const vulnList = Object.entries(audit.vulnerabilities).slice(0, 5);
+          for (const [name, data] of vulnList) {
+            result.issues.push({
+              severity: data.severity,
+              package: name,
+              title: data.via?.[0]?.title || 'Vulnerability found',
+              fixAvailable: data.fixAvailable
+            });
+          }
+        }
+      }
+    }
+  } catch (error) {
+    result.issues.push({
+      severity: 'info',
+      title: 'Could not run npm audit',
+      message: (error as Error).message
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Scan for exposed secrets
+ */
+async function runSecretsDetection(projectRoot: string): Promise<CheckResult> {
+  const result: CheckResult = {
+    score: 100,
+    issues: [],
+    summary: { critical: 0, high: 0, moderate: 0, low: 0 }
+  };
+
+  // Patterns to detect secrets
+  const secretPatterns: Array<{ pattern: RegExp; name: string; severity: string }> = [
+    { pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*['"][a-zA-Z0-9]{20,}['"]/gi, name: 'API Key', severity: 'high' },
+    { pattern: /(?:secret|password|passwd|pwd)\s*[:=]\s*['"][^'"]{8,}['"]/gi, name: 'Password/Secret', severity: 'critical' },
+    { pattern: /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/g, name: 'Private Key', severity: 'critical' },
+    { pattern: /(?:aws[_-]?(?:access|secret)[_-]?(?:key|id))\s*[:=]\s*['"][A-Z0-9]{16,}['"]/gi, name: 'AWS Credentials', severity: 'critical' },
+    { pattern: /ghp_[a-zA-Z0-9]{36}/g, name: 'GitHub Token', severity: 'high' },
+    { pattern: /sk-[a-zA-Z0-9]{48}/g, name: 'OpenAI API Key', severity: 'high' },
+    { pattern: /xox[baprs]-[a-zA-Z0-9-]{10,}/g, name: 'Slack Token', severity: 'high' },
+    { pattern: /AKIA[0-9A-Z]{16}/g, name: 'AWS Access Key ID', severity: 'critical' },
+    { pattern: /stripe[_-]?(?:sk|pk)_(?:live|test)_[a-zA-Z0-9]{24}/gi, name: 'Stripe Key', severity: 'high' }
+  ];
+
+  // Files to scan (exclude node_modules, .git, etc.)
+  const excludeDirs = ['node_modules', '.git', 'dist', 'build', '.next', 'coverage'];
+  const includeExts = ['.js', '.ts', '.jsx', '.tsx', '.json', '.yaml', '.yml', '.env.example', '.config.js'];
+
+  function scanDir(dir: string, depth = 0): void {
+    if (depth > 5) return; // Limit depth
+
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+          if (!excludeDirs.includes(entry.name) && !entry.name.startsWith('.')) {
+            scanDir(fullPath, depth + 1);
+          }
+        } else if (entry.isFile()) {
+          const ext = path.extname(entry.name);
+
+          // Skip .env files (they're supposed to have secrets but should be gitignored)
+          if (entry.name === '.env' || entry.name.endsWith('.env.local')) {
+            continue;
+          }
+
+          if (includeExts.includes(ext) || entry.name.includes('.env.')) {
+            scanFile(fullPath);
+          }
+        }
+      }
+    } catch {
+      // Ignore permission errors
+    }
+  }
+
+  function scanFile(filePath: string): void {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const relativePath = path.relative(projectRoot, filePath);
+
+      for (const { pattern, name, severity } of secretPatterns) {
+        pattern.lastIndex = 0; // Reset regex
+        const matches = content.match(pattern);
+
+        if (matches) {
+          const summary = result.summary as SeveritySummary;
+          const currentCount = (summary[severity as keyof SeveritySummary] as number | undefined) || 0;
+          (summary as unknown as Record<string, number>)[severity] = currentCount + matches.length;
+          result.issues.push({
+            severity,
+            title: `Potential ${name} exposed`,
+            file: relativePath,
+            count: matches.length
+          });
+        }
+      }
+    } catch {
+      // Ignore read errors
+    }
+  }
+
+  scanDir(projectRoot);
+
+  // Calculate score
+  const summary = result.summary as SeveritySummary;
+  const deductions =
+    (summary.critical * (SEVERITY_WEIGHTS.critical || 0)) +
+    (summary.high * (SEVERITY_WEIGHTS.high || 0)) +
+    (summary.moderate * (SEVERITY_WEIGHTS.moderate || 0)) +
+    (summary.low * (SEVERITY_WEIGHTS.low || 0));
+
+  result.score = Math.max(0, 100 - deductions);
+
+  return result;
+}
+
+/**
+ * Check file permissions
+ */
+async function runPermissionsCheck(projectRoot: string): Promise<CheckResult> {
+  const result: CheckResult = {
+    score: 100,
+    issues: [],
+    summary: { critical: 0, high: 0, moderate: 0, low: 0 }
+  };
+
+  // Check common sensitive files
+  const sensitiveFiles: Array<{ path: string; recommended: string; severity: string }> = [
+    { path: '.env', recommended: '600', severity: 'high' },
+    { path: '.env.local', recommended: '600', severity: 'high' },
+    { path: 'id_rsa', recommended: '600', severity: 'critical' },
+    { path: '.ssh/id_rsa', recommended: '600', severity: 'critical' },
+    { path: 'credentials.json', recommended: '600', severity: 'high' },
+    { path: 'serviceAccount.json', recommended: '600', severity: 'high' }
+  ];
+
+  for (const { path: filePath, recommended, severity } of sensitiveFiles) {
+    const fullPath = path.join(projectRoot, filePath);
+
+    if (fs.existsSync(fullPath)) {
+      try {
+        const stats = fs.statSync(fullPath);
+        const mode = (stats.mode & parseInt('777', 8)).toString(8);
+
+        // Check if file is world-readable
+        if (stats.mode & parseInt('004', 8)) {
+          const summary = result.summary as SeveritySummary;
+          const currentVal = (summary as unknown as Record<string, number>)[severity] || 0;
+          (summary as unknown as Record<string, number>)[severity] = currentVal + 1;
+          result.issues.push({
+            severity,
+            title: `${filePath} is world-readable`,
+            current: mode,
+            recommended,
+            fix: `chmod ${recommended} ${filePath}`
+          });
+        }
+      } catch {
+        // Ignore stat errors
+      }
+    }
+  }
+
+  const summary = result.summary as SeveritySummary;
+  const deductions =
+    (summary.critical * 20) +
+    (summary.high * 10) +
+    (summary.moderate * 5);
+
+  result.score = Math.max(0, 100 - deductions);
+
+  return result;
+}
+
+/**
+ * Check security headers configuration
+ */
+async function runHeadersCheck(projectRoot: string): Promise<CheckResult> {
+  const result: CheckResult = {
+    score: 100,
+    issues: [],
+    summary: { missing: 0, configured: 0 } as HeadersSummary
+  };
+
+  // Check for Next.js security headers
+  const nextConfig = path.join(projectRoot, 'next.config.js');
+  const nextConfigMjs = path.join(projectRoot, 'next.config.mjs');
+  const vercelJson = path.join(projectRoot, 'vercel.json');
+
+  const requiredHeaders = [
+    'X-Content-Type-Options',
+    'X-Frame-Options',
+    'X-XSS-Protection',
+    'Strict-Transport-Security',
+    'Content-Security-Policy'
+  ];
+
+  let hasHeaderConfig = false;
+  const summary = result.summary as HeadersSummary;
+
+  // Check next.config.js
+  for (const configPath of [nextConfig, nextConfigMjs]) {
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, 'utf-8');
+      if (content.includes('headers') || content.includes('securityHeaders')) {
+        hasHeaderConfig = true;
+
+        // Check which headers are configured
+        for (const header of requiredHeaders) {
+          if (content.includes(header)) {
+            summary.configured++;
+          } else {
+            summary.missing++;
+            result.issues.push({
+              severity: 'moderate',
+              title: `Missing ${header}`,
+              file: path.basename(configPath)
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // Check vercel.json
+  if (fs.existsSync(vercelJson)) {
+    const content = fs.readFileSync(vercelJson, 'utf-8');
+    if (content.includes('headers')) {
+      hasHeaderConfig = true;
+    }
+  }
+
+  if (!hasHeaderConfig) {
+    result.score = 50;
+    result.issues.push({
+      severity: 'moderate',
+      title: 'No security headers configured',
+      recommendation: 'Add security headers to next.config.js or vercel.json'
+    });
+  } else {
+    result.score = Math.max(0, 100 - (summary.missing * 10));
+  }
+
+  return result;
+}
+
+/**
+ * Check environment variable best practices
+ */
+async function runEnvCheck(projectRoot: string): Promise<CheckResult> {
+  const result: CheckResult = {
+    score: 100,
+    issues: [],
+    summary: { warnings: 0, good: 0 } as EnvSummary
+  };
+
+  const envExample = path.join(projectRoot, '.env.example');
+  const envLocal = path.join(projectRoot, '.env.local');
+  const envFile = path.join(projectRoot, '.env');
+  const summary = result.summary as EnvSummary;
+
+  // Check if .env.example exists
+  if (!fs.existsSync(envExample)) {
+    result.issues.push({
+      severity: 'low',
+      title: 'Missing .env.example',
+      recommendation: 'Create .env.example to document required environment variables'
+    });
+    summary.warnings++;
+  } else {
+    summary.good++;
+  }
+
+  // Check if .env is in .gitignore
+  const gitignore = path.join(projectRoot, '.gitignore');
+  if (fs.existsSync(gitignore)) {
+    const content = fs.readFileSync(gitignore, 'utf-8');
+
+    if (!content.includes('.env') || content.includes('.env.example')) {
+      if (fs.existsSync(envFile) || fs.existsSync(envLocal)) {
+        result.issues.push({
+          severity: 'high',
+          title: '.env files may not be properly gitignored',
+          recommendation: 'Ensure .env and .env.local are in .gitignore'
+        });
+        summary.warnings++;
+      }
+    } else {
+      summary.good++;
+    }
+  }
+
+  // Check for hardcoded values that should be env vars
+  const configFiles = ['next.config.js', 'next.config.mjs', 'config.js'];
+  const hardcodedPatterns = [
+    /https?:\/\/[a-z0-9-]+\.(supabase|neon|planetscale)\.co/gi,
+    /mongodb\+srv:\/\//gi,
+    /postgres:\/\//gi
+  ];
+
+  for (const configFile of configFiles) {
+    const filePath = path.join(projectRoot, configFile);
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf-8');
+
+      for (const pattern of hardcodedPatterns) {
+        pattern.lastIndex = 0;
+        if (pattern.test(content) && !content.includes('process.env')) {
+          result.issues.push({
+            severity: 'moderate',
+            title: `Potential hardcoded URL in ${configFile}`,
+            recommendation: 'Use environment variables for database/service URLs'
+          });
+          summary.warnings++;
+        }
+      }
+    }
+  }
+
+  result.score = Math.max(0, 100 - (summary.warnings * 15));
+
+  return result;
+}
+
+/**
+ * Check gitignore for sensitive file coverage
+ */
+async function runGitignoreCheck(projectRoot: string): Promise<CheckResult> {
+  const result: CheckResult = {
+    score: 100,
+    issues: [],
+    summary: { missing: 0, covered: 0 } as GitignoreSummary
+  };
+
+  const gitignore = path.join(projectRoot, '.gitignore');
+
+  if (!fs.existsSync(gitignore)) {
+    return {
+      score: 50,
+      issues: [{ severity: 'high', title: 'No .gitignore file found' }],
+      summary: { missing: 1, covered: 0 } as GitignoreSummary
+    };
+  }
+
+  const content = fs.readFileSync(gitignore, 'utf-8');
+  const summary = result.summary as GitignoreSummary;
+
+  // Sensitive patterns that should be gitignored
+  const requiredPatterns: Array<{ pattern: string; severity: string; name: string }> = [
+    { pattern: '.env', severity: 'high', name: 'Environment files' },
+    { pattern: '.env.local', severity: 'high', name: 'Local env files' },
+    { pattern: 'node_modules', severity: 'moderate', name: 'Node modules' },
+    { pattern: '*.pem', severity: 'critical', name: 'PEM certificates' },
+    { pattern: '*.key', severity: 'critical', name: 'Key files' },
+    { pattern: '.DS_Store', severity: 'low', name: 'macOS files' },
+    { pattern: 'coverage', severity: 'low', name: 'Coverage reports' }
+  ];
+
+  for (const { pattern, severity, name } of requiredPatterns) {
+    if (content.includes(pattern)) {
+      summary.covered++;
+    } else {
+      // Check if file exists before warning
+      const patternPath = path.join(projectRoot, pattern.replace('*', ''));
+      if (fs.existsSync(patternPath) || pattern.includes('*')) {
+        summary.missing++;
+        result.issues.push({
+          severity,
+          title: `${name} (${pattern}) not in .gitignore`,
+          recommendation: `Add ${pattern} to .gitignore`
+        });
+      }
+    }
+  }
+
+  const deductions =
+    (result.issues.filter(i => i.severity === 'critical').length * 20) +
+    (result.issues.filter(i => i.severity === 'high').length * 15) +
+    (result.issues.filter(i => i.severity === 'moderate').length * 5);
+
+  result.score = Math.max(0, 100 - deductions);
+
+  return result;
+}
+
+// ============================================================================
+// Main Security Functions
+// ============================================================================
+
+/**
+ * Run all security checks and calculate score
+ */
+async function runFullScan(projectRoot: string, options: ScanOptions = {}): Promise<ScanResults> {
+  const results: ScanResults = {
+    timestamp: new Date().toISOString(),
+    overallScore: 0,
+    checks: {},
+    summary: {
+      critical: 0,
+      high: 0,
+      moderate: 0,
+      low: 0,
+      info: 0
+    },
+    recommendations: []
+  };
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}🔒 Security Scan${utils.COLORS.reset}
+${utils.COLORS.dim}Running comprehensive security checks...${utils.COLORS.reset}
+`);
+
+  let totalWeight = 0;
+  let weightedScore = 0;
+
+  for (const [id, check] of Object.entries(SECURITY_CHECKS)) {
+    if (options.skip && options.skip.includes(id)) {
+      console.log(`${utils.COLORS.dim}○${utils.COLORS.reset} ${check.name}: skipped`);
+      continue;
+    }
+
+    const spinner = utils.createSpinner(`${check.name}: ${check.description}`).start();
+
+    try {
+      const result = await check.run(projectRoot);
+      results.checks[id] = result;
+
+      // Update summary
+      if (result.summary) {
+        for (const [severity, count] of Object.entries(result.summary)) {
+          if (results.summary[severity as keyof SeveritySummary] !== undefined) {
+            results.summary[severity as keyof SeveritySummary] += count as number;
+          }
+        }
+      }
+
+      // Calculate weighted score
+      totalWeight += check.weight;
+      weightedScore += result.score * check.weight;
+
+      // Show result
+      if (result.score >= 90) {
+        spinner.succeed(`${check.name}: ${utils.COLORS.green}${result.score}%${utils.COLORS.reset}`);
+      } else if (result.score >= 70) {
+        spinner.warn(`${check.name}: ${utils.COLORS.yellow}${result.score}%${utils.COLORS.reset}`);
+      } else {
+        spinner.fail(`${check.name}: ${utils.COLORS.red}${result.score}%${utils.COLORS.reset}`);
+      }
+
+      // Show critical issues
+      if (!options.quiet && result.issues.length > 0) {
+        const criticalIssues = result.issues.filter(i =>
+          i.severity === 'critical' || i.severity === 'high'
+        );
+        for (const issue of criticalIssues.slice(0, 3)) {
+          const color = issue.severity === 'critical' ? utils.COLORS.red : utils.COLORS.yellow;
+          console.log(`  ${color}└ ${issue.title}${utils.COLORS.reset}`);
+        }
+      }
+    } catch (error) {
+      spinner.fail(`${check.name}: error`);
+      results.checks[id] = { score: 0, error: (error as Error).message, issues: [], summary: { critical: 0, high: 0, moderate: 0, low: 0 } };
+    }
+  }
+
+  // Calculate overall score
+  results.overallScore = totalWeight > 0
+    ? Math.round(weightedScore / totalWeight)
+    : 0;
+
+  // Generate recommendations
+  results.recommendations = generateRecommendations(results);
+
+  return results;
+}
+
+/**
+ * Generate recommendations based on scan results
+ */
+function generateRecommendations(results: ScanResults): Recommendation[] {
+  const recommendations: Recommendation[] = [];
+
+  // Priority: critical issues first
+  if (results.summary.critical > 0) {
+    recommendations.push({
+      priority: 'critical',
+      title: `Fix ${results.summary.critical} critical security issue(s)`,
+      action: 'Review critical findings and address immediately'
+    });
+  }
+
+  if (results.summary.high > 0) {
+    recommendations.push({
+      priority: 'high',
+      title: `Address ${results.summary.high} high priority issue(s)`,
+      action: 'Run `npm audit fix` for dependency issues'
+    });
+  }
+
+  // Check-specific recommendations
+  const secretsScore = results.checks.secrets?.score;
+  if (secretsScore !== undefined && secretsScore < 100) {
+    recommendations.push({
+      priority: 'high',
+      title: 'Remove exposed secrets from codebase',
+      action: 'Move secrets to .env files and rotate compromised credentials'
+    });
+  }
+
+  const headersScore = results.checks.headers?.score;
+  if (headersScore !== undefined && headersScore < 70) {
+    recommendations.push({
+      priority: 'moderate',
+      title: 'Configure security headers',
+      action: 'Add security headers to next.config.js or vercel.json'
+    });
+  }
+
+  const gitignoreScore = results.checks.gitignore?.score;
+  if (gitignoreScore !== undefined && gitignoreScore < 90) {
+    recommendations.push({
+      priority: 'moderate',
+      title: 'Update .gitignore',
+      action: 'Ensure sensitive files are excluded from version control'
+    });
+  }
+
+  return recommendations;
+}
+
+/**
+ * Store security score in project state
+ */
+function storeSecurityScore(projectRoot: string, results: ScanResults): SecurityState {
+  const state = projectState.getOrCreateState(projectRoot);
+
+  // Add security section if not exists
+  if (!state.security) {
+    state.security = {
+      score: 0,
+      lastScan: null,
+      history: []
+    };
+  }
+
+  // Update security data
+  state.security = {
+    score: results.overallScore,
+    lastScan: results.timestamp,
+    summary: results.summary,
+    checks: Object.fromEntries(
+      Object.entries(results.checks).map(([id, check]) => [
+        id,
+        { score: check.score, issues: check.issues?.length || 0 }
+      ])
+    ),
+    history: [
+      { score: results.overallScore, date: results.timestamp },
+      ...(state.security.history || []).slice(0, 9) // Keep last 10
+    ]
+  };
+
+  // Update health breakdown if exists
+  if (state.health?.breakdown) {
+    state.health.breakdown.security = Math.round(results.overallScore * 0.25); // 25% of overall health
+  }
+
+  projectState.saveState(projectRoot, state);
+
+  return state.security;
+}
+
+/**
+ * Show security status
+ */
+function showStatus(projectRoot: string): void {
+  const state = projectState.loadState(projectRoot);
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}🔒 Security Status${utils.COLORS.reset}
+`);
+
+  if (!state?.security?.lastScan) {
+    console.log(`${utils.COLORS.dim}No security scan has been run yet.${utils.COLORS.reset}`);
+    console.log(`${utils.COLORS.dim}Run 'bootspring security scan' to perform a scan.${utils.COLORS.reset}`);
+    return;
+  }
+
+  const sec = state.security;
+  const scoreColor = sec.score >= 90 ? utils.COLORS.green :
+    sec.score >= 70 ? utils.COLORS.yellow : utils.COLORS.red;
+
+  console.log(`${utils.COLORS.bold}Overall Score${utils.COLORS.reset}`);
+  console.log(`  ${scoreColor}${utils.COLORS.bold}${sec.score}%${utils.COLORS.reset}`);
+  const lastScanDate = sec.lastScan ? new Date(sec.lastScan).toLocaleString() : 'Unknown';
+  console.log(`  ${utils.COLORS.dim}Last scan: ${lastScanDate}${utils.COLORS.reset}`);
+  console.log();
+
+  if (sec.summary) {
+    console.log(`${utils.COLORS.bold}Issues Found${utils.COLORS.reset}`);
+    console.log(`  ${utils.COLORS.red}Critical: ${sec.summary.critical || 0}${utils.COLORS.reset}`);
+    console.log(`  ${utils.COLORS.yellow}High: ${sec.summary.high || 0}${utils.COLORS.reset}`);
+    console.log(`  ${utils.COLORS.cyan}Moderate: ${sec.summary.moderate || 0}${utils.COLORS.reset}`);
+    console.log(`  ${utils.COLORS.dim}Low: ${sec.summary.low || 0}${utils.COLORS.reset}`);
+    console.log();
+  }
+
+  if (sec.checks) {
+    console.log(`${utils.COLORS.bold}Check Scores${utils.COLORS.reset}`);
+    for (const [id, check] of Object.entries(sec.checks)) {
+      const name = SECURITY_CHECKS[id]?.name || id;
+      const checkColor = check.score >= 90 ? utils.COLORS.green :
+        check.score >= 70 ? utils.COLORS.yellow : utils.COLORS.red;
+      const bar = utils.createProgressBar ?
+        utils.createProgressBar(check.score, 100, 20) :
+        `${check.score}%`;
+      console.log(`  ${name.padEnd(20)} ${checkColor}${bar}${utils.COLORS.reset}`);
+    }
+    console.log();
+  }
+
+  if (sec.history && sec.history.length > 1) {
+    console.log(`${utils.COLORS.bold}Score History${utils.COLORS.reset}`);
+    const firstHistory = sec.history[0];
+    const secondHistory = sec.history[1];
+    if (firstHistory && secondHistory) {
+      const trend = firstHistory.score - secondHistory.score;
+      const trendIcon = trend > 0 ? '↑' : trend < 0 ? '↓' : '→';
+      const trendColor = trend > 0 ? utils.COLORS.green : trend < 0 ? utils.COLORS.red : utils.COLORS.dim;
+      console.log(`  ${trendColor}${trendIcon} ${Math.abs(trend)} points from last scan${utils.COLORS.reset}`);
+      console.log(`  ${utils.COLORS.dim}${sec.history.slice(0, 5).map(h => h.score).join(' → ')}${utils.COLORS.reset}`);
+    }
+  }
+}
+
+/**
+ * Show detailed findings
+ */
+function showFindings(projectRoot: string): void {
+  const state = projectState.loadState(projectRoot);
+
+  if (!state?.security?.lastScan) {
+    console.log(`${utils.COLORS.dim}No security scan results. Run 'bootspring security scan' first.${utils.COLORS.reset}`);
+    return;
+  }
+
+  // Re-run scan to get detailed findings
+  console.log(`${utils.COLORS.dim}Re-scanning for detailed findings...${utils.COLORS.reset}\n`);
+}
+
+/**
+ * Quick security check
+ */
+async function runQuickCheck(projectRoot: string): Promise<void> {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}🔒 Quick Security Check${utils.COLORS.reset}
+`);
+
+  // Just run dependency audit and secrets detection
+  const results = {
+    dependencies: await runDependencyAudit(projectRoot),
+    secrets: await runSecretsDetection(projectRoot)
+  };
+
+  const depSummary = results.dependencies.summary as SeveritySummary;
+  const secretsSummary = results.secrets.summary as SeveritySummary;
+
+  const issues =
+    (depSummary.critical || 0) +
+    (depSummary.high || 0) +
+    (secretsSummary.critical || 0) +
+    (secretsSummary.high || 0);
+
+  if (issues === 0) {
+    utils.print.success('No critical security issues found');
+  } else {
+    utils.print.warn(`Found ${issues} high/critical security issue(s)`);
+    console.log(`${utils.COLORS.dim}Run 'bootspring security scan' for full details${utils.COLORS.reset}`);
+  }
+}
+
+/**
+ * Show help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}🔒 Bootspring Security${utils.COLORS.reset}
+${utils.COLORS.dim}Security scanning and score tracking${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring security <command> [options]
+
+${utils.COLORS.bold}Commands:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}scan${utils.COLORS.reset}           Run full security scan and store score
+  ${utils.COLORS.cyan}quick${utils.COLORS.reset}          Quick check (deps + secrets only)
+  ${utils.COLORS.cyan}status${utils.COLORS.reset}         Show current security score and history
+  ${utils.COLORS.cyan}findings${utils.COLORS.reset}       Show detailed findings from last scan
+
+${utils.COLORS.bold}Options:${utils.COLORS.reset}
+  --skip <check>   Skip specific check (deps, secrets, headers, etc.)
+  --quiet          Suppress detailed output
+  --json           Output results as JSON
+
+${utils.COLORS.bold}Checks Performed:${utils.COLORS.reset}
+  ${utils.COLORS.dim}dependencies${utils.COLORS.reset}   npm audit for vulnerable packages
+  ${utils.COLORS.dim}secrets${utils.COLORS.reset}        Scan for exposed API keys and passwords
+  ${utils.COLORS.dim}permissions${utils.COLORS.reset}    Check file permissions on sensitive files
+  ${utils.COLORS.dim}headers${utils.COLORS.reset}        Verify security headers configuration
+  ${utils.COLORS.dim}env${utils.COLORS.reset}            Check .env best practices
+  ${utils.COLORS.dim}gitignore${utils.COLORS.reset}      Verify sensitive files are ignored
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring security scan
+  bootspring security scan --skip headers
+  bootspring security quick
+  bootspring security status
+`);
+}
+
+/**
+ * Main run function
+ */
+export async function run(args: string[]): Promise<void> {
+  const parsedArgs = utils.parseArgs(args);
+  const subcommand = parsedArgs._[0];
+  const cfg = config.load();
+  const projectRoot = cfg._projectRoot;
+
+  switch (subcommand) {
+    case 'scan':
+    case 'full': {
+      const results = await runFullScan(projectRoot, {
+        skip: parsedArgs.skip ? [parsedArgs.skip] : [],
+        quiet: parsedArgs.quiet
+      });
+
+      // Store score
+      storeSecurityScore(projectRoot, results);
+
+      // Show summary
+      console.log();
+      const scoreColor = results.overallScore >= 90 ? utils.COLORS.green :
+        results.overallScore >= 70 ? utils.COLORS.yellow : utils.COLORS.red;
+
+      console.log(`${utils.COLORS.bold}Security Score: ${scoreColor}${results.overallScore}%${utils.COLORS.reset}`);
+
+      if (results.recommendations.length > 0) {
+        console.log(`\n${utils.COLORS.bold}Top Recommendations:${utils.COLORS.reset}`);
+        for (const rec of results.recommendations.slice(0, 3)) {
+          const icon = rec.priority === 'critical' ? '🔴' :
+            rec.priority === 'high' ? '🟡' : '🔵';
+          console.log(`  ${icon} ${rec.title}`);
+        }
+      }
+
+      console.log(`\n${utils.COLORS.dim}Score saved to planning/PROJECT_STATE.json${utils.COLORS.reset}`);
+
+      if (parsedArgs.json) {
+        console.log(JSON.stringify(results, null, 2));
+      }
+
+      // Exit with error if critical issues
+      if (results.summary.critical > 0) {
+        process.exitCode = 1;
+      }
+      break;
+    }
+
+    case 'quick':
+    case 'check':
+      await runQuickCheck(projectRoot);
+      break;
+
+    case 'status':
+      showStatus(projectRoot);
+      break;
+
+    case 'findings':
+    case 'details':
+      showFindings(projectRoot);
+      break;
+
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+
+    default:
+      if (!subcommand) {
+        showHelp();
+      } else {
+        utils.print.error(`Unknown command: ${subcommand}`);
+        showHelp();
+      }
+  }
+}
+
+export { runFullScan, storeSecurityScore, SECURITY_CHECKS };