gh-agentsecops-secopsagentkit/skills/devsecops/secrets-gitleaks/references/compliance_mapping.md

Compliance Framework Mapping

Detailed mapping of Gitleaks secret detection to compliance and security frameworks.

Table of Contents

• OWASP Top 10
• CWE (Common Weakness Enumeration)
• PCI-DSS
• SOC 2
• GDPR
• NIST Cybersecurity Framework
• ISO 27001
• HIPAA
• 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:

# 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:

# 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:

{
  "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:

# 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:

# 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

# 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:

# 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

# 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:

#!/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:

# 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

#!/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

# 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:

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