trufflehog-js/SECURITY.md

TypeScript wrapper for TruffleHog secret scanner

<!--
Copyright (c) 2025 maloma7. All rights reserved.
SPDX-License-Identifier: MIT
-->

# Security Policy

## Overview

TruffleHog-JS is a security-critical component that protects developers from accidentally committing secrets to their repositories. This document outlines our security practices, threat model, and vulnerability reporting procedures.

## Supported Versions

We provide security updates for the following versions:

| Version | Supported          |
| ------- | ------------------ |
| 1.0.x   | :white_check_mark: |

## Security Architecture

### Threat Model

TruffleHog-JS operates in a security-sensitive environment and faces several potential threats:

#### **1. Supply Chain Attacks**
- **Threat**: Malicious actors compromising TruffleHog binary distribution
- **Mitigation**:
  - HTTPS-only communication with TruffleHog releases
  - Cryptographic verification using SHA256 checksums and GPG signatures
  - Fail-safe behavior on binary verification failures

#### **2. Binary Manipulation Attacks**
- **Threat**: Man-in-the-middle attacks on TruffleHog binary downloads
- **Mitigation**:
  - Certificate pinning through HTTPS
  - Binary integrity validation with checksums
  - GPG signature verification against official signing keys

#### **3. Secret Exposure Attacks**
- **Threat**: Detected secrets being exposed in logs or error messages
- **Mitigation**:
  - All detected secrets are redacted in output and logs
  - TypeScript strict mode prevents type confusion
  - Input sanitization for logging outputs

#### **4. Denial of Service (DoS)**
- **Threat**: Scanner resource exhaustion or binary download failures
- **Mitigation**:
  - Configurable scan timeouts (120s default)
  - Binary caching to reduce download frequency
  - Fail-safe behavior (allow commits on scanner errors)
  - Process isolation with timeout controls

#### **5. Information Disclosure**
- **Threat**: Secret data leakage through logs or errors
- **Mitigation**:
  - Structured logging with configurable levels
  - No actual secrets or sensitive data in logs
  - Error messages provide minimal information disclosure

### Security Design Principles

#### **1. Fail-Safe Behavior**
The scanner is designed to **never block legitimate commits** due to scanner failures:

```typescript
} catch (error) {
    logger.error("TruffleHog scanner encountered an unexpected error", { error: message });
    // Fail-safe: allow commit to proceed on scanner errors
    return [];
}
```

**Rationale**: Developer productivity must not be compromised by scanner infrastructure failures.

#### **2. Defense in Depth**
Multiple layers of security controls:

- **Binary Verification**: SHA256 checksums and GPG signature validation
- **Network Security**: HTTPS-only, timeout controls, retry logic
- **Error Handling**: Graceful degradation with comprehensive error logging
- **Type Safety**: Full TypeScript coverage with strict compilation

#### **3. Principle of Least Privilege**
- Scanner operates with minimal permissions
- No file system write access required beyond cache
- Read-only access to staged files and Git repository
- No external network access beyond TruffleHog binary downloads

#### **4. Transparency**
- All secret detection based on open source TruffleHog patterns
- Open source implementation allows security review
- Comprehensive logging for audit trails

## Security Features

### **Binary Verification**
All TruffleHog binaries are cryptographically verified:

```typescript
// Binary integrity verification with checksums and signatures
await this.verifyChecksum(tempPath, expectedChecksum);
await this.verifySignature(checksums, signature, publicKey);
```

### **Network Security**
- **HTTPS Enforcement**: All TruffleHog binary downloads use HTTPS
- **Binary Timeouts**: 5-minute default timeout prevents hanging downloads
- **Retry Logic**: Exponential backoff with smart retry conditions
- **User Agent**: Identifies scanner for TruffleHog release monitoring

### **Error Handling**
- **Fail-Safe**: Scanner errors never block commits
- **Graceful Degradation**: Partial failures handled appropriately
- **Comprehensive Logging**: Full error context for debugging

### **Data Privacy**
- **No Secret Exposure**: All detected secrets are redacted in logs
- **Secure Caching**: Binary caching with integrity verification
- **Minimal Logging**: Only essential information logged, secrets redacted

## Configuration Security

### Environment Variables
The scanner supports security-relevant environment variables:

```bash
# Logging configuration
TRUFFLEHOG_LOG_LEVEL=warn         # Controls information disclosure in logs

# Binary security
TRUFFLEHOG_BINARY_PATH=...        # Allows custom TruffleHog binary path (enterprise)
TRUFFLEHOG_VERBOSE=false          # Controls verbose output for debugging
TRUFFLEHOG_CONFIG_PATH=...        # Path to TruffleHog configuration file
```

### Secure Defaults
- Default timeout: 120 seconds (prevents DoS during scanning)
- Default log level: `warn` (balances security and debugging)
- HTTPS enforcement (no HTTP fallback)
- Binary verification enabled (ensures integrity)

## Vulnerability Assessment

### Regular Security Practices

#### **1. Dependency Management**
- Minimal dependency footprint (only Zod for runtime)
- Regular security audits of dependencies
- Automated dependency updates through Dependabot

