@havoc-security/scanner 0.1.0

package/src/types/index.ts

@@ -0,0 +1,164 @@
+/**
+ * HAVOC Scanner — Core Type Definitions
+ */
+
+// ─── Severity ────────────────────────────────────────────────────────────────
+
+export enum Severity {
+  Critical = 'critical',
+  High = 'high',
+  Medium = 'medium',
+  Low = 'low',
+  Info = 'info',
+}
+
+// ─── Finding ─────────────────────────────────────────────────────────────────
+
+export interface Finding {
+  /** Unique identifier for this finding (e.g., "HAVOC-001") */
+  id: string;
+  /** Severity level */
+  severity: Severity;
+  /** Name of the analyzer that produced this finding */
+  analyzer: string;
+  /** Short, descriptive title */
+  title: string;
+  /** Full description of the vulnerability */
+  description: string;
+  /** Relative file path where the issue was found */
+  file: string;
+  /** Line number (1-indexed) */
+  line: number;
+  /** Actionable recommendation for the developer */
+  recommendation: string;
+  /** CWE identifier (e.g., "CWE-89" for SQL Injection) */
+  cwe?: string;
+  /** Optional code snippet for context */
+  snippet?: string;
+}
+
+// ─── Parsed File ─────────────────────────────────────────────────────────────
+
+export interface ParsedFile {
+  /** Relative path to the file */
+  path: string;
+  /** Raw file contents */
+  content: string;
+  /** AST representation (framework-specific) */
+  ast?: unknown;
+}
+
+// ─── Analyzer ────────────────────────────────────────────────────────────────
+
+export interface Analyzer {
+  /** Unique analyzer name (e.g., "authorization-coverage") */
+  name: string;
+  /** Human-readable description of what this analyzer checks */
+  description: string;
+  /**
+   * Analyze the given parsed files and return any findings.
+   * @param files - Parsed PHP files to analyze
+   * @param config - Scanner configuration
+   */
+  analyze(files: ParsedFile[], config: HavocConfig): Promise<Finding[]>;
+}
+
+// ─── Coverage Stats ───────────────────────────────────────────────────────────
+
+export interface CoverageStats {
+  /** Total routes/endpoints found */
+  totalRoutes: number;
+  /** Routes with authorization middleware */
+  coveredRoutes: number;
+  /** Coverage percentage (0–100) */
+  coveragePercent: number;
+  /** Models scanned for mass assignment */
+  totalModels: number;
+  /** Models with $fillable or $guarded properly set */
+  protectedModels: number;
+}
+
+// ─── Scan Result ─────────────────────────────────────────────────────────────
+
+export interface ScanResult {
+  /** All findings from all analyzers */
+  findings: Finding[];
+  /** Coverage statistics */
+  coverage: CoverageStats;
+  /** Metadata about the scan */
+  metadata: ScanMetadata;
+}
+
+export interface ScanMetadata {
+  /** When the scan was performed */
+  scannedAt: string;
+  /** Framework detected (e.g., "laravel", "symfony") */
+  framework: string;
+  /** Framework version if detected */
+  frameworkVersion?: string;
+  /** Total files scanned */
+  filesScanned: number;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** HAVOC scanner version */
+  scannerVersion: string;
+}
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+
+export interface HavocConfig {
+  /**
+   * Framework to use for analysis.
+   * @default "laravel"
+   */
+  framework: 'laravel' | 'symfony' | 'auto';
+
+  /**
+   * Severity threshold for failing CI.
+   * Findings at or above this level will fail the build.
+   * @default "high"
+   */
+  failOn: Severity;
+
+  /** List of file/directory patterns to exclude */
+  exclude?: string[];
+
+  /** Analyzer-specific configuration */
+  analyzers?: AnalyzerConfig;
+
+  /** Baseline file path for suppressing known findings */
+  baseline?: string;
+
+  /**
+   * Output format.
+   * @default "text"
+   */
+  output?: 'text' | 'json' | 'sarif' | 'github';
+}
+
+export interface AnalyzerConfig {
+  authorizationCoverage?: {
+    enabled: boolean;
+    /** Minimum acceptable coverage percent */
+    minCoverage?: number;
+    /** Route prefixes to exclude (e.g., ["api/public"]) */
+    excludePrefixes?: string[];
+  };
+  massAssignment?: {
+    enabled: boolean;
+  };
+  xssSurface?: {
+    enabled: boolean;
+  };
+  sqlInjection?: {
+    enabled: boolean;
+  };
+  dependencyAudit?: {
+    enabled: boolean;
+    /** Max allowed days since last security update */
+    maxAgeDays?: number;
+  };
+  idor?: {
+    enabled: boolean;
+  };
+}

package/tests/EncryptionAnalyzer.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect } from 'vitest';
+import { EncryptionAnalyzer } from '../src/analyzers/EncryptionAnalyzer.js';
+import { DEFAULT_CONFIG } from '../src/index.js';
+import { PhpParser } from '../src/parsers/PhpParser.js';
+import { writeFile, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ParsedFile } from '../src/types/index.js';
+import { Severity } from '../src/types/index.js';
+
+const analyzer = new EncryptionAnalyzer();
+const parser = new PhpParser();
+
+async function parsedModel(phpContent: string, className = 'TestModel'): Promise<ParsedFile> {
+  const tmpPath = join(tmpdir(), `${className}_${Date.now()}.php`);
+  await writeFile(tmpPath, phpContent, 'utf-8');
+  try {
+    const parsed = await parser.parseFile(tmpPath, tmpdir());
+    return { ...parsed, path: `app/Models/${className}.php` };
+  } finally {
+    await unlink(tmpPath).catch(() => {});
+  }
+}
+
+describe('EncryptionAnalyzer', () => {
+  it('has correct name', () => {
+    expect(analyzer.name).toBe('EncryptionAnalyzer');
+  });
+
+  it('has a non-empty description', () => {
+    expect(analyzer.description.length).toBeGreaterThan(0);
+  });
+
+  it('returns empty array for empty file list', async () => {
+    const result = await analyzer.analyze([], DEFAULT_CONFIG);
+    expect(result).toHaveLength(0);
+  });
+
+  it('flags ssn field without encrypted cast as HIGH severity', async () => {
+    const file = await parsedModel(`<?php
+namespace App\\Models;
+class Patient extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['name', 'ssn'];
+}`);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const finding = result.find((f) => f.id === 'HAVOC-ENC-001' && f.title.includes('ssn'));
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe(Severity.High);
+  });
+
+  it('flags api_key field without encrypted cast', async () => {
+    const file = await parsedModel(`<?php
+namespace App\\Models;
+class Integration extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['name', 'api_key'];
+}`);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.some((f) => f.title.includes('api_key'))).toBe(true);
+  });
+
+  it('does NOT flag sensitive field that has encrypted cast', async () => {
+    const file = await parsedModel(`<?php
+namespace App\\Models;
+class Patient extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['name', 'ssn'];
+  protected $casts = ['ssn' => 'encrypted'];
+}`);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-ENC-001' && f.title.includes('ssn'))).toHaveLength(0);
+  });
+
+  it('flags sensitive field with non-encrypted cast as MEDIUM', async () => {
+    const file = await parsedModel(`<?php
+namespace App\\Models;
+class Payment extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['amount', 'credit_card'];
+  protected $casts = ['credit_card' => 'string'];
+}`);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const finding = result.find((f) => f.id === 'HAVOC-ENC-002');
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe(Severity.Medium);
+  });
+
+  it('does NOT flag non-sensitive fields', async () => {
+    const file = await parsedModel(`<?php
+namespace App\\Models;
+class Post extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['title', 'body', 'published_at'];
+}`);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-ENC-001')).toHaveLength(0);
+  });
+
+  it('ignores non-model files', async () => {
+    const file: ParsedFile = {
+      path: 'app/Http/Controllers/UserController.php',
+      content: "<?php class UserController { protected $fillable = ['ssn']; }",
+      ast: null,
+    };
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-ENC-001')).toHaveLength(0);
+  });
+
+  it('emits APP_KEY rotation info finding when config/app.php is present', async () => {
+    const appConfig: ParsedFile = {
+      path: 'config/app.php',
+      content: "<?php return ['key' => env('APP_KEY', '')];",
+      ast: null,
+    };
+    const result = await analyzer.analyze([appConfig], DEFAULT_CONFIG);
+    expect(result.some((f) => f.id === 'HAVOC-ENC-003')).toBe(true);
+    expect(result.find((f) => f.id === 'HAVOC-ENC-003')?.severity).toBe(Severity.Info);
+  });
+
+  it('uses CWE-312 for unencrypted sensitive fields', async () => {
+    const file = await parsedModel(`<?php
+namespace App\\Models;
+class Employee extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['name', 'tax_id'];
+}`);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const finding = result.find((f) => f.title.includes('tax_id'));
+    expect(finding?.cwe).toBe('CWE-312');
+  });
+
+  it('accepts encrypted:array and encrypted:object as valid encrypted casts', async () => {
+    const file = await parsedModel(`<?php
+namespace App\\Models;
+class Vault extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['bank_account', 'secret'];
+  protected $casts = ['bank_account' => 'encrypted:array', 'secret' => 'encrypted:object'];
+}`);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-ENC-001')).toHaveLength(0);
+  });
+});

package/tests/PrivilegeEscalationAnalyzer.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import { PrivilegeEscalationAnalyzer } from '../src/analyzers/PrivilegeEscalationAnalyzer.js';
+import { DEFAULT_CONFIG } from '../src/index.js';
+import { PhpParser } from '../src/parsers/PhpParser.js';
+import { writeFile, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ParsedFile } from '../src/types/index.js';
+import { Severity } from '../src/types/index.js';
+
+const analyzer = new PrivilegeEscalationAnalyzer();
+const parser = new PhpParser();
+
+async function parsedFile(phpContent: string, subPath: string): Promise<ParsedFile> {
+  const tmpPath = join(tmpdir(), `pe_test_${Date.now()}.php`);
+  await writeFile(tmpPath, phpContent, 'utf-8');
+  try {
+    const parsed = await parser.parseFile(tmpPath, tmpdir());
+    return { ...parsed, path: subPath };
+  } finally {
+    await unlink(tmpPath).catch(() => {});
+  }
+}
+
+function routeFile(content: string): ParsedFile {
+  return { path: 'routes/web.php', content, ast: null };
+}
+
+describe('PrivilegeEscalationAnalyzer', () => {
+  it('has correct name', () => {
+    expect(analyzer.name).toBe('PrivilegeEscalationAnalyzer');
+  });
+
+  it('has a non-empty description', () => {
+    expect(analyzer.description.length).toBeGreaterThan(0);
+  });
+
+  it('returns empty array for empty file list', async () => {
+    const result = await analyzer.analyze([], DEFAULT_CONFIG);
+    expect(result).toHaveLength(0);
+  });
+
+  it('flags is_admin in $fillable as CRITICAL', async () => {
+    const file = await parsedFile(`<?php
+namespace App\\Models;
+class User extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['name', 'email', 'is_admin'];
+}`, 'app/Models/User.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const finding = result.find((f) => f.id === 'HAVOC-PE-001' && f.title.includes('is_admin'));
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe(Severity.Critical);
+  });
+
+  it('flags role in $fillable as CRITICAL', async () => {
+    const file = await parsedFile(`<?php
+namespace App\\Models;
+class User extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['name', 'email', 'role'];
+}`, 'app/Models/User.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.some((f) => f.id === 'HAVOC-PE-001' && f.title.includes('role'))).toBe(true);
+  });
+
+  it('flags is_superadmin in $fillable as CRITICAL', async () => {
+    const file = await parsedFile(`<?php
+namespace App\\Models;
+class User extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['name', 'is_superadmin'];
+}`, 'app/Models/User.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.some((f) => f.severity === Severity.Critical)).toBe(true);
+  });
+
+  it('does NOT flag non-privilege fields in $fillable', async () => {
+    const file = await parsedFile(`<?php
+namespace App\\Models;
+class Post extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['title', 'body', 'user_id'];
+}`, 'app/Models/Post.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-PE-001')).toHaveLength(0);
+  });
+
+  it('flags assignRole() without authorization in controller as HIGH', async () => {
+    const file = await parsedFile(`<?php
+namespace App\\Http\\Controllers;
+class AdminController extends Controller {
+  public function assignRole(Request $request, User $user) {
+    $user->assignRole($request->role);
+    return response()->json(['status' => 'ok']);
+  }
+}`, 'app/Http/Controllers/AdminController.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const finding = result.find((f) => f.id === 'HAVOC-PE-002');
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe(Severity.High);
+  });
+
+  it('does NOT flag assignRole() when authorization is present', async () => {
+    const file = await parsedFile(`<?php
+namespace App\\Http\\Controllers;
+class AdminController extends Controller {
+  public function assignRole(Request $request, User $user) {
+    $this->authorize('manage-roles');
+    $user->assignRole($request->role);
+  }
+}`, 'app/Http/Controllers/AdminController.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-PE-002' && result[0]?.title.includes('without authorization'))).toHaveLength(0);
+  });
+
+  it('flags admin route without admin middleware as MEDIUM', async () => {
+    const content = "Route::get('/admin/users', [AdminController::class, 'index']);";
+    const file = routeFile(content);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const finding = result.find((f) => f.id === 'HAVOC-PE-003');
+    expect(finding).toBeDefined();
+    expect(finding?.severity).toBe(Severity.Medium);
+  });
+
+  it('does NOT flag admin route that has role:admin middleware', async () => {
+    const content = `
+Route::middleware(['auth', 'role:admin'])->group(function () {
+    Route::get('/admin/users', [AdminController::class, 'index']);
+});`;
+    const file = routeFile(content);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-PE-003')).toHaveLength(0);
+  });
+
+  it('uses CWE-269 for all privilege escalation findings', async () => {
+    const file = await parsedFile(`<?php
+namespace App\\Models;
+class User extends \\Illuminate\\Database\\Eloquent\\Model {
+  protected $fillable = ['name', 'is_admin'];
+}`, 'app/Models/User.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result[0]?.cwe).toBe('CWE-269');
+  });
+});

package/tests/RateLimitAnalyzer.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { RateLimitAnalyzer } from '../src/analyzers/RateLimitAnalyzer.js';
+import { DEFAULT_CONFIG } from '../src/index.js';
+import type { ParsedFile } from '../src/types/index.js';
+import { Severity } from '../src/types/index.js';
+
+function routeFile(content: string, name = 'routes/api.php'): ParsedFile {
+  return { path: name, content, ast: null };
+}
+
+const analyzer = new RateLimitAnalyzer();
+
+describe('RateLimitAnalyzer', () => {
+  it('has correct name', () => {
+    expect(analyzer.name).toBe('RateLimitAnalyzer');
+  });
+
+  it('has a non-empty description', () => {
+    expect(analyzer.description.length).toBeGreaterThan(0);
+  });
+
+  it('returns empty array for empty file list', async () => {
+    const result = await analyzer.analyze([], DEFAULT_CONFIG);
+    expect(result).toHaveLength(0);
+  });
+
+  it('ignores non-route files', async () => {
+    const file: ParsedFile = {
+      path: 'app/Http/Controllers/AuthController.php',
+      content: "Route::post('/login', [AuthController::class, 'login']);",
+      ast: null,
+    };
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result).toHaveLength(0);
+  });
+
+  it('flags login route without throttle as HIGH severity', async () => {
+    const file = routeFile("Route::post('/login', [AuthController::class, 'login']);");
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.length).toBeGreaterThan(0);
+    expect(result[0].severity).toBe(Severity.High);
+    expect(result[0].id).toBe('HAVOC-RL-001');
+  });
+
+  it('flags password reset route without throttle', async () => {
+    const file = routeFile("Route::post('/password/reset', [PasswordController::class, 'reset']);");
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const authFindings = result.filter((f) => f.id === 'HAVOC-RL-001');
+    expect(authFindings.length).toBeGreaterThan(0);
+  });
+
+  it('does NOT flag login route when throttle middleware is present', async () => {
+    const file = routeFile(
+      "Route::post('/login', [AuthController::class, 'login'])->middleware('throttle:5,1');",
+    );
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-RL-001')).toHaveLength(0);
+  });
+
+  it('does NOT flag routes inside a throttled group', async () => {
+    const content = `
+Route::middleware(['throttle:10,1'])->group(function () {
+    Route::post('/login', [AuthController::class, 'login']);
+});
+`;
+    const file = routeFile(content);
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.filter((f) => f.id === 'HAVOC-RL-001')).toHaveLength(0);
+  });
+
+  it('flags API endpoints without throttle as MEDIUM severity', async () => {
+    const content = "Route::get('/users', [UserController::class, 'index']);";
+    const file = routeFile(content, 'routes/api.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const apiFindings = result.filter((f) => f.id === 'HAVOC-RL-002');
+    expect(apiFindings.length).toBeGreaterThan(0);
+    expect(apiFindings[0].severity).toBe(Severity.Medium);
+  });
+
+  it('includes CWE-307 on auth findings and CWE-770 on API findings', async () => {
+    const content = `
+Route::post('/login', [AuthController::class, 'login']);
+Route::get('/items', [ItemController::class, 'index']);
+`;
+    const file = routeFile(content, 'routes/api.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    const authFinding = result.find((f) => f.id === 'HAVOC-RL-001');
+    const apiFinding = result.find((f) => f.id === 'HAVOC-RL-002');
+    expect(authFinding?.cwe).toBe('CWE-307');
+    expect(apiFinding?.cwe).toBe('CWE-770');
+  });
+
+  it('does not flag web.php non-auth non-api routes', async () => {
+    const content = "Route::get('/home', [HomeController::class, 'index']);";
+    const file = routeFile(content, 'routes/web.php');
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    // home route is not auth-sensitive and web.php is not api file
+    expect(result.filter((f) => f.id === 'HAVOC-RL-001')).toHaveLength(0);
+  });
+
+  it('flags register endpoint without throttle', async () => {
+    const file = routeFile("Route::post('/register', [RegisterController::class, 'store']);");
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.some((f) => f.id === 'HAVOC-RL-001')).toBe(true);
+  });
+
+  it('flags webhook endpoint without throttle', async () => {
+    const file = routeFile("Route::post('/webhook/stripe', [WebhookController::class, 'handle']);");
+    const result = await analyzer.analyze([file], DEFAULT_CONFIG);
+    expect(result.some((f) => f.id === 'HAVOC-RL-001')).toBe(true);
+  });
+});