secret-protection

密钥保护

Agent Skills™ 的一部分，由 googleadsagent.ai™ 提供

描述

密钥保护通过扫描 .env、设置提交前钩子、制定密钥轮换策略和进行运行时检测，防止在开发生命周期中泄露凭据。Agent 会对代码、配置、日志或 AI 对话历史中的密钥采取零容忍策略，在泄漏内容进入版本控制、CI 产物或生产日志之前将其拦截。

源代码中的密钥是现代应用发生安全漏洞的最常见原因。一个已提交的 API 密钥在推送到公开仓库后的几分钟内，就可能危及整个云账户。自动化机器人会持续扫描 GitHub 中暴露的凭据，从提交到遭利用的平均时间不到 15 分钟。这项技能会在每个阶段拦截密钥，从而防止此类问题。

保护机制分为三道防线：提交前（防止密钥进入仓库）、CI/CD（捕获绕过提交前检查的密钥）和运行时（检测并脱敏日志、错误消息和 AI Agent 输出中的密钥）。每道防线都独立运作；若一道失效，下一道便会捕获泄漏。系统会按计划强制轮换密钥，确保即使发生未检测到的泄漏，其影响范围也有限。

使用场景

• 为新仓库设置妥善的密钥管理
• 添加提交前钩子，防止凭据泄漏
• 审计现有仓库中是否存在已提交的密钥
• 配置带有密钥扫描关卡的 CI/CD 流水线
• 实施密钥轮换策略
• 防止 Agent 在输出中暴露密钥

工作原理

graph TD
    A[Developer / Agent Writes Code] --> B[Ring 1: Pre-Commit Hook]
    B --> C{Secrets Detected?}
    C -->|Yes| D[Block Commit + Alert]
    C -->|No| E[Allow Commit]
    E --> F[Ring 2: CI/CD Scan]
    F --> G{Secrets in Diff?}
    G -->|Yes| H[Fail Pipeline + Alert]
    G -->|No| I[Continue Pipeline]
    I --> J[Ring 3: Runtime Detection]
    J --> K[Redact Secrets in Logs]
    J --> L[Redact Secrets in Agent Output]
    K --> M[Production Safe]
    L --> M
    N[Rotation Schedule] --> O[Rotate Keys Monthly]
    O --> P[Update Secrets Manager]
    P --> Q[Deploy Updated References]

三道独立防线确保密钥泄漏必须绕过所有三层才能造成损害。轮换计划可限制任何未检测到的泄漏所造成的影响范围。

实施

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks

  - repo: local
    hooks:
      - id: dotenv-check
        name: Check .env files not committed
        entry: bash -c 'git diff --cached --name-only | grep -E "\.env($|\.)" && exit 1 || exit 0'
        language: system
        pass_filenames: false

import re
from dataclasses import dataclass

@dataclass
class SecretPattern:
    name: str
    pattern: str
    severity: str

SECRET_PATTERNS = [
    SecretPattern("AWS Access Key", r"AKIA[0-9A-Z]{16}", "CRITICAL"),
    SecretPattern("AWS Secret Key", r"(?i)aws_secret_access_key\s*=\s*[A-Za-z0-9/+=]{40}", "CRITICAL"),
    SecretPattern("GitHub Token", r"gh[ps]_[A-Za-z0-9_]{36,}", "CRITICAL"),
    SecretPattern("Generic API Key", r"(?i)(api[_-]?key|apikey)\s*[:=]\s*['\"][A-Za-z0-9]{20,}['\"]", "HIGH"),
    SecretPattern("Private Key", r"-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----", "CRITICAL"),
    SecretPattern("Cloudflare Token", r"(?i)cloudflare.*(?:token|key)\s*[:=]\s*['\"][A-Za-z0-9_-]{40,}['\"]", "CRITICAL"),
    SecretPattern("JWT Token", r"eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}", "HIGH"),
    SecretPattern("Database URL", r"(?:postgres|mysql|mongodb)://\w+:[^@\s]+@", "CRITICAL"),
]

class SecretScanner:
    def __init__(self, patterns: list[SecretPattern] = SECRET_PATTERNS):
        self.patterns = [(p, re.compile(p.pattern)) for p in patterns]

    def scan_text(self, text: str, source: str = "unknown") -> list[dict]:
        findings = []
        for pattern, compiled in self.patterns:
            for match in compiled.finditer(text):
                findings.append({
                    "type": pattern.name,
                    "severity": pattern.severity,
                    "source": source,
                    "position": match.start(),
                    "preview": self._redact(match.group(), keep_chars=4),
                })
        return findings

    def redact_output(self, text: str) -> str:
        """Redact any detected secrets from agent output."""
        for pattern, compiled in self.patterns:
            text = compiled.sub(f"[REDACTED:{pattern.name}]", text)
        return text

    @staticmethod
    def _redact(secret: str, keep_chars: int = 4) -> str:
        if len(secret) <= keep_chars * 2:
            return "*" * len(secret)
        return secret[:keep_chars] + "*" * (len(secret) - keep_chars * 2) + secret[-keep_chars:]

class SecretRotationPolicy:
    ROTATION_SCHEDULES = {
        "CRITICAL": 30,
        "HIGH": 90,
        "MEDIUM": 180,
    }

    def check_rotation_due(self, secret_metadata: dict) -> bool:
        from datetime import datetime, timedelta
        last_rotated = datetime.fromisoformat(secret_metadata["last_rotated"])
        max_age = self.ROTATION_SCHEDULES[secret_metadata["severity"]]
        return datetime.now() - last_rotated > timedelta(days=max_age)

最佳实践

• 在任何新仓库中，首先安装提交前钩子
• 切勿忽略密钥检测结果；应修复问题，或证明它们是误报
• 将密钥存储在专用的密钥管理器中（Wrangler secrets、Vault、AWS Secrets Manager）
• 每 30 天轮换一次 CRITICAL 密钥（云凭据、API 密钥）
• 对所有日志输出、错误消息和 Agent 对话历史中的密钥进行脱敏
• 定期扫描 git 历史记录（gitleaks detect）；已提交后删除的密钥仍会保留在历史记录中

平台兼容性

平台	支持情况	备注
Cursor	完整	提交前检查 + 扫描
VS Code	完整	gitleaks 扩展
Windsurf	完整	密钥检测
Claude Code	完整	提交前集成
Cline	完整	安全扫描
aider	完整	支持提交前钩子

相关技能

• Agent 安全扫描 - 更全面的安全分析，在三层扫描流水线中包含密钥检测
• 沙箱加固 - 通过文件系统范围和权限边界限制 Agent 访问密钥，实现执行隔离
• CodeQL & Semgrep - 静态分析规则，可检测代码中硬编码的凭据和不安全的密钥处理模式

关键词

secret-protection credential-leak pre-commit gitleaks secret-rotation redaction .env-scanning api-key-security

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License