#### **2. Code Security**
- TypeScript strict mode enabled
- Comprehensive linting with security rules
- No `eval()` or dynamic code execution
- Input sanitization for all external data

#### **3. Testing**
- Comprehensive test suite including security scenarios
- Edge case testing for malformed API responses
- Network failure simulation tests

### Known Security Considerations

#### **1. TruffleHog Binary Trust**
- **Risk**: Scanner depends on TruffleHog binary integrity
- **Mitigation**: TruffleHog is Truffle Security-operated, industry-standard secret scanner
- **Residual Risk**: Acceptable for most use cases

#### **2. Network Connectivity**
- **Risk**: Scanner requires internet access for initial binary download
- **Mitigation**: Fail-safe behavior allows offline development with cached binary
- **Enterprise**: Custom TRUFFLEHOG_BINARY_PATH for internal binary management

#### **3. Binary Download Security**
- **Risk**: GitHub releases may be compromised during download
- **Mitigation**: Cryptographic verification, checksums, GPG signatures

## Reporting a Vulnerability

### Supported Languages
- English

### Reporting Process

#### **1. Initial Report**
Please report security vulnerabilities using **GitHub Security Advisories** at:
https://github.com/maloma7/trufflehog-js/security/advisories/new

Include the following information in your report:
- **Impact Assessment**: Critical/High/Medium/Low
- **Vulnerability Type**: Code execution, data disclosure, DoS, etc.
- **Affected Versions**: Specific versions affected
- **Proof of Concept**: Steps to reproduce (if applicable)
- **Suggested Mitigation**: Your recommended fix (optional)

#### **2. Response Timeline**
- **Initial Response**: Within 3 days
- **Impact Assessment**: Within 7 days  
- **Security Fix**: Within 14 days for critical, 30 days for others
- **Public Disclosure**: 90 days after fix release

#### **3. Disclosure Policy**
We follow **responsible disclosure**:

1. **Private Report**: Initial vulnerability report kept confidential
2. **Coordinated Fix**: We work with reporter to develop fix
3. **Security Release**: Fixed version released with security advisory
4. **Public Disclosure**: Full details published after fix deployment

### What Qualifies as a Security Vulnerability

#### **In Scope**
- Code execution vulnerabilities
- Authentication/authorization bypasses  
- Data disclosure or privacy violations
- Denial of service attacks
- Supply chain attack vectors
- Cryptographic weaknesses

#### **Out of Scope**
- Issues in dependencies (report to upstream)
- Social engineering attacks
- Physical security issues
- Issues in TruffleHog binary infrastructure (report to Truffle Security)
- Performance issues without security impact

## Security Hardening Guide

### For Users

#### **1. Environment Security**
```bash
# Use minimal logging in production
TRUFFLEHOG_LOG_LEVEL=warn

# Configure custom binary for enterprise environments
TRUFFLEHOG_BINARY_PATH=/usr/local/bin/trufflehog

# Control verbosity for security
TRUFFLEHOG_VERBOSE=false
```

#### **2. Network Security**
- Ensure HTTPS connectivity to GitHub releases for binary downloads
- Configure corporate firewalls to allow TruffleHog binary downloads
- Consider proxy/VPN requirements for enterprise environments

#### **3. Monitoring**
- Monitor scanner logs for unusual patterns
- Set up alerts for repeated scanner failures
- Track secret detection rates and patterns

### For Developers

#### **1. Development Environment**
```bash
# Enable debug logging for development
TRUFFLEHOG_LOG_LEVEL=debug

# Enable verbose output for development
TRUFFLEHOG_VERBOSE=true
```

#### **2. Testing**
```bash
# Test with known secret patterns
bunx trufflehog-js --staged --verbose

# Test binary download failure handling
TRUFFLEHOG_BINARY_PATH=/invalid/path/trufflehog bun test
```

## Incident Response

### In Case of Security Incident

#### **1. Immediate Actions**
- Assess impact and scope
- Disable scanner if necessary (set TRUFFLEHOG_BINARY_PATH to empty)
- Notify security team
- Begin incident documentation

#### **2. Investigation**
- Collect relevant logs and evidence
- Determine root cause
- Assess data exposure risk
- Document timeline

#### **3. Remediation**
- Apply security fix
- Update to latest secure version
- Review and update security practices
- Communicate with stakeholders

## Compliance and Standards

### Security Standards
- **OWASP Top 10**: Address common web application security risks
- **NIST Cybersecurity Framework**: Identify, Protect, Detect, Respond, Recover
- **Supply Chain Security**: SLSA (Supply chain Levels for Software Artifacts) principles

### Audit Trail
- All security-relevant events logged with timestamps
- Vulnerability detection events recorded
- Configuration changes logged
- API interactions tracked

## Contact Information

- **Security Vulnerabilities**: https://github.com/maloma7/trufflehog-js/security/advisories/new
- **General Issues**: https://github.com/maloma7/trufflehog-js/issues
- **Security Advisories**: https://github.com/maloma7/trufflehog-js/security

---

**Last Updated**: September 21, 2025
**Version**: 1.0.0

*This security policy is a living document and will be updated as the project evolves and new security considerations emerge.*