@havoc-security/scanner 0.1.0

package/src/analyzers/SqlInjectionAnalyzer.ts

@@ -0,0 +1,99 @@
+import { Analyzer, Finding, HavocConfig, ParsedFile, Severity } from '../types/index.js';
+
+const RAW_SQL_METHODS = [
+  'whereRaw', 'orWhereRaw', 'orderByRaw', 'selectRaw',
+  'havingRaw', 'orHavingRaw', 'groupByRaw', 'fromRaw',
+] as const;
+
+const DB_FACADE_METHODS = [
+  'DB::raw', 'DB::statement', 'DB::select', 'DB::insert', 'DB::update', 'DB::delete',
+] as const;
+
+// Matches: "str" . $var, "$var inside string", $var . 'str'
+const INTERPOLATION_PATTERN =
+  /(?:['"]\s*\.\s*\$|\$\{[^}]+\}|"[^"]*\$[a-zA-Z_][a-zA-Z0-9_]*[^"]*"|\$[a-zA-Z_][a-zA-Z0-9_]*\s*\.\s*['"])/;
+
+// Matches ? placeholders or :named (but NOT ::method calls)
+const BINDING_PATTERN = /\[\s*\$|\?\s*[,\]]|(?<![:])\s*:\s*(?!:)[a-zA-Z_]\w*/;
+
+const FINDING_INJECTION = 'HAVOC-SQL-001';
+const FINDING_RAW_INFO = 'HAVOC-SQL-002';
+const ANALYZER_NAME = 'SqlInjectionAnalyzer';
+
+interface SqlMatch {
+  method: string;
+  line: number;
+  snippet: string;
+  hasInterpolation: boolean;
+  hasBinding: boolean;
+}
+
+function findRawSqlUsages(content: string): SqlMatch[] {
+  const lines = content.split('\n');
+  const matches: SqlMatch[] = [];
+
+  lines.forEach((lineText, idx) => {
+    const lineNum = idx + 1;
+    for (const method of [...RAW_SQL_METHODS, ...DB_FACADE_METHODS]) {
+      const escaped = method.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const methodPattern = new RegExp(`${escaped}\\s*\\(`, 'g');
+      if (methodPattern.test(lineText)) {
+        const hasInterpolation = INTERPOLATION_PATTERN.test(lineText);
+        const hasBinding = BINDING_PATTERN.test(lineText);
+        matches.push({ method, line: lineNum, snippet: lineText.trim(), hasInterpolation, hasBinding });
+      }
+    }
+  });
+
+  return matches;
+}
+
+export class SqlInjectionAnalyzer implements Analyzer {
+  readonly name = ANALYZER_NAME;
+  readonly description = 'Finds raw SQL queries with potential injection vulnerabilities';
+
+  async analyze(files: ParsedFile[], _config: HavocConfig): Promise<Finding[]> {
+    const findings: Finding[] = [];
+
+    for (const file of files) {
+      if (!file.path.endsWith('.php') || file.path.endsWith('.blade.php')) continue;
+
+      const usages = findRawSqlUsages(file.content);
+
+      for (const usage of usages) {
+        if (usage.hasInterpolation && !usage.hasBinding) {
+          findings.push({
+            id: FINDING_INJECTION,
+            severity: Severity.High,
+            analyzer: ANALYZER_NAME,
+            title: `SQL injection risk in \`${usage.method}()\``,
+            description:
+              `\`${usage.method}()\` is called with a string containing variable interpolation ` +
+              `or concatenation without parameter bindings.`,
+            file: file.path,
+            line: usage.line,
+            recommendation:
+              `Use parameter bindings: \`${usage.method}('col = ?', [$value])\`.`,
+            cwe: 'CWE-89',
+            snippet: usage.snippet,
+          });
+        } else if (!usage.hasBinding) {
+          findings.push({
+            id: FINDING_RAW_INFO,
+            severity: Severity.Info,
+            analyzer: ANALYZER_NAME,
+            title: `Raw SQL usage in \`${usage.method}()\` — verify safety`,
+            description: `\`${usage.method}()\` contains a raw SQL fragment. Ensure no user input reaches this query.`,
+            file: file.path,
+            line: usage.line,
+            recommendation: 'If any part of this query can be user-influenced, use parameter bindings.',
+            cwe: 'CWE-89',
+            snippet: usage.snippet,
+          });
+        }
+      }
+    }
+
+    return findings;
+  }
+}

package/src/analyzers/XssSurfaceAnalyzer.ts

@@ -0,0 +1,112 @@
+import { isDocsFile } from './exclusions.js';
+import { Analyzer, Finding, HavocConfig, ParsedFile, Severity } from '../types/index.js';
+
+const UNESCAPED_OUTPUT_PATTERN = /\{!!\s*(.+?)\s*!!\}/g;
+
+const TRUSTED_CONTEXT_PATTERNS = [
+  /config\s*\(/,
+  /asset\s*\(/,
+  /url\s*\(/,
+  /route\s*\(/,
+  /__\s*\(/,
+  /trans\s*\(/,
+];
+
+const USER_CONTROLLED_PATTERNS = [
+  /\$[a-zA-Z_][a-zA-Z0-9_]*->(?:body|content|message|description|text|html|comment|bio|about|summary)/i,
+  /\$(?:body|content|message|description|text|html|comment|bio|about|summary)\b/i,
+  /request\(\)/i,
+  /->input\s*\(/i,
+];
+
+const ESCAPE_FUNCTION_PATTERNS = [
+  /\be\s*\(/,
+  /htmlspecialchars\s*\(/,
+  /Purifier::/,
+  /clean\s*\(/,
+  /strip_tags\s*\(/,
+];
+
+const FINDING_HIGH = 'HAVOC-XSS-001';
+const FINDING_MED = 'HAVOC-XSS-002';
+const ANALYZER_NAME = 'XssSurfaceAnalyzer';
+
+function isTrustedFilePath(path: string): boolean {
+  return (
+    path.includes('/mail/') ||
+    path.includes('/emails/') ||
+    path.includes('/notifications/') ||
+    path.includes('\\mail\\') ||
+    path.includes('\\emails\\') ||
+    path.includes('/svg/') ||
+    path.includes('/icons/') ||
+    path.endsWith('.svg.blade.php')
+  );
+}
+
+function classifyExpression(expression: string, filePath: string): 'trusted' | 'user-controlled' | 'unknown' {
+  if (ESCAPE_FUNCTION_PATTERNS.some((re) => re.test(expression))) return 'trusted';
+  if (TRUSTED_CONTEXT_PATTERNS.some((re) => re.test(expression))) return 'trusted';
+  if (isTrustedFilePath(filePath)) return 'trusted';
+  if (USER_CONTROLLED_PATTERNS.some((re) => re.test(expression))) return 'user-controlled';
+  return 'unknown';
+}
+
+export class XssSurfaceAnalyzer implements Analyzer {
+  readonly name = ANALYZER_NAME;
+  readonly description = 'Identifies unescaped Blade output that could lead to Cross-Site Scripting (XSS)';
+
+  async analyze(files: ParsedFile[], _config: HavocConfig): Promise<Finding[]> {
+    const findings: Finding[] = [];
+
+    for (const file of files) {
+      if (!file.path.endsWith('.blade.php') || isDocsFile(file.path)) continue;
+
+      const lines = file.content.split('\n');
+      lines.forEach((lineText, idx) => {
+        const lineNum = idx + 1;
+        const re = new RegExp(UNESCAPED_OUTPUT_PATTERN.source, 'g');
+        let match: RegExpExecArray | null;
+
+        while ((match = re.exec(lineText)) !== null) {
+          const expression = match[1];
+          const classification = classifyExpression(expression, file.path);
+          if (classification === 'trusted') continue;
+
+          if (classification === 'user-controlled') {
+            findings.push({
+              id: FINDING_HIGH,
+              severity: Severity.High,
+              analyzer: ANALYZER_NAME,
+              title: 'Unescaped user-controlled output in Blade template',
+              description:
+                `\`{!! ${expression} !!}\` outputs potentially user-controlled content without HTML escaping.`,
+              file: file.path,
+              line: lineNum,
+              recommendation: 'Use `{{ $variable }}` for automatic escaping.',
+              cwe: 'CWE-79',
+              snippet: lineText.trim(),
+            });
+          } else {
+            findings.push({
+              id: FINDING_MED,
+              severity: Severity.Medium,
+              analyzer: ANALYZER_NAME,
+              title: 'Unescaped output in Blade template — verify safety',
+              description:
+                `\`{!! ${expression} !!}\` outputs content without HTML escaping. Verify this cannot contain user HTML.`,
+              file: file.path,
+              line: lineNum,
+              recommendation:
+                'If the value could contain user input, switch to `{{ $variable }}`.',
+              cwe: 'CWE-79',
+              snippet: lineText.trim(),
+            });
+          }
+        }
+      });
+    }
+
+    return findings;
+  }
+}

package/src/analyzers/exclusions.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared file exclusion patterns for analyzers.
+ * Reduces false positives by skipping files that aren't relevant.
+ */
+
+/** Files that should never be scanned for security vulnerabilities */
+const EXCLUDED_PATTERNS = [
+  /database\/migrations\//,
+  /database\/seeders\//,
+  /database\/factories\//,
+];
+
+/** Files that contain test/example code, not production code */
+const TEST_PATTERNS = [
+  /tests?\//,
+  /spec\//,
+  /__tests__\//,
+  /\.test\./,
+  /\.spec\./,
+];
+
+/** Documentation files */
+const DOCS_PATTERNS = [
+  /docs?\//,
+  /documentation\//,
+  /examples?\//,
+  /demo\//,
+];
+
+/** Model directories (for model-specific analyzers) */
+const MODEL_PATTERNS = [
+  /app\/Models\//,
+];
+
+export function isExcludedPath(path: string): boolean {
+  return EXCLUDED_PATTERNS.some(p => p.test(path));
+}
+
+export function isTestFile(path: string): boolean {
+  return TEST_PATTERNS.some(p => p.test(path));
+}
+
+export function isDocsFile(path: string): boolean {
+  return DOCS_PATTERNS.some(p => p.test(path));
+}
+
+export function isModelFile(path: string): boolean {
+  return MODEL_PATTERNS.some(p => p.test(path));
+}
+
+export function isBladeFile(path: string): boolean {
+  return path.endsWith('.blade.php');
+}
+
+/**
+ * Check if a raw SQL string is static (no PHP variable interpolation).
+ * Static SQL like selectRaw('MAX(id)') is safe.
+ */
+export function isStaticSql(sqlString: string): boolean {
+  // Extract the string argument from the method call (the part inside quotes)
+  const stringArg = sqlString.match(/\(\s*['"](.*?)['"]\s*[,)]/s);
+  const sqlPart = stringArg ? stringArg[1] : sqlString;
+  
+  // Contains PHP variable interpolation inside the SQL string
+  if (/\$[a-zA-Z_]/.test(sqlPart)) return false;
+  // Contains string concatenation with variable
+  if (/\.\s*\$/.test(sqlPart)) return false;
+  return true;
+}
+
+/**
+ * Check if a credential-like value is obviously fake/test.
+ */
+export function isFakeCredential(value: string): boolean {
+  const fakePatterns = [
+    /super.?secret/i,
+    /test.?token/i,
+    /example[_\-]?(key|secret|token|password|value|here)/i,  // e.g., example_key, example-token
+    /fake/i,
+    /dummy/i,
+    /placeholder/i,
+    /your.?key.?here/i,
+    /xxx+/i,
+    /000+/,
+  ];
+  return fakePatterns.some(p => p.test(value));
+}

package/src/analyzers/index.ts

@@ -0,0 +1,15 @@
+export { AuthorizationCoverageAnalyzer } from './AuthorizationCoverageAnalyzer.js';
+export { MassAssignmentAnalyzer } from './MassAssignmentAnalyzer.js';
+export { XssSurfaceAnalyzer } from './XssSurfaceAnalyzer.js';
+export { SqlInjectionAnalyzer } from './SqlInjectionAnalyzer.js';
+export { DependencyAuditAnalyzer } from './DependencyAuditAnalyzer.js';
+export { IdorAnalyzer } from './IdorAnalyzer.js';
+export { CredentialExposureAnalyzer } from './CredentialExposureAnalyzer.js';
+export { SessionSecurityAnalyzer } from './SessionSecurityAnalyzer.js';
+export { FileUploadAnalyzer } from './FileUploadAnalyzer.js';
+export { RateLimitAnalyzer } from './RateLimitAnalyzer.js';
+export { EncryptionAnalyzer } from './EncryptionAnalyzer.js';
+export { PrivilegeEscalationAnalyzer } from './PrivilegeEscalationAnalyzer.js';
+export { InsecureDeserializationAnalyzer } from './InsecureDeserializationAnalyzer.js';
+export { OpenRedirectAnalyzer } from './OpenRedirectAnalyzer.js';
+export { SecurityHeaderAnalyzer } from './SecurityHeaderAnalyzer.js';

package/src/index.ts

@@ -0,0 +1,226 @@
+export * from './types/index.js';
+export * from './analyzers/index.js';
+export { PhpParser, PHP_FILE_PATTERNS } from './parsers/PhpParser.js';
+export type { ParsedPhpFile, PhpClassInfo, PhpMethodInfo, PhpPropertyInfo } from './parsers/PhpParser.js';
+export { RouteParser, buildRouteMap, getRouteMiddleware, isAuthorizationMiddleware, isAuthenticationMiddleware, hasAuthorizationMiddleware, hasAuthenticationMiddleware, isWebhookHandler } from './parsers/RouteParser.js';
+export type { RouteInfo, ParsedRouteFile } from './parsers/RouteParser.js';
+export { rules } from './rules/index.js';
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { glob } from 'glob';
+import { Analyzer, HavocConfig, ParsedFile, ScanResult, Severity } from './types/index.js';
+import { AuthorizationCoverageAnalyzer } from './analyzers/AuthorizationCoverageAnalyzer.js';
+import { MassAssignmentAnalyzer } from './analyzers/MassAssignmentAnalyzer.js';
+import { XssSurfaceAnalyzer } from './analyzers/XssSurfaceAnalyzer.js';
+import { SqlInjectionAnalyzer } from './analyzers/SqlInjectionAnalyzer.js';
+import { DependencyAuditAnalyzer } from './analyzers/DependencyAuditAnalyzer.js';
+import { IdorAnalyzer } from './analyzers/IdorAnalyzer.js';
+import { CredentialExposureAnalyzer } from './analyzers/CredentialExposureAnalyzer.js';
+import { SessionSecurityAnalyzer } from './analyzers/SessionSecurityAnalyzer.js';
+import { FileUploadAnalyzer } from './analyzers/FileUploadAnalyzer.js';
+import { RateLimitAnalyzer } from './analyzers/RateLimitAnalyzer.js';
+import { EncryptionAnalyzer } from './analyzers/EncryptionAnalyzer.js';
+import { PrivilegeEscalationAnalyzer } from './analyzers/PrivilegeEscalationAnalyzer.js';
+import { InsecureDeserializationAnalyzer } from './analyzers/InsecureDeserializationAnalyzer.js';
+import { OpenRedirectAnalyzer } from './analyzers/OpenRedirectAnalyzer.js';
+import { SecurityHeaderAnalyzer } from './analyzers/SecurityHeaderAnalyzer.js';
+import { PhpParser } from './parsers/PhpParser.js';
+import { RouteParser } from './parsers/RouteParser.js';
+import type { ParsedRouteFile } from './parsers/RouteParser.js';
+
+// ─── Security Grade ──────────────────────────────────────────────────────────
+
+export type SecurityGrade = 'A' | 'B' | 'C' | 'D' | 'F';
+
+interface GradeThreshold {
+  readonly grade: SecurityGrade;
+  readonly maxPenalty: number;
+}
+
+const SEVERITY_PENALTIES: Record<Severity, number> = {
+  [Severity.Critical]: 25,
+  [Severity.High]: 10,
+  [Severity.Medium]: 3,
+  [Severity.Low]: 1,
+  [Severity.Info]: 0,
+};
+
+const GRADE_THRESHOLDS: readonly GradeThreshold[] = [
+  { grade: 'A', maxPenalty: 0 },
+  { grade: 'B', maxPenalty: 10 },
+  { grade: 'C', maxPenalty: 25 },
+  { grade: 'D', maxPenalty: 50 },
+  { grade: 'F', maxPenalty: Infinity },
+];
+
+export function calculateSecurityGrade(findings: { severity: Severity }[]): SecurityGrade {
+  const penalty = findings.reduce((sum, f) => sum + (SEVERITY_PENALTIES[f.severity] ?? 0), 0);
+  for (const threshold of GRADE_THRESHOLDS) {
+    if (penalty <= threshold.maxPenalty) return threshold.grade;
+  }
+  return 'F';
+}
+
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+
+export function createDefaultAnalyzers(routeFiles: ParsedRouteFile[] = []): Analyzer[] {
+  return [
+    new AuthorizationCoverageAnalyzer(routeFiles),
+    new MassAssignmentAnalyzer(),
+    new XssSurfaceAnalyzer(),
+    new SqlInjectionAnalyzer(),
+    new DependencyAuditAnalyzer(),
+    new IdorAnalyzer(),
+    new CredentialExposureAnalyzer(),
+    new SessionSecurityAnalyzer(),
+    new FileUploadAnalyzer(),
+    new RateLimitAnalyzer(),
+    new EncryptionAnalyzer(),
+    new PrivilegeEscalationAnalyzer(),
+    new InsecureDeserializationAnalyzer(),
+    new OpenRedirectAnalyzer(),
+    new SecurityHeaderAnalyzer(),
+  ];
+}
+
+/** @deprecated Use createDefaultAnalyzers() for route-aware analysis */
+export const DEFAULT_ANALYZERS: Analyzer[] = createDefaultAnalyzers();
+
+export const DEFAULT_CONFIG: HavocConfig = {
+  framework: 'laravel',
+  failOn: Severity.High,
+  output: 'text',
+};
+
+const SCANNER_VERSION = '0.2.0';
+
+const DEFAULT_EXCLUDE_PATTERNS = [
+  'vendor/**', 'node_modules/**', 'storage/**',
+  'bootstrap/cache/**', 'public/vendor/**', '.git/**',
+];
+
+async function discoverProjectFiles(
+  projectPath: string,
+  config: HavocConfig,
+  parser: PhpParser,
+): Promise<ParsedFile[]> {
+  const absPath = resolve(projectPath);
+  const excludePatterns = [
+    ...DEFAULT_EXCLUDE_PATTERNS,
+    ...(config.exclude ?? []),
+  ].map((e) => `${absPath}/${e}`);
+
+  const phpFiles = await glob(`${absPath}/**/*.php`, { ignore: excludePatterns, nodir: true });
+  const bladeFiles = await glob(`${absPath}/resources/views/**/*.blade.php`, { ignore: excludePatterns, nodir: true });
+
+  const parsedPhp = await Promise.all(phpFiles.map((f) => parser.parseFile(f, absPath)));
+
+  const parsedBlade = await Promise.all(
+    bladeFiles
+      .filter((f) => !phpFiles.includes(f))
+      .map(async (f) => ({
+        path: f.replace(`${absPath}/`, ''),
+        content: await readFile(f, 'utf-8').catch(() => ''),
+        ast: null,
+      })),
+  );
+
+  const composerJsonPath = join(absPath, 'composer.json');
+  const composerFiles: ParsedFile[] = existsSync(composerJsonPath)
+    ? [{ path: 'composer.json', content: await readFile(composerJsonPath, 'utf-8').catch(() => ''), ast: null }]
+    : [];
+
+  return [...parsedPhp, ...parsedBlade, ...composerFiles];
+}
+
+async function discoverRouteFiles(projectPath: string): Promise<ParsedRouteFile[]> {
+  const absPath = resolve(projectPath);
+  const routesDir = join(absPath, 'routes');
+  if (!existsSync(routesDir)) return [];
+
+  const routeParser = new RouteParser();
+  return routeParser.parseDirectory(absPath);
+}
+
+function computeCoverage(files: ParsedFile[]) {
+  let totalRoutes = 0;
+  let coveredRoutes = 0;
+  let totalModels = 0;
+  let protectedModels = 0;
+
+  for (const file of files) {
+    if (file.path.startsWith('routes/') || file.path.startsWith('routes\\')) {
+      const routeMatches = file.content.match(/Route::\w+\s*\(/g) ?? [];
+      totalRoutes += routeMatches.length;
+      const authMatches = file.content.match(/->middleware\s*\(\s*['"]auth/g) ?? [];
+      coveredRoutes += authMatches.length;
+    }
+    if ((file.path.includes('app/Models') || file.path.includes('app\\Models')) && file.path.endsWith('.php')) {
+      totalModels++;
+      if (/\$fillable\s*=|protected\s+\$guarded\s*=\s*\[(?:[^\]]+)\]/.test(file.content)) {
+        protectedModels++;
+      }
+    }
+  }
+
+  const coveragePercent = totalRoutes > 0 ? Math.round((coveredRoutes / totalRoutes) * 100) : 100;
+  return { totalRoutes, coveredRoutes, coveragePercent, totalModels, protectedModels };
+}
+
+export async function scan(
+  files: ParsedFile[],
+  config: HavocConfig = DEFAULT_CONFIG,
+  analyzers: Analyzer[] = DEFAULT_ANALYZERS,
+): Promise<ScanResult> {
+  const startTime = Date.now();
+
+  const allFindings = await Promise.all(
+    analyzers.map((analyzer) => analyzer.analyze(files, config)),
+  );
+
+  const findings = allFindings.flat();
+  const coverage = computeCoverage(files);
+
+  return {
+    findings,
+    coverage,
+    metadata: {
+      scannedAt: new Date().toISOString(),
+      framework: config.framework,
+      filesScanned: files.length,
+      durationMs: Date.now() - startTime,
+      scannerVersion: SCANNER_VERSION,
+    },
+  };
+}
+
+export async function scanProject(
+  projectPath: string,
+  config: HavocConfig = DEFAULT_CONFIG,
+  analyzers?: Analyzer[],
+): Promise<ScanResult & { grade: SecurityGrade }> {
+  const parser = new PhpParser();
+
+  // Parse route files first so we can pass them to analyzers
+  const routeFiles = await discoverRouteFiles(projectPath);
+
+  // Build route-aware analyzers unless caller supplied their own
+  const effectiveAnalyzers = analyzers ?? createDefaultAnalyzers(routeFiles);
+
+  // If caller supplied analyzers, try to inject route data into any AuthorizationCoverageAnalyzer
+  if (analyzers) {
+    for (const a of analyzers) {
+      if (a instanceof AuthorizationCoverageAnalyzer) {
+        a.setRouteFiles(routeFiles);
+      }
+    }
+  }
+
+  const files = await discoverProjectFiles(projectPath, config, parser);
+  const configWithRoot = { ...config, projectRoot: resolve(projectPath) } as HavocConfig & { projectRoot: string };
+  const result = await scan(files, configWithRoot, effectiveAnalyzers);
+  const grade = calculateSecurityGrade(result.findings);
+  return { ...result, grade };
+}