Writing Scanner Adapters

Relevant source files

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

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

Scanner Adapters are the core integration points for the Unified Security Scanner, allowing the system to orchestrate various security tools—such as TruffleHog, Semgrep, and CodeQL—under a single interface. These adapters reside in the packages/core/src/adapters/ directory and are responsible for executing specific security tools and normalizing their output into a unified format for the scanner's orchestrator.

Sources: CONTRIBUTING.md:12-19, README.md:21-25

Architecture and Interface

The system utilizes a multi-tool orchestration architecture where the ScanOrchestrator manages multiple adapters. Every adapter must implement the ScannerAdapter interface, ensuring a consistent contract for initialization and execution.

The ScannerAdapter Interface

An adapter is primarily responsible for taking a configuration object and returning a promise that resolves to an array of security findings.

export class NewScannerAdapter implements ScannerAdapter {
  async scan(config: ScanConfig): Promise<Finding[]> {
    // Implementation: Execute tool and parse results
  }
}

Sources: CONTRIBUTING.md:41-47, QUICK_START.md:152-160

Integration Flow

The diagram below illustrates how an adapter interacts with the core engine and external security tools during a scan cycle.

This flow ensures that the orchestrator remains agnostic of the specific tool implementation details, such as CLI flags or output formats (SARIF, JSON, etc.).
Sources: CONTRIBUTING.md:14-16, QUICK_START.md:152-160

Implementation Steps

To add a new scanner integration, developers must follow a standardized process to ensure the tool is correctly recognized by the core engine.

1. File Location and Structure

Adapters must be placed in packages/core/src/adapters/. The directory structure separates the core engine logic from the specific tool integrations.
Sources: CONTRIBUTING.md:14-16, CONTRIBUTING.md:37

2. Core Implementation Tasks

Developers are required to complete the following:

• Implement Interface: Use the ScannerAdapter class structure.
• Configuration: Add tool-specific options to the global configuration types.
• Execution Logic: Handle the spawning of external processes. Care must be taken to avoid security risks like shell injection by avoiding shell: true in process spawning.
• Data Normalization: Map tool-specific results to the project's standard Finding data model.

Sources: CONTRIBUTING.md:38-40, SECURITY_REVIEW.md:43-55

3. Handling Configuration

Adapters should respect the settings defined in the project's configuration files (e.g., .securityrc.json or configs/default.json).

Configuration Field	Purpose
tools.<toolName>.enabled	Boolean flag to toggle the adapter.
tools.<toolName>.exclude	Patterns to ignore during the tool's execution.
scan.target	The root directory or files to be processed by the tool.

Sources: configs/default.json:3-13, QUICK_START.md:310-330

Execution and Safety Guidelines

When writing adapters that wrap CLI tools, implementation must prioritize security to prevent vulnerabilities within the scanner itself.

Process Spawning Safety

Experience with the technical-debt and npm audit analyzers showed that using shell: true when spawning commands with user-controlled input (like targetDir) leads to CRITICAL shell injection vulnerabilities.

Vulnerable Pattern (Avoid):

const proc = spawn('tool', ['args'], { shell: true });

Secure Pattern (Required):

const proc = spawn('tool', ['args'], { 
  cwd: validateTargetDir(targetDir),
  shell: false 
});

Sources: SECURITY_REVIEW.md:43-65

Sequence of Operation

The following sequence diagram shows the interaction between the CLI, the Orchestrator, and a specific Adapter.

Testing Requirements

All new adapters must be accompanied by a comprehensive test suite to maintain the project's requirement of 90% code coverage.

• Unit Tests: Test the mapping logic and configuration handling.
• Integration Tests: Verify that the adapter correctly interacts with the external tool.
• False Positive Regression: Ensure the adapter does not introduce high rates of false positives (target is <5%).

Sources: CONTRIBUTING.md:40, CONTRIBUTING.md:85-88, README.md:12

Summary

Writing a Scanner Adapter involves implementing the ScannerAdapter interface, securely executing an external security tool, and normalizing findings into the project's unified format. By following the modular architecture in packages/core/src/adapters/, developers can extend the scanner's capabilities while benefiting from the core engine's false positive reduction and reporting features.