Security Model & Compliance
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
SecretForge AI employs a local-first, zero-trust security architecture designed to prevent the accidental exposure of sensitive credentials. The system's primary goal is to eliminate the practice of committing API keys to version control by providing a secure, encrypted storage layer and automated detection mechanisms. The model relies on industry-standard cryptographic primitives and automated CI/CD security workflows to ensure data integrity and confidentiality.
The security scope encompasses encryption at rest using AES-256-GCM, cryptographically secure ID generation, and proactive secret scanning via GitHub Actions. These components work together to mitigate threats such as unauthorized access, tampering, and secret leakage in logs or source code.
Sources: SECURITY_SUMMARY.md:1-10, PHASE1_IMPLEMENTATION.md:5-15, SYSTEM_EVALUATION.md:10-20
Cryptographic Architecture
SecretForge AI utilizes the AES-256-GCM (Galois/Counter Mode) algorithm for all secret encryption. This NIST-approved algorithm provides both confidentiality and built-in authentication (integrity verification) through authentication tags.
Key Components of the Crypto Layer
- Algorithm: AES-256-GCM.
- Key Management: Encryption keys are 256-bit (32-byte) Base64-encoded strings stored in the
SECRETFORGE_ENCRYPTION_KEYenvironment variable. Keys are never stored in the database or configuration files. - Initialization Vector (IV): A random 12-byte IV is generated per encryption operation to ensure that the same plaintext results in different ciphertexts, preventing pattern detection.
- Integrity: A 128-bit authentication tag is used for GCM mode to verify that the data has not been tampered with.
Sources: SECURITY_SUMMARY.md:31-50, PHASE1_IMPLEMENTATION.md:75-90, SYSTEM_EVALUATION.md:118-135
Data Flow for Secret Storage
The following diagram illustrates the secure flow of a secret from input to the local SQLite database.
This diagram shows the encryption process before data hits the storage layer.
Sources: PHASE1_IMPLEMENTATION.md:80-100, SECURITY_SUMMARY.md:52-60
Secret Detection Engine
The project includes an advanced detection engine capable of identifying exposed secrets through pattern matching and entropy analysis. This engine is utilized both in the CLI for local scanning and in GitHub Actions for PR verification.
Supported Patterns and Severity
The engine uses regex patterns to detect specific service keys:
| Service | Pattern Type | Severity |
|---|---|---|
| AWS | Access Key ID / Secret Key | Critical |
| Stripe | Live Secret Key | Critical |
| OpenAI | API Key | Critical |
| GitHub | Personal Access Token (ghp_) | Critical |
| Google Cloud | API Key / OAuth Token | High/Critical |
| Slack | Bot Token / Webhook | Critical/High |
Sources: packages/shared/src/security/secretDetector.ts:40-140, packages/github-action/README.md:55-70
Confidence and Entropy Analysis
The detection engine calculates a confidence score (0-1) by evaluating:
- Shannon Entropy: Measures the randomness of the string (e.g., generic API keys require a minimum entropy of 4.0).
- Contextual Analysis: Increases confidence if keywords like "key" or "secret" are nearby; decreases confidence if found in comments or documentation.
Sources: packages/shared/src/security/secretDetector.ts:260-310
Automated Security Workflows
Security is enforced through a multi-layered automation pipeline running on GitHub Actions.
The sequence diagram details the automated checks performed during the development lifecycle.
Sources: AUTOMATION_SUMMARY.md:10-35, CONTRIBUTING.md:65-85
Security Tooling Summary
| Tool | Purpose | Schedule |
|---|---|---|
| CodeQL | Code vulnerability analysis | Push, PR, Weekly |
| TruffleHog | Secret and credential detection | Push, PR |
| pnpm audit | Dependency vulnerability checks | CI execution |
| Dependabot | Automated security updates | Weekly |
Sources: AUTOMATION_SUMMARY.md:12-25, CONTRIBUTING.md:70-80
Compliance Status
The system is evaluated against several compliance frameworks. As of Phase 1, the foundation is established for SOC 2, GDPR, and HIPAA.
Compliance Mapping
- GDPR: Supports data minimization and the "right to delete" through the
deletecommand. All data is encrypted. - SOC 2 Type II: Implements encryption at rest and access logging (timestamps). Full RBAC and detailed audit trails are slated for future phases.
- HIPAA: Uses unique cryptographic identifiers (UUID v4) and strong AES-256-GCM encryption at rest.
Sources: SECURITY_SUMMARY.md:110-130, SYSTEM_EVALUATION.md:215-245
Database Security & Integrity
SecretForge uses an embedded SQLite database. Security is maintained at the file level and through database-level constraints.
- At Rest: Only encrypted values and metadata are stored.
- Unique Constraints: A unique index on
(name, project, environment)prevents duplicate secrets. - Secure IDs: Identifiers are generated using
crypto.randomUUID(), producing unpredictable 122-bit random strings to prevent ID prediction attacks. - Audit Trail: Every record includes
created_atandupdated_attimestamps.
Sources: PHASE1_IMPLEMENTATION.md:38-55, SECURITY_SUMMARY.md:15-25, SYSTEM_EVALUATION.md:120-130
Database Schema Structure
Sources: PHASE1_IMPLEMENTATION.md:40-50
Conclusion
The Security Model of SecretForge AI centers on robust AES-256-GCM encryption and a comprehensive automated scanning ecosystem. By shifting security "left" into the developer's local environment and CI/CD pipelines, the project ensures that sensitive credentials are encrypted at the moment of creation and monitored throughout the development lifecycle. While Phase 1 successfully establishes core cryptographic protections and compliance foundations, future enhancements will focus on KMS integration and role-based access control.
Sources: SECURITY_SUMMARY.md:165-180, SYSTEM_EVALUATION.md:280-295