@havoc-security/scanner 0.1.0

package/src/parsers/PhpParser.ts

@@ -0,0 +1,259 @@
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { resolve, relative } from 'node:path';
+import { glob } from 'glob';
+import { ParsedFile } from '../types/index.js';
+
+interface PhpNode {
+  kind: string;
+  name?: string | PhpNode;
+  isAbstract?: boolean;
+  isFinal?: boolean;
+  isStatic?: boolean;
+  visibility?: string;
+  body?: PhpNode[] | PhpNode | null;
+  children?: PhpNode[];
+  arguments?: PhpNode[];
+  items?: PhpNode[];
+  properties?: PhpNode[];
+  value?: PhpNode | string | number | boolean | null;
+  loc?: { start: { line: number }; end: { line: number } };
+  extends?: PhpNode | null;
+  traits?: PhpNode[];
+  key?: PhpNode | null;
+}
+
+export interface PhpMethodInfo {
+  name: string;
+  visibility: 'public' | 'protected' | 'private';
+  isStatic: boolean;
+  line: number;
+  bodyText: string;
+  parameters: string[];
+}
+
+export interface PhpPropertyInfo {
+  name: string;
+  visibility: 'public' | 'protected' | 'private';
+  isStatic: boolean;
+  line: number;
+  initializer?: string;
+}
+
+export interface PhpClassInfo {
+  name: string;
+  isAbstract: boolean;
+  isTrait: boolean;
+  methods: PhpMethodInfo[];
+  properties: PhpPropertyInfo[];
+  traitUses: string[];
+  importedTraits: string[];
+  parent?: string;
+  line: number;
+}
+
+export interface ParsedPhpFile extends ParsedFile {
+  classes: PhpClassInfo[];
+  useStatements: string[];
+  namespace?: string;
+}
+
+export const PHP_FILE_PATTERNS = {
+  CONTROLLERS: 'app/Http/Controllers/**/*.php',
+  MODELS: 'app/Models/**/*.php',
+  ROUTES_WEB: 'routes/web.php',
+  ROUTES_API: 'routes/api.php',
+  ROUTES_ALL: 'routes/**/*.php',
+  BLADE_TEMPLATES: 'resources/views/**/*.blade.php',
+  CONFIG: 'config/**/*.php',
+  ALL_PHP: '**/*.php',
+} as const;
+
+function nodeName(n: string | PhpNode | undefined | null): string {
+  if (!n) return '';
+  if (typeof n === 'string') return n;
+  if (typeof n === 'object') {
+    if (typeof n.name === 'string') return n.name;
+    if (typeof n.name === 'object') return nodeName(n.name);
+  }
+  return '';
+}
+
+function normalizeVisibility(v: string | undefined): 'public' | 'protected' | 'private' {
+  if (v === 'protected') return 'protected';
+  if (v === 'private') return 'private';
+  return 'public';
+}
+
+export class PhpParser {
+  private engine: { parseCode(code: string, filename: string): PhpNode };
+
+  constructor() {
+    const _require = createRequire(import.meta.url);
+    const mod = _require('php-parser');
+    const Engine = mod.Engine ?? mod.default?.Engine ?? mod;
+    this.engine = new Engine({
+      parser: { extractDoc: true, suppressErrors: true, php7: true },
+      ast: { withPositions: true },
+    }) as { parseCode(code: string, filename: string): PhpNode };
+  }
+
+  async parseFile(filePath: string, rootDir?: string): Promise<ParsedPhpFile> {
+    const content = await readFile(filePath, 'utf-8').catch(() => '');
+    const relativePath = rootDir ? relative(rootDir, filePath) : filePath;
+
+    try {
+      const ast = this.engine.parseCode(content, filePath);
+      const extracted = this.extractFromAst(ast, content);
+      return { path: relativePath, content, ast, ...extracted };
+    } catch {
+      return { path: relativePath, content, ast: null, classes: [], useStatements: [] };
+    }
+  }
+
+  async parseDirectory(dir: string, exclude: string[] = []): Promise<ParsedPhpFile[]> {
+    const absDir = resolve(dir);
+    const files = await glob(`${absDir}/${PHP_FILE_PATTERNS.ALL_PHP}`, {
+      ignore: exclude.map((e) => resolve(absDir, e)),
+      nodir: true,
+    });
+    return Promise.all(files.map((f) => this.parseFile(f, absDir)));
+  }
+
+  async parseByPattern(rootDir: string, pattern: string, exclude: string[] = []): Promise<ParsedPhpFile[]> {
+    const absRoot = resolve(rootDir);
+    const files = await glob(`${absRoot}/${pattern}`, {
+      ignore: exclude.map((e) => resolve(absRoot, e)),
+      nodir: true,
+    });
+    return Promise.all(files.map((f) => this.parseFile(f, absRoot)));
+  }
+
+  async parseBladeFiles(rootDir: string): Promise<ParsedFile[]> {
+    const absRoot = resolve(rootDir);
+    const files = await glob(`${absRoot}/${PHP_FILE_PATTERNS.BLADE_TEMPLATES}`, { nodir: true });
+    return Promise.all(
+      files.map(async (f) => ({
+        path: relative(absRoot, f),
+        content: await readFile(f, 'utf-8').catch(() => ''),
+        ast: null,
+      })),
+    );
+  }
+
+  private extractFromAst(ast: PhpNode, source: string): { classes: PhpClassInfo[]; useStatements: string[]; namespace?: string } {
+    const classes: PhpClassInfo[] = [];
+    const useStatements: string[] = [];
+    let namespace: string | undefined;
+
+    const processNodes = (nodes: PhpNode[]) => {
+      for (const node of nodes) {
+        if (node.kind === 'namespace') {
+          namespace = nodeName(node.name);
+          processNodes((node.children ?? []) as PhpNode[]);
+        } else if (node.kind === 'usegroup') {
+          for (const item of (node.items ?? []) as PhpNode[]) {
+            const name = nodeName(item.name);
+            if (name) useStatements.push(name);
+          }
+        } else if (node.kind === 'class' || node.kind === 'trait') {
+          classes.push(this.extractClass(node, source));
+        }
+      }
+    };
+
+    processNodes((ast.children ?? []) as PhpNode[]);
+    return { classes, useStatements, namespace };
+  }
+
+  private extractClass(node: PhpNode, source: string): PhpClassInfo {
+    const name = nodeName(node.name);
+    const isAbstract = node.isAbstract ?? false;
+    const isTrait = node.kind === 'trait';
+    const line = node.loc?.start.line ?? 1;
+    const methods: PhpMethodInfo[] = [];
+    const properties: PhpPropertyInfo[] = [];
+    const importedTraits: string[] = [];
+
+    const body = (node.body ?? []) as PhpNode[];
+    for (const member of body) {
+      if (member.kind === 'method') {
+        methods.push(this.extractMethod(member, source));
+      } else if (member.kind === 'propertystatement') {
+        const prop = this.extractProperty(member);
+        if (prop) properties.push(prop);
+      } else if (member.kind === 'traituse') {
+        for (const trait of (member.traits ?? []) as PhpNode[]) {
+          importedTraits.push(nodeName(trait));
+        }
+      }
+    }
+
+    const parentNode = node.extends;
+    const parent = parentNode ? nodeName((parentNode as PhpNode).name ?? parentNode) : undefined;
+
+    return { name, isAbstract, isTrait, methods, properties, traitUses: [], importedTraits, parent, line };
+  }
+
+  private extractMethod(node: PhpNode, source: string): PhpMethodInfo {
+    const name = nodeName(node.name);
+    const visibility = normalizeVisibility(node.visibility);
+    const isStatic = node.isStatic ?? false;
+    const line = node.loc?.start.line ?? 1;
+
+    const bodyNode = node.body as PhpNode | null;
+    let bodyText = '';
+    if (bodyNode?.loc) {
+      const lines = source.split('\n');
+      bodyText = lines.slice(bodyNode.loc.start.line - 1, bodyNode.loc.end.line).join('\n');
+    }
+
+    const params = ((node as PhpNode & { arguments?: PhpNode[] }).arguments ?? [])
+      .map((p) => nodeName(p.name));
+
+    return { name, visibility, isStatic, line, bodyText, parameters: params };
+  }
+
+  private extractProperty(node: PhpNode): PhpPropertyInfo | null {
+    // php-parser uses "properties" for propertystatement children
+    const props = (node.properties ?? node.items ?? []) as PhpNode[];
+    if (props.length === 0) return null;
+
+    const first = props[0];
+    const name = nodeName(first.name);
+    if (!name) return null;
+
+    const visibility = normalizeVisibility(node.visibility);
+    const isStatic = node.isStatic ?? false;
+    const line = node.loc?.start.line ?? 1;
+    const initializer = first.value != null ? this.stringifyNode(first.value as PhpNode) : undefined;
+
+    return { name, visibility, isStatic, line, initializer };
+  }
+
+  private stringifyNode(node: PhpNode): string {
+    if (!node) return '';
+    switch (node.kind) {
+      case 'string': return `"${node.value as string}"`;
+      case 'number': return String(node.value);
+      case 'boolean': return String(node.value);
+      case 'nullkeyword': return 'null';
+      case 'array': {
+        const items = (node.items ?? []) as PhpNode[];
+        const parts = items.map((item) => {
+          // php-parser wraps array values in "entry" nodes
+          const entryVal = (item as PhpNode & { value?: PhpNode }).value ?? item;
+          const val = this.stringifyNode(entryVal as PhpNode);
+          const entryKey = (item as PhpNode & { key?: PhpNode | null }).key;
+          return entryKey ? `${this.stringifyNode(entryKey)} => ${val}` : val;
+        });
+        return `[${parts.join(', ')}]`;
+      }
+      case 'identifier':
+      case 'name':
+        return nodeName(node);
+      default:
+        return '';
+    }
+  }
+}

