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

sops --encrypt config.yaml > config.enc.yaml

Desencriptar un Archivo

sops --decrypt config.enc.yaml > config.yaml

Editar un Archivo Encriptado

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

sops config.enc.yaml

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

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.

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

3. No compartir archivos encriptados con usuarios que no posean la clave adecuada.

4. Verificar los permisos de archivo para los archivos SOPS encriptados (permisos 600 recomendados).

5. Actualizar regularmente SOPS para obtener mejoras de seguridad.

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.