Local Developer Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Setting up the Unified Security Scanner locally allows developers to build, test, and contribute to an AI-powered multi-phase security analysis tool. The environment is designed for Node.js development, utilizing a monorepo structure managed by pnpm to coordinate the core scanning engine, CLI, and various tool adapters.
The setup process focuses on ensuring all prerequisites are met, dependencies are correctly linked, and the TypeScript source is compiled into executable JavaScript. This enables developers to run scans against local projects, develop new security rules, or integrate additional scanning adapters.
Sources: README.md:1-15, CONTRIBUTING.md:7-15, QUICK_START.md:15-30
Prerequisites
Before beginning the installation, the following software must be installed on the local machine:
| Requirement | Version | Purpose |
|---|---|---|
| Node.js | 18+ | Primary runtime for the scanner engine and CLI. |
| pnpm | 8+ | Fast, efficient package manager for monorepo dependency management. |
| Git | Any modern | Version control for cloning and contributing to the repository. |
| TruffleHog | Latest | Required for secret detection (external dependency). |
| Semgrep | Latest | Required for static analysis (external dependency). |
Sources: QUICK_START.md:32-50, CONTRIBUTING.md:10-14, package.json:35-37
Environment Setup Flow
The local setup follows a linear progression from cloning the repository to verifying the build.
This diagram illustrates the standard workflow for initializing a developer environment.
Sources: CONTRIBUTING.md:16-24, QUICK_START.md:54-75
Installation Steps
To build the project from source, execute the following commands in the project root:
# 1. Clone the repository
git clone https://github.com/GeeksikhSecurity/unified-security-scanner.git
cd unified-security-scanner
# 2. Install dependencies
pnpm install
# 3. Build the project
pnpm build
Sources: CONTRIBUTING.md:16-21, QUICK_START.md:58-68
Project Architecture
The repository is structured as a monorepo to separate concerns between the execution interface and the scanning logic.
| Directory | Component | Description |
|---|---|---|
packages/core/ | Scanner Engine | Contains the orchestrator, tool adapters (TruffleHog/Semgrep), and false-positive reducers. |
packages/cli/ | Command Line Interface | The user-facing tool that processes commands and outputs results. |
rules/ | Security Rules | YAML definitions for Semgrep and custom scanning patterns. |
configs/ | Default Configs | Base JSON configurations for tool behavior and exclusions. |
Sources: CONTRIBUTING.md:26-38, QUICK_START.md:70-75, configs/default.json:1-10
Build Configuration
The project uses TypeScript with an ESM (ECMAScript Modules) target. The configuration ensures strict type checking and proper source mapping for debugging.
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"outDir": "./dist",
"rootDir": "./src",
"strict": true
}
}
The build process transpiles files from the src/ directory into dist/ for execution.
Sources: tsconfig.json:2-10, package.json:7-14
Running and Testing
After building, developers should verify their setup by running the internal test suite and performing a self-scan.
Executing Tests
The project utilizes jest for unit and integration testing. A minimum of 90% code coverage is required for new contributions.
# Run all tests
pnpm test
# Run with coverage report
pnpm test:coverage
Sources: CONTRIBUTING.md:54-65, package.json:9-10
Initial Scan Verification
To verify the scanner is operational, run a basic scan on the local directory:
cd packages/cli
node dist/index.js scan ../..
Sources: QUICK_START.md:86-95
Dependency Flow Analysis
The following sequence diagram shows how the CLI interacts with the Core engine during a local development scan.
This diagram demonstrates the internal data flow from the initial command to the final filtered results.
Sources: CONTRIBUTING.md:27-33, QUICK_START.md:100-110, configs/default.json:1-25
Conclusion
A successful local setup requires Node.js 18+ and pnpm 8+. By building the project from source and verifying it with the provided test suite, developers ensure they are working with the latest security rules and orchestration logic. This foundation is necessary for contributing new adapters or refining the AI-enhanced false-positive reduction engine.
Sources: QUICK_START.md:435-450, CONTRIBUTING.md:88-95