Secret Detection Logic
Relevant source files
The following files were used as context for generating this wiki page:
The Secret Detection Logic in SecretForge AI is an advanced engine designed to identify exposed credentials, API keys, and private keys within source code and git history. It employs a multi-layered approach combining regular expression pattern matching, Shannon entropy analysis, and contextual confidence scoring to ensure high accuracy while minimizing false positives. Sources: packages/shared/src/security/secretDetector.ts:1-5, SECURITY_SUMMARY.md:200-205
This logic is integrated across the ecosystem, including the core CLI for local scanning, GitHub Actions for Pull Request validation, and the Model Context Protocol (MCP) server for AI-assisted security audits. Sources: AUTOMATION_SUMMARY.md:15-20, packages/mcp-server/src/index.ts:120-130
Detection Methodology
The engine evaluates potential secrets through three primary stages: pattern matching, entropy verification, and confidence calculation.
Pattern Matching and Metadata
The system maintains a comprehensive list of SECRET_PATTERNS targeting various services like AWS, Stripe, GitHub, OpenAI, and more. Each pattern includes metadata such as severity levels and remediation recommendations.
| Provider | Secret Type | Severity |
|---|---|---|
| AWS | Access Key ID, Secret Access Key | Critical |
| Stripe | Live Secret Key, Live Publishable Key | Critical/High |
| GitHub | PAT, OAuth, App Tokens | Critical |
| Cloud Providers | Google Cloud, Azure, AWS | Critical/High |
| Databases | Postgres, MongoDB Connection Strings | Critical |
| Crypto | RSA/OpenSSH Private Keys | Critical |
Sources: packages/shared/src/security/secretDetector.ts:39-160, SECURITY_SUMMARY.md:140-150
Entropy Analysis
To distinguish between actual cryptographic keys and random strings or placeholders, the engine calculates the Shannon entropy of detected matches. Generic API keys and secrets require a minimum entropy (e.g., 4.0) to be flagged. Sources: packages/shared/src/security/secretDetector.ts:153-165, packages/shared/src/security/secretDetector.ts:285-300
Confidence Scoring
A confidence score (0-1) is assigned to each match based on surrounding context.
- Boosts (+0.1): Presence of assignment operators (
=,:) or keywords like "secret", "token", or "api". - Penalties (-0.3 to -0.4): Detection within code comments (
//,#) or proximity to placeholder strings like "example" or "sample".
Sources: packages/shared/src/security/secretDetector.ts:305-335
Component Architecture
The detection system is encapsulated within the SecretDetector class, which provides methods for different scanning scopes.
The diagram shows the data flow from raw content through specific scanning methods to the final detection results. Sources: packages/shared/src/security/secretDetector.ts:175-280
Key Data Structures
SecretMatch: Contains the type, masked value, location (file, line, column), confidence score, and severity.DetectionResult: A summary object aggregating all matches and providing counts for each severity level (Critical, High, Medium, Low).
Sources: packages/shared/src/security/secretDetector.ts:7-35
Integration Points
Pre-commit Hooks
The logic is used to generate shell scripts for Git pre-commit hooks. These scripts scan staged files using the secretforge scan --staged command and block commits if high-severity secrets are detected. Sources: packages/shared/src/security/secretDetector.ts:355-385, CONTRIBUTING.md:45-55
MCP Server Integration
The Model Context Protocol server exposes the detection logic to AI assistants through tools like analyze_project. This tool reads a project's package.json to detect required services and suggests security validations. Sources: packages/mcp-server/src/index.ts:45-60, packages/mcp-server/src/index.ts:210-230
This sequence illustrates how AI tools leverage the internal detection logic to provide architectural security audits. Sources: packages/mcp-server/src/index.ts:180-215, README.md:120-130
Security Operations and Safeguards
Masking Logic
To prevent accidental exposure within log files or terminal output, the system includes a maskSecret utility. It preserves the first and last 4 characters while replacing the middle content with asterisks for any value longer than 8 characters. Sources: packages/shared/src/security/secretDetector.ts:340-350, SECURITY_SUMMARY.md:80-90
Vulnerability Mitigation
The implementation includes sanitization logic to prevent injection attacks when exporting or injecting secrets. It specifically escapes backslashes and quotes to ensure that detected secrets do not corrupt configuration files or shells. Sources: SECURITY_SUMMARY.md:25-40, SECURITY_SUMMARY.md:100-115
Summary
The Secret Detection Logic serves as the primary defensive layer of SecretForge AI. By combining rigid pattern matching with flexible entropy and context analysis, it provides a robust mechanism for preventing credential leakage across local development, CI/CD pipelines, and AI-driven workflows. Sources: SYSTEM_EVALUATION.md:15-30, SECURITY_SUMMARY.md:230-245