Configuration Guide (.securityrc.json)
Relevant source files
The following files were used as context for generating this wiki page:
The .securityrc.json file serves as the primary configuration mechanism for the Unified Security Scanner, allowing developers to customize scan behavior, tool integrations, and false positive reduction strategies. It enables consistent security enforcement across different environments, from local development to enterprise CI/CD pipelines.
This configuration file defines the orchestration of multiple security tools—such as TruffleHog for secrets and Semgrep for SAST—while providing fine-grained control over file exclusions, severity thresholds, and AI-enhanced validation phases.
Sources: configs/default.json, QUICK_START.md:374-378, README.md:104-108
Core Configuration Structure
The configuration is organized into logical sections that govern different aspects of the scanning engine. The scanner follows a specific lookup order for configuration: the --config flag, followed by .securityrc.json in the current directory or project root, and finally the built-in defaults.
The diagram shows the hierarchical precedence of configuration sources used to initialize the scanner engine.
Sources: QUICK_START.md:435-440, configs/default.json
Global Scan Settings
These settings define the boundaries of the scan, including target directories and file-level constraints.
| Option | Type | Default | Description |
|---|---|---|---|
target | string | . | The root directory to begin the security scan. |
exclude | array | ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/coverage/**"] | Glob patterns of directories or files to ignore globally. |
includeTests | boolean | false | Whether to include test files in the security analysis. |
maxFileSize | number | 10485760 | Maximum file size in bytes (default 10MB) to process. |
maxDepth | number | 50 | Maximum directory recursion depth. |
Sources: configs/default.json:18-32, README.md:144-149
Tool Orchestration
The scanner operates as an orchestrator for multiple specialized security tools. Each tool can be toggled and configured individually within the tools or phases sections.
Tool Control (v1.0)
In the standard configuration, individual adapters are enabled or disabled.
- TruffleHog: Used for detecting hardcoded secrets and credentials. It supports specific exclusions for test fixtures or examples.
- Semgrep: Used for static analysis (SAST). Configuration allows for the definition of specific rule sets.
- Custom Scanners: Allows for the integration of internal modules or proprietary scanning logic.
Sources: configs/default.json:3-16, QUICK_START.md:380-388
Multi-Phase Strategy (v2.0)
Enhanced versions of the scanner utilize a 3-phase strategy defined in the configuration.
Sources: README.md:110-130
False Positive Management
One of the most critical aspects of the .securityrc.json is the falsePositives section, designed to achieve a <5% false positive rate through context-aware filtering.
Suppression Logic
The configuration allows for pattern-based suppression where specific files or code fragments known to be safe (such as test credentials or mock data) can be ignored.
"falsePositives": {
"excludeTestFiles": true,
"patterns": [
{
"file": "**/*.example.ts",
"pattern": "API_KEY",
"reason": "Example files with placeholder API keys"
}
]
}
Sources: QUICK_START.md:399-410, configs/default.json:34-38
Context-Aware Filtering
The scanner can be configured to recognize framework-specific security controls (e.g., DOMPurify for React) to automatically suppress injection warnings.
Sources: README.md:42-45, SECURITY_REVIEW.md:131-135
Severity and Build Failure Policies
The severity section defines the threshold for reporting and the criteria for failing a build in CI/CD environments.
| Setting | Type | Description |
|---|---|---|
threshold | string | Minimum severity level to report (e.g., "LOW", "MEDIUM"). |
failOn | array | Severities that will trigger a non-zero exit code (e.g., ["CRITICAL", "HIGH"]). |
Sources: configs/default.json:45-48, QUICK_START.md:364-370
Fail-On Strategy Guide
- Development: Often set to
["CRITICAL"]to avoid blocking developers on minor issues. - Production/Main: Typically set to
["CRITICAL", "HIGH"]to ensure no major vulnerabilities are merged.
Sources: QUICK_START.md:330-340, README.md:188-193
Performance and Output
Performance Tuning
The performance block allows for optimization based on the execution environment.
- parallelWorkers: Sets the number of concurrent worker threads (default 4).
- cacheEnabled: Enables result caching for unchanged files.
- incrementalScan: When enabled, uses Git diffs to scan only modified files.
Sources: configs/default.json:50-54, README.md:154-158
Output Configuration
The scanner supports multiple formats simultaneously, which can be specified in the output section. Supported formats include terminal, sarif, json, and html. The dir parameter specifies where report files should be saved.
Sources: configs/default.json:40-44, QUICK_START.md:315-321
Summary
The .securityrc.json file is the central point of control for the Unified Security Scanner. By properly configuring tool adapters, exclusion patterns, and severity thresholds, teams can balance comprehensive security coverage with developer productivity, ensuring that only high-confidence, critical vulnerabilities impact the development lifecycle.