From 9e638c29be740053ef9c24f063588d521a7cfe7e Mon Sep 17 00:00:00 2001 From: "Mauro Rosero P." Date: Sun, 6 Apr 2025 11:13:55 -0500 Subject: [PATCH] =?UTF-8?q?[DOCS]=20Mejorada=20la=20documentaci=C3=B3n=20d?= =?UTF-8?q?e=20SOPS=20con=20informaci=C3=B3n=20del=20repositorio=20oficial?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Expandida la documentación de SOPS con ejemplos más completos de comandos - Añadidos detalles sobre opciones avanzadas de configuración en .sops.yaml - Documentadas las configuraciones con múltiples claves PGP - Mejorada la sección de mejores prácticas de seguridad - Incluida información sobre rotación de claves - Añadidos ejemplos de uso con variables de entorno - Ampliadas las recomendaciones para equipos y proyectos compartidos 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/sops.md | 55 ++++++++++++++++++++++++++++++---- docs/sops_rules.md | 73 ++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 117 insertions(+), 11 deletions(-) diff --git a/docs/sops.md b/docs/sops.md index 2fc51dc..6d5ac0e 100644 --- a/docs/sops.md +++ b/docs/sops.md @@ -6,7 +6,7 @@ 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) +![SOPS en funcionamiento](img/sops-overview.gif "SOPS en funcionamiento") ## Características Principales @@ -48,13 +48,28 @@ SOPS utiliza claves GPG para encriptar y desencriptar secretos. La ventaja princ ### 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 @@ -62,10 +77,26 @@ sops --decrypt config.enc.yaml > config.yaml 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 predeterminado. Al guardar y salir, SOPS reencriptará automáticamente el archivo. +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 @@ -103,14 +134,28 @@ $HOME/ 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. **No compartir archivos encriptados** con usuarios que no posean la clave adecuada. +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. **Verificar los permisos de archivo** para los archivos SOPS encriptados (permisos 600 recomendados). +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. **Actualizar regularmente** SOPS para obtener mejoras de seguridad. +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 diff --git a/docs/sops_rules.md b/docs/sops_rules.md index c454cfe..98a25b1 100644 --- a/docs/sops_rules.md +++ b/docs/sops_rules.md @@ -62,7 +62,7 @@ El script sigue estos pasos: ## Estructura del Archivo .sops.yaml -El archivo generado tiene la siguiente estructura: +El archivo generado por `sops_rules.sh` tiene la siguiente estructura básica: ```yaml creation_rules: @@ -77,6 +77,47 @@ Las "creation_rules" definidas en el archivo `.sops.yaml` determinan cómo SOPS 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 @@ -172,15 +213,35 @@ Si experimentas problemas al usar SOPS después de configurarlo: ## Mejores Prácticas -1. **Hacer copia de seguridad de tus claves GPG**: Utiliza `bin/profile_backup.sh` para respaldar toda tu configuración GPG. +### Gestión de Claves -2. **Usar una contraseña robusta** para proteger tu clave GPG. +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` -3. **Limitar el acceso** al archivo `.sops.yaml` solo a usuarios autorizados. +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. -4. **Documentar la clave utilizada** en un lugar seguro para referencia futura. +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. -5. **Establecer un proceso de rotación de claves** periódico según las políticas de seguridad de tu organización. +### 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