devs/docs/sops_rules.md

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.

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:

bin/gpg_init.sh

Uso del Script

Ejecutar el script es sencillo:

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.

   

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:

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:

cd $HOME/devs
sops --encrypt config_secrets.yaml > config_secrets.sops.yaml

2. Desencriptar un Archivo Existente

sops --decrypt .cortana/cortana.sops.yaml

3. Editar un Archivo Encriptado In-Situ

sops .developer/github.sops.yaml

4. Verificar la Configuración Actual

Para verificar qué clave se está utilizando actualmente:

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:

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:

   gpg --list-keys
   

2. Si no tienes ninguna clave, genera una:

   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:

   ls -la $HOME/devs
   

2. Asegúrate de que SOPS está instalado correctamente:

   sops --version
   

3. Prueba a ejecutar el script con modo verbose (ejecuta el script con comando bash en modo verbose):

   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: Guía completa sobre el uso de SOPS en MRDevs Tools.
• Configuración de GPG: Documentación oficial de GPG.
• Guía de Seguridad: 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.