Scan Result Aggregation
Relevant source files
The following files were used as context for generating this wiki page:
Scan Result Aggregation is the core process of collecting, normalizing, and deduplicating security findings from multiple heterogeneous scanning tools. The system utilizes a multi-phase strategy to orchestrate traditional Static Application Security Testing (SAST) tools, AI-enhanced validation, and targeted deep dives to produce a unified security posture with high accuracy and low false-positive rates.
This system is designed to handle outputs from various adapters, including secrets detection (TruffleHog), pattern-based SAST (Semgrep), and custom analyzers for technical debt or malicious packages. The final aggregated results are processed through a False Positive (FP) reducer and exported into standardized formats such as SARIF, JSON, and HTML.
Sources: README.md:12-28, CONTRIBUTING.md:15-25, src/index.ts
Architecture and Data Flow
The aggregation logic resides primarily within the MultiScanOrchestrator and SARIFProcessor. The workflow follows a 3-phase strategy to refine data from broad discovery to validated findings.
The 3-Phase Aggregation Strategy
- Phase 1: Traditional SAST: Initial collection of potential issues using permissive queries from tools like Semgrep and CodeQL.
- Phase 2: AI-Enhanced Analysis: Aggregated results from Phase 1 are subjected to multi-scan iterations (3 iterations) to embrace non-determinism and validate findings via LLMs.
- Phase 3: Targeted Deep Dive: Focused analysis on critical findings, such as complex multi-file vulnerability flows or business logic detection.
Sources: README.md:32-46, src/index.ts
Aggregation Pipeline
The following diagram illustrates how raw findings from different tools flow through the system to become an aggregated report.
The diagram shows the transition from diverse tool outputs to a centralized orchestration layer, followed by refinement and multi-format reporting.
Sources: CONTRIBUTING.md:15-25, README.md:162-178
Key Components
MultiScanOrchestrator
The MultiScanOrchestrator is responsible for coordinating the execution of various ScannerAdapter implementations. It manages the lifecycle of a scan, ensuring that all findings are collected into a unified collection before passing them to the reporting layer.
Sources: CONTRIBUTING.md:15-20, src/index.ts
SARIFProcessor
The SARIFProcessor handles the normalization of findings into the Static Analysis Results Interchange Format (SARIF). This allows the scanner to integrate with enterprise security dashboards like the GitHub Security tab.
Sources: README.md:195-215, src/index.ts
False Positive Reduction (FP-Reducer)
A specialized module that applies context-aware filtering and pattern matching (defined in rule-engine.ts) to the aggregated results. It identifies and suppresses findings such as lock file integrity hashes or known framework security controls.
Sources: CONTRIBUTING.md:23-25, README.md:61-66
Configuration Options
Aggregation behavior is controlled through the severity and output sections of the configuration files.
| Configuration Key | Type | Default | Description |
|---|---|---|---|
severity.threshold | String | "LOW" | Minimum severity level to include in the aggregated report. |
severity.failOn | Array | ["CRITICAL", "HIGH"] | Severity levels that trigger a non-zero exit code. |
output.formats | Array | ["terminal"] | Target formats for result aggregation (sarif, json, html). |
performance.parallelWorkers | Number | 4 | Number of concurrent scanner tasks during collection. |
Sources: configs/default.json
Aggregation Logic and Normalization
During aggregation, findings are mapped to a standard internal structure. This ensures that a "Critical" finding from a secrets scanner is treated with the same priority as a "Critical" finding from a SAST tool.
Severity Mapping
The system categorizes all aggregated findings into four standard levels:
- 🔴 CRITICAL: Exposed secrets or immediate RCE (e.g., Shell Injection).
- 🟠 HIGH: SQL Injection, XSS, or EOL dependencies.
- 🟡 MEDIUM: Outdated packages or missing security headers.
- ⚪ LOW: Code quality issues or minor optimizations.
Sources: QUICK_START.md:105-125, SECURITY_REVIEW.md:15-25
Deduplication Process
The system identifies overlapping findings by comparing the file path, line number, and vulnerability type (CWE). This prevents the same issue from being reported multiple times when detected by different engines (e.g., both Semgrep and a custom analyzer identifying the same vulnerability).
Sources: QUICK_START.md:270-280, CHANGELOG.md:40-45
Aggregation Sequence Diagram
This diagram outlines the synchronous request for scan data followed by the asynchronous collection and synchronous processing of normalized results.
Sources: QUICK_START.md:270-280, CONTRIBUTING.md:15-25
Result Reporting
Aggregated results are summarized in a terminal dashboard and written to the specified output directory. The summary includes statistics on the total number of files scanned, lines of code (LOC), and the count of findings by severity.
┌─────────────────────────────────────────────────────────────┐
│ Unified Security Scanner v1.0 │
│ Scanned: 34 files (2,150 LOC) in 5.2s │
└─────────────────────────────────────────────────────────────┘
🔴 CRITICAL: 3 │ 🟠 HIGH: 8 │ 🟡 MEDIUM: 9 │ ⚪ LOW: 3
Sources: QUICK_START.md:95-103, README.md:118-125
Conclusion
Scan Result Aggregation is the mechanism that transforms raw, noisy data from multiple security tools into a refined, actionable security report. By employing a 3-phase strategy—comprising broad SAST discovery, AI-driven validation, and deduplication—the scanner achieves a false-positive rate of less than 5%. This aggregation is essential for providing a single source of truth for the security posture of the project.
Sources: README.md:9-15, SECURITY_REVIEW.md:10-15