@freshguard/freshguard-core 0.13.2 → 0.15.0

package/dist/security/query-analyzer.d.ts

@@ -1,82 +1,206 @@
+/**
+ * Query Complexity Analyzer for FreshGuard Core Phase 2
+ *
+ * Analyzes SQL queries for complexity and security risks, providing
+ * risk scoring and recommendations for safe query execution.
+ *
+ * @license MIT
+ */
+/**
+ * Query complexity analysis result
+ */
 export interface QueryComplexity {
+    /** Whether the query should be allowed to execute */
     allowExecution: boolean;
+    /** Risk score from 0 (safe) to 100 (dangerous) */
     riskScore: number;
+    /** Complexity score based on query structure */
     complexityScore: number;
+    /** Estimated execution cost */
     estimatedCost: number;
+    /** Security warnings found */
     securityWarnings: string[];
+    /** Performance warnings found */
     performanceWarnings: string[];
+    /** Recommendations for optimization */
     recommendations: string[];
+    /** Query analysis details */
     details: QueryAnalysisDetails;
 }
+/**
+ * Detailed query analysis breakdown
+ */
 export interface QueryAnalysisDetails {
+    /** Query type (SELECT, INSERT, etc.) */
     queryType: string;
+    /** Number of tables involved */
     tableCount: number;
+    /** Number of joins */
     joinCount: number;
+    /** Has subqueries */
     hasSubqueries: boolean;
+    /** Has aggregations */
     hasAggregations: boolean;
+    /** Has wildcards in SELECT */
     hasWildcards: boolean;
+    /** Has LIMIT clause */
     hasLimit: boolean;
+    /** LIMIT value if present */
     limitValue?: number;
+    /** Has WHERE clause */
     hasWhere: boolean;
+    /** Has ORDER BY clause */
     hasOrderBy: boolean;
+    /** Has GROUP BY clause */
     hasGroupBy: boolean;
+    /** Has HAVING clause */
     hasHaving: boolean;
+    /** Estimated result set size */
     estimatedResultSize: number;
 }
+/**
+ * Table metadata for analysis
+ */
 export interface TableMetadata {
+    /** Table name */
     name: string;
+    /** Estimated row count */
     estimatedRows: number;
+    /** Table size in bytes */
     sizeBytes?: number;
+    /** Available indexes */
     indexes: IndexInfo[];
+    /** Column information */
     columns: ColumnInfo[];
+    /** When metadata was last updated */
     lastUpdated: Date;
 }
+/**
+ * Index information
+ */
 export interface IndexInfo {
+    /** Index name */
     name: string;
+    /** Columns in the index */
     columns: string[];
+    /** Whether index is unique */
     unique: boolean;
+    /** Index type (btree, hash, etc.) */
     type?: string;
 }
+/**
+ * Column information
+ */
 export interface ColumnInfo {
+    /** Column name */
     name: string;
+    /** Data type */
     type: string;
+    /** Whether column is nullable */
     nullable: boolean;
+    /** Whether column is indexed */
     indexed: boolean;
+    /** Estimated cardinality */
     cardinality?: number;
 }
+/**
+ * Query analyzer configuration
+ */
 export interface QueryAnalyzerConfig {
+    /** Maximum risk score to allow execution (0-100) */
     maxRiskScore: number;
+    /** Maximum complexity score to allow (0-100) */
     maxComplexityScore: number;
+    /** Maximum estimated cost to allow */
     maxEstimatedCost: number;
+    /** Maximum result set size to allow */
     maxResultSetSize: number;
+    /** Enable performance analysis */
     enablePerformanceAnalysis: boolean;
+    /** Enable security analysis */
     enableSecurityAnalysis: boolean;
+    /** Custom risk factors */
     customRiskFactors: RiskFactor[];
 }
+/**
+ * Custom risk factor definition
+ */
 export interface RiskFactor {
+    /** Pattern to match */
     pattern: RegExp;
+    /** Risk score to add (0-100) */
     riskScore: number;
+    /** Description of the risk */
     description: string;
+    /** Whether this should block execution */
     blocking: boolean;
 }
