Architecture Overview

Relevant source files

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

• src/index.ts
• README.md
• QUICK_START.md
• CONTRIBUTING.md
• configs/default.json
• SECURITY_REVIEW.md

The Unified Security Scanner (v2.0) is an enterprise-grade, AI-powered security analysis platform designed to orchestrate multiple scanning tools into a cohesive workflow. The system architecture prioritizes a multi-phase scanning strategy to achieve a low false positive rate (under 5%) by combining traditional Static Application Security Testing (SAST) with AI-enhanced validation and targeted deep dives.

The project is structured as a monorepo containing a core scanning engine and a command-line interface (CLI), allowing for modular integration of third-party security tools like Semgrep, CodeQL, and TruffleHog.

Sources: README.md:1-15, src/index.ts:1-12, CONTRIBUTING.md:13-25

Core System Components

The architecture is divided into two primary packages that separate the scanning logic from the user interface.

Package Structure

• packages/core: The scanning engine containing the EnhancedSecurityScanner and MultiScanOrchestrator. It manages tool adapters, analyzers, and report generation.
• packages/cli: The user interface that handles command parsing, configuration loading, and terminal output formatting.

Sources: CONTRIBUTING.md:15-25, QUICK_START.md:43-52

Key Architectural Classes

The system's functionality is exported via the main index and relies on specialized managers for different aspects of the scan lifecycle:

Class	Responsibility
EnhancedSecurityScanner	Main entry point for the scanning engine.
MultiScanOrchestrator	Manages the 3-phase scanning workflow and tool execution.
SARIFProcessor	Handles results merging, validation, and conversion to standard formats.
FlakyTestManager	Detects and manages non-deterministic results across scan iterations.

Sources: src/index.ts:6-10, README.md:330-345

3-Phase Scanning Strategy

The scanner utilizes a tiered execution model to filter noise and increase finding accuracy.

The diagram shows the progression from high-noise traditional scanning to high-fidelity AI-validated results.
Sources: README.md:20-35, README.md:95-120

Phase Details

1. Traditional SAST: Uses Semgrep and CodeQL with permissive/high-noise queries to ensure maximum coverage of potential issues.
2. AI-Enhanced Analysis: Executes 3 iterations to embrace AI non-determinism, comparing implementation against developer intent and documentation.
3. Deep Dive: Performs function-level and multi-file analysis to track vulnerability flows across complex business logic.

Sources: README.md:22-35, README.md:143-160

Data Flow and Orchestration

The MultiScanOrchestrator coordinates the lifecycle of a scan from configuration to final reporting.

The sequence diagram illustrates the synchronous flow of data from raw tool output to AI-validated security findings.
Sources: README.md:100-115, CONTRIBUTING.md:30-45

Scanner Adapters

The system uses an adapter pattern to integrate external tools. Every adapter must implement the ScannerAdapter interface, which provides a uniform way to retrieve Finding[] objects.

export class NewScannerAdapter implements ScannerAdapter {
  async scan(config: ScanConfig): Promise<Finding[]> {
    // Logic to call external tool (e.g., TruffleHog)
    // and map results to standard Finding structure
  }
}

Sources: CONTRIBUTING.md:35-43

Configuration and Extensibility

The scanner behavior is governed by a hierarchical configuration system, typically defined in .securityrc.json.

Configuration Schema

Section	Description	Key Options
tools	Individual tool toggles and exclusions.	truffleHog.enabled, semgrep.rules
scan	Target path and file filtering rules.	exclude, includeTests, maxFileSize
aiAnalysis	Configuration for LLM providers.	provider, model, apiKey
severity	Failure criteria for CI/CD gates.	failOn, threshold

Sources: configs/default.json:2-60, README.md:135-180

Security Rule Definitions

Rules are defined using YAML (for Semgrep) or custom TypeScript logic for more complex patterns. Rules are categorized by CWE (Common Weakness Enumeration) classes such as CWE-78 (OS Command Injection) and CWE-79 (XSS).

Sources: README.md:183-205, SECURITY_REVIEW.md:40-60

Performance Optimization

To achieve a scan speed of approximately 1,400 files per second, the architecture incorporates several performance-oriented features:

• Parallel Execution: Multi-worker scanning with configurable concurrency (defaulting to 4 workers).
• Incremental Scanning: Utilizes git diff to scan only changed files in CI/CD environments.
• Caching: Caches results for unchanged files to bypass redundant analysis in subsequent runs.

Sources: configs/default.json:54-58, CHANGELOG.md:35-42, README.md:300-310

Conclusion

The Unified Security Scanner architecture shifts from simple tool execution to a sophisticated orchestration layer. By centering the design around the MultiScanOrchestrator and a 3-phase verification cycle, the system effectively bridges the gap between high-coverage SAST tools and the high-accuracy requirements of enterprise security teams.

Sources: README.md:435-445, QUICK_START.md:650-660