Security Rule Engine

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• QUICK_START.md
• CONTRIBUTING.md
• rules/react/hooks.yml
• rules/npm/security.yml
• configs/default.json
• packages/core/src/enhanced-scanner.ts (referenced via project structure in README)

The Security Rule Engine is the core intelligence component of the Enhanced Security Scanner v2.0. It orchestrates a multi-phase analysis strategy that combines traditional Static Application Security Testing (SAST) with AI-enhanced validation to identify vulnerabilities, secrets, and malicious code with a reported false positive rate of less than 5%. Sources: README.md:1-20, QUICK_START.md:52-65

The engine operates by coordinating multiple specialized tools, including Semgrep and CodeQL, alongside custom scanners and AI providers like OpenAI and Anthropic. It processes codebases across multiple languages—including JavaScript, TypeScript, Python, Java, and Go—using a layered approach to ensure comprehensive detection of 9 critical CWE classes. Sources: README.md:25-45, CONTRIBUTING.md:20-35

3-Phase Scanning Strategy

The engine executes scans in three distinct phases to balance speed, depth, and accuracy.

The diagram shows the 3-phase progression from broad high-noise filtering to targeted AI-validated deep dives. Sources: README.md:25-30, README.md:95-110

Phase 1: Traditional SAST

The engine uses Semgrep and CodeQL as primary filters. It runs permissive queries and high-noise configurations to ensure no potential vulnerabilities are missed during the initial pass. Sources: README.md:27, README.md:126-137

Phase 2: AI-Enhanced Analysis

To address non-determinism, the engine employs a "Multi-Scan Strategy" consisting of three iterations. It integrates with LLM providers (OpenAI, Anthropic, AWS Q) to validate the findings from Phase 1. Sources: README.md:32-34, README.md:210-215

Phase 3: Targeted Deep Dives

The final phase performs multi-file vulnerability flow analysis and intent analysis, comparing developer comments against actual implementation to detect complex business logic flaws. Sources: README.md:30, README.md:139-145

Rule Definitions and Schema

Rules are defined primarily in YAML format (leveraging Semgrep syntax) or as custom TypeScript modules. They are categorized by technology stack and vulnerability type. Sources: CONTRIBUTING.md:38-45, rules/react/hooks.yml:1-5

Rule Structure Example

Field	Description	Example
id	Unique identifier for the rule	react-hardcoded-api-key-in-hook
patterns	Logic or regex used to match code	pattern-regex: .*(API_KEY)...
severity	Impact level (CRITICAL, HIGH, etc.)	ERROR
metadata	Mapping to standards (CWE, OWASP)	cwe: CWE-798

Sources: rules/react/hooks.yml:2-19, rules/npm/security.yml:3-15

Custom Rule Implementation

Developers can extend the engine by implementing the SecurityRule interface in TypeScript.

export const MY_CUSTOM_RULE: SecurityRule = {
  id: 'my-custom-vulnerability',
  severity: 'HIGH',
  languages: ['javascript', 'typescript'],
  patterns: [
    /dangerous_function\s*\(/,
    /unsafe_pattern\s*=/
  ]
};

Sources: README.md:365-375, CONTRIBUTING.md:28-35

Detection Capabilities

The engine is pre-configured to detect critical vulnerabilities across various languages and frameworks.

React and Frontend Rules

The engine includes specific rules for React hooks and the Context API to prevent data leaks and XSS.

• Hardcoded Credentials: Detects secrets within createContext or hooks.
• Unsafe HTML: Flags dangerouslySetInnerHTML usage without DOMPurify sanitization.
• Sensitive Storage: Warns against storing JWTs or passwords in localStorage.

Sources: rules/react/hooks.yml:1-60

Supply Chain and npm Security

The engine analyzes package.json and install scripts to detect malicious activity.

• Typosquatting: Identifies suspicious packages using Levenshtein distance (e.g., jest vs next).
• Malicious Scripts: Detects network requests (curl/wget) in postinstall scripts.
• Data Exfiltration: Flags access to npm_ environment variables in scripts.

Sources: rules/npm/security.yml:1-40, README.md:40-45, CHANGELOG.md:16-18

False Positive Reduction (FPR)

A core feature of the engine is its advanced filtering logic, which achieves a <5% false positive rate through context-aware analysis. Sources: README.md:47-52, CHANGELOG.md:14-15

The sequence diagram illustrates the interaction between the reduction logic and external validators. Sources: README.md:220-230, CONTRIBUTING.md:47-52

Reduction Methods

1. Framework Awareness: Automatically ignores patterns if a known security control (like DOMPurify) is detected in the same context. Sources: README.md:48, rules/react/hooks.yml:45-50
2. Exclusion Patterns: Configurable via .securityrc.json to ignore test fixtures, build artifacts, or specific files. Sources: configs/default.json:20-35, QUICK_START.md:215-230
3. LLM Validation: Uses AI to assess exploitability and impact on a 0-1 scale. Sources: README.md:210-225

Configuration

The engine's behavior is controlled via a central configuration file.

Section	Key Options	Purpose
phases	traditionalSAST, aiEnhanced, deepDive	Enable/disable specific scan stages.
scan	target, exclude, includeTests	Define the filesystem scope of the engine.
severity	threshold, failOn	Determine which findings trigger build failures.
performance	parallelWorkers, cacheEnabled	Manage resource usage (default 4 workers).

Sources: configs/default.json:1-60, README.md:150-195

Conclusion

The Security Rule Engine transforms raw code analysis into actionable security intelligence. By layering traditional pattern matching with AI-driven intent analysis and a robust false-positive reduction system, it provides a high-fidelity scanning environment suitable for both local development and enterprise CI/CD pipelines. Sources: README.md:5-15, QUICK_START.md:435-450