devs/docs/sops.md

SOPS: Gestión Segura de Secretos

Introducción

SOPS (Secrets OPerationS) es una herramienta de código abierto diseñada para la gestión segura de secretos. Desarrollada originalmente por Mozilla y posteriormente mantenida por la comunidad, SOPS permite encriptar y desencriptar archivos de configuración que contienen secretos como contraseñas, tokens API, claves de acceso y otros datos sensibles.

En el entorno de MRDevs Tools, SOPS es un componente fundamental para la seguridad general de la plataforma, proporcionando una forma estandarizada y segura de manejar información confidencial.

Características Principales

• Encriptación de archivos de configuración: Permite almacenar secretos de forma segura en repositorios Git.
• Soporte para múltiples formatos: Funciona con YAML, JSON, ENV, INI y BINARY.
• Encriptación selectiva: Puede encriptar solo valores específicos dentro de un archivo, manteniendo las claves y la estructura visibles.
• Múltiples métodos de encriptación: Soporta KMS de AWS, GCP KMS, Azure Key Vault, PGP, age y HashiCorp Vault.
• Integración con Git: Funciona perfectamente con flujos de trabajo de control de versiones.
• Rotación de claves: Permite actualizar las claves de encriptación sin necesidad de desencriptar y reencriptar los secretos.

Instalación

En MRDevs Tools, SOPS se instala automáticamente como parte del proceso de bootstrap:

bin/bootstrap.sh

Para verificar que SOPS está instalado correctamente:

sops --version

Funcionamiento Básico

SOPS utiliza claves GPG para encriptar y desencriptar secretos. La ventaja principal es que permite almacenar archivos de configuración encriptados en sistemas de control de versiones mientras se mantiene la seguridad de los datos sensibles.

Conceptos Clave

1. Encriptación a nivel de valor: A diferencia de otras herramientas que encriptan archivos completos, SOPS encripta solo los valores individuales, manteniendo la estructura del archivo visible.

2. Transparencia y auditabilidad: Cada archivo encriptado contiene metadatos sobre quién lo encriptó, cuándo, y con qué clave.

3. Archivos de configuración: SOPS puede ser configurado utilizando un archivo .sops.yaml, que define reglas de creación y reglas de descifrado.

Uso Básico

Encriptar un Archivo

# Usando archivo .sops.yaml para la configuración
sops --encrypt config.yaml > config.enc.yaml

# Especificando la clave PGP directamente
sops --encrypt --pgp=FBC7B9E2A4F9289AC0C1D4843D16CEE4A27381B4 config.yaml > config.enc.yaml

# Usando variable de entorno para especificar claves
export SOPS_PGP_FP="85D77543B3D624B63CEA9E6DBC17301B491B3F21,FBC7B9E2A4F9289AC0C1D4843D16CEE4A27381B4"
sops --encrypt config.yaml > config.enc.yaml

Desencriptar un Archivo

# Desencriptar a stdout
sops --decrypt config.enc.yaml

# Desencriptar a un archivo
sops --decrypt config.enc.yaml > config.yaml

# Desencriptar sección específica de un archivo YAML
sops --decrypt --extract '["database"]["password"]' config.enc.yaml

Editar un Archivo Encriptado

SOPS incluye un editor integrado que facilita la edición de archivos encriptados:

# Editar utilizando el editor predeterminado
sops config.enc.yaml

# Especificar editor usando variable de entorno
EDITOR=nano sops config.enc.yaml

Este comando abrirá el archivo desencriptado en tu editor. Al guardar y salir, SOPS reencriptará automáticamente el archivo.

Rotar Claves

Si necesitas actualizar o añadir claves a un archivo ya encriptado:

# Actualizar usando el nuevo .sops.yaml
sops updatekeys config.enc.yaml

# Especificar nuevas claves explícitamente
sops updatekeys --pgp=NUEVA_FINGERPRINT config.enc.yaml

Integración con MRDevs Tools

MRDevs Tools utiliza SOPS para encriptar varios tipos de información sensible:

1. Tokens de API: Para servicios como GitHub, GitLab, Forgejo, y APIs de IA.
2. Credenciales de acceso: Para servicios internos y externos.
3. Configuraciones VPN: Datos de configuración para conexiones VPN seguras.
4. Secretos TOTP/HOTP: Extraídos de códigos QR y almacenados de forma segura.

Todos estos secretos se almacenan en archivos YAML encriptados en la estructura de directorios de MRDevs Tools:

$HOME/
└── .developer/               # Tokens para desarrollo
    ├── github.sops.yaml      # Token GitHub encriptado
    └── forgejo.sops.yaml     # Token Forgejo encriptado
└── .cortana/                 # Configuración para IA
    └── cortana.sops.yaml     # Token Claude Code encriptado
└── .sops.yaml                # Configuración SOPS global

Flujo de Trabajo con SOPS en MRDevs Tools

1. Configuración inicial: Durante la instalación de MRDevs Tools, se establece una clave GPG maestra para encriptación mediante el script bin/sops_rules.sh.

2. Creación de secretos: Cuando se añade un nuevo secreto (por ejemplo, un token de API), se encripta automáticamente con SOPS utilizando la clave GPG configurada.

3. Acceso a secretos: Las herramientas de MRDevs Tools acceden a estos secretos desencriptándolos en memoria cuando es necesario, sin exponerlos en texto plano.

4. Rotación de claves: Si es necesario cambiar la clave GPG, el script bin/sops_rules.sh puede ser ejecutado nuevamente para actualizar la configuración.

Seguridad y Mejores Prácticas

Para garantizar la máxima seguridad al utilizar SOPS en MRDevs Tools:

1. Proteger la clave GPG: La seguridad de tus secretos depende de la seguridad de tu clave GPG.

   • Utiliza contraseñas fuertes para proteger tu clave privada.
   • Considera utilizar una tarjeta YubiKey u otro token de hardware para almacenar claves GPG.

2. Hacer copias de seguridad: Utilizar bin/profile_backup.sh para hacer copias de seguridad de tu configuración GPG.

   • Almacena las copias de seguridad en un lugar seguro, fuera de línea si es posible.
   • Documenta el procedimiento de recuperación de claves.

3. Usar múltiples claves cuando sea apropiado:

   • Para equipos, configura SOPS con múltiples claves GPG para que varios miembros puedan acceder a los secretos.
   • Considera utilizar subclaves GPG específicas para cada propósito (encriptación vs. firma).

4. Establecer políticas de permisos estrictas:

   • Verificar los permisos de archivo para los archivos SOPS encriptados (permisos 600 recomendados).
   • Limitar el acceso al archivo .sops.yaml solo a usuarios autorizados.

5. Implementar rotación de claves periódica:

   • Actualiza tus claves GPG periódicamente y utiliza sops updatekeys para actualizar los archivos encriptados.
   • Establece un procedimiento para la revocación de claves en caso de compromiso.

6. Mantener el software actualizado:

   • Actualizar regularmente SOPS para obtener mejoras de seguridad.
   • Mantener también actualizado GPG y las bibliotecas relacionadas.

Resolución de Problemas

Error: "Failed to decrypt"

Este error sucede cuando no tienes la clave privada correcta para desencriptar el archivo. Posibles soluciones:

1. Asegurarte de que tienes la clave GPG correcta importada.
2. Verificar que el archivo .sops.yaml está correctamente configurado.
3. Comprobar que el archivo no está corrupto.

Error: "No matching encryption keys found"

Este error ocurre cuando SOPS no puede encontrar una clave que coincida con las reglas de creación. Soluciones:

1. Ejecutar bin/sops_rules.sh para configurar correctamente el archivo .sops.yaml.
2. Verificar que tu clave GPG está disponible para el sistema.

Recursos Adicionales

• Documentación oficial de SOPS
• Tutorial en profundidad de Mozilla
• Mejores prácticas para gestión de secretos

---

Si necesitas ayuda adicional con SOPS, contacta con el equipo de desarrollo mediante mauro@rosero.one.