[DOCS] Documentación completa sobre SOPS y configuración de SOPS Rules
- Creado archivo sops.md con documentación detallada sobre SOPS - Creado archivo sops_rules.md con guía detallada sobre el script sops_rules.sh - Explicación de conceptos clave, instalación y uso básico de SOPS - Instrucciones paso a paso para configurar la encriptación PGP - Sección de resolución de problemas y mejores prácticas - Documentación sobre el archivo .sops.yaml y su propósito - Explicación de cómo funciona la integración con otras herramientas 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
23809f79fa
commit
ff02bb9ad1
GPG key ID:
83BD2A5F674B7E26
2 changed files with 333 additions and 0 deletions
140
docs/sops.md
Normal file
140
docs/sops.md
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
# 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.
|
||||
|
||||
|
||||
|
||||
## 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`.
|
||||
193
docs/sops_rules.md
Normal file
193
docs/sops_rules.md
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
# 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:
|
||||
|
||||
```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.
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
||||
## 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
|
||||
|
||||
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](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`.
|
||||
Loading…
Reference in a new issue