diff --git a/docs/sops.md b/docs/sops.md new file mode 100644 index 0000000..2fc51dc --- /dev/null +++ b/docs/sops.md @@ -0,0 +1,140 @@ +# SOPS: Gestión Segura de Secretos + +## Introducción + +[SOPS (Secrets OPerationS)](https://github.com/getsops/sops) 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. + +![SOPS en funcionamiento](img/sops-overview.png) + +## 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: + +```bash +bin/bootstrap.sh +``` + +Para verificar que SOPS está instalado correctamente: + +```bash +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 + +```bash +sops --encrypt config.yaml > config.enc.yaml +``` + +### Desencriptar un Archivo + +```bash +sops --decrypt config.enc.yaml > config.yaml +``` + +### Editar un Archivo Encriptado + +SOPS incluye un editor integrado que facilita la edición de archivos encriptados: + +```bash +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](https://github.com/getsops/sops) +- [Tutorial en profundidad de Mozilla](https://blog.mozilla.org/security/2017/10/17/managing-secrets-mozilla-sops/) +- [Mejores prácticas para gestión de secretos](https://cloud.google.com/secret-manager/docs/best-practices) + +--- + +Si necesitas ayuda adicional con SOPS, contacta con el equipo de desarrollo mediante `mauro@rosero.one`. \ No newline at end of file diff --git a/docs/sops_rules.md b/docs/sops_rules.md new file mode 100644 index 0000000..c454cfe --- /dev/null +++ b/docs/sops_rules.md @@ -0,0 +1,193 @@ +# Configuración de SOPS Rules en MRDevs Tools + +## Introducción + +El script `sops_rules.sh` es una herramienta fundamental en MRDevs Tools que configura la encriptación PGP para SOPS (Secrets OPerationS). Este script genera el archivo `.sops.yaml` que define las reglas de creación y encriptación para todos los secretos gestionados por la plataforma. + +La ejecución de `sops_rules.sh` es un paso **obligatorio** durante la instalación de MRDevs Tools, ya que establece la base para la gestión segura de secretos en todo el sistema. + +![Proceso de configuración SOPS Rules](img/sops-rules-flow.png) + +## Objetivo y Funcionamiento + +El objetivo principal de `sops_rules.sh` es simplificar la configuración de SOPS mediante una interfaz interactiva que: + +1. Detecta todas las claves GPG disponibles en el sistema +2. Permite seleccionar la clave maestra que se utilizará para encriptar/desencriptar secretos +3. Genera el archivo de configuración `.sops.yaml` con las reglas adecuadas +4. Valida la configuración para asegurar su correcto funcionamiento + +Este proceso garantiza que todos los secretos de la plataforma (tokens API, credenciales, configuraciones) sean encriptados de manera consistente con la misma clave GPG, facilitando su gestión y manteniendo la seguridad. + +## Requisitos Previos + +Antes de ejecutar `sops_rules.sh`, debes tener: + +1. **GPG instalado y configurado**: Al menos una clave GPG debe estar disponible en tu keyring. +2. **Bootstrap completado**: El script `bootstrap.sh` debe haberse ejecutado previamente para instalar las dependencias necesarias. + +Si no tienes una clave GPG configurada, puedes crear una ejecutando: + +```bash +bin/gpg_init.sh +``` + +## Uso del Script + +Ejecutar el script es sencillo: + +```bash +bin/sops_rules.sh +``` + +### Proceso Paso a Paso + +El script sigue estos pasos: + +1. **Verificación de requisitos**: Comprueba que GPG, SOPS y Gum (para la interfaz) estén instalados. + +2. **Detección de claves GPG**: Busca todas las claves GPG disponibles en tu sistema. + +3. **Selección de clave**: Muestra una lista interactiva de las claves disponibles con sus fingerprints y nombres de usuario. + + ![Selección de clave GPG](img/sops-rules-selection.png) + +4. **Validación**: Verifica que la clave seleccionada es válida (longitud correcta, formato hexadecimal, presente en el keyring). + +5. **Confirmación**: Muestra un resumen de la clave seleccionada y solicita confirmación antes de continuar. + +6. **Generación de configuración**: Crea el archivo `.sops.yaml` en el directorio raíz de MRDevs Tools (`$HOME/devs/.sops.yaml`). + +7. **Verificación final**: Confirma que el archivo se ha creado correctamente y muestra ejemplos de uso. + +## Estructura del Archivo .sops.yaml + +El archivo generado tiene la siguiente estructura: + +```yaml +creation_rules: + - pgp: 'FINGERPRINT_COMPLETO_DE_TU_CLAVE_GPG' +``` + +Donde `FINGERPRINT_COMPLETO_DE_TU_CLAVE_GPG` es el fingerprint de 40 caracteres de la clave seleccionada (por ejemplo: `ACB17A9DB7A680D0FED714E2A17ADF8EA1E9DB07`). + +### Explicación de las Reglas de Creación + +Las "creation_rules" definidas en el archivo `.sops.yaml` determinan cómo SOPS encriptará nuevos archivos. Este archivo de configuración permite a SOPS saber automáticamente qué claves usar cuando no se especifican explícitamente en la línea de comandos. + +Con esta configuración, cualquier comando SOPS ejecutado dentro del directorio de MRDevs Tools utilizará automáticamente esta clave GPG para la encriptación sin necesidad de especificarla cada vez. + +## Casos de Uso Comunes + +### 1. Encriptar un Nuevo Archivo de Configuración + +Una vez configurado SOPS con `sops_rules.sh`, puedes encriptar fácilmente archivos: + +```bash +cd $HOME/devs +sops --encrypt config_secrets.yaml > config_secrets.sops.yaml +``` + +### 2. Desencriptar un Archivo Existente + +```bash +sops --decrypt .cortana/cortana.sops.yaml +``` + +### 3. Editar un Archivo Encriptado In-Situ + +```bash +sops .developer/github.sops.yaml +``` + +### 4. Verificar la Configuración Actual + +Para verificar qué clave se está utilizando actualmente: + +```bash +cat $HOME/devs/.sops.yaml +``` + +## Reconfiguración y Actualización + +Si necesitas cambiar la clave GPG utilizada para encriptar secretos (por ejemplo, porque has generado una nueva o porque la anterior ha caducado), simplemente vuelve a ejecutar el script: + +```bash +bin/sops_rules.sh +``` + +**Nota importante**: Cambiar la clave de encriptación no reencripta automáticamente los archivos existentes. Deberás desencriptar y reencriptar manualmente los archivos que ya estaban encriptados con la clave anterior. + +## Integración con Otras Herramientas + +El archivo `.sops.yaml` generado por `sops_rules.sh` es utilizado por varias herramientas en MRDevs Tools: + +- **`bin/ai_token.sh`**: Para encriptar tokens de proveedores de IA +- **`bin/cortana_token.sh`**: Para gestionar de forma segura el token de Claude Code +- **`bin/cversion_token.sh`**: Para encriptar tokens de plataformas de control de versiones +- **`bin/qr_secret.sh`**: Para almacenar de forma segura los secretos extraídos de códigos QR + +## Resolución de Problemas + +### No se detectan claves GPG + +Si el script no muestra ninguna clave GPG disponible: + +1. Verifica que tienes al menos una clave GPG generada: + ```bash + gpg --list-keys + ``` + +2. Si no tienes ninguna clave, genera una: + ```bash + bin/gpg_init.sh + ``` + +### Error al generar el archivo .sops.yaml + +Si encuentras errores al generar el archivo de configuración: + +1. Verifica que tienes permisos de escritura en el directorio: + ```bash + ls -la $HOME/devs + ``` + +2. Asegúrate de que SOPS está instalado correctamente: + ```bash + sops --version + ``` + +3. Prueba a ejecutar el script con modo verbose (ejecuta el script con comando bash en modo verbose): + ```bash + bash -x bin/sops_rules.sh + ``` + +### Problemas al encriptar/desencriptar archivos después de la configuración + +Si experimentas problemas al usar SOPS después de configurarlo: + +1. Verifica que la clave privada GPG está disponible y desbloqueada. +2. Comprueba que el archivo `.sops.yaml` contiene el fingerprint correcto. +3. Asegúrate de estar en el directorio correcto al ejecutar comandos SOPS. + +## Mejores Prácticas + +1. **Hacer copia de seguridad de tus claves GPG**: Utiliza `bin/profile_backup.sh` para respaldar toda tu configuración GPG. + +2. **Usar una contraseña robusta** para proteger tu clave GPG. + +3. **Limitar el acceso** al archivo `.sops.yaml` solo a usuarios autorizados. + +4. **Documentar la clave utilizada** en un lugar seguro para referencia futura. + +5. **Establecer un proceso de rotación de claves** periódico según las políticas de seguridad de tu organización. + +## Recursos Adicionales + +- [Documentación de SOPS](docs/sops.md): Guía completa sobre el uso de SOPS en MRDevs Tools. +- [Configuración de GPG](https://www.gnupg.org/documentation/): Documentación oficial de GPG. +- [Guía de Seguridad](https://cloud.google.com/security/encryption-at-rest/default-encryption): Mejores prácticas para la encriptación de datos en reposo. + +--- + +Si necesitas ayuda adicional con la configuración de SOPS Rules, contacta con el equipo de desarrollo mediante `mauro@rosero.one`. \ No newline at end of file