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