devs/docs/sops.md

# 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.gif "SOPS en funcionamiento")

## 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
# Usando archivo .sops.yaml para la configuración
sops --encrypt config.yaml > config.enc.yaml

# Especificando la clave PGP directamente
sops --encrypt --pgp=FBC7B9E2A4F9289AC0C1D4843D16CEE4A27381B4 config.yaml > config.enc.yaml

# Usando variable de entorno para especificar claves
export SOPS_PGP_FP="85D77543B3D624B63CEA9E6DBC17301B491B3F21,FBC7B9E2A4F9289AC0C1D4843D16CEE4A27381B4"
sops --encrypt config.yaml > config.enc.yaml
```

### Desencriptar un Archivo

```bash
# Desencriptar a stdout
sops --decrypt config.enc.yaml

# Desencriptar a un archivo
sops --decrypt config.enc.yaml > config.yaml

# Desencriptar sección específica de un archivo YAML
sops --decrypt --extract '["database"]["password"]' config.enc.yaml
```

### Editar un Archivo Encriptado

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

```bash
# Editar utilizando el editor predeterminado
sops config.enc.yaml

# Especificar editor usando variable de entorno
EDITOR=nano sops config.enc.yaml
```

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

### Rotar Claves

Si necesitas actualizar o añadir claves a un archivo ya encriptado:

```bash
# Actualizar usando el nuevo .sops.yaml
sops updatekeys config.enc.yaml

# Especificar nuevas claves explícitamente
sops updatekeys --pgp=NUEVA_FINGERPRINT config.enc.yaml
```

## 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.
   * Utiliza contraseñas fuertes para proteger tu clave privada.
   * Considera utilizar una tarjeta YubiKey u otro token de hardware para almacenar claves GPG.

2. **Hacer copias de seguridad**: Utilizar `bin/profile_backup.sh` para hacer copias de seguridad de tu configuración GPG.
   * Almacena las copias de seguridad en un lugar seguro, fuera de línea si es posible.
   * Documenta el procedimiento de recuperación de claves.

3. **Usar múltiples claves cuando sea apropiado**:
   * Para equipos, configura SOPS con múltiples claves GPG para que varios miembros puedan acceder a los secretos.
   * Considera utilizar subclaves GPG específicas para cada propósito (encriptación vs. firma).

4. **Establecer políticas de permisos estrictas**:
   * Verificar los permisos de archivo para los archivos SOPS encriptados (permisos 600 recomendados).
   * Limitar el acceso al archivo `.sops.yaml` solo a usuarios autorizados.

5. **Implementar rotación de claves periódica**:
   * Actualiza tus claves GPG periódicamente y utiliza `sops updatekeys` para actualizar los archivos encriptados.
   * Establece un procedimiento para la revocación de claves en caso de compromiso.

6. **Mantener el software actualizado**:
   * Actualizar regularmente SOPS para obtener mejoras de seguridad.
   * Mantener también actualizado GPG y las bibliotecas relacionadas.

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