Home
Relevant source files
The following files were used as context for generating this wiki page:
The Unified Security Scanner (v2.0) is an enterprise-grade, AI-powered security analysis tool designed to identify vulnerabilities, hardcoded secrets, and supply chain threats with high precision. It employs a multi-phase scanning strategy to orchestrate traditional Static Application Security Testing (SAST) tools alongside LLM-based validation to achieve a false positive rate of less than 5%.
Sources: README.md:1-15, package.json:2-5
Core Architecture and Scanning Strategy
The system is built on a modular architecture consisting of a core scanning engine, various tool adapters, and a command-line interface (CLI). The execution logic follows a 3-phase strategy to filter noise and validate critical findings.
3-Phase Scanning Workflow
- Phase 1: Traditional SAST: Utilizes tools like Semgrep and CodeQL with permissive queries to capture a broad range of potential issues.
- Phase 2: AI-Enhanced Analysis: Employs multiple iterations (typically 3) of AI validation to address non-determinism and confirm findings.
- Phase 3: Targeted Deep Dive: Conducts function-level and multi-file analysis for critical vulnerabilities such as SQL injection or business logic flaws.
Sources: README.md:17-28, README.md:73-86
The diagram illustrates the sequential filtering process from broad SAST detection to deep AI-validated analysis.
Sources: README.md:73-102, CONTRIBUTING.md:12-23
System Components
The project is organized into distinct packages and modules to separate orchestration from implementation.
| Component | Path | Description |
|---|---|---|
| Core Engine | packages/core/ | Handles orchestrator logic, adapters, and reporting. |
| CLI | packages/cli/ | Manages command-line interactions and user input. |
| Orchestrator | src/orchestrator/ | Coordinates multi-tool execution and data flow. |
| Adapters | src/adapters/ | Integration wrappers for TruffleHog, Semgrep, and CodeQL. |
| FP Reducer | src/fp-reducer/ | Logic for false positive reduction and context filtering. |
Sources: CONTRIBUTING.md:12-23, src/index.ts:6-11
Key Features and Capabilities
Detection Categories
The scanner identifies several critical classes of vulnerabilities (CWEs) across multiple languages including JavaScript, TypeScript, Python, and Java.
- Secrets Detection: Identifies hardcoded API keys and credentials.
- Injection Flaws: Detects SQLi, Command Injection, and XSS.
- Supply Chain: Monitors for typosquatting and dependency confusion.
- Malicious Code: Flags data exfiltration and obfuscated backdoors.
Sources: README.md:30-41, QUICK_START.md:104-118
Performance Metrics
The v2.0 engine is optimized for speed and parallel processing.
| Metric | Performance Value |
|---|---|
| Scan Speed | ~1,400 files per second |
| False Positive Rate | < 5% |
| Concurrency | Configurable via parallelWorkers |
Sources: README.md:310-322, configs/default.json:44-48
Configuration and Integration
The scanner is configured via a .securityrc.json file, which defines tool behavior, exclusions, and failure conditions.
Standard Configuration Options
{
"scan": {
"target": ".",
"exclude": ["**/node_modules/**", "**/dist/**"],
"includeTests": false
},
"severity": {
"failOn": ["CRITICAL", "HIGH"]
}
}
Sources: configs/default.json:22-30, QUICK_START.md:214-250
CI/CD Pipeline
The scanner supports SARIF output for native integration with GitHub Security tabs, allowing it to block Pull Requests based on defined severity thresholds.
Sequence of events during an automated CI/CD security gate.
Sources: README.md:173-195, QUICK_START.md:144-165
Development and Reliability
To maintain high accuracy, the project includes specialized modules for handling transient failures and non-deterministic results.
- Flaky Test Manager: Detects and quarantines unstable security tests using inter-run thresholds.
- Multi-Scan Orchestrator: Runs multiple iterations of AI analysis to ensure consistency in findings.
- SARIF Processor: Merges results from disparate tools into a unified standard format.
Sources: src/index.ts:6-10, README.md:214-230, tests/basic.test.ts:13-16
Installation and Setup
Developers can build the project from source using pnpm:
pnpm installpnpm buildnode packages/cli/dist/index.js scan <target>
Sources: QUICK_START.md:38-55, CONTRIBUTING.md:7-10
The Unified Security Scanner provides a robust framework for automating complex security audits, bridging the gap between high-speed static analysis and high-accuracy manual or AI reviews.