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 por sops_rules.sh tiene la siguiente estructura básica:

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.

Configuraciones Avanzadas

El archivo .sops.yaml puede ser mucho más sofisticado, permitiendo configuraciones avanzadas:

Múltiples Claves PGP

Si deseas que varios miembros del equipo puedan desencriptar los secretos, puedes especificar múltiples fingerprints GPG:

creation_rules:
  - pgp: >-
      85D77543B3D624B63CEA9E6DBC17301B491B3F21,
      FBC7B9E2A4F9289AC0C1D4843D16CEE4A27381B4      

Reglas Basadas en Patrones de Archivos

Puedes definir diferentes reglas de encriptación según el patrón de nombre de archivo:

creation_rules:
  - path_regex: \.dev\.yaml$
    pgp: 'DEV_ENVIRONMENT_GPG_FINGERPRINT'
  - path_regex: \.prod\.yaml$
    pgp: 'PRODUCTION_ENVIRONMENT_GPG_FINGERPRINT'

Con esta configuración, los archivos que terminen en .dev.yaml usarán una clave, mientras que los que terminen en .prod.yaml usarán otra.

Soporte para Otros Métodos de Encriptación

Aunque en MRDevs Tools utilizamos principalmente PGP, SOPS soporta otros métodos de encriptación como AWS KMS, GCP KMS, Azure Key Vault, age, y HashiCorp Vault:

creation_rules:
  - path_regex: \.dev\.yaml$
    kms: 'arn:aws:kms:us-west-2:927034868273:key/fe86dd69-4132-404c-ab86-4269956b4500'
  - path_regex: \.prod\.yaml$
    gcp_kms: 'projects/my-project/locations/global/keyRings/my-keyring/cryptoKeys/my-key'

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

Gestión de Claves

1. Hacer copia de seguridad de tus claves GPG:

   • Utiliza bin/profile_backup.sh para respaldar toda tu configuración GPG.
   • Considera exportar las claves manualmente con gpg --export-secret-keys --armor > my-private-key.asc

2. Proteger tus claves adecuadamente:

   • Usar una contraseña robusta para proteger tu clave GPG.
   • Considerar el uso de tokens físicos como YubiKey para mayor seguridad.
   • Evitar compartir o exponer la clave privada.

3. Almacenar de forma segura los fingerprints:

   • Documentar el fingerprint completo (40 caracteres) en un lugar seguro para referencia futura.
   • Mantener un registro de qué clave se usa para cada entorno o proyecto.

Configuración y Mantenimiento

1. Estructura de permisos óptima:

   • Limitar el acceso al archivo .sops.yaml solo a usuarios autorizados (permisos 600 recomendados).
   • Asegurar que el directorio que contiene los secretos encriptados tenga permisos adecuados.

2. Rotación de claves programada:

   • Establecer un proceso de rotación de claves periódico según las políticas de seguridad de tu organización.
   • Documentar el procedimiento completo para actualizar claves en archivos ya encriptados.

3. Configuración para equipos:

   • Para entornos con múltiples desarrolladores, configurar reglas con múltiples claves PGP.
   • Considerar el uso de estructuras de claves jerárquicas para equipos grandes.
   • Implementar políticas claras sobre quién puede añadir/eliminar claves del archivo de configuració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.