@synapta/skills 0.1.0 → 0.1.2

package/skills/secret-hygiene/assets/precommit-config.yaml

@@ -0,0 +1,70 @@
+# Pre-commit Framework Configuration for Gitleaks
+# Install pre-commit: pip install pre-commit
+# Install hooks: pre-commit install
+# Run manually: pre-commit run --all-files
+#
+# More info: https://pre-commit.com/
+
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.0  # Update to latest version: https://github.com/gitleaks/gitleaks/releases
+    hooks:
+      - id: gitleaks
+        name: Gitleaks - Secret Detection
+        description: Scan staged changes for hardcoded secrets
+        entry: gitleaks protect --verbose --redact --staged
+        language: system
+        pass_filenames: false
+        # Optional: Custom configuration
+        # args: ['--config', '.gitleaks.toml']
+
+  # Optional: Additional security hooks
+
+  # Detect private keys
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: detect-private-key
+        name: Detect Private Keys
+
+  # Check for AWS credentials
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: detect-aws-credentials
+        name: Detect AWS Credentials
+        args: ['--allow-missing-credentials']
+
+  # Prevent large files (may contain secrets)
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-added-large-files
+        name: Check for Large Files
+        args: ['--maxkb=1000']
+
+  # Check for merge conflicts
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-merge-conflict
+        name: Check for Merge Conflicts
+
+  # Ensure files end with newline
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: end-of-file-fixer
+        name: Fix End of Files
+
+  # Trim trailing whitespace
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        name: Trim Trailing Whitespace
+
+# Configuration for pre-commit.ci (optional CI service)
+ci:
+  autofix_prs: false
+  autoupdate_schedule: monthly

package/skills/secret-hygiene/references/EXAMPLE.md

@@ -0,0 +1,40 @@
+# Reference Document Template
+
+This file contains detailed reference material that Claude should load only when needed.
+
+## Table of Contents
+
+- [Section 1](#section-1)
+- [Section 2](#section-2)
+- [Security Standards](#security-standards)
+
+## Section 1
+
+Detailed information, schemas, or examples that are too large for SKILL.md.
+
+## Section 2
+
+Additional reference material.
+
+## Security Standards
+
+### OWASP Top 10
+
+Reference relevant OWASP categories:
+- A01: Broken Access Control
+- A02: Cryptographic Failures
+- etc.
+
+### CWE Mappings
+
+Map to relevant Common Weakness Enumeration categories:
+- CWE-79: Cross-site Scripting
+- CWE-89: SQL Injection
+- etc.
+
+### MITRE ATT&CK
+
+Reference relevant tactics and techniques if applicable:
+- TA0001: Initial Access
+- T1190: Exploit Public-Facing Application
+- etc.

package/skills/secret-hygiene/references/compliance_mapping.md

@@ -0,0 +1,538 @@
+# 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