3-Phase Scanning Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The 3-Phase Scanning Strategy is the core architectural approach of the Enhanced Security Scanner v2.0. It is designed to provide enterprise-grade security analysis by combining traditional Static Application Security Testing (SAST) with AI-enhanced validation and targeted deep dives. This methodology aims to achieve an industry-leading false positive rate of less than 5% while maintaining high detection coverage across 9 critical CWE classes.
This strategy is orchestrated by the MultiScanOrchestrator and the EnhancedSecurityScanner engine, which coordinate multiple tool integrations including Semgrep, CodeQL, and various AI providers. By layering analysis techniques, the system moves from broad, high-noise discovery to precise, validated findings.
Sources: README.md:10-15, README.md:21-25, src/index.ts:6-7
Strategy Overview and Workflow
The scanning process is divided into three distinct chronological phases. Each phase serves a specific purpose in the funnel of vulnerability detection, ranging from initial broad filtering to final context-aware verification.
Phase 1: Traditional SAST Analysis
In this initial phase, the scanner utilizes traditional SAST tools like Semgrep and CodeQL. The strategy employs "permissive" and "high-noise" queries to ensure maximum reach, even at the cost of initial accuracy. This creates a broad base of potential issues for further refinement.
Phase 2: AI-Enhanced Analysis
Phase 2 introduces a multi-scan iteration strategy (typically 3 iterations) to address the non-deterministic nature of AI. During this phase, the system validates the findings from Phase 1 using AI models (OpenAI, Anthropic, or AWS Q Developer) to filter out false positives and analyze intent.
Phase 3: Targeted Deep Dives
The final phase performs intensive analysis on the most critical findings. This includes function-level analysis, multi-file data flow tracking, and business logic detection to confirm the exploitability of identified vulnerabilities.
Sources: README.md:26-30, README.md:86-105
High-Level Scanning Flow
The following diagram illustrates the data flow through the three phases:
The diagram shows how potential issues are funneled through increasingly rigorous layers of analysis.
Sources: README.md:26-31, README.md:86-105
Phase Details and Components
Phase Execution Logic
The strategy is implemented through the MultiScanOrchestrator, which manages the transition between phases and the merging of results.
| Phase | Primary Tools | Objective | Key Configuration |
|---|---|---|---|
| Phase 1 | Semgrep, CodeQL | Discovery | permissive: true, highNoise: true |
| Phase 2 | LLMs (OpenAI/Anthropic) | False Positive Reduction | iterations: 3, aiProvider: "openai" |
| Phase 3 | Custom Analyzers | Exploitability Confirmation | functionLevel: true, intentAnalysis: true |
Sources: README.md:115-135, CONTRIBUTING.md:15-25
AI Validation Prompting
During Phase 2, the orchestrator uses specific validation prompts to evaluate the potential findings from Phase 1. These prompts require the AI to determine if a finding is a "True Positive," calculate an exploitability score (0-1), and suggest remediation steps.
const validationPrompt = `
Analyze this security finding:
FINDING:
- Type: ${finding.category}
- Code: ${finding.snippet}
QUESTIONS:
1. Is this a true positive or false positive?
2. What is the exploitability (0-1 scale)?
Respond in JSON format.
`;
Sources: README.md:195-212
Configuration and Orchestration
The behavior of the 3-Phase strategy is defined in the .securityrc.json or configs/default.json file. This configuration controls which tools are active in each phase and sets the thresholds for failure.
Phase Configuration Example
{
"phases": {
"traditionalSAST": {
"enabled": true,
"semgrep": { "permissive": true }
},
"aiEnhanced": {
"enabled": true,
"iterations": 3,
"aiProvider": "openai"
},
"deepDive": {
"enabled": true,
"multiFileAnalysis": true
}
}
}
Sources: README.md:115-130, configs/default.json:1-10
Execution Workflow (Sequence)
The following sequence diagram details how the orchestrator interacts with the different scanning layers.
The sequence demonstrates the iterative nature of Phase 2 and the focused execution of Phase 3.
Sources: README.md:86-105, CONTRIBUTING.md:15-22
Effectiveness and False Positive Management
The primary goal of the 3-Phase strategy is the reduction of false positives (FP). By using Phase 2 to filter Phase 1, the system achieves a reported FP rate of <5%.
- Context-Aware Filtering: Identifies framework-specific security controls (e.g., sanitization with DOMPurify) to dismiss incorrect flags.
- Intent Analysis: Compares developer comments against implementation logic to find discrepancies.
- Historical Pattern Learning: Uses ML-enhanced classification to avoid repeating past mistakes.
Sources: README.md:44-50, README.md:213-220, SECURITY_REVIEW.md:190-210
Conclusion
The 3-Phase Scanning Strategy represents a shift from simple pattern matching to multi-layered, context-aware security intelligence. By orchestrating SAST, AI, and Deep Dive analysis, the system provides a balance between the speed of traditional tools and the accuracy of manual security reviews, making it suitable for high-velocity CI/CD environments.
Sources: README.md:20-25, QUICK_START.md:320-330