Rotação e segurança de segredos

Por que os segredos precisam ser alternados

Políticas de expiração de chaves de 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 para agentes

# 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 para segredos

# 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

Verificação de segredos: truffleHog

# 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: proteção de pré-confirmação

# 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')

O que fazer se uma chave for exposta

# 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.')

Detectando uso não autorizado

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()

Definindo limites de gastos para chaves de 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')

Princípio do menor privilégio para chaves

# 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')

Criando uma verificação de integridade das chaves

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')

Verificação de conhecimento: rotação e segurança de segredos

Recapitulação: rotação e segurança de segredos