Core Engine (@unified-scanner/core)
Relevant source files
The following files were used as context for generating this wiki page:
The Core Engine is the central processing unit of the Unified Security Scanner. It is responsible for orchestrating multiple security tools, performing AI-enhanced validation, and reducing false positives to provide high-accuracy security insights. Built on Node.js, the engine supports multi-language analysis and integrates traditional Static Application Security Testing (SAST) with modern machine learning techniques.
The engine operates as a multi-package monorepo component, primarily housed in packages/core/. It serves as the backbone for the CLI and other integrations, handling the complex logic of scanning 1,400+ files per second while maintaining a false positive rate of less than 5%.
Sources: README.md:1-20, CONTRIBUTING.md:15-25, package.json:1-15
Architecture and Components
The architecture is divided into specialized modules that handle different stages of the security lifecycle, from raw data collection to refined reporting.
Module Breakdown
- Orchestrator: Coordinates the execution flow between various adapters and analyzers.
- Adapters: Provide interfaces for external tools like TruffleHog (secret detection) and Semgrep (pattern matching).
- Analyzers: Implement custom logic for specific threats such as malicious packages, technical debt, and supply chain attacks.
- False Positive (FP) Reducer: Uses context-aware filtering and ML-enhanced classification to remove noise.
- Reporters: Formats the findings into standardized outputs like SARIF, JSON, and HTML.
Sources: CONTRIBUTING.md:15-25, README.md:100-115
Core System Flow
The following diagram illustrates how the Core Engine processes a target directory through its internal modules.
The flow begins with the Orchestrator receiving a target path, passing it through three distinct scanning phases, and finally refining results through the FP Reducer.
Sources: README.md:25-45, CONTRIBUTING.md:15-25
Multi-Phase Scanning Strategy
The Core Engine employs a 3-phase strategy to balance speed and depth, as defined in the MultiScanOrchestrator.
Phase 1: Traditional SAST
This phase uses high-noise, permissive queries via tools like Semgrep and CodeQL to catch the widest possible net of potential vulnerabilities. It focuses on broad pattern matching across the codebase.
Phase 2: AI-Enhanced Analysis
To address the non-determinism of AI, the engine runs up to 3 iterations of analysis. It uses LLM integrations (OpenAI, Anthropic) to validate Phase 1 findings and perform intent analysis—comparing developer comments against actual implementation logic.
Phase 3: Targeted Deep Dives
The final phase performs multi-file flow analysis on high-confidence findings. This includes specific checks for business logic vulnerabilities and complex injection chains that require cross-file context.
Sources: README.md:25-45, README.md:140-160, src/index.ts:1-10
| Phase | Tooling/Method | Primary Goal |
|---|---|---|
| Phase 1 | Semgrep, CodeQL | Maximum coverage, high recall |
| Phase 2 | OpenAI, Anthropic | Validation, intent analysis |
| Phase 3 | Custom Analyzers | Exploitability verification |
Sources: README.md:25-45, configs/default.json:1-15
Detection Capabilities and Rules
The engine is pre-configured with rules targeting 9 critical CWE classes. These are defined in YAML formats and processed by the EnhancedSecurityScanner.
Key Security Rule Categories
- Injection: SQL Injection, Command Injection, and XSS.
- Secrets: Detection of hardcoded API keys, tokens, and database credentials.
- Supply Chain: Identifying typosquatting and dependency confusion.
- Technical Debt: Tracking EOL packages and outdated dependencies with upgrade paths.
Sources: README.md:120-135, rules/react/hooks.yml, rules/npm/security.yml
Scanning Logic Sequence
The sequence below demonstrates the interaction between the Orchestrator and the Adapter interfaces during a typical scan.
This sequence highlights the iterative validation process used to achieve the <5% false positive rate.
Sources: README.md:145-155, CONTRIBUTING.md:35-45, QUICK_START.md:350-365
Configuration and Performance
The engine behavior is controlled via .securityrc.json or a default internal configuration.
Performance Benchmarks
- Scan Speed: 1,400 files/second.
- Parallelism: Supports configurable workers (default 4, up to 16).
- Optimization: Uses incremental scanning based on Git diffs and result caching.
Sources: README.md:230-245, configs/default.json:35-50
Configuration Data Model
| Field | Type | Description | Default |
|---|---|---|---|
scan.target | String | Root directory for the security scan. | . |
scan.exclude | String[] | Glob patterns for files/directories to skip. | [node_modules, dist, .git] |
severity.failOn | String[] | Severities that trigger a non-zero exit code. | [CRITICAL, HIGH] |
performance.cache | Boolean | Whether to cache results for unchanged files. | true |
Sources: configs/default.json:1-50, README.md:70-95
Technical Debt and Reliability
The Core Engine includes a FlakyTestManager to handle instability in security tool execution, such as network timeouts or resource constraints during deep analysis.
Flaky Test Management Logic
The system monitors failure rates across builds. If a test fails more than 10% within a single run or 20% across multiple runs, it is moved to a quarantine state for up to 30 days to prevent CI/CD disruption.
Sources: README.md:195-215, src/index.ts:9, tests/basic.test.ts:10-15
Identified Architectural Risks
During security reviews, certain engine components were flagged for potential shell injection when executing external commands like npm audit.
// VULNERABLE PATTERN identified in core/analyzers/technical-debt.ts
const proc = spawn('npm', ['audit', '--json'], {
cwd: targetDir,
shell: true, // RISK: Enables shell interpretation of user input
});
Remediation involves setting shell: false and validating the targetDir via path normalization.
Sources: SECURITY_REVIEW.md:25-50, SECURITY_REVIEW.md:65-80
The Core Engine (@unified-scanner/core) represents a high-performance, modular approach to security scanning, prioritizing accuracy through its unique 3-phase validation pipeline and robust false-positive reduction logic.
Sources: README.md:1-10, CONTRIBUTING.md:15-20