Monorepo Structure

Relevant source files

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

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

The Unified Security Scanner is organized as a monorepo designed to house multiple interconnected packages, including the core scanning engine and the command-line interface (CLI). This structure facilitates shared development standards, unified dependency management via pnpm, and a modular architecture where the scanning logic is decoupled from the user interface.

The monorepo uses a multi-package layout under the packages/ directory, supported by root-level configuration for TypeScript, testing, and security rules. This approach allows the project to scale by adding new adapters or specialized scanners without disrupting the core orchestration logic.

Sources: CONTRIBUTING.md:14-25, README.md:166-177, QUICK_START.md:37-45

Core Directory Layout

The project follows a standardized monorepo structure where the primary functional logic is partitioned into distinct packages. Each package serves a specific role in the security analysis lifecycle.

Directory	Purpose	Key Contents
packages/core	The scanning engine and orchestrator	Adapters, analyzers, reporters, and FP reduction logic.
packages/cli	User interface and command execution	CLI command definitions and terminal output formatting.
rules/	Security rule definitions	YAML-based rules for Semgrep, React, and npm security.
configs/	System-wide defaults	Default JSON configurations for scanner behavior.
tests/	Global test suites	Basic integration and functionality tests.

Sources: CONTRIBUTING.md:14-25, README.md:166-177, configs/default.json

Visualizing the Project Hierarchy

The following diagram illustrates the relationship between the root configuration and the individual packages within the monorepo.

Package Architecture

packages/core (The Engine)

The core package is the primary component of the system. It handles the orchestration of various security tools and the processing of their results.

• Orchestrator: Coordinates the execution of different scanning tools.
• Adapters: Integrate third-party tools like TruffleHog and Semgrep.
• Analyzers: Custom scanning modules for technical debt and malicious packages.
• Reporters: Handles output generation in formats like SARIF, JSON, and HTML.
• FP Reducer: Logic for reducing false positives to below 5%.

Sources: CONTRIBUTING.md:14-25, README.md:166-177

packages/cli (The Interface)

The cli package provides the entry point for users. It utilizes the core engine to execute scans based on user-provided arguments and configurations.

• Commands: Definitions for the scan and test commands.
• Distribution: The compiled output is located in packages/cli/dist/index.js.

Sources: CONTRIBUTING.md:23-25, QUICK_START.md:39-45

Configuration and Tooling

The monorepo uses a unified tooling stack to ensure consistency across all packages.

Workspace Management

The project utilizes pnpm for workspace management. This allows for efficient dependency linking and synchronized builds across the monorepo.

• pnpm install: Installs dependencies for all packages.
• pnpm build: Triggers the TypeScript compiler (tsc) across the project.
• pnpm test: Executes the Jest test suite for all packages.

Sources: QUICK_START.md:37-45, package.json:7-14, CONTRIBUTING.md:28-34

Shared Configuration Files

Root-level configuration files define the behavior of the entire monorepo:

• tsconfig.json: Configures the TypeScript compiler with strict mode, ESNext modules, and an output directory of ./dist.
• package.json: Defines global scripts and common devDependencies like jest and typescript.
• configs/default.json: Contains default settings for tools (TruffleHog, Semgrep), scan exclusions (e.g., node_modules, dist), and performance settings (e.g., parallelWorkers).

Sources: tsconfig.json:1-16, package.json:1-29, configs/default.json:1-49

Build and Execution Flow

Development Standards

To maintain the monorepo structure, contributors must follow specific standards:

• Exports: The src/index.ts in the core package acts as the central export point for EnhancedSecurityScanner, MultiScanOrchestrator, and SARIFProcessor.
• Testing: Tests are required for all new features, with unit tests located in packages/core/tests/ and CLI tests in packages/cli/tests/.
• Strict Typing: The tsconfig.json enforces strict: true across the monorepo to ensure type safety.

Sources: src/index.ts:1-10, CONTRIBUTING.md:46-52, tsconfig.json:7

Summary

The monorepo structure of the Unified Security Scanner ensures a modular and scalable codebase. By separating the core engine logic into packages/core and the command-line interface into packages/cli, the project allows for independent evolution of the scanning capabilities and the user interface. Centralized configuration and workspace management through pnpm and tsconfig.json maintain high development standards across all modules.

Sources: CONTRIBUTING.md:14-25, README.md:166-177, package.json:1-14