AI Agents · 课时

密钥轮换与安全性

Q: 「密钥轮换与安全性」这节课中我会学到什么？

密钥过期、轮换策略和密钥保管库解决方案（AWS Secrets Manager）。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

密钥过期、轮换策略和密钥保管库解决方案（AWS Secrets Manager）。

密钥轮换与安全性 是 CoddyKit 上的免费 AI Agents 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

为什么需要轮换机密信息

即使机密信息从未被明确暴露，定期轮换也能限制未被发现的入侵造成的损害。6 个月前被悄悄窃取的密钥，在轮换后就会失效。

许多安全标准（SOC 2、PCI-DSS）要求定期轮换机密信息。构建便于轮换的代理代码是一种专业实践。

API 密钥过期策略

不同提供商的过期策略各不相同。有些允许您为密钥设置过期日期；另一些提供的密钥除非手动轮换，否则永不过期。请定期审核密钥，并为手动轮换设置日历提醒。

# Key rotation schedule by provider (as of mid-2025):
# OpenAI: no automatic expiry, rotate manually every 90 days
# Anthropic: no automatic expiry, rotate manually every 90 days
# Google Cloud: API keys can have expiry dates set in the console
# AWS: IAM access keys: rotate every 90 days (AWS Security Hub recommends)
# Tavily: no automatic expiry, rotate when suspected compromise

# Best practices:
# - Set a recurring calendar event: 'Rotate API keys'
# - Document when each key was last rotated
# - Store rotation date in a secrets manager, not a spreadsheet
print('Schedule key rotation every 60-90 days as a standing task')

用于代理的 AWS Secrets Manager

AWS Secrets Manager 可以安全地存储机密信息，并支持自动轮换。代理在运行时通过 SDK 获取当前的机密值——无需硬编码密钥，也无需在生产环境中使用 .env 文件。

# pip install boto3
import boto3
import json

def get_secret(secret_name: str, region: str = 'us-east-1') -> dict:
    client = boto3.client('secretsmanager', region_name=region)
    response = client.get_secret_value(SecretId=secret_name)
    return json.loads(response['SecretString'])

# Store secrets as JSON in Secrets Manager:
# Secret name: 'prod/myagent/api-keys'
# Secret value: {'OPENAI_API_KEY': 'sk-...', 'SEARCH_API_KEY': 'tvly-...'}

# Fetch at agent startup:
# secrets = get_secret('prod/myagent/api-keys')
# openai_key = secrets['OPENAI_API_KEY']

使用 HashiCorp Vault 管理机密信息

HashiCorp Vault 是一个开源的机密信息管理系统，在企业环境中广受欢迎。它支持动态机密信息、细粒度访问控制，以及对每次机密信息访问进行审计日志记录。

# pip install hvac
import hvac
import os

def get_vault_secret(path: str, key: str) -> str:
    client = hvac.Client(
        url=os.environ['VAULT_ADDR'],
        token=os.environ['VAULT_TOKEN']  # from env, not hard-coded
    )

    if not client.is_authenticated():
        raise RuntimeError('Vault authentication failed')

    response = client.secrets.kv.read_secret_version(path=path)
    return response['data']['data'][key]

# Usage:
# openai_key = get_vault_secret('secret/myagent', 'OPENAI_API_KEY')

# Vault provides:
# - Audit log of every secret read
# - Lease-based secrets that expire automatically
# - Fine-grained ACL policies

机密信息扫描：truffleHog

truffleHog 会扫描 Git 仓库，查找可能被意外提交的机密信息。它会检查完整的提交历史，而不仅是当前代码。在将仓库公开之前运行它。

# pip install trufflehog
# Or: brew install trufflehog (Mac)

# Scan current git repository:
# trufflehog git file://.

# Scan only recent commits:
# trufflehog git file://. --since-commit HEAD~50

# Scan a GitHub repository:
# trufflehog github --repo https://github.com/yourorg/yourrepo

# truffleHog detects:
# - OpenAI API keys (sk-proj-...)
# - Anthropic keys (sk-ant-...)
# - AWS access keys (AKIA...)
# - Private keys (BEGIN RSA PRIVATE KEY)
# - And 700+ other secret patterns

print('Run truffleHog before open-sourcing any private repository')

git-secrets：提交前保护

git-secrets 是 AWS 提供的 Git 钩子工具，可以阻止包含符合已配置模式的机密信息的提交。它会在每次提交前运行，如果发现匹配的机密信息模式，就会拒绝该提交。

# Install:
# brew install git-secrets  (Mac)
# or: git clone https://github.com/awslabs/git-secrets && make install

# Set up in your repo:
# git secrets --install
# git secrets --register-aws  (adds AWS key patterns)

# Add custom patterns (e.g., OpenAI keys):
# git secrets --add 'sk-proj-[A-Za-z0-9_-]{48,}'

# Now attempting to commit a secret:
# git add agent.py  # file containing API key
# git commit -m 'add agent'
# [ERROR] Untracked secret found in agent.py
# Commit blocked!

print('git-secrets prevents secrets from ever entering git history')

密钥泄露时该怎么办

这是针对已泄露 API 密钥的分步应对方案。速度至关重要——自动扫描器会在提交后的几分钟内抓取暴露的密钥。

# INCIDENT RESPONSE: Exposed API Key
#
# Step 1 (IMMEDIATE): Revoke the exposed key
#   OpenAI: platform.openai.com/api-keys -> Delete key
#   Anthropic: console.anthropic.com -> API Keys -> Delete
#   AWS: IAM console -> Access Keys -> Deactivate/Delete
#
# Step 2: Generate a new key
#   Create a replacement key with the same permissions
#
# Step 3: Update everywhere
#   - Local .env
#   - Staging environment
#   - Production environment (Secrets Manager / Vault)
#   - CI/CD secrets (GitHub Actions, GitLab CI)
#
# Step 4: Audit usage
#   - Check provider usage logs for unauthorized activity
#   - Check billing for unexpected charges
#
# Step 5: Prevent recurrence
#   - Add pattern to git-secrets
#   - Enable pre-commit hooks
print('Revoke first. Then rotate. Then audit. Then prevent.')

检测未经授权的使用

轮换密钥后，请检查它是否曾被未经授权地使用。大多数服务提供商都会提供使用日志和支出提醒，帮助您发现被盗密钥是否曾被用于发起 API 调用。

import openai
import datetime

client = openai.OpenAI(api_key='YOUR_NEW_API_KEY')

# Check OpenAI usage for the past day
# (requires usage read permissions on the key)
def check_recent_usage():
    # OpenAI billing/usage dashboard: platform.openai.com/usage
    # Set up spending alerts: platform.openai.com/account/limits
    # - 'Email alert' when monthly spend exceeds $X

    print('Suspicious usage indicators to look for:')
    print('1. Spikes in token usage outside business hours')
    print('2. Requests from unexpected IP addresses')
    print('3. Models or endpoints you do not use')
    print('4. Unusual cost patterns')
    print('\nAlways set spending limits and alerts on new API keys')

check_recent_usage()

设置 API 密钥的支出限额

为 API 密钥设置严格的支出限额，以限制密钥泄露造成的损失。即使有人使用您的密钥，也无法产生无限额的账单。

# OpenAI spending limits:
# platform.openai.com/account/limits
# - Set 'Monthly budget' (hard limit — API stops when reached)
# - Set 'Email notification threshold' (soft alert)

# Best practice for agent keys:
# - Development key: $5-10/month hard limit
# - Staging key: $20-50/month hard limit
# - Production key: Based on expected usage + 2x buffer
# - CI/CD test key: $5/month hard limit (mocks should handle most tests)

# Anthropic:
# console.anthropic.com -> Settings -> Spending Limits

# Use separate keys per environment so limits are independent
print('Spending limits cap the blast radius of a compromised key')

密钥的最小权限原则

为每个 API 密钥仅授予其所需的权限。只能读取数据的密钥不应拥有写入或删除权限。大多数服务提供商都支持限定范围或限制权限的密钥。

# Principle of Least Privilege applied to agent API keys:

# OpenAI key scopes (if API allows scoped keys):
# - Read-only key: for logging/audit agents
# - Write key: for agents that create content
# - Admin key: NEVER use in agent code — only for management

# Tavily API:
# - Basic plan: limited search results
# - Research plan: more results, images
# Use the plan appropriate to the agent's needs

# AWS IAM for agents:
# Create a dedicated IAM role/user per agent with only the S3/DynamoDB
# paths it needs to read/write. No admin permissions.

# Rule: If the key is compromised, how much damage can be done?
# Minimize the answer through scoped permissions.
print('Least privilege limits blast radius of any single key compromise')

构建密钥健康检查

在代理启动时验证 API 密钥是否仍然有效。应立即发现已过期或已撤销的密钥，而不是等到代理已经消耗资源、执行任务到一半时才失败。

import openai

def check_openai_key_health(api_key: str) -> bool:
    try:
        client = openai.OpenAI(api_key=api_key)
        # Make a minimal API call to verify the key
        models = client.models.list()
        print(f'OpenAI key valid. {len(list(models))} models available.')
        return True
    except openai.AuthenticationError:
        print('ERROR: OpenAI API key is invalid or expired.')
        return False
    except openai.PermissionDeniedError:
        print('ERROR: API key lacks required permissions.')
        return False

# At agent startup:
# import os
# if not check_openai_key_health(os.environ['OPENAI_API_KEY']):
#     raise SystemExit('Cannot start: invalid API key')

知识检查：密钥轮换与安全

测试您对密钥轮换和安全实践的理解。

回顾：密钥轮换与安全

现在，您已经掌握了面向生产代理的完整密钥安全策略：

将 API 密钥轮换作为日常实践，每 60 至 90 天轮换一次
在生产环境中使用 AWS Secrets Manager 或 HashiCorp Vault
在将任何代码仓库开源之前运行 truffleHog
将 git-secrets 安装为提交前钩子，防止意外提交
如果密钥泄露：立即撤销，然后轮换，最后审计使用情况
为所有 API 密钥设置支出限额，以限制泄露造成的损失
应用最小权限原则——为每个密钥仅授予其所需的权限

常见问题解答

「密钥轮换与安全性」课时是免费的吗？

是的 — 「密钥轮换与安全性」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「密钥轮换与安全性」这节课中我会学到什么？

密钥过期、轮换策略和密钥保管库解决方案（AWS Secrets Manager）。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「密钥轮换与安全性」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents