Módulo 5: Secrets Management

1. Introducción: Secrets Management

Descripción

En los módulos anteriores construiste defensas para proteger el flujo de datos de tu sistema AI: un threat model documentado (M1), mapeo OWASP (M2), defensa contra prompt injection (M3), y sanitización completa de inputs/outputs (M4). Tu pipeline de datos es sólido. Pero hay un vector de compromiso que ningún guardrail, filtro, o validator puede prevenir: si un atacante obtiene tus API keys, puede usar tus credenciales sin tocar tu aplicación.

Piensa en lo que tienes ahora mismo en tu archivo .env:

OPENAI_API_KEY=sk-proj-abc123...
ANTHROPIC_API_KEY=sk-ant-xyz789...
DATABASE_URL=postgresql://user:password@host:5432/mydb
PINECONE_API_KEY=pcsk_abc...
REDIS_URL=redis://:secretpassword@host:6379

Cada una de esas líneas es una credencial de alto valor. Con tu API key de OpenAI, un atacante puede generar $10,000+ de consumo en horas. Con tu API key de Anthropic con acceso a Claude Opus, el costo puede ser mayor. Con tu DATABASE_URL, tiene acceso a todos tus datos. Y a diferencia de una base de datos hackeada donde el daño es detectable, el robo de una API key es silencioso — el atacante usa tu cuenta y tú pagas la factura.

El archivo .env con .gitignore funciona para desarrollo local. Pero en producción, es insuficiente por razones concretas que este módulo hace tangibles: no hay rotación automática (si una key se filtra, sigue activa hasta que alguien la cambie manualmente), no hay audit trail (no sabes quién accedió a qué secret ni cuándo), no hay granularidad (todos los procesos ven todas las keys), y no escala con equipos (compartir secrets vía Slack o 1Password es un anti-pattern de seguridad).

Este módulo te lleva de .env a secrets management enterprise-grade. No significa que todos necesiten HashiCorp Vault — significa que necesitas entender los conceptos (rotación, audit trails, least privilege, dynamic secrets) y poder implementarlos con las herramientas apropiadas a tu escala.

¿Por qué un módulo completo para secrets management?

La decisión de dedicar un módulo a secrets management (separado de las defensas de datos de los módulos 3-4) es deliberada. Hay tres razones:

1. Secrets son un asset class diferente

Los módulos 3-4 protegen el flujo de datos: lo que entra y sale del LLM. Los secrets protegen el acceso: quién puede usar qué servicio. Un sistema con sanitización perfecta pero API keys expuestas es como una casa con alarma pero con las llaves debajo del tapete. El atacante no necesita romper tu alarma — entra por la puerta.

2. Las API keys de LLM son targets de alto valor

A diferencia de una API key de un servicio gratuito, las keys de LLM permiten acceso directo a capacidad computacional costosa. Un bot que descubre tu key de OpenAI puede hacer miles de llamadas a GPT-4o en minutos. GitHub reporta que escanea más de 100 millones de commits diarios buscando secrets expuestos — y las API keys de LLM son de las más buscadas.

3. Compliance lo requiere

SOC 2, ISO 27001, HIPAA, y PCI-DSS tienen requisitos específicos sobre gestión de credenciales: rotación periódica, audit trails, principio de menor privilegio, encryption at rest. Si tu empresa necesita cumplir con alguno de estos frameworks, .env no es suficiente.

¿Qué aprenderás en este módulo?

Al terminar este módulo vas a poder:

Articular por qué .env es insuficiente para producción con argumentos técnicos concretos: sin rotación, sin audit, sin granularidad, sin encryption-at-rest
Comprender los conceptos fundamentales de secrets management: rotation, audit trails, least privilege, dynamic secrets, encryption at rest, access policies
Conocer HashiCorp Vault como la referencia open-source: architecture, transit engine, dynamic secrets, policies, y cuándo es overkill vs necesario
Implementar API key rotation con zero-downtime: estrategias de dual-key, rotation schedulers, y automation con Python
Usar cloud KMS (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault) con código Python funcional para al menos un proveedor
Configurar token lifecycle management: creación con scope mínimo, rotación programada, revocación inmediata cuando se sospecha compromiso
Implementar audit trails: logging de quién accedió a qué secret, cuándo, y desde dónde — integrado con structured logging
Integrar secrets management con FastAPI usando dependency injection, con fallback y resilience cuando el secrets service no está disponible

Roadmap del módulo

Este módulo tiene 8 cápsulas que construyen tu sistema de secrets management capa por capa:

#	Cápsula	Qué aprenderás
01	Introducción: Secrets Management	Por qué este módulo, roadmap, conexión con el proyecto, setup
02	Más Allá de .env: Por Qué No Es Suficiente	Limitaciones de .env, incidentes reales, transición a producción
03	HashiCorp Vault: Conceptos y Setup	Architecture, secrets engines, auth methods, policies, hvac client
04	API Key Rotation Strategies	Zero-downtime rotation, dual-key, automation, schedules
05	Cloud KMS: AWS, GCP, Azure	Secrets Manager por proveedor, unified Python interface, migración
06	Token Lifecycle y Audit Trails	Lifecycle management, audit logging, compliance, revocación
07	Least Privilege e Integración con Python	Scoped tokens, per-service keys, FastAPI integration, fallback
08	Proyecto: Secrets Management Setup	Setup completo con secrets client, rotation scheduler, audit logger

La progresión es: contexto (01) → problema (02) → solución enterprise (03) → rotación (04) → cloud (05) → lifecycle (06) → integración (07) → proyecto (08).

Las cápsulas 02-03 establecen el por qué y el qué. La cápsula 04 aborda la operación más crítica (rotación). La cápsula 05 cubre las opciones cloud que la mayoría usará. Las cápsulas 06-07 completan el ciclo con lifecycle management e integración. La cápsula 08 consolida todo en el proyecto.

Contexto en la guía

Esta guía tiene 8 módulos organizados en 3 fases:

Phase 1: Security Foundations (Módulos 1-3)
├── Módulo 1: AI Security Landscape & Threat Model    ✅ COMPLETADO
├── Módulo 2: OWASP LLM Top 10 Deep Dive             ✅ COMPLETADO
└── Módulo 3: Prompt Injection — Attacks & Defenses   ✅ COMPLETADO

Phase 2: Defense Implementation (Módulos 4-6)
├── Módulo 4: Input & Output Sanitization             ✅ COMPLETADO
├── Módulo 5: Secrets Management                      ← ESTÁS AQUÍ
└── Módulo 6: Data Privacy & PII Protection

Phase 3: Production Security (Módulos 7-8)
├── Módulo 7: Security Testing & Auditing
└── Módulo 8: Proyecto Integrador — Secured AI System

El Módulo 4 te dio un pipeline de sanitización que limpia datos antes y después del LLM. Ese pipeline usa API keys para acceder al modelo. Hasta ahora, esas keys vienen de un .env. Después de este módulo, vienen de un secrets manager con rotación, audit trails, y least privilege.

La relación con los módulos anteriores es de complemento:

Módulo 3 (Injection Defense)          Módulo 5 (Secrets Management)
─────────────────────────             ─────────────────────────
Protege el flujo de datos             Protege el acceso a servicios
Defiende contra ataques al LLM       Defiende contra robo de credenciales
El código del pipeline                Las credenciales del pipeline
Foco: LLM01                          Foco: infraestructura de acceso

La conexión práctica es directa: el código de los módulos anteriores no cambia — solo la fuente de las credenciales. Donde antes tenías os.getenv("OPENAI_API_KEY"), ahora tienes secrets_client.get("openai-api-key") con rotación automática y audit trail.

Prerequisites

Para este módulo necesitas:

Módulos 1-4 completados: Threat Model Document, OWASP Mapping Audit, Injection Defense Pipeline, Sanitization Pipeline
Python 3.10+ instalado
Una API key de OpenAI (o proveedor compatible) — la usarás como ejemplo de secret a gestionar
Familiaridad con FastAPI — dependency injection, middleware
Docker instalado (opcional, para Vault en dev mode)

Setup técnico

Si ya tienes el entorno de los módulos anteriores, actívalo y agrega las dependencias nuevas:

source security-guide-env/bin/activate  # macOS/Linux
# security-guide-env\Scripts\activate   # Windows

