CLI Interface (@unified-scanner/cli)

Relevant source files

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

• QUICK_START.md
• README.md
• CONTRIBUTING.md
• SECURITY_REVIEW.md
• configs/default.json
• package.json

The CLI Interface (@unified-scanner/cli) serves as the primary entry point for users to interact with the Unified Security Scanner. It provides a command-line wrapper around the core scanning engine, allowing developers to execute security audits, configure scan parameters, and generate reports in various formats directly from their terminal or CI/CD pipelines.

The CLI acts as an orchestrator that translates user-provided flags and configuration files into actionable instructions for the underlying scanning phases, which include traditional SAST, AI-enhanced validation, and targeted deep dives. It is designed for high performance, capable of processing up to 1,400 files per second while maintaining a low false positive rate.

Sources: README.md:1-20, QUICK_START.md:44-55

Core Command: scan

The primary functionality of the CLI is encapsulated in the scan command. This command triggers the multi-phase scanning process on a target directory.

Command Syntax and Arguments

The basic usage involves specifying the scan command followed by the target path. Users can modify the behavior using various flags for formatting, output locations, and severity thresholds.

# Basic usage
node dist/index.js scan <target_directory>

# Advanced usage with multi-phase analysis
enhanced-scanner scan --multi-phase --ai-validation --format sarif --output ./reports

Sources: QUICK_START.md:70-75, README.md:52-58

Scan Execution Flow

When a scan is initiated, the CLI coordinates between the user's local environment and the core scanning engine.

The CLI handles the transition between these phases, ensuring that results from initial SAST filters (like Semgrep and CodeQL) are passed to AI-enhanced validation layers.
Sources: README.md:23-30, QUICK_START.md:80-95

Configuration Management

The CLI utilizes a hierarchical configuration system. It looks for settings in the following order of precedence:

1. Explicit flags passed via the --config flag.
2. .securityrc.json in the current working directory.
3. .securityrc.json in the project root.
4. Internal default configuration.

Sources: QUICK_START.md:370-385

Configuration Options

The following table outlines key configuration elements handled by the CLI:

Option	Type	Description	Default
target	string	The directory or file to scan	.
exclude	array	Globs to ignore (e.g., node_modules)	["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**"]
format	array	Output formats (terminal, sarif, json, html)	["terminal"]
failOn	array	Severities that trigger a non-zero exit code	["CRITICAL", "HIGH"]
parallelWorkers	number	Number of concurrent worker threads	4

Sources: configs/default.json:20-56, QUICK_START.md:330-345

Integration and Automation

The CLI is built to support seamless CI/CD integration, particularly through its support for the SARIF (Static Analysis Results Interchange Format) standard. This allows the CLI to provide inline code annotations within GitHub Pull Requests.

CI/CD Workflow Example

In a CI environment, the CLI is typically invoked with specific failure criteria to act as a security gate.

Exit Code Strategy

The CLI communicates scan outcomes via standard exit codes to facilitate automation:

• Code 0: Scan passed (no issues found above the --fail-on threshold).
• Code 1: Security issues found matching the failure criteria.
• Code 2: Internal scanner error or misconfiguration.

Sources: QUICK_START.md:195-210, SECURITY_REVIEW.md:45-50

Internal Architecture

Within the project structure, the CLI is located in packages/cli/. It follows a command-based pattern for extensibility.

Directory Structure

• packages/cli/src/commands/: Implementation of specific CLI commands like scan.
• packages/cli/tests/: Unit and integration tests for CLI logic.

Sources: CONTRIBUTING.md:17-25

Security Considerations for CLI Usage

Because the CLI executes shell commands for certain tool integrations (e.g., npm outdated or npm audit), it must sanitize user-controlled input. A security review identified potential CWE-78 (OS Command Injection) risks when shell: true is used with user-provided directory paths, leading to recommendations for path normalization and strict input validation within the CLI command logic.

Sources: SECURITY_REVIEW.md:25-60

Summary

The @unified-scanner/cli is the operational face of the Unified Security Scanner. It provides a robust set of tools for both local development and enterprise-grade CI/CD pipelines, enabling multi-phase security analysis with a focus on speed and accuracy. By managing configurations, orchestrating complex scanning phases, and outputting standardized SARIF reports, it bridges the gap between raw security analysis and developer workflow.