539 lines
16 KiB
Markdown
539 lines
16 KiB
Markdown
# Compliance Framework Mapping
|
||
|
||
Detailed mapping of Gitleaks secret detection to compliance and security frameworks.
|
||
|
||
## Table of Contents
|
||
|
||
- [OWASP Top 10](#owasp-top-10)
|
||
- [CWE (Common Weakness Enumeration)](#cwe-common-weakness-enumeration)
|
||
- [PCI-DSS](#pci-dss)
|
||
- [SOC 2](#soc-2)
|
||
- [GDPR](#gdpr)
|
||
- [NIST Cybersecurity Framework](#nist-cybersecurity-framework)
|
||
- [ISO 27001](#iso-27001)
|
||
- [HIPAA](#hipaa)
|
||
- [Compliance Reporting](#compliance-reporting)
|
||
|
||
## OWASP Top 10
|
||
|
||
### A07:2021 – Identification and Authentication Failures
|
||
|
||
**Relevance**: Hardcoded credentials lead to authentication bypass and unauthorized access.
|
||
|
||
**Gitleaks Coverage**:
|
||
- Detects hardcoded passwords, API keys, tokens
|
||
- Identifies database connection strings with embedded credentials
|
||
- Finds SSH keys, certificates, and cryptographic secrets
|
||
|
||
**Control Implementation**:
|
||
```yaml
|
||
# CI/CD check to prevent authentication failures
|
||
name: OWASP A07 - Authentication Control
|
||
on: [push, pull_request]
|
||
jobs:
|
||
secrets-scan:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
with:
|
||
fetch-depth: 0
|
||
- name: Scan for hardcoded credentials (OWASP A07)
|
||
uses: gitleaks/gitleaks-action@v2
|
||
env:
|
||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||
```
|
||
|
||
**Evidence for Auditors**:
|
||
- Gitleaks scan reports (JSON/SARIF format)
|
||
- CI/CD pipeline logs showing regular scans
|
||
- Pre-commit hook installation across developer workstations
|
||
- Remediation tracking for detected secrets
|
||
|
||
### A01:2021 – Broken Access Control
|
||
|
||
**Relevance**: Exposed API keys and tokens can bypass access control mechanisms.
|
||
|
||
**Gitleaks Coverage**:
|
||
- Cloud provider credentials (AWS, GCP, Azure)
|
||
- Service account keys and OAuth tokens
|
||
- Administrative API keys
|
||
|
||
**Control Implementation**:
|
||
- Implement secret scanning before deployment
|
||
- Rotate credentials when exposure detected
|
||
- Review cloud provider audit logs for unauthorized access
|
||
|
||
### A02:2021 – Cryptographic Failures
|
||
|
||
**Relevance**: Hardcoded cryptographic keys compromise encryption.
|
||
|
||
**Gitleaks Coverage**:
|
||
- Private keys (RSA, DSA, EC)
|
||
- JWT signing secrets
|
||
- Encryption keys in configuration files
|
||
|
||
**Evidence**:
|
||
- Detection rules for CWE-321 (Use of Hard-coded Cryptographic Key)
|
||
- Remediation procedures for exposed cryptographic material
|
||
|
||
## CWE (Common Weakness Enumeration)
|
||
|
||
### CWE-798: Use of Hard-coded Credentials
|
||
|
||
**Description**: Software contains hard-coded credentials (e.g., password, cryptographic key).
|
||
|
||
**CVSS Base Score**: Typically 7.5 - 9.8 (High to Critical)
|
||
|
||
**Gitleaks Detection**:
|
||
- All API key rules
|
||
- Database connection strings
|
||
- Service account credentials
|
||
- Generic password patterns
|
||
|
||
**Remediation Mapping**:
|
||
```toml
|
||
# Tag all findings with CWE-798
|
||
[[rules]]
|
||
id = "generic-api-key"
|
||
description = "Generic API Key (CWE-798)"
|
||
regex = '''(?i)api_key\s*=\s*["']([a-zA-Z0-9]{32,})["']'''
|
||
tags = ["api-key", "CWE-798"]
|
||
```
|
||
|
||
### CWE-259: Use of Hard-coded Password
|
||
|
||
**Description**: Software contains hard-coded password.
|
||
|
||
**Gitleaks Detection**:
|
||
- Password variables in code
|
||
- Database connection strings with passwords
|
||
- Configuration files with password fields
|
||
|
||
**Example Finding**:
|
||
```json
|
||
{
|
||
"RuleID": "generic-password",
|
||
"Description": "Hard-coded password detected",
|
||
"File": "config/database.py",
|
||
"Line": 42,
|
||
"CWE": "CWE-259"
|
||
}
|
||
```
|
||
|
||
### CWE-321: Use of Hard-coded Cryptographic Key
|
||
|
||
**Description**: Use of hard-coded cryptographic key in product.
|
||
|
||
**Gitleaks Detection**:
|
||
- Private key files (PEM format)
|
||
- JWT signing secrets
|
||
- Encryption keys in source code
|
||
|
||
### CWE-522: Insufficiently Protected Credentials
|
||
|
||
**Description**: Product transmits or stores authentication credentials in insufficiently protected form.
|
||
|
||
**Gitleaks Coverage**: Detects credentials stored in source code (inadequate protection).
|
||
|
||
### CWE-257: Storing Passwords in a Recoverable Format
|
||
|
||
**Description**: Storing passwords in a recoverable format makes them vulnerable.
|
||
|
||
**Gitleaks Coverage**: Identifies plaintext passwords in configuration and code.
|
||
|
||
## PCI-DSS
|
||
|
||
### Requirement 6.5.3: Insecure Cryptographic Storage
|
||
|
||
**Control Objective**: Protect stored cardholder data.
|
||
|
||
**Gitleaks Implementation**:
|
||
- Scan payment processing code for embedded API keys (Stripe, PayPal, etc.)
|
||
- Detect hardcoded encryption keys
|
||
- Identify database credentials used for cardholder data access
|
||
|
||
**Compliance Evidence**:
|
||
```bash
|
||
# Generate PCI-DSS compliance report
|
||
gitleaks detect \
|
||
--source ./payment-processing \
|
||
--report-format json \
|
||
--report-path pci-compliance-scan.json
|
||
|
||
# Extract payment-related findings
|
||
jq '.[] | select(.Tags[] | contains("payment"))' pci-compliance-scan.json
|
||
```
|
||
|
||
### Requirement 8.2.1: Strong Cryptography for Authentication
|
||
|
||
**Control Objective**: Use strong authentication credentials.
|
||
|
||
**Gitleaks Implementation**:
|
||
- Detect weak/hardcoded authentication tokens
|
||
- Identify test credentials in production code paths
|
||
|
||
### Requirement 10.2: Logging and Monitoring
|
||
|
||
**Control Objective**: Implement automated audit trails.
|
||
|
||
**Gitleaks Implementation**:
|
||
```python
|
||
# Log all secret detection events
|
||
import logging
|
||
import json
|
||
|
||
with open('gitleaks-findings.json', 'r') as f:
|
||
findings = json.load(f)
|
||
|
||
for finding in findings:
|
||
logging.warning(
|
||
f"PCI-DSS Violation: Hardcoded credential detected",
|
||
extra={
|
||
"rule": finding["RuleID"],
|
||
"file": finding["File"],
|
||
"line": finding["StartLine"],
|
||
"compliance_requirement": "PCI-DSS 6.5.3"
|
||
}
|
||
)
|
||
```
|
||
|
||
### PCI-DSS Reporting Template
|
||
|
||
```markdown
|
||
# PCI-DSS Requirement 6.5.3 - Secret Scanning Report
|
||
|
||
**Reporting Period**: Q1 2024
|
||
**Scan Date**: 2024-01-15
|
||
**Scope**: All repositories handling cardholder data
|
||
|
||
## Summary
|
||
- **Repositories Scanned**: 15
|
||
- **Secrets Detected**: 3
|
||
- **Remediation Status**: All resolved within 24 hours
|
||
|
||
## Findings
|
||
|
||
| Finding ID | Rule | Severity | File | Status | Remediation Date |
|
||
|------------|------|----------|------|--------|------------------|
|
||
| F001 | stripe-api-key | CRITICAL | payment/config.py | Resolved | 2024-01-15 |
|
||
| F002 | database-password | HIGH | db/setup.sql | Resolved | 2024-01-15 |
|
||
| F003 | aws-access-key | HIGH | deploy/config.yml | Resolved | 2024-01-16 |
|
||
|
||
## Control Effectiveness
|
||
✅ Automated secret scanning implemented
|
||
✅ All findings remediated within SLA
|
||
✅ Pre-commit hooks prevent new violations
|
||
```
|
||
|
||
## SOC 2
|
||
|
||
### CC6.1: Logical and Physical Access Controls
|
||
|
||
**Control Activity**: Implement controls to prevent unauthorized access to system resources.
|
||
|
||
**Gitleaks Implementation**:
|
||
- Automated detection of exposed credentials
|
||
- Pre-commit hooks to prevent credential commits
|
||
- CI/CD gates blocking deployments with secrets
|
||
|
||
**SOC 2 Evidence Package**:
|
||
1. Secret scanning policy and procedures
|
||
2. Gitleaks configuration file (`.gitleaks.toml`)
|
||
3. CI/CD pipeline configurations
|
||
4. Scan execution logs (last 12 months)
|
||
5. Remediation tracking (issue tickets)
|
||
6. Training materials for developers
|
||
|
||
### CC6.6: Logical Access - Provisioning
|
||
|
||
**Control Activity**: Provision access based on role, revoke when no longer needed.
|
||
|
||
**Gitleaks Implementation**:
|
||
- Detection of service account keys and tokens
|
||
- Audit trail of credential exposure and rotation
|
||
- Automated revocation workflows
|
||
|
||
### CC7.2: System Monitoring
|
||
|
||
**Control Activity**: Monitor system for security events and anomalies.
|
||
|
||
**Gitleaks Implementation**:
|
||
```yaml
|
||
# Continuous monitoring workflow
|
||
name: SOC2 CC7.2 - Security Monitoring
|
||
on:
|
||
schedule:
|
||
- cron: '0 2 * * *' # Daily at 2 AM
|
||
jobs:
|
||
security-scan:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
with:
|
||
fetch-depth: 0
|
||
- name: Secret Detection Scan
|
||
uses: gitleaks/gitleaks-action@v2
|
||
- name: Report to SIEM
|
||
run: |
|
||
curl -X POST https://siem.company.com/api/events \
|
||
-H "Content-Type: application/json" \
|
||
-d @gitleaks-report.json
|
||
```
|
||
|
||
### SOC 2 Audit Response Template
|
||
|
||
```markdown
|
||
# SOC 2 Control CC6.1 - Secret Scanning Control
|
||
|
||
**Control Description**: Automated secret scanning prevents unauthorized access through exposed credentials.
|
||
|
||
**Control Design**:
|
||
1. Pre-commit hooks block credential commits at developer workstation
|
||
2. CI/CD pipeline scans all pull requests before merge
|
||
3. Nightly scans of all production repositories
|
||
4. Automated alerting to security team for violations
|
||
|
||
**Control Operating Effectiveness**:
|
||
- **Frequency**: Continuous (pre-commit) + Daily (scheduled scans)
|
||
- **Population**: 247 repositories, 85 developers
|
||
- **Sample Period**: January 1 - December 31, 2024
|
||
- **Samples Tested**: 52 weekly scan reports
|
||
- **Exceptions**: 0
|
||
|
||
**Evidence of Operation**:
|
||
- Attached: gitleaks-audit-log-2024.json
|
||
- Attached: remediation-tracking.csv
|
||
- Attached: developer-training-records.pdf
|
||
```
|
||
|
||
## GDPR
|
||
|
||
### Article 32: Security of Processing
|
||
|
||
**Requirement**: Implement appropriate technical measures to ensure security of personal data.
|
||
|
||
**Gitleaks Implementation**:
|
||
- Detect API keys for services processing personal data
|
||
- Identify database credentials for systems storing personal data
|
||
- Scan for OAuth tokens with user data access scopes
|
||
|
||
**GDPR Compliance Mapping**:
|
||
|
||
| GDPR Requirement | Gitleaks Control | Evidence |
|
||
|------------------|------------------|----------|
|
||
| Art. 32(1)(a) - Pseudonymization | Detect database credentials protecting personal data | Scan reports |
|
||
| Art. 32(1)(b) - Confidentiality | Prevent credential exposure in source code | Pre-commit hooks |
|
||
| Art. 32(2) - Risk Assessment | Regular security scanning | Scan schedules |
|
||
| Art. 33 - Breach Notification | Detection triggers incident response | Alert logs |
|
||
|
||
### Data Breach Notification
|
||
|
||
If Gitleaks detects exposed credentials accessing personal data:
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# gdpr-incident-response.sh
|
||
|
||
# Assess if personal data is at risk
|
||
echo "1. Identify data accessed by exposed credential"
|
||
echo "2. Determine if data is personal data under GDPR"
|
||
echo "3. Assess likelihood of unauthorized access"
|
||
|
||
# 72-hour notification requirement
|
||
echo "If personal data breach confirmed:"
|
||
echo "- Notify supervisory authority within 72 hours"
|
||
echo "- Document: nature of breach, data categories affected, likely consequences, measures taken"
|
||
```
|
||
|
||
## NIST Cybersecurity Framework
|
||
|
||
### Identify (ID.AM): Asset Management
|
||
|
||
**Subcategory**: ID.AM-2 - Software platforms and applications are inventoried.
|
||
|
||
**Gitleaks Implementation**: Catalog all repositories with secret scanning coverage.
|
||
|
||
### Protect (PR.AC): Access Control
|
||
|
||
**Subcategory**: PR.AC-1 - Identities and credentials are managed.
|
||
|
||
**Gitleaks Implementation**:
|
||
- Automated detection of exposed credentials
|
||
- Credential lifecycle management (rotation after exposure)
|
||
|
||
### Detect (DE.CM): Security Continuous Monitoring
|
||
|
||
**Subcategory**: DE.CM-4 - Malicious code is detected.
|
||
|
||
**Gitleaks Implementation**: Secrets considered "malicious" when hardcoded.
|
||
|
||
### Respond (RS.AN): Analysis
|
||
|
||
**Subcategory**: RS.AN-1 - Notifications are investigated.
|
||
|
||
**Gitleaks Implementation**: Alert triage and investigation procedures.
|
||
|
||
### Recover (RC.RP): Recovery Planning
|
||
|
||
**Subcategory**: RC.RP-1 - Recovery plan is executed during or after an event.
|
||
|
||
**Gitleaks Implementation**: Credential rotation and git history cleanup procedures.
|
||
|
||
## ISO 27001
|
||
|
||
### A.9.2.4: Management of Secret Authentication Information
|
||
|
||
**Control**: Allocation of secret authentication information shall be controlled through a formal management process.
|
||
|
||
**Gitleaks Implementation**:
|
||
- Detect deviations from secret management process (hardcoded secrets)
|
||
- Enforce secret management policy through pre-commit hooks
|
||
|
||
### A.9.4.3: Password Management System
|
||
|
||
**Control**: Password management systems shall be interactive and ensure quality passwords.
|
||
|
||
**Gitleaks Implementation**: Prevent password hardcoding in source code.
|
||
|
||
### A.12.6.1: Management of Technical Vulnerabilities
|
||
|
||
**Control**: Obtain information about technical vulnerabilities and take appropriate measures.
|
||
|
||
**Gitleaks Implementation**: Continuous vulnerability scanning for credential exposure.
|
||
|
||
## HIPAA
|
||
|
||
### § 164.312(a)(1): Access Control
|
||
|
||
**Standard**: Implement technical policies to allow only authorized access to ePHI.
|
||
|
||
**Gitleaks Implementation**:
|
||
- Detect credentials for systems accessing ePHI
|
||
- Prevent unauthorized access through exposed credentials
|
||
|
||
### § 164.308(a)(1)(ii)(D): Information System Activity Review
|
||
|
||
**Standard**: Implement procedures to regularly review records of information system activity.
|
||
|
||
**Gitleaks Implementation**:
|
||
```bash
|
||
# Weekly HIPAA compliance review
|
||
gitleaks detect \
|
||
--source ./healthcare-systems \
|
||
--report-format json \
|
||
> hipaa-weekly-scan.json
|
||
|
||
# Review findings for ePHI access credentials
|
||
jq '.[] | select(.Tags[] | contains("database") or contains("api-key"))' \
|
||
hipaa-weekly-scan.json
|
||
```
|
||
|
||
### § 164.312(b): Audit Controls
|
||
|
||
**Standard**: Implement hardware, software, procedures to record and examine system activity.
|
||
|
||
**Gitleaks Implementation**: Audit trail of secret detection events.
|
||
|
||
## Compliance Reporting
|
||
|
||
### Automated Compliance Report Generation
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""Generate compliance report from Gitleaks findings."""
|
||
|
||
import json
|
||
import sys
|
||
from datetime import datetime
|
||
|
||
# Compliance framework mappings
|
||
COMPLIANCE_MAPPINGS = {
|
||
"CWE-798": ["OWASP-A07", "PCI-DSS-6.5.3", "SOC2-CC6.1", "ISO27001-A.9.2.4"],
|
||
"CWE-259": ["OWASP-A07", "PCI-DSS-8.2.1", "SOC2-CC6.1", "ISO27001-A.9.4.3"],
|
||
"CWE-321": ["OWASP-A02", "PCI-DSS-6.5.3", "ISO27001-A.12.3.1"],
|
||
}
|
||
|
||
def generate_compliance_report(findings_file, framework):
|
||
"""Generate compliance-specific report."""
|
||
|
||
with open(findings_file, 'r') as f:
|
||
findings = json.load(f)
|
||
|
||
# Filter findings relevant to framework
|
||
relevant_findings = []
|
||
for finding in findings:
|
||
cwe = finding.get("CWE", "")
|
||
if framework in COMPLIANCE_MAPPINGS.get(cwe, []):
|
||
relevant_findings.append(finding)
|
||
|
||
# Generate report
|
||
report = {
|
||
"framework": framework,
|
||
"generated": datetime.now().isoformat(),
|
||
"total_findings": len(relevant_findings),
|
||
"findings": relevant_findings,
|
||
"compliance_status": "NON-COMPLIANT" if relevant_findings else "COMPLIANT"
|
||
}
|
||
|
||
return report
|
||
|
||
if __name__ == "__main__":
|
||
if len(sys.argv) != 3:
|
||
print("Usage: compliance_report.py <findings.json> <framework>")
|
||
print("Frameworks: OWASP, PCI-DSS, SOC2, ISO27001, GDPR, HIPAA")
|
||
sys.exit(1)
|
||
|
||
report = generate_compliance_report(sys.argv[1], sys.argv[2])
|
||
print(json.dumps(report, indent=2))
|
||
```
|
||
|
||
### Usage
|
||
|
||
```bash
|
||
# Generate PCI-DSS specific report
|
||
./compliance_report.py gitleaks-findings.json PCI-DSS > pci-dss-report.json
|
||
|
||
# Generate SOC2 specific report
|
||
./compliance_report.py gitleaks-findings.json SOC2 > soc2-report.json
|
||
```
|
||
|
||
### Compliance Dashboard Metrics
|
||
|
||
Track these KPIs for compliance reporting:
|
||
|
||
```yaml
|
||
metrics:
|
||
- name: "Secret Detection Coverage"
|
||
description: "Percentage of repositories with secret scanning enabled"
|
||
target: 100%
|
||
|
||
- name: "Mean Time to Remediation (MTTR)"
|
||
description: "Average time from detection to credential rotation"
|
||
target: < 4 hours
|
||
|
||
- name: "False Positive Rate"
|
||
description: "Percentage of findings classified as false positives"
|
||
target: < 10%
|
||
|
||
- name: "Pre-commit Hook Adoption"
|
||
description: "Percentage of developers with hooks installed"
|
||
target: > 95%
|
||
|
||
- name: "Scan Frequency"
|
||
description: "Scans per repository per month"
|
||
target: > 30 (daily)
|
||
```
|
||
|
||
## Audit Preparation Checklist
|
||
|
||
- [ ] Configure Gitleaks across all in-scope repositories
|
||
- [ ] Implement CI/CD secret scanning gates
|
||
- [ ] Deploy pre-commit hooks to developer workstations
|
||
- [ ] Establish remediation procedures and SLAs
|
||
- [ ] Create audit trail (scan logs, remediation tickets)
|
||
- [ ] Generate compliance-specific reports
|
||
- [ ] Document control design and operating effectiveness
|
||
- [ ] Prepare evidence package for auditors
|
||
- [ ] Train team on secret management policies
|
||
- [ ] Schedule regular compliance reviews
|