@havoc-security/scanner 0.1.0

package/src/analyzers/AuthorizationCoverageAnalyzer.ts

@@ -0,0 +1,213 @@
+import { Analyzer, Finding, HavocConfig, ParsedFile, Severity } from '../types/index.js';
+import type { ParsedPhpFile, PhpMethodInfo } from '../parsers/PhpParser.js';
+import {
+  buildRouteMap,
+  getRouteMiddleware,
+  hasAuthorizationMiddleware,
+  hasAuthenticationMiddleware,
+  isWebhookHandler,
+} from '../parsers/RouteParser.js';
+import type { ParsedRouteFile } from '../parsers/RouteParser.js';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const EXCLUDED_METHOD_NAMES = new Set([
+  '__construct', '__destruct', 'middleware', 'callAction',
+  'authorize', 'authorizeResource', 'authorizeForUser',
+]);
+
+const AUTHORIZATION_PATTERNS = [
+  /\$this->authorize\s*\(/,
+  /Gate::authorize\s*\(/,
+  /Gate::allows\s*\(/,
+  /Gate::denies\s*\(/,
+  /Gate::check\s*\(/,
+  /Gate::any\s*\(/,
+  /Gate::none\s*\(/,
+  /->can\s*\(/,
+  /->cannot\s*\(/,
+  /->cant\s*\(/,
+  /\$this->middleware\s*\(\s*['"]can:/,
+];
+
+const FORM_REQUEST_PATTERNS = [/extends\s+FormRequest/];
+
+const FINDING_ID = 'HAVOC-AUTH-001';
+const COVERAGE_FINDING_ID = 'HAVOC-AUTH-002';
+const ANALYZER_NAME = 'AuthorizationCoverageAnalyzer';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function isControllerFile(path: string): boolean {
+  return path.includes('Http/Controllers') || path.includes('Http\\Controllers');
+}
+
+function isPublicAction(method: PhpMethodInfo): boolean {
+  return (
+    method.visibility === 'public' &&
+    !EXCLUDED_METHOD_NAMES.has(method.name) &&
+    !method.name.startsWith('_')
+  );
+}
+
+function hasInlineAuthorization(method: PhpMethodInfo): boolean {
+  return AUTHORIZATION_PATTERNS.some((re) => re.test(method.bodyText));
+}
+
+// ─── Authorization Coverage Result ───────────────────────────────────────────
+
+/**
+ * Describes the authorization status of a single controller action.
+ */
+export type AuthorizationStatus =
+  | 'authorized'        // Has authorization — not flagged
+  | 'auth-only'         // Has authentication middleware only — LOW finding
+  | 'webhook'           // Signature-verified webhook — not flagged
+  | 'unprotected';      // No auth at all — HIGH finding
+
+function determineStatus(
+  method: PhpMethodInfo,
+  hasFormRequest: boolean,
+  routeMiddleware: string[],
+): AuthorizationStatus {
+  // Inline authorization or FormRequest → fully authorized
+  if (hasInlineAuthorization(method) || hasFormRequest) return 'authorized';
+
+  // Webhook pattern detected → no auth needed
+  if (isWebhookHandler(method.bodyText)) return 'webhook';
+
+  // Route-level authorization middleware (can:*, permission:*, role:*) → authorized
+  if (hasAuthorizationMiddleware(routeMiddleware)) return 'authorized';
+
+  // Route-level authentication-only middleware → downgrade to LOW
+  if (hasAuthenticationMiddleware(routeMiddleware)) return 'auth-only';
+
+  return 'unprotected';
+}
+
+// ─── Analyzer ─────────────────────────────────────────────────────────────────
+
+export class AuthorizationCoverageAnalyzer implements Analyzer {
+  readonly name = ANALYZER_NAME;
+  readonly description = 'Checks that all controller action methods have authorization in place';
+
+  /**
+   * Optional route data to reduce false positives.
+   * When provided, controllers protected by route-level middleware are handled correctly.
+   */
+  private routeFiles: ParsedRouteFile[];
+
+  constructor(routeFiles: ParsedRouteFile[] = []) {
+    this.routeFiles = routeFiles;
+  }
+
+  /**
+   * Set (or replace) route data after construction.
+   * Useful when the scan pipeline discovers routes after initialization.
+   */
+  setRouteFiles(routeFiles: ParsedRouteFile[]): void {
+    this.routeFiles = routeFiles;
+  }
+
+  async analyze(files: ParsedFile[], _config: HavocConfig): Promise<Finding[]> {
+    const findings: Finding[] = [];
+    let totalActions = 0;
+    let coveredActions = 0;
+
+    const routeMap = buildRouteMap(this.routeFiles);
+
+    for (const file of files) {
+      if (!isControllerFile(file.path)) continue;
+
+      const phpFile = file as ParsedPhpFile;
+      if (!phpFile.classes) continue;
+
+      const hasFormRequest = FORM_REQUEST_PATTERNS.some((re) => re.test(file.content));
+
+      for (const cls of phpFile.classes) {
+        for (const method of cls.methods) {
+          if (!isPublicAction(method)) continue;
+          totalActions++;
+
+          const routeMiddleware = getRouteMiddleware(routeMap, cls.name, method.name);
+          const status = determineStatus(method, hasFormRequest, routeMiddleware);
+
+          switch (status) {
+            case 'authorized':
+            case 'webhook':
+              coveredActions++;
+              break;
+
+            case 'auth-only':
+              // Authentication only — controller is behind a login wall but has no
+              // fine-grained authorization. Flag as LOW (not HIGH).
+              // NOTE: does NOT count toward coveredActions — authentication ≠ authorization.
+              findings.push({
+                id: FINDING_ID,
+                severity: Severity.Low,
+                analyzer: ANALYZER_NAME,
+                title: `No authorization check in authenticated action: ${cls.name}::${method.name}()`,
+                description:
+                  `The method \`${method.name}()\` in \`${cls.name}\` is behind authentication ` +
+                  `middleware but has no authorization check. Any authenticated user can access it.`,
+                file: file.path,
+                line: method.line,
+                recommendation:
+                  'Add `$this->authorize(\'action\', Model::class)` or apply `can:permission` middleware ' +
+                  'to restrict access to authorized users only.',
+                cwe: 'CWE-862',
+                snippet: method.bodyText.slice(0, 200),
+              });
+              break;
+
+            case 'unprotected':
+            default:
+              findings.push({
+                id: FINDING_ID,
+                severity: Severity.High,
+                analyzer: ANALYZER_NAME,
+                title: `Unprotected controller action: ${cls.name}::${method.name}()`,
+                description:
+                  `The method \`${method.name}()\` in \`${cls.name}\` does not appear to perform ` +
+                  `any authorization checks. Missing \`$this->authorize()\`, Gate checks, ` +
+                  `policy-backed FormRequest, or route middleware.`,
+                file: file.path,
+                line: method.line,
+                recommendation:
+                  'Add `$this->authorize(\'action\', Model::class)` at the top of the method, ' +
+                  'or use a policy-backed FormRequest, or apply `can:permission` middleware to the route.',
+                cwe: 'CWE-862',
+                snippet: method.bodyText.slice(0, 200),
+              });
+              break;
+          }
+        }
+      }
+    }
+
+    if (totalActions > 0) {
+      const coveragePercent = Math.round((coveredActions / totalActions) * 100);
+      const minCoverage = (_config.analyzers?.authorizationCoverage?.minCoverage ?? 80);
+
+      if (coveragePercent < minCoverage) {
+        findings.push({
+          id: COVERAGE_FINDING_ID,
+          severity: Severity.Medium,
+          analyzer: ANALYZER_NAME,
+          title: `Authorization coverage is ${coveragePercent}% (minimum: ${minCoverage}%)`,
+          description:
+            `Only ${coveredActions} of ${totalActions} controller actions have detectable ` +
+            `authorization checks (inline Gate/policy or can:* route middleware). Target: ${minCoverage}%.`,
+          file: 'app/Http/Controllers',
+          line: 1,
+          recommendation:
+            'Review unprotected controller actions and add appropriate authorization. ' +
+            'Consider using Laravel policies for consistent authorization.',
+          cwe: 'CWE-862',
+        });
+      }
+    }
+
+    return findings;
+  }
+}

package/src/analyzers/CredentialExposureAnalyzer.ts

@@ -0,0 +1,312 @@
+import { isTestFile, isFakeCredential } from './exclusions.js';
+import { Analyzer, Finding, HavocConfig, ParsedFile, Severity } from '../types/index.js';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const ANALYZER_NAME = 'CredentialExposureAnalyzer';
+
+const FINDING_ENV_FILE_COMMITTED = 'HAVOC-CRED-001';
+const FINDING_HARDCODED_SECRET = 'HAVOC-CRED-002';
+const FINDING_APP_DEBUG = 'HAVOC-CRED-003';
+const FINDING_APP_ENV = 'HAVOC-CRED-004';
+const FINDING_DEBUG_CONFIG = 'HAVOC-CRED-005';
+const FINDING_DB_CREDENTIALS = 'HAVOC-CRED-006';
+const FINDING_PRIVATE_KEY = 'HAVOC-CRED-007';
+const FINDING_CONFIG_HARDCODED = 'HAVOC-CRED-008';
+
+const SENSITIVE_CONFIG_KEYS = [
+  'password', 'secret', 'key', 'token', 'api_key', 'apikey',
+  'access_key', 'private_key', 'client_secret', 'client_id',
+  'app_id', 'app_secret', 'encryption_key', 'signing_secret',
+  'webhook_secret',
+];
+
+// Secret patterns
+const SECRET_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /['"]sk_live_[0-9a-zA-Z]{24,}['"]/, label: 'Stripe live secret key' },
+  { pattern: /['"]pk_live_[0-9a-zA-Z]{24,}['"]/, label: 'Stripe live publishable key' },
+  { pattern: /['"]AKIA[0-9A-Z]{16}['"]/, label: 'AWS Access Key ID' },
+  { pattern: /(?:password|passwd|pwd)\s*=\s*['"][^'"]{3,}['"]/, label: 'Hardcoded password' },
+  { pattern: /(?:api_key|apikey|api_secret)\s*=\s*['"][^'"]{8,}['"]/, label: 'Hardcoded API key' },
+  { pattern: /(?:access_token|auth_token)\s*=\s*['"][^'"]{8,}['"]/, label: 'Hardcoded access token' },
+  { pattern: /ghp_[0-9a-zA-Z]{36}/, label: 'GitHub personal access token' },
+  { pattern: /xox[baprs]-[0-9a-zA-Z-]{10,}/, label: 'Slack token' },
+];
+
+const DB_CREDENTIAL_PATTERNS: Array<RegExp> = [
+  /new\s+PDO\s*\(\s*['"][^'"]+['"],\s*['"][^'"]+['"],\s*['"][^'"]{3,}['"]/,
+  /mysqli_connect\s*\([^)]*,\s*['"][^'"]+['"],\s*['"][^'"]{3,}['"]/,
+];
+
+const PRIVATE_KEY_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/, label: 'Private key (PEM)' },
+  { pattern: /'jwt_secret'\s*=>\s*'[^']{16,}'/, label: 'JWT secret in config' },
+];
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function isPhpFile(path: string): boolean {
+  return path.endsWith('.php') && !path.endsWith('.blade.php');
+}
+
+function isEnvFile(path: string): boolean {
+  const filename = path.split('/').pop() ?? '';
+  return filename === '.env' || /^\.env\.[a-z]+$/.test(filename);
+}
+
+function isProductionEnvConfig(path: string): boolean {
+  return /\.env\.(production|prod|staging|live)/.test(path);
+}
+
+function isLocalEnvFile(path: string): boolean {
+  return /\.env\.(local|testing|test|development|dev)/.test(path) || path === '.env.example';
+}
+
+function isAppConfig(path: string): boolean {
+  return path === 'config/app.php' || path.endsWith('/config/app.php');
+}
+
+function isConfigFile(path: string): boolean {
+  return /(?:^|\/)config\/[^/]+\.php$/.test(path);
+}
+
+function findLineNumber(content: string, matchIndex: number): number {
+  return content.slice(0, matchIndex).split('\n').length;
+}
+
+// ─── Analyzer ─────────────────────────────────────────────────────────────────
+
+export class CredentialExposureAnalyzer implements Analyzer {
+  readonly name = ANALYZER_NAME;
+  readonly description = 'Detects hardcoded credentials, secrets, and insecure configuration exposure';
+
+  async analyze(files: ParsedFile[], _config: HavocConfig): Promise<Finding[]> {
+    const findings: Finding[] = [];
+
+    for (const file of files) {
+      // 1. .env files committed to the repo
+      if (isEnvFile(file.path)) {
+        findings.push({
+          id: FINDING_ENV_FILE_COMMITTED,
+          severity: Severity.Critical,
+          analyzer: ANALYZER_NAME,
+          title: '`.env` file committed to repository',
+          description:
+            `The file \`${file.path}\` was found in the scanned path. ` +
+            `.env files typically contain secrets and should never be committed to version control.`,
+          file: file.path,
+          line: 1,
+          recommendation:
+            'Add `.env` to `.gitignore`. Use `.env.example` with placeholder values instead.',
+          cwe: 'CWE-312',
+        });
+      }
+
+      // 2. Hardcoded secrets in PHP source
+      if (isPhpFile(file.path)) {
+        this.checkHardcodedSecrets(file, findings);
+        this.checkDbCredentials(file, findings);
+        this.checkPrivateKeys(file, findings);
+      }
+
+      // 3. APP_DEBUG=true in non-local env configs
+      if (isEnvFile(file.path) && !isLocalEnvFile(file.path)) {
+        const debugIdx = file.content.search(/^APP_DEBUG\s*=\s*true/im);
+        if (debugIdx !== -1) {
+          findings.push({
+            id: FINDING_APP_DEBUG,
+            severity: Severity.High,
+            analyzer: ANALYZER_NAME,
+            title: '`APP_DEBUG=true` in non-local environment config',
+            description:
+              `\`APP_DEBUG=true\` was found in \`${file.path}\`. ` +
+              `Debug mode exposes stack traces and sensitive application internals to end users.`,
+            file: file.path,
+            line: findLineNumber(file.content, debugIdx),
+            recommendation: 'Set `APP_DEBUG=false` in all non-local environment configs.',
+            cwe: 'CWE-209',
+            snippet: 'APP_DEBUG=true',
+          });
+        }
+
+        // 4. APP_ENV=local or testing in production-looking configs
+        if (isProductionEnvConfig(file.path)) {
+          const envMatch = /^APP_ENV\s*=\s*(local|testing)/im.exec(file.content);
+          if (envMatch) {
+            findings.push({
+              id: FINDING_APP_ENV,
+              severity: Severity.Medium,
+              analyzer: ANALYZER_NAME,
+              title: `\`APP_ENV=${envMatch[1]}\` in production environment config`,
+              description:
+                `\`APP_ENV=${envMatch[1]}\` was found in \`${file.path}\`. ` +
+                `Production configs should use \`APP_ENV=production\`.`,
+              file: file.path,
+              line: findLineNumber(file.content, envMatch.index),
+              recommendation: 'Set `APP_ENV=production` in production environment configs.',
+              cwe: 'CWE-16',
+              snippet: `APP_ENV=${envMatch[1]}`,
+            });
+          }
+        }
+      }
+
+      // 5. Config files with hardcoded credentials
+      if (isPhpFile(file.path) && isConfigFile(file.path)) {
+        this.checkConfigHardcodedCredentials(file, findings);
+      }
+
+      // 6. Verbose error display in config/app.php
+      if (isPhpFile(file.path) && isAppConfig(file.path)) {
+        const debugConfigIdx = file.content.search(/'debug'\s*=>\s*true/);
+        if (debugConfigIdx !== -1) {
+          findings.push({
+            id: FINDING_DEBUG_CONFIG,
+            severity: Severity.High,
+            analyzer: ANALYZER_NAME,
+            title: '`debug => true` hardcoded in `config/app.php`',
+            description:
+              `\`'debug' => true\` is hardcoded in \`${file.path}\`. ` +
+              `This enables debug mode regardless of the APP_DEBUG environment variable.`,
+            file: file.path,
+            line: findLineNumber(file.content, debugConfigIdx),
+            recommendation:
+              "Use `'debug' => (bool) env('APP_DEBUG', false)` to read the value from the environment.",
+            cwe: 'CWE-209',
+            snippet: "'debug' => true",
+          });
+        }
+
+        const envHardcoded = /'env'\s*=>\s*'(local|testing)'/.exec(file.content);
+        if (envHardcoded) {
+          findings.push({
+            id: FINDING_APP_ENV,
+            severity: Severity.Medium,
+            analyzer: ANALYZER_NAME,
+            title: `\`'env' => '${envHardcoded[1]}'\` hardcoded in \`config/app.php\``,
+            description:
+              `The application environment is hardcoded as \`${envHardcoded[1]}\` in \`${file.path}\`. `,
+            file: file.path,
+            line: findLineNumber(file.content, envHardcoded.index),
+            recommendation: "Use `'env' => env('APP_ENV', 'production')` to read from the environment.",
+            cwe: 'CWE-16',
+            snippet: `'env' => '${envHardcoded[1]}'`,
+          });
+        }
+      }
+    }
+
+    return findings;
+  }
+
+  private checkConfigHardcodedCredentials(file: ParsedFile, findings: Finding[]): void {
+    for (const key of SENSITIVE_CONFIG_KEYS) {
+      const regex = new RegExp(`['"]\\b${key}\\b['"]\\s*=>\\s*'([^']{3,})'`, 'gi');
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(file.content)) !== null) {
+        const value = match[1];
+        // Skip ORM/framework config keys that aren't credentials
+        if (/pivot_key|morph_key|foreign_key|primary_key|route_key/.test(match[0])) continue;
+        if (/^(null|true|false|your-|xxx|placeholder|changeme)/i.test(value)) continue;
+        const before = file.content.slice(Math.max(0, match.index - 80), match.index);
+        if (/env\s*\([^)]*,\s*$/.test(before)) continue;
+
+        findings.push({
+          id: FINDING_CONFIG_HARDCODED,
+          severity: Severity.High,
+          analyzer: ANALYZER_NAME,
+          title: `Hardcoded \`${key}\` in config file \`${file.path}\``,
+          description:
+            `The config key \`${key}\` in \`${file.path}\` has a hardcoded value instead of ` +
+            `using \`env()\`. Credentials in source control are exposed to anyone with repo access.`,
+          file: file.path,
+          line: findLineNumber(file.content, match.index),
+          recommendation:
+            `Use \`'${key}' => env('${key.toUpperCase()}')\` to read from environment variables.`,
+          cwe: 'CWE-798',
+          snippet: match[0].slice(0, 60),
+        });
+      }
+    }
+  }
+
+  private checkHardcodedSecrets(file: ParsedFile, findings: Finding[]): void {
+    // Skip test files — they often contain fake credentials
+    if (isTestFile(file.path)) return;
+    for (const { pattern, label } of SECRET_PATTERNS) {
+      const regex = new RegExp(pattern.source, 'g');
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(file.content)) !== null) {
+        // Skip if value comes from env() call
+        // Skip fake/test credentials
+        if (isFakeCredential(match[0])) continue;
+        const before = file.content.slice(Math.max(0, match.index - 40), match.index);
+        if (/env\s*\(/.test(before)) continue;
+
+        findings.push({
+          id: FINDING_HARDCODED_SECRET,
+          severity: Severity.Critical,
+          analyzer: ANALYZER_NAME,
+          title: `Hardcoded ${label} detected`,
+          description:
+            `A ${label} appears to be hardcoded in \`${file.path}\`. ` +
+            `Hardcoded credentials can be extracted from source code and version control history.`,
+          file: file.path,
+          line: findLineNumber(file.content, match.index),
+          recommendation:
+            'Store secrets in environment variables and access them via `env()`. Never commit secrets to source control.',
+          cwe: 'CWE-798',
+          snippet: match[0].slice(0, 60),
+        });
+      }
+    }
+  }
+
+  private checkDbCredentials(file: ParsedFile, findings: Finding[]): void {
+    for (const pattern of DB_CREDENTIAL_PATTERNS) {
+      const regex = new RegExp(pattern.source, 'gs');
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(file.content)) !== null) {
+        findings.push({
+          id: FINDING_DB_CREDENTIALS,
+          severity: Severity.Critical,
+          analyzer: ANALYZER_NAME,
+          title: 'Database credentials hardcoded in source',
+          description:
+            `Database credentials appear to be hardcoded in \`${file.path}\`. ` +
+            `This exposes credentials to anyone with read access to the source code.`,
+          file: file.path,
+          line: findLineNumber(file.content, match.index),
+          recommendation:
+            'Use environment variables for database credentials: `DB_HOST`, `DB_USERNAME`, `DB_PASSWORD`.',
+          cwe: 'CWE-312',
+          snippet: match[0].slice(0, 60),
+        });
+      }
+    }
+  }
+
+  private checkPrivateKeys(file: ParsedFile, findings: Finding[]): void {
+    for (const { pattern, label } of PRIVATE_KEY_PATTERNS) {
+      const regex = new RegExp(pattern.source, 'g');
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(file.content)) !== null) {
+        findings.push({
+          id: FINDING_PRIVATE_KEY,
+          severity: Severity.Critical,
+          analyzer: ANALYZER_NAME,
+          title: `${label} found inline in source code`,
+          description:
+            `A ${label} was found inline in \`${file.path}\`. ` +
+            `Private keys and JWT secrets must never be stored in source code.`,
+          file: file.path,
+          line: findLineNumber(file.content, match.index),
+          recommendation:
+            'Store private keys in environment variables or a secrets manager. Never commit them to source control.',
+          cwe: 'CWE-321',
+          snippet: match[0].slice(0, 60),
+        });
+      }
+    }
+  }
+}

package/src/analyzers/DependencyAuditAnalyzer.ts

@@ -0,0 +1,135 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Analyzer, Finding, HavocConfig, ParsedFile, Severity } from '../types/index.js';
+
+const execFileAsync = promisify(execFile);
+
+const FINDING_VULNERABLE_DEP = 'HAVOC-DEP-001';
+const FINDING_COMPOSER_UNAVAILABLE = 'HAVOC-DEP-002';
+const ANALYZER_NAME = 'DependencyAuditAnalyzer';
+
+const SEVERITY_MAP: Record<string, Severity> = {
+  critical: Severity.Critical,
+  high: Severity.High,
+  medium: Severity.Medium,
+  moderate: Severity.Medium,
+  low: Severity.Low,
+  info: Severity.Info,
+};
+
+interface ComposerAdvisory {
+  advisoryId: string;
+  packageName: string;
+  title: string;
+  link: string;
+  cve: string | null;
+  severity: string;
+  affectedVersions: string;
+  sources: { name: string; remoteId: string }[];
+  reportedAt: string;
+}
+
+interface ComposerAuditResult {
+  advisories: Record<string, ComposerAdvisory[]>;
+  abandoned: Record<string, string>;
+}
+
+function mapSeverity(severity: string): Severity {
+  return SEVERITY_MAP[severity.toLowerCase()] ?? Severity.Medium;
+}
+
+export class DependencyAuditAnalyzer implements Analyzer {
+  readonly name = ANALYZER_NAME;
+  readonly description = 'Audits composer.json for known vulnerable PHP dependencies';
+
+  private readonly composerRunner: (projectPath: string) => Promise<ComposerAuditResult | null>;
+
+  constructor(composerRunner?: (projectPath: string) => Promise<ComposerAuditResult | null>) {
+    this.composerRunner = composerRunner ?? defaultComposerRunner;
+  }
+
+  async analyze(files: ParsedFile[], config: HavocConfig): Promise<Finding[]> {
+    const findings: Finding[] = [];
+
+    const composerFile = files.find((f) => f.path === 'composer.json' || f.path.endsWith('/composer.json'));
+    if (!composerFile) return findings;
+
+    const projectRoot = (config as HavocConfig & { projectRoot?: string }).projectRoot ?? '.';
+
+    try {
+      const auditResult = await this.composerRunner(projectRoot);
+      if (!auditResult) {
+        findings.push({
+          id: FINDING_COMPOSER_UNAVAILABLE,
+          severity: Severity.Info,
+          analyzer: ANALYZER_NAME,
+          title: 'composer audit unavailable — dependency check skipped',
+          description:
+            '`composer` is not available in PATH or does not support the `audit` command (requires Composer 2.4+).',
+          file: composerFile.path,
+          line: 1,
+          recommendation: 'Install Composer 2.4+ and run `composer audit` manually.',
+          cwe: 'CWE-1104',
+        });
+        return findings;
+      }
+
+      for (const [packageName, advisories] of Object.entries(auditResult.advisories)) {
+        for (const advisory of advisories) {
+          findings.push({
+            id: FINDING_VULNERABLE_DEP,
+            severity: mapSeverity(advisory.severity),
+            analyzer: ANALYZER_NAME,
+            title: `Vulnerable dependency: ${packageName} — ${advisory.title}`,
+            description:
+              `Package \`${packageName}\` has a known vulnerability: ${advisory.title}. ` +
+              (advisory.cve ? `CVE: ${advisory.cve}. ` : '') +
+              `Affected versions: ${advisory.affectedVersions}.`,
+            file: 'composer.json',
+            line: 1,
+            recommendation: `Update \`${packageName}\` to a patched version. See: ${advisory.link}`,
+            cwe: advisory.cve ? `CVE: ${advisory.cve}` : 'CWE-1104',
+            snippet: `"${packageName}": "${advisory.affectedVersions}"`,
+          });
+        }
+      }
+    } catch (err) {
+      findings.push({
+        id: FINDING_COMPOSER_UNAVAILABLE,
+        severity: Severity.Info,
+        analyzer: ANALYZER_NAME,
+        title: 'composer audit failed — dependency check skipped',
+        description: `composer audit returned an error: ${(err as Error).message}`,
+        file: composerFile.path,
+        line: 1,
+        recommendation: 'Ensure composer is installed and `composer.lock` is present.',
+        cwe: 'CWE-1104',
+      });
+    }
+
+    return findings;
+  }
+}
+
+async function defaultComposerRunner(projectPath: string): Promise<ComposerAuditResult | null> {
+  const composerLock = resolve(projectPath, 'composer.lock');
+  if (!existsSync(composerLock)) return null;
+
+  try {
+    const { stdout } = await execFileAsync('composer', ['audit', '--format=json', '--no-interaction'], {
+      cwd: projectPath,
+      timeout: 30_000,
+    });
+    return JSON.parse(stdout) as ComposerAuditResult;
+  } catch (err) {
+    const error = err as { code?: number; stdout?: string };
+    if (error.stdout) {
+      try {
+        return JSON.parse(error.stdout) as ComposerAuditResult;
+      } catch { /* not JSON */ }
+    }
+    return null;
+  }
+}