package/src/parsers/RouteParser.ts

@@ -0,0 +1,384 @@
+/**
+ * HAVOC Route Parser
+ *
+ * Parses Laravel route files (routes/web.php, routes/api.php, etc.) to extract
+ * route definitions and their associated middleware — including group-inherited
+ * middleware. This data is used by the AuthorizationCoverageAnalyzer to eliminate
+ * false positives where auth/authorization is handled at the route level.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve, relative } from 'node:path';
+import { glob } from 'glob';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface RouteInfo {
+  /** HTTP method (GET, POST, PUT, PATCH, DELETE, ANY) or 'resource' */
+  method: string;
+  /** Route URI */
+  uri: string;
+  /** Controller class name (short, without namespace) */
+  controller: string;
+  /** Controller action/method name */
+  action: string;
+  /** All effective middleware applied to this route (including group inheritance) */
+  middleware: string[];
+}
+
+export interface ParsedRouteFile {
+  /** Source file path (relative) */
+  path: string;
+  /** All extracted route definitions */
+  routes: RouteInfo[];
+}
+
+// ─── Middleware Classification ────────────────────────────────────────────────
+
+/** Middleware that provide AUTHORIZATION (i.e., permission checks — clears finding) */
+const AUTHORIZATION_MIDDLEWARE_PATTERNS = [
+  /^can:/,
+  /^permission:/,
+  /^role:/,
+];
+
+/** Middleware that provide AUTHENTICATION only (downgrades severity but does not clear) */
+const AUTHENTICATION_MIDDLEWARE_PATTERNS = [
+  /^auth$/,
+  /^auth:/,
+  /^sanctum$/,
+  /^verified$/,
+];
+
+export function isAuthorizationMiddleware(mw: string): boolean {
+  return AUTHORIZATION_MIDDLEWARE_PATTERNS.some((re) => re.test(mw.trim()));
+}
+
+export function isAuthenticationMiddleware(mw: string): boolean {
+  return AUTHENTICATION_MIDDLEWARE_PATTERNS.some((re) => re.test(mw.trim()));
+}
+
+export function hasAuthorizationMiddleware(middleware: string[]): boolean {
+  return middleware.some(isAuthorizationMiddleware);
+}
+
+export function hasAuthenticationMiddleware(middleware: string[]): boolean {
+  return middleware.some(isAuthenticationMiddleware);
+}
+
+// ─── Webhook Detection ────────────────────────────────────────────────────────
+
+const WEBHOOK_PATTERNS = [
+  /\$request->header\s*\(\s*['"]X-[^'"]*Signature/i,
+  /hash_hmac\s*\(/,
+  /hash_equals\s*\(/,
+  /SignatureVerif/i,
+  /validateSignature/i,
+  /verifySignature/i,
+  /StripeSignature/i,
+  /WebhookSignature/i,
+];
+
+export function isWebhookHandler(bodyText: string): boolean {
+  return WEBHOOK_PATTERNS.some((re) => re.test(bodyText));
+}
+
+// ─── Internal Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Parses middleware from a middleware() call argument string.
+ * Handles both string and array forms:
+ *   'auth'
+ *   ['auth', 'can:view-admin', 'verified']
+ */
+function parseMiddlewareArg(arg: string): string[] {
+  arg = arg.trim();
+
+  // Array form: ['auth', 'can:view-admin']
+  if (arg.startsWith('[')) {
+    const inner = arg.slice(1, arg.lastIndexOf(']'));
+    return inner.match(/['"]([^'"]+)['"]/g)?.map((s) => s.replace(/['"]/g, '')) ?? [];
+  }
+
+  // String form: 'auth' or "auth"
+  const m = arg.match(/^['"]([^'"]+)['"]$/);
+  if (m) return [m[1]];
+
+  return [];
+}
+
+/**
+ * Extract the controller class name (short name) and action from a route action string.
+ *
+ * Supported formats:
+ *   [PostController::class, 'index']
+ *   'PostController@index'
+ *   PostController::class (resource)
+ */
+function parseControllerAction(actionStr: string): { controller: string; action: string } | null {
+  actionStr = actionStr.trim();
+
+  // Array syntax: [PostController::class, 'index']
+  const arrayMatch = actionStr.match(/\[?\s*([A-Za-z_\\]+)(?:::class)?\s*,\s*['"]([^'"]+)['"]\s*\]?/);
+  if (arrayMatch) {
+    const parts = arrayMatch[1].split('\\');
+    return { controller: parts[parts.length - 1], action: arrayMatch[2] };
+  }
+
+  // String syntax: 'PostController@index'
+  const atMatch = actionStr.match(/['"]?([A-Za-z_\\]+)@([A-Za-z_]+)['"]?/);
+  if (atMatch) {
+    const parts = atMatch[1].split('\\');
+    return { controller: parts[parts.length - 1], action: atMatch[2] };
+  }
+
+  // Resource: PostController::class (no explicit action)
+  const resourceMatch = actionStr.match(/([A-Za-z_\\]+)::class/);
+  if (resourceMatch) {
+    const parts = resourceMatch[1].split('\\');
+    return { controller: parts[parts.length - 1], action: '*' };
+  }
+
+  return null;
+}
+
+/** Standard Laravel resource controller actions */
+const RESOURCE_ACTIONS = ['index', 'create', 'store', 'show', 'edit', 'update', 'destroy'];
+
+// ─── Route Parser ─────────────────────────────────────────────────────────────
+
+/**
+ * Regex-based Laravel route file parser.
+ *
+ * Handles:
+ * - Route::get/post/put/patch/delete/any('uri', ...)
+ * - Route::resource('resource', Controller::class)
+ * - Route::middleware([...])->group(function () { ... })
+ * - Nested groups
+ */
+export class RouteParser {
+  /**
+   * Parse a single route file's content and return extracted routes.
+   */
+  parseContent(content: string, filePath: string = ''): ParsedRouteFile {
+    const routes: RouteInfo[] = [];
+    this.parseBlock(content, [], routes);
+    return { path: filePath, routes };
+  }
+
+  /**
+   * Parse a route file from disk.
+   */
+  async parseFile(filePath: string, rootDir?: string): Promise<ParsedRouteFile> {
+    const content = await readFile(filePath, 'utf-8').catch(() => '');
+    const relativePath = rootDir ? relative(rootDir, filePath) : filePath;
+    return this.parseContent(content, relativePath);
+  }
+
+  /**
+   * Parse all route files in a Laravel project's routes/ directory.
+   */
+  async parseDirectory(projectRoot: string): Promise<ParsedRouteFile[]> {
+    const absRoot = resolve(projectRoot);
+    const files = await glob(`${absRoot}/routes/**/*.php`, { nodir: true });
+    return Promise.all(files.map((f) => this.parseFile(f, absRoot)));
+  }
+
+  /**
+   * Recursively parse a block of PHP route code, tracking inherited middleware.
+   */
+  private parseBlock(content: string, inheritedMiddleware: string[], routes: RouteInfo[]): void {
+    let pos = 0;
+    while (pos < content.length) {
+      const routeIdx = content.indexOf('Route::', pos);
+      if (routeIdx === -1) break;
+
+      const chain = this.extractChain(content, routeIdx);
+      if (!chain) { pos = routeIdx + 7; continue; }
+
+      const { text, end } = chain;
+
+      // Check if this is a group
+      const groupMiddleware = this.extractGroupMiddleware(text);
+      if (groupMiddleware !== null) {
+        const groupBody = this.extractGroupBody(content, routeIdx);
+        if (groupBody) {
+          const combined = [...inheritedMiddleware, ...groupMiddleware];
+          this.parseBlock(groupBody.body, combined, routes);
+          pos = groupBody.end;
+          continue;
+        }
+      }
+
+      const extracted = this.extractRoute(text, inheritedMiddleware);
+      if (extracted.length > 0) {
+        routes.push(...extracted);
+      }
+
+      pos = end;
+    }
+  }
+
+  /**
+   * Extract the full chained call text starting at a Route:: position.
+   * Stops at semicolons not inside brackets/parens.
+   */
+  private extractChain(content: string, start: number): { text: string; end: number } | null {
+    let depth = 0;
+    let i = start;
+    let inString = false;
+    let stringChar = '';
+
+    while (i < content.length) {
+      const ch = content[i];
+
+      if (inString) {
+        if (ch === stringChar && content[i - 1] !== '\\') inString = false;
+      } else if (ch === '"' || ch === "'") {
+        inString = true;
+        stringChar = ch;
+      } else if (ch === '(' || ch === '[') {
+        depth++;
+      } else if (ch === ')' || ch === ']') {
+        depth--;
+      } else if (ch === '{' && depth === 0) {
+        // Entering a closure body — stop here (group handling takes over)
+        break;
+      } else if (ch === '}' && depth < 0) {
+        break;
+      } else if (ch === ';' && depth === 0) {
+        return { text: content.slice(start, i + 1), end: i + 1 };
+      }
+      i++;
+    }
+
+    if (i > start) {
+      return { text: content.slice(start, i), end: i };
+    }
+    return null;
+  }
+
+  /**
+   * If the chain is a Route::middleware(...)->group(...), extract the middleware list.
+   * Returns null if this is not a group.
+   */
+  private extractGroupMiddleware(chain: string): string[] | null {
+    const mwMatch = chain.match(/Route::(?:\w+\([^)]*\)->)*middleware\s*\(([^)]+)\)/);
+    if (!mwMatch) return null;
+    if (!chain.includes('->group(')) return null;
+    return parseMiddlewareArg(mwMatch[1]);
+  }
+
+  /**
+   * Find the closure body of a ->group(function () { ... }) call.
+   */
+  private extractGroupBody(content: string, routeStart: number): { body: string; end: number } | null {
+    const groupIdx = content.indexOf('->group(', routeStart);
+    if (groupIdx === -1) return null;
+
+    const braceIdx = content.indexOf('{', groupIdx);
+    if (braceIdx === -1) return null;
+
+    let depth = 1;
+    let i = braceIdx + 1;
+    while (i < content.length && depth > 0) {
+      const ch = content[i];
+      if (ch === '{') depth++;
+      else if (ch === '}') depth--;
+      i++;
+    }
+
+    return { body: content.slice(braceIdx + 1, i - 1), end: i };
+  }
+
+  /**
+   * Extract route info from a single Route::method() chain.
+   */
+  private extractRoute(chain: string, inheritedMiddleware: string[]): RouteInfo[] {
+    const results: RouteInfo[] = [];
+
+    // Extract inline middleware from ->middleware(...) in this chain
+    const inlineMiddleware: string[] = [];
+    const mwRegex = /->middleware\s*\(([^)]+)\)/g;
+    let mwMatch;
+    while ((mwMatch = mwRegex.exec(chain)) !== null) {
+      inlineMiddleware.push(...parseMiddlewareArg(mwMatch[1]));
+    }
+    const allMiddleware = [...inheritedMiddleware, ...inlineMiddleware];
+
+    // Route::resource('posts', PostController::class)
+    const resourceMatch = chain.match(/Route::resource\s*\(\s*['"]([^'"]+)['"]\s*,\s*([^,)]+)/);
+    if (resourceMatch) {
+      const uri = resourceMatch[1];
+      const ctrlRaw = resourceMatch[2].trim();
+      const parsed = parseControllerAction(ctrlRaw)
+        ?? { controller: ctrlRaw.replace(/::class.*/, '').split('\\').pop() ?? ctrlRaw, action: '*' };
+      for (const action of RESOURCE_ACTIONS) {
+        results.push({ method: 'resource', uri, controller: parsed.controller, action, middleware: allMiddleware });
+      }
+      return results;
+    }
+
+    // Route::apiResource(...)
+    const apiResourceMatch = chain.match(/Route::apiResource\s*\(\s*['"]([^'"]+)['"]\s*,\s*([^,)]+)/);
+    if (apiResourceMatch) {
+      const uri = apiResourceMatch[1];
+      const ctrlRaw = apiResourceMatch[2].trim();
+      const parsed = parseControllerAction(ctrlRaw)
+        ?? { controller: ctrlRaw.replace(/::class.*/, '').split('\\').pop() ?? ctrlRaw, action: '*' };
+      for (const action of ['index', 'store', 'show', 'update', 'destroy']) {
+        results.push({ method: 'apiResource', uri, controller: parsed.controller, action, middleware: allMiddleware });
+      }
+      return results;
+    }
+
+    // Route::get/post/put/patch/delete/any(...)
+    const verbMatch = chain.match(/Route::(get|post|put|patch|delete|any|options)\s*\(\s*['"]([^'"]+)['"]\s*,\s*([\s\S]+?)\s*\)/);
+    if (verbMatch) {
+      const method = verbMatch[1].toUpperCase();
+      const uri = verbMatch[2];
+      const actionStr = verbMatch[3];
+      const parsed = parseControllerAction(actionStr);
+      if (parsed) {
+        results.push({ method, uri, controller: parsed.controller, action: parsed.action, middleware: allMiddleware });
+      }
+    }
+
+    return results;
+  }
+}
+
+// ─── Route Map Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Build a lookup map: "ControllerName::action" → RouteInfo[]
+ * Used by analyzers for O(1) route lookups.
+ */
+export function buildRouteMap(routeFiles: ParsedRouteFile[]): Map<string, RouteInfo[]> {
+  const map = new Map<string, RouteInfo[]>();
+
+  for (const file of routeFiles) {
+    for (const route of file.routes) {
+      const key = `${route.controller}::${route.action}`;
+      if (!map.has(key)) map.set(key, []);
+      map.get(key)!.push(route);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Get all middleware for a given controller action from the route map.
+ * Returns an empty array if the action is not found in any route.
+ */
+export function getRouteMiddleware(
+  routeMap: Map<string, RouteInfo[]>,
+  controller: string,
+  action: string,
+): string[] {
+  const key = `${controller}::${action}`;
+  const routes = routeMap.get(key) ?? [];
+  if (routes.length === 0) return [];
+  return [...new Set(routes.flatMap((r) => r.middleware))];
+}

package/src/rules/index.ts

@@ -0,0 +1,16 @@
+/**
+ * HAVOC Rule Definitions
+ *
+ * Rules define patterns and thresholds for each analyzer.
+ * Full rule set implemented in Sprint 2.
+ */
+
+export interface Rule {
+  id: string;
+  analyzer: string;
+  description: string;
+  cwe?: string;
+}
+
+// Rule registry — populated in Sprint 2
+export const rules: Rule[] = [];