pip install hvac boto3 cryptography schedule
pip install google-cloud-secret-manager  # Si usas GCP (opcional)
pip install azure-keyvault-secrets azure-identity  # Si usas Azure (opcional)

Si estás empezando desde este módulo:

python -m venv security-guide-env
source security-guide-env/bin/activate

pip install hvac boto3 cryptography schedule fastapi uvicorn pydantic
pip install python-dotenv  # Solo para dev/transición

export OPENAI_API_KEY="sk-..."

Verificación rápida:

import os
import json
from datetime import datetime
from cryptography.fernet import Fernet

key = Fernet.generate_key()
cipher = Fernet(key)

secret_value = "sk-proj-my-openai-key-12345"
encrypted = cipher.encrypt(secret_value.encode())
decrypted = cipher.decrypt(encrypted).decode()

print(f"Original:  {secret_value}")
print(f"Encrypted: {encrypted[:50]}...")
print(f"Decrypted: {decrypted}")
print(f"Match: {secret_value == decrypted}")

audit_entry = {
    "timestamp": datetime.utcnow().isoformat(),
    "action": "secret_accessed",
    "secret_name": "openai-api-key",
    "accessor": "setup-check",
}
print(f"\nAudit entry: {json.dumps(audit_entry, indent=2)}")
# Output esperado:
# Original:  sk-proj-my-openai-key-12345
# Encrypted: gAAAAABn...
# Decrypted: sk-proj-my-openai-key-12345
# Match: True
#
# Audit entry: {
#   "timestamp": "2026-03-13T...",
#   "action": "secret_accessed",
#   "secret_name": "openai-api-key",
#   "accessor": "setup-check"
# }

Si ves las salidas correctas, tu setup está listo. Las dependencias clave de este módulo son:

Paquete	Para qué
`hvac`	Cliente Python para HashiCorp Vault
`boto3`	AWS SDK (Secrets Manager, KMS)
`cryptography`	Encryption local, Fernet symmetric encryption
`schedule`	Rotation scheduler
`google-cloud-secret-manager`	GCP Secret Manager (opcional)
`azure-keyvault-secrets`	Azure Key Vault (opcional)

Conexión con el proyecto del módulo

Este módulo cierra con el proyecto Secrets Management Setup: un sistema completo de gestión de secrets para tu aplicación AI. Es el quinto artefacto de la guía y se diferencia de los anteriores en que es infraestructura, no código de aplicación.

El Secrets Management Setup incluye:

Secrets Client — Capa de abstracción sobre Vault o cloud KMS con interface unificada
Rotation Scheduler — Rotación automática de API keys con zero-downtime
Audit Logger — Registro de cada acceso a secrets con timestamps y accessor identity
FastAPI Integration — Dependency injection para secrets en endpoints
Fallback Strategy — Resilience cuando el secrets service no está disponible

El setup se integra con tu pipeline existente:

Request
  │
  ▼
┌──────────────────────────┐
│  Secrets Client          │ ← Obtiene API key del vault/KMS
├──────────────────────────┤
│  Input Sanitizer (M4)    │ ← Tu pipeline del Módulo 4
├──────────────────────────┤
│  Injection Detector (M3) │ ← Tu pipeline del Módulo 3
├──────────────────────────┤
│  LLM Processing          │ ← Usa la key del secrets client
├──────────────────────────┤
│  Output Validator (M4)   │ ← Validación de respuesta
├──────────────────────────┤
│  Audit Logger            │ ← Registra acceso a secrets
└──────────────────────────┘
  │
  ▼
Response

En el Módulo 8 (proyecto integrador), el Secrets Management Setup se integra con el Injection Defense Pipeline (M3), el Sanitization Pipeline (M4), y el PII Protection Layer (M6) para formar el sistema completo asegurado.

Módulo 1: Threat Model Document (base)
Módulo 2: + OWASP Mapping Audit (mapeo detallado)
Módulo 3: + Injection Defense Pipeline (defensa contra LLM01)
Módulo 4: + Sanitization Pipeline (input/output)
Módulo 5: + Secrets Management Setup (credenciales)      ← LO PRODUCES AQUÍ
Módulo 6: + PII Protection Layer (datos sensibles)
Módulo 7: + Security Audit Report (validación)
Módulo 8: → Secured AI System (integración total)

Qué hace diferente a este módulo vs Production Best Practices (#13)

Si completaste Production Best Practices (#13), ya usas .env con python-dotenv. Este módulo no repite ese contenido — lo profundiza:

Concepto	Production Best Practices (#13)	Este módulo (M5)
Secrets storage	`.env` con `python-dotenv`	Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault
Rotation	"Rota tus keys periódicamente"	Automation con zero-downtime, dual-key strategy, scheduler
Audit	No cubierto	Logging de cada acceso con timestamps, accessor, contexto
Least privilege	Mención básica	Scoped tokens, per-service keys, IAM policies por servicio
Encryption	`.env` no encripta	Encryption at rest, transit encryption con Vault
Fallback	No cubierto	Cache local con TTL, fallback a encrypted storage
Team scaling	"No compartas keys por Slack"	Secret distribution con policies, per-environment configs

La regla es: si algo te suena familiar de #13, aquí ves la versión enterprise con código completo y consideraciones de producción.

Lo que NO cubre este módulo

Para mantener el foco:

Prompt injection defense: Eso fue el Módulo 3. Los secrets no previenen ataques al modelo.
Input/output sanitization: Eso fue el Módulo 4. Los secrets protegen acceso, no datos.
PII protection: Eso es el Módulo 6. Los secrets protegen credenciales, no datos personales.
Full DevSecOps pipeline: Mencionamos CI/CD integration pero no cubrimos Jenkins, GitHub Actions, o Terraform en profundidad.
Compliance legal completa: Mencionamos SOC 2 e ISO 27001 como motivación, no como guía de compliance.
Hardware Security Modules (HSM): Mencionamos HSM como nivel enterprise pero no cubrimos configuración.

La analogía: las llaves de un edificio

Imagina que tu sistema AI es un edificio corporativo:

Edificio corporativo                  Sistema AI
────────────────────────              ────────────────────────
Llaves del edificio                   API keys (OpenAI, Anthropic)
Llaves de la oficina                  Database credentials
Tarjeta de acceso al data center      Cloud provider keys
Llave de la caja fuerte              Encryption keys

¿Cómo gestionas las llaves?          ¿Cómo gestionas los secrets?
────────────────────────              ────────────────────────
Bajo el tapete (.env)                 Archivo .env en el servidor
En tu bolsillo (env vars)             Variables de entorno del OS
En un llavero (keychain)              Encrypted local storage
En una oficina de seguridad (vault)   HashiCorp Vault / Cloud KMS

Con .env es como dejar las llaves bajo el tapete: funciona, pero cualquiera que sepa dónde mirar tiene acceso. Un secrets manager es la oficina de seguridad del edificio: las llaves se guardan en un lugar seguro, se registra quién las toma, se cambian periódicamente, y cada persona solo recibe las llaves que necesita.

La progresión de este módulo sigue la misma lógica:

📋 Cápsula 02: Entender por qué el tapete no es seguro
🏗️ Cápsula 03: Conocer la oficina de seguridad (Vault)
🔄 Cápsula 04: Aprender a cambiar las llaves periódicamente (rotation)
☁️ Cápsula 05: Opciones cloud para la oficina de seguridad (KMS)
📝 Cápsula 06: Registrar quién toma qué llave (audit trails)
🔑 Cápsula 07: Dar solo las llaves necesarias (least privilege)
🏢 Cápsula 08: Montar tu oficina de seguridad completa (proyecto)

Tu sistema: ejercicio de pre-evaluación

Antes de empezar con las cápsulas técnicas, toma 5 minutos para evaluar tu sistema actual:

¿Tienes API keys de LLM en un archivo .env en producción? → Si sí, la cápsula 02 es urgente
¿Cuándo fue la última vez que rotaste tus API keys? → Si la respuesta es "nunca" o "no sé", la cápsula 04 es prioritaria
¿Sabes quién accedió a qué secret en las últimas 24 horas? → Si no, la cápsula 06 te da audit trails
¿Todos tus servicios ven todas las API keys? → Si sí, la cápsula 07 implementa least privilege
¿Qué pasa si tu secrets service se cae? → Si no sabes, la cápsula 07 cubre fallback y resilience
¿Puedes revocar una key comprometida en menos de 5 minutos? → Si no, la cápsula 06 tiene emergency revocation

Si respondiste de forma preocupante a más de tres preguntas, sigue el módulo completo en orden. Si ya tienes respuestas sólidas para algunas, enfócate en las cápsulas que cubren tus gaps — pero lee las demás por las técnicas avanzadas que podrían mejorar lo que ya tienes.

Los 4 pilares de secrets management

Todo sistema de secrets management enterprise se construye sobre cuatro pilares. Cada cápsula refuerza uno o más de estos pilares:

┌────────────────────────────────────────────────────────────────┐
│                    SECRETS MANAGEMENT                           │
│                                                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │  Encryption  │  │  Rotation    │  │  Audit       │         │
│  │  at Rest     │  │  Automática  │  │  Trails      │         │
│  │              │  │              │  │              │         │
│  │  Los secrets │  │  Las keys se │  │  Cada acceso │         │
│  │  están       │  │  cambian     │  │  queda       │         │
│  │  encriptados │  │  periódica-  │  │  registrado  │         │
│  │  en storage  │  │  mente sin   │  │  con quién,  │         │
│  │              │  │  downtime    │  │  cuándo, qué │         │
│  │  Cap: 03, 05 │  │  Cap: 04     │  │  Cap: 06     │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
│                                                                │
│  ┌──────────────┐                                              │
│  │  Least       │  El sistema completo:                        │
│  │  Privilege   │  - Encripta secrets en storage               │
│  │              │  - Los rota automáticamente                  │
│  │  Cada        │  - Registra cada acceso                      │
│  │  servicio    │  - Limita acceso por servicio                │
│  │  solo ve lo  │                                              │
│  │  que necesita│  Cap: 07, 08                                 │
│  │              │                                              │
│  │  Cap: 07     │                                              │
│  └──────────────┘                                              │
└────────────────────────────────────────────────────────────────┘

Estos pilares no son independientes — se refuerzan mutuamente. Encryption sin rotation significa que una key comprometida permanece activa. Rotation sin audit means que no sabes si la rotación ocurrió correctamente. Audit sin least privilege significa que el log registra accesos legítimos pero innecesarios. El proyecto de la cápsula 08 integra los cuatro pilares.

Errores comunes al abordar secrets management

"Ya tengo .gitignore, mis secrets están seguros"

.gitignore previene que commitees el .env accidentalmente. No previene que alguien lo lea del servidor, que un backup lo incluya, que un log lo capture, o que un colega lo comparta por Slack. .gitignore es necesario pero absolutamente insuficiente.

"Solo soy un developer, no necesito enterprise security"

Si tu API key de OpenAI se filtra, el daño es financiero e inmediato independientemente del tamaño de tu equipo. Un indie developer con una key robada puede recibir una factura de $10,000. La escala cambia la solución (no necesitas Vault), pero los conceptos (rotación, audit) aplican a todos.

"Rotaré las keys cuando tenga tiempo"

La rotación manual no ocurre. En la práctica, si no es automática, no se hace. El Módulo 5 te da automation para que la rotación sea un proceso, no una intención.

"Los secrets del proveedor cloud están seguros por defecto"

Las API keys de OpenAI y Anthropic no vienen con encryption at rest, rotación automática, ni audit trails por defecto. Esas capas las implementas tú. El proveedor del LLM te da la key — tú decides cómo la proteges.

"Es demasiado complejo para mi proyecto"

AWS Secrets Manager o GCP Secret Manager con un wrapper de Python son ~100 líneas de código adicionales. El costo es ~$2/mes para 5 secrets. La complejidad real es aprender los conceptos — una vez entendidos, la implementación es directa. Este módulo descompone esa complejidad en pasos manejables.

Trade-offs: seguridad vs velocidad de desarrollo

Un tema que atraviesa todo el módulo es el trade-off entre seguridad y agilidad:

Enfoque	Seguridad	Velocidad de dev	Costo	Ideal para
`.env` sin protección	❌ Mínima	✅ Máxima	✅ $0	Prototipos, hackathons
`.env` + encryption local	⚠️ Baja	✅ Alta	✅ $0	Dev local, proyectos personales
Cloud KMS + rotación manual	✅ Media	⚠️ Media	⚠️ ~$2-5/mes	Startups, MVPs en producción
Cloud KMS + rotación automática	✅ Alta	⚠️ Media	⚠️ ~$5-20/mes	Producción con usuarios reales
Vault + dynamic secrets + audit	✅ Máxima	❌ Menor (setup complejo)	❌ ~$100+/mes	Enterprise, compliance

El objetivo no es maximizar seguridad — es elegir el nivel apropiado para tu contexto y escalar cuando sea necesario. Este módulo te prepara para cualquier nivel.

Escala de soluciones: no todos necesitan Vault

Un concepto clave que atraviesa todo el módulo: la solución correcta depende de tu escala. No todos necesitan HashiCorp Vault. Todos necesitan rotación y audit.

Escala	Solución recomendada	Costo
Indie/Freelancer	AWS Secrets Manager o GCP Secret Manager con rotación manual cada 90 días	~$0.40/secret/mes
Startup (2-10 devs)	Cloud KMS con rotación semi-automática (script + cron)	~$1-5/mes
Equipo mediano (10-50)	Cloud KMS con rotación automática + CI/CD integration	~$5-20/mes
Enterprise (50+)	HashiCorp Vault (self-hosted o HCP) con dynamic secrets	~$100+/mes

En cada cápsula verás las opciones por escala. La cápsula 03 cubre Vault como la referencia enterprise. La cápsula 05 cubre cloud KMS como la opción pragmática para la mayoría. El proyecto (cápsula 08) te permite elegir la que aplique a tu contexto.

Cómo usar cada cápsula

Cada cápsula técnica (02-07) sigue esta estructura:

Contexto — Por qué esta pieza existe y qué problema resuelve
Concepto — La teoría necesaria (40% del contenido)
Implementación — Código Python completo y ejecutable (60% del contenido)
Conexión con el proyecto — Cómo encaja en el Secrets Management Setup
Troubleshooting — 3-5 problemas comunes con soluciones
Ejercicios — 4-6 ejercicios prácticos con soluciones en <details>
Resumen — Puntos clave del tema
Recursos — 6-8 referencias para profundizar

Te recomiendo seguir las cápsulas en orden (02 → 07) porque la progresión construye sobre los conceptos anteriores. La cápsula 02 establece el problema. La cápsula 03 introduce la solución enterprise. Las cápsulas 04-05 cubren operaciones y opciones. Las cápsulas 06-07 completan con lifecycle e integración.

El pipeline completo como arquitectura

Antes de profundizar en cada componente (cápsulas 02-07), necesitas ver cómo el secrets management se integra en tu sistema AI. Este diagrama es la referencia para todo el módulo:

┌──────────────────────────────────────────────────────────────────┐
│                    SECRETS MANAGEMENT SETUP                       │
│                                                                  │
│  SECRETS LAYER                                                   │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐     │
│  │ 1. Provider    │→ │ 2. Policy      │→ │ 3. Cache       │     │
│  │    (Vault/KMS) │  │    Enforcer    │  │    (TTL-based) │     │
│  └────────────────┘  └────────────────┘  └────────────────┘     │
│           │                   │                   │              │
│           │          Secrets Client               │              │
│           ├───────────────────┴───────────────────┤              │
│           │                                       │              │
│  OPERATIONS LAYER                                 │              │
│  ┌────────────────┐  ┌────────────────┐          │              │
│  │ 4. Rotation    │  │ 5. Audit       │          │              │
│  │    Scheduler   │  │    Logger      │          │              │
│  └────────────────┘  └────────────────┘          │              │
│           │                   │                   │              │
│  APPLICATION LAYER                                │              │
│  ┌────────────────┐  ┌────────────────┐          │              │
│  │ 6. FastAPI     │  │ 7. Fallback    │          │              │
│  │    DI          │  │    & Circuit   │          │              │
│  │    Integration │  │    Breaker     │          │              │
│  └────────────────┘  └────────────────┘          │              │
│           │                                       │              │
│           ▼                                       │              │
│  ┌────────────────────────────────────────────────┘              │
│  │                                                               │
│  │  Tu aplicación AI:                                            │
│  │  Injection Defense (M3) + Sanitization (M4) + LLM API        │
│  │                                                               │
│  │  Donde antes tenías:  os.getenv("OPENAI_API_KEY")            │
│  │  Ahora tienes:        secrets_client.get("openai-api-key")   │
│  │                       → con rotation, audit, least privilege  │
│  │                                                               │
│  └───────────────────────────────────────────────────────────────┘
└──────────────────────────────────────────────────────────────────┘

Cada cápsula construye un bloque de este diagrama. La cápsula 08 los integra en el Secrets Management Setup como artefacto reutilizable.

Diferencia entre secrets y configuración

Un error común es tratar toda la configuración como secrets. No toda variable de entorno necesita protección enterprise:

Tipo	Ejemplo	¿Es un secret?	Tratamiento
API keys de LLM	`OPENAI_API_KEY`	✅ Sí — high value	Vault/KMS + rotación + audit
Database passwords	`DATABASE_PASSWORD`	✅ Sí — acceso a datos	Vault/KMS + rotación
Encryption keys	`JWT_SECRET`	✅ Sí — compromete auth	Vault/KMS + rotación cuidadosa
Webhook secrets	`STRIPE_WEBHOOK_SECRET`	✅ Sí — verificación	KMS + rotación
Service URLs	`DATABASE_HOST`	❌ No — no es sensible	Env vars o config file
Feature flags	`ENABLE_NEW_UI`	❌ No — no es sensible	Env vars o config service
Log level	`LOG_LEVEL`	❌ No — no es sensible	Env vars
Port	`PORT`	❌ No — no es sensible	Env vars

La regla es: si exponer el valor causa daño (financiero, acceso no autorizado, compromiso de datos), es un secret y necesita protección. Si no, es configuración y puede vivir en env vars normales.

Conceptos clave del módulo: glosario rápido

Antes de entrar en las cápsulas, estos son los conceptos que verás repetidamente:

Secret: Cualquier credencial, token, o key que otorga acceso a un servicio o recurso
Rotation: El proceso de reemplazar un secret activo por uno nuevo, invalidando el anterior
Audit trail: Registro inmutable de cada operación realizada sobre un secret (lectura, escritura, rotación, revocación)
Least privilege: Principio de dar a cada componente solo el acceso mínimo necesario para funcionar
Dynamic secrets: Credenciales generadas on-demand con tiempo de vida limitado (TTL) que se revocan automáticamente
Encryption at rest: Los secrets están encriptados cuando se almacenan, no legibles como texto plano
Transit encryption: Servicio que encripta/desencripta datos sin exponer las encryption keys
Secrets engine: Módulo de un secrets manager que almacena, genera, o encripta datos (e.g., KV, Transit, Database en Vault)
Auth method: Mecanismo por el cual un cliente se autentica ante el secrets manager (token, AppRole, IAM, etc.)
Policy: Regla que define qué operaciones puede realizar un cliente autenticado sobre qué paths de secrets
Lease: Período de validez de un secret dinámico — al expirar, el secret se revoca automáticamente
Circuit breaker: Patrón de resilience que detiene temporalmente las llamadas a un servicio fallido para evitar cascading failures
Fallback: Fuente alternativa de secrets cuando el provider principal no está disponible

El costo real de no gestionar secrets

Para que entiendas el peso de la gestión de secrets, estos son datos concretos de la industria:

Incidentes documentados

Patrón	Qué pasó	Impacto
Key en GitHub	Desarrollador commiteó `.env` con API keys de AWS. Bot automatizado encontró las keys en <5 minutos y provisionó instancias de mining.	$50,000+ en facturación antes de detección
Key en Docker image	API key de OpenAI hardcodeada en Dockerfile. Imagen pública en Docker Hub.	Consumo ilimitado de la cuenta hasta revocación
Key compartida por Slack	Equipo compartió API key por canal de Slack. Ex-empleado conservó acceso al canal.	Acceso no autorizado durante 6+ meses
Sin rotación	API key de producción no se rotó en 2 años. Empleado que la creó se fue. Nadie sabía si había sido comprometida.	Riesgo de acceso no detectado
Key en logs	API key logueada accidentalmente en structured logging. Logs enviados a Datadog. Accesibles a todo el equipo.	Exposición a audience amplia

Cifras de la industria

🔍 GitHub Secret Scanning detecta millones de secrets expuestos por año en repositorios públicos
💰 El costo promedio de un data breach relacionado con credenciales es $4.5M (IBM 2024)
⏱️ El tiempo promedio para detectar una credencial comprometida es 277 días (IBM 2024)
🤖 Bots automatizados encuentran API keys expuestas en GitHub en menos de 5 minutos desde el commit

Cada uno de estos incidentes se previene con las prácticas que aprendes en este módulo: encryption at rest, rotación automática, audit trails, y least privilege.

El antes y después de tu código

Para que visualices el impacto concreto de este módulo, aquí está el cambio en tu código:

Antes (con .env)

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

Problemas: sin encryption, sin rotación, sin audit, sin granularidad, sin fallback.

Después (con Secrets Management Setup)

from secrets import ResilientSecretsClient

secrets = ResilientSecretsClient(config=secrets_config)

result = secrets.get("openai-api-key", service_name="api-service")
client = OpenAI(api_key=result.value)

Beneficios: encrypted at rest, rotación automática, audit trail de cada acceso, least privilege por servicio, fallback con circuit breaker.

El código de aplicación apenas cambia — una línea diferente para obtener la key. La infraestructura de seguridad detrás cambia completamente.

Resumen

Este módulo construye la capa de gestión de credenciales que protege el acceso a los servicios que tu sistema AI usa — separado del flujo de datos (M3-M4)
Las API keys de LLM son targets de alto valor: una key robada de OpenAI puede generar miles de dólares en consumo en minutos
.env funciona para desarrollo local pero es insuficiente para producción: sin rotación, sin audit, sin granularidad, sin encryption
Los 4 pilares de secrets management son: encryption at rest, rotation automática, audit trails, y least privilege — cada cápsula refuerza uno o más pilares
El módulo cubre el espectro completo: desde por qué necesitas esto (02) hasta cómo implementarlo (03-07) y el proyecto integrado (08)
La solución correcta depende de tu escala: cloud KMS para la mayoría, Vault para enterprise — los conceptos (rotación, audit, least privilege) son universales
El Secrets Management Setup es el quinto artefacto de la guía y cambia la fuente de credenciales de tu pipeline sin modificar el código de aplicación
El cambio en tu código es mínimo: de os.getenv("OPENAI_API_KEY") a secrets_client.get("openai-api-key") — con toda la infraestructura de seguridad detrás
En el Módulo 8, este setup se combina con Injection Defense (M3), Sanitization (M4), y PII Protection (M6) para el sistema completo asegurado

Próxima cápsula: En la cápsula 02 vas a entender en profundidad por qué .env no es suficiente para producción, con incidentes reales de exposición de API keys, el costo financiero de keys filtradas, y el path de transición desde .env hacia un secrets manager. Verás código que demuestra las vulnerabilidades y la comparación técnica entre las opciones disponibles.

Recursos adicionales

HashiCorp Vault Documentation — Documentación oficial de Vault, la referencia enterprise para secrets management
AWS Secrets Manager — Documentación del servicio de secrets de AWS, la opción cloud más adoptada
GCP Secret Manager — Documentación del servicio de secrets de Google Cloud
OWASP Secrets Management Cheat Sheet — Guía de OWASP para gestión de secrets con mejores prácticas
GitHub Secret Scanning — Documentación de GitHub sobre detección de secrets en repositorios
12-Factor App — Config — Principios para gestión de configuración y secrets en aplicaciones modernas
CIS Benchmarks — Secret Management — Benchmarks de seguridad para gestión de credenciales
Python Cryptography Library — Librería Python para encryption, base para encryption local de secrets

Creado: Marzo 2026 Versión: 1.0

← Anterior8. Proyecto: Sanitization Pipeline Siguiente →2. Más Allá de .env: Por Qué No Es Suficiente