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.

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

```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.

### 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:

```yaml
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:

```yaml
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:

```yaml
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:

```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

### 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](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`.