+/**
+ * Analyzes SQL queries for complexity and security risks
+ */
 export declare class QueryComplexityAnalyzer {
     private config;
     private readonly riskFactors;
     constructor(config?: Partial<QueryAnalyzerConfig>);
+    /**
+     * Analyze a SQL query for complexity and security risks
+     */
     analyzeQuery(sql: string, tableMetadata?: TableMetadata[]): QueryComplexity;
+    /**
+     * Calculate query complexity score (0-100)
+     */
     private calculateComplexityScore;
+    /**
+     * Calculate security risk score (0-100)
+     */
     private calculateRiskScore;
+    /**
+     * Calculate estimated execution cost
+     */
     private calculateEstimatedCost;
+    /**
+     * Generate security warnings
+     */
     private generateSecurityWarnings;
+    /**
+     * Generate performance warnings
+     */
     private generatePerformanceWarnings;
+    /**
+     * Generate optimization recommendations
+     */
     private generateRecommendations;
+    /**
+     * Determine if query execution should be allowed
+     */
     private shouldAllowExecution;
+    /**
+     * Update configuration
+     */
     updateConfig(config: Partial<QueryAnalyzerConfig>): void;
+    /**
+     * Add custom risk factor
+     */
     addRiskFactor(factor: RiskFactor): void;
+    /**
+     * Get current configuration
+     */
     getConfig(): QueryAnalyzerConfig;
 }
+/**
+ * Create a query analyzer with default configuration
+ */
 export declare function createQueryAnalyzer(config?: Partial<QueryAnalyzerConfig>): QueryComplexityAnalyzer;
+/**
+ * Create a strict security analyzer
+ */
 export declare function createSecurityAnalyzer(): QueryComplexityAnalyzer;
+/**
+ * Create a performance-focused analyzer
+ */
 export declare function createPerformanceAnalyzer(): QueryComplexityAnalyzer;
+/**
+ * Default query analyzer instance
+ */
 export declare const defaultQueryAnalyzer: QueryComplexityAnalyzer;
 //# sourceMappingURL=query-analyzer.d.ts.map

package/dist/security/query-analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-analyzer.d.ts","sourceRoot":"","sources":["../../src/security/query-analyzer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query-analyzer.d.ts","sourceRoot":"","sources":["../../src/security/query-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/security/query-analyzer.js

@@ -1,12 +1,29 @@
+/**
+ * Query Complexity Analyzer for FreshGuard Core Phase 2
+ *
+ * Analyzes SQL queries for complexity and security risks, providing
+ * risk scoring and recommendations for safe query execution.
+ *
+ * @license MIT
+ */
+// ==============================================
+// Default Configuration
+// ==============================================
+/**
+ * Default query analyzer configuration
+ */
 const DEFAULT_CONFIG = {
     maxRiskScore: 70,
     maxComplexityScore: 80,
-    maxEstimatedCost: 1000000,
+    maxEstimatedCost: 1000000, // 1 million cost units
     maxResultSetSize: 10000,
     enablePerformanceAnalysis: true,
     enableSecurityAnalysis: true,
     customRiskFactors: []
 };
+/**
+ * Default risk factors for security analysis
+ */
 const DEFAULT_RISK_FACTORS = [
     {
         pattern: /union\s+all|union\s+select/i,
@@ -63,12 +80,26 @@ const DEFAULT_RISK_FACTORS = [
         blocking: false
     }
 ];
+// ==============================================
+// SQL Parser Utilities
+// ==============================================
+/**
+ * Simple SQL parser for query analysis
+ * Note: This is a simplified parser for basic analysis
+ */
 class SimpleSQLParser {
+    /**
+     * Parse basic query structure
+     */
     static parseQuery(sql) {
         const normalizedSql = sql.trim().toLowerCase();
+        // Determine query type
         const queryType = this.getQueryType(normalizedSql);
+        // Count tables (simplified - counts FROM and JOIN clauses)
         const tableCount = this.countTables(normalizedSql);
+        // Count joins
         const joinCount = this.countJoins(normalizedSql);
+        // Check for various SQL constructs
         const hasSubqueries = /\(\s*select\b/.test(normalizedSql);
         const hasAggregations = /\b(count|sum|avg|max|min|group_concat)\s*\(/.test(normalizedSql);
         const hasWildcards = /select\s+\*\s+from\b/.test(normalizedSql);
@@ -76,9 +107,11 @@ class SimpleSQLParser {
         const hasOrderBy = /\border\s+by\b/.test(normalizedSql);
         const hasGroupBy = /\bgroup\s+by\b/.test(normalizedSql);
         const hasHaving = /\bhaving\b/.test(normalizedSql);
+        // Check for LIMIT
         const limitMatch = /\blimit\s+(\d+)/.exec(normalizedSql);
         const hasLimit = !!limitMatch;
         const limitValue = limitMatch?.[1] ? parseInt(limitMatch[1], 10) : undefined;
+        // Estimate result set size (simplified)
         const estimatedResultSize = this.estimateResultSize(tableCount, hasWhere, hasLimit, limitValue);
         return {
             queryType,
@@ -96,6 +129,9 @@ class SimpleSQLParser {
             estimatedResultSize
         };
     }
+    /**
+     * Get query type from SQL
+     */
     static getQueryType(sql) {
         if (sql.startsWith('select'))
             return 'SELECT';
@@ -117,26 +153,47 @@ class SimpleSQLParser {
             return 'DESCRIBE';
         return 'UNKNOWN';
     }
+    /**
+     * Count number of tables in query
+     */
     static countTables(sql) {
+        // Count FROM clauses
         const fromMatches = sql.match(/\bfrom\s+[\w.]+/g) ?? [];
+        // Count JOIN clauses
         const joinMatches = sql.match(/\bjoin\s+[\w.]+/g) ?? [];
         return fromMatches.length + joinMatches.length;
     }
+    /**
+     * Count number of joins
+     */
     static countJoins(sql) {
         const joinMatches = sql.match(/\b(inner\s+join|left\s+join|right\s+join|full\s+join|join)\b/g) ?? [];
         return joinMatches.length;
     }
+    /**
+     * Estimate result set size
+     */
     static estimateResultSize(tableCount, hasWhere, hasLimit, limitValue) {
+        // If LIMIT is specified, use that as max
         if (hasLimit && limitValue) {
             return Math.min(limitValue, 10000);
         }
-        let estimate = Math.pow(1000, tableCount);
+        // Base estimate on table count and filtering
+        let estimate = Math.pow(1000, tableCount); // Exponential growth with joins
+        // Reduce estimate if WHERE clause exists (assumes filtering)
         if (hasWhere) {
-            estimate = Math.floor(estimate * 0.1);
+            estimate = Math.floor(estimate * 0.1); // Assume WHERE reduces by 90%
         }
+        // Cap at reasonable maximum
         return Math.min(estimate, 100000);
     }
 }
+// ==============================================
+// Query Complexity Analyzer
+// ==============================================
+/**
+ * Analyzes SQL queries for complexity and security risks
+ */
 export class QueryComplexityAnalyzer {
     config;
     riskFactors;
@@ -147,14 +204,21 @@ export class QueryComplexityAnalyzer {
             ...(config.customRiskFactors ?? [])
         ];
     }
+    /**
+     * Analyze a SQL query for complexity and security risks
+     */
     analyzeQuery(sql, tableMetadata = []) {
+        // Parse query structure
         const details = SimpleSQLParser.parseQuery(sql);
+        // Calculate scores
         const complexityScore = this.calculateComplexityScore(details, tableMetadata);
         const riskScore = this.calculateRiskScore(sql, details);
         const estimatedCost = this.calculateEstimatedCost(details, tableMetadata);
+        // Generate warnings and recommendations
         const securityWarnings = this.generateSecurityWarnings(sql, details);
         const performanceWarnings = this.generatePerformanceWarnings(details, tableMetadata);
         const recommendations = this.generateRecommendations(details, securityWarnings, performanceWarnings);
+        // Determine if execution should be allowed
         const allowExecution = this.shouldAllowExecution(sql, riskScore, complexityScore, estimatedCost, details);
         return {
             allowExecution,
@@ -167,8 +231,12 @@ export class QueryComplexityAnalyzer {
             details
         };
     }
+    /**
+     * Calculate query complexity score (0-100)
+     */
     calculateComplexityScore(details, _tableMetadata) {
         let score = 0;
+        // Base score by query type
         switch (details.queryType) {
             case 'SELECT':
                 score += 5;
@@ -193,79 +261,107 @@ export class QueryComplexityAnalyzer {
                 break;
             default: score += 10;
         }
-        score += Math.min(details.tableCount * 10, 30);
-        score += Math.min(details.joinCount * 15, 40);
+        // Table complexity
+        score += Math.min(details.tableCount * 10, 30); // Max 30 for tables
+        // Join complexity
+        score += Math.min(details.joinCount * 15, 40); // Max 40 for joins
+        // Subquery complexity
         if (details.hasSubqueries)
             score += 20;
+        // Aggregation complexity
         if (details.hasAggregations)
             score += 10;
+        // Wildcard penalty (SELECT *)
         if (details.hasWildcards)
             score += 15;
+        // Missing WHERE clause on multi-table queries
         if (details.tableCount > 1 && !details.hasWhere)
             score += 25;
+        // Large result set penalty
         if (details.estimatedResultSize > 1000)
             score += 10;
         if (details.estimatedResultSize > 10000)
             score += 20;
+        // No LIMIT on potentially large results
         if (!details.hasLimit && details.estimatedResultSize > 1000)
             score += 15;
         return Math.min(score, 100);
     }
+    /**
+     * Calculate security risk score (0-100)
+     */
     calculateRiskScore(sql, details) {
         let score = 0;
         if (!this.config.enableSecurityAnalysis) {
             return 0;
         }
+        // Check against risk factors
         for (const factor of this.riskFactors) {
             if (factor.pattern.test(sql)) {
                 score += factor.riskScore;
             }
         }
+        // Additional risk factors based on query structure
         if (details.queryType !== 'SELECT' && details.queryType !== 'SHOW' && details.queryType !== 'DESCRIBE') {
-            score += 30;
+            score += 30; // Non-read operations are inherently riskier
         }
+        // Multiple statements (potential injection)
         const statementCount = sql.split(';').filter(s => s.trim()).length;
         if (statementCount > 1) {
             score += 40;
         }
         return Math.min(score, 100);
     }
+    /**
+     * Calculate estimated execution cost
+     */
     calculateEstimatedCost(details, tableMetadata) {
-        let cost = 1;
+        let cost = 1; // Base cost
+        // Cost based on estimated result size
         cost += details.estimatedResultSize * 0.1;
+        // Join costs (exponential)
         if (details.joinCount > 0) {
             cost *= Math.pow(10, details.joinCount);
         }
+        // Table scan costs
         for (let i = 0; i < details.tableCount; i++) {
             const metadata = tableMetadata[i];
             if (metadata) {
                 cost += metadata.estimatedRows * 0.01;
             }
             else {
-                cost += 10000;
+                cost += 10000; // Unknown table - assume large
             }
         }
+        // Subquery costs
         if (details.hasSubqueries) {
             cost *= 5;
         }
+        // Aggregation costs
         if (details.hasAggregations) {
             cost *= 2;
         }
+        // Sorting costs
         if (details.hasOrderBy && !details.hasLimit) {
             cost *= 3;
         }
         return Math.floor(cost);
     }
+    /**
+     * Generate security warnings
+     */
     generateSecurityWarnings(sql, details) {
         const warnings = [];
         if (!this.config.enableSecurityAnalysis) {
             return warnings;
         }
+        // Check risk factors
         for (const factor of this.riskFactors) {
             if (factor.pattern.test(sql)) {
                 warnings.push(factor.description);
             }
         }
+        // Additional security checks
         if (details.queryType !== 'SELECT' && details.queryType !== 'SHOW' && details.queryType !== 'DESCRIBE') {
             warnings.push('Non-read operation detected - ensure proper authorization');
         }
@@ -277,36 +373,49 @@ export class QueryComplexityAnalyzer {
         }
         return warnings;
     }
+    /**
+     * Generate performance warnings
+     */
     generatePerformanceWarnings(details, tableMetadata) {
         const warnings = [];
         if (!this.config.enablePerformanceAnalysis) {
             return warnings;
         }
+        // Large result set without LIMIT
         if (details.estimatedResultSize > 1000 && !details.hasLimit) {
             warnings.push(`Large result set estimated (${details.estimatedResultSize}) without LIMIT clause`);
         }
+        // Multiple joins without WHERE
         if (details.joinCount > 1 && !details.hasWhere) {
             warnings.push('Multiple JOINs without WHERE clause may produce Cartesian product');
         }
+        // SELECT * on large tables
         if (details.hasWildcards && tableMetadata.some(t => t.estimatedRows > 10000)) {
             warnings.push('SELECT * on large table(s) - consider selecting specific columns');
         }
+        // ORDER BY without LIMIT on large result
         if (details.hasOrderBy && !details.hasLimit && details.estimatedResultSize > 1000) {
             warnings.push('ORDER BY without LIMIT on large result set - consider adding LIMIT');
         }
+        // Subqueries
         if (details.hasSubqueries) {
             warnings.push('Subqueries detected - consider using JOINs for better performance');
         }
         return warnings;
     }
+    /**
+     * Generate optimization recommendations
+     */
     generateRecommendations(details, securityWarnings, performanceWarnings) {
         const recommendations = [];
+        // Security recommendations
         if (securityWarnings.length > 0) {
             recommendations.push('Review security warnings and validate query source');
         }
         if (details.hasWildcards) {
             recommendations.push('Replace SELECT * with specific column names');
         }
+        // Performance recommendations
         if (!details.hasLimit && details.estimatedResultSize > 1000) {
             recommendations.push('Add LIMIT clause to prevent large result sets');
         }
@@ -324,7 +433,11 @@ export class QueryComplexityAnalyzer {
         }
         return recommendations;
     }
+    /**
+     * Determine if query execution should be allowed
+     */
     shouldAllowExecution(sql, riskScore, complexityScore, estimatedCost, details) {
+        // Check against thresholds
         if (riskScore > this.config.maxRiskScore) {
             return false;
         }
@@ -337,6 +450,7 @@ export class QueryComplexityAnalyzer {
         if (details.estimatedResultSize > this.config.maxResultSetSize) {
             return false;
         }
+        // Check for blocking risk factors
         for (const factor of this.riskFactors) {
             if (factor.blocking && factor.pattern.test(sql)) {
                 return false;
@@ -344,19 +458,37 @@ export class QueryComplexityAnalyzer {
         }
         return true;
     }
+    /**
+     * Update configuration
+     */
     updateConfig(config) {
         this.config = { ...this.config, ...config };
     }
+    /**
+     * Add custom risk factor
+     */
     addRiskFactor(factor) {
         this.riskFactors.push(factor);
     }
+    /**
+     * Get current configuration
+     */
     getConfig() {
         return { ...this.config };
     }
 }
+// ==============================================
+// Factory Functions
+// ==============================================
+/**
+ * Create a query analyzer with default configuration
+ */
 export function createQueryAnalyzer(config) {
     return new QueryComplexityAnalyzer(config);
 }
+/**
+ * Create a strict security analyzer
+ */
 export function createSecurityAnalyzer() {
     return new QueryComplexityAnalyzer({
         maxRiskScore: 30,
@@ -367,9 +499,12 @@ export function createSecurityAnalyzer() {
         enablePerformanceAnalysis: false
     });
 }
+/**
+ * Create a performance-focused analyzer
+ */
 export function createPerformanceAnalyzer() {
     return new QueryComplexityAnalyzer({
-        maxRiskScore: 100,
+        maxRiskScore: 100, // Allow all from security perspective
         maxComplexityScore: 60,
         maxEstimatedCost: 500000,
         maxResultSetSize: 5000,
@@ -377,5 +512,11 @@ export function createPerformanceAnalyzer() {
         enablePerformanceAnalysis: true
     });
 }
+// ==============================================
+// Default Analyzer Instance
+// ==============================================
+/**
+ * Default query analyzer instance
+ */
 export const defaultQueryAnalyzer = createQueryAnalyzer();
 //# sourceMappingURL=query-analyzer.js.map