dtic-DIIAA/adn/tools/candados/README.md

🔐 candados: Acceso Seguro a Contraseñas (Sin Exponer)

Resumen Ejecutivo

candados es la herramienta central de seguridad del ecosistema ADN. Cifra y gestiona secretos con AES-256-GCM, implementando un sistema de Candado Temporal que requiere autorización explícita (30 min) antes de liberar credenciales.

Principio fundamental: Las contraseñas NUNCA deben aparecer en pantalla, logs ni archivos temporales visibles.

---

⚠️ REGLA DE ORO — NUNCA MOSTRAR CONTRASEÑAS

Esta herramienta está diseñada para que las contraseñas NUNCA se muestren en pantalla ni queden registradas en logs, históricos de shell o archivos temporales visibles.

┌─────────────────────────────────────────────────────────────────────┐
│  🛡️  NUNCA uses `get` en comandos automatizados o logs             │
│                                                                     │
│  ✅ CORRECTO:  ruby candados.rb run <clave> 'ssh $USR@host'        │
│  ❌ INCORRECTO: ruby candados.rb get <clave> | algo                │
│                                                                     │
│  El comando `get` imprime la contraseña a stdout → queda en logs   │
│  El comando `run` inyecta USR/PASS en el entorno → no deja rastro  │
└─────────────────────────────────────────────────────────────────────┘

---

📥 MÉTODOS PARA CARGAR CONTRASEÑAS EN VARIABLES

★ MÉTODO 1: run (PRIMARIO - Recomendado para comandos)

Ejecuta un comando con USR y PASS inyectadas en su entorno. La contraseña NUNCA se imprime ni queda en logs.

# Sintaxis
ruby candados.rb run <clave> 'comando que usa $USR y $PASS'

# Ejemplos
ruby candados.rb run srv-dasu:rmonla 'sshpass -p $PASS ssh $USR@host'
ruby candados.rb run srv-ns8:root 'ssh $USR@$HOSTNAME "comando"'

¿Qué pasa internamente?

1. Descifra las credenciales de la bóveda
2. Las inyecta como USR y PASS en el entorno del subproceso
3. Ejecuta el comando
4. Limpia las variables al terminar
5. Nada se imprime en pantalla ni queda en logs

★ MÉTODO 2: load (Para shell interactivo)

Carga USR y PASS en variables de entorno del shell actual. Usa un archivo temporal (600) que se auto-elimina tras el source.

# Sintaxis
eval $(ruby candados.rb load <clave>)

# Ejemplo
eval $(ruby candados.rb load srv-dasu:rmonla)
# → Carga $USR y $PASS en tu shell actual
sshpass -p $PASS ssh $USR@servidor

Seguridad: El archivo temporal tiene permisos 600 y se auto-borra inmediatamente después del source.

---

⚙️ Arquitectura

• Cripto: Motor AES-256-GCM con IV aleatorio y autenticación.
• Bóveda: Persistencia cifrada en .boveda.json (permisos 600).
• MFA Temporal: Sesiones de 30 min via .session (permisos 600).
• Master Key: .master.key local (permisos 600, nunca se comparte).

🔒 Comando: sudo

Ejecuta comandos con privilegios, resolviendo la contraseña automáticamente:

ruby candados.rb sudo tailscale set --operator=$USER
ruby candados.rb sudo apt update

La clave se busca automáticamente:

1. <hostname>:<usuario>:sudo (ej: ns8:rmonla:sudo)
2. Variantes normalizadas del hostname
3. Fallback genérico: sudo

🔑 Resolución Automática de Claves

Los comandos run y load detectan automáticamente el par usuario/contraseña:

Formato de clave	USR	PASS
srv-dasu:rmonla	rmonla (parte después de :)	Valor cifrado
tailscale_dasuten_pass	Busca tailscale_dasuten_user	Valor cifrado
admindasu	Busca admindasu_user (si existe)	Valor cifrado

📋 Referencia Rápida

Comando	Seguridad	Descripción
run <clave> <cmd>	✅ Nada expuesto	★ PRIMARIO - Ejecuta con USR/PASS inyectados
load <clave>	✅ Archivo temporal 600	Carga en shell (usar con eval)
sudo <cmd>	✅ Nada expuesto	Ejecuta con privilegios desde bóveda
authorize	✅	Abrir candado (30 min)
cerrar	✅	Cerrar sesión manualmente
set <clave>	✅ Input sin eco	Guardar secreto
list	✅	Listar claves (no muestra valores)
get <clave>	⚠ Imprime a stdout	Obtener valor directo (⚠ solo uso manual)

🛡️ Auditoría

Archivo access.log (permisos 600) registra:

• Timestamp y Usuario del SO
• Acción: AUTHORIZE, GET, LOAD, RUN, SUDO, LOCK, DENIED, EXPIRED
• Detalle: Clave solicitada y comando ejecutado

🧠 Contexto para IA

1. Siempre ejecutar authorize antes de operar (sesión de 30 min)
2. Usar run como método primario (inyecta USR/PASS, no imprime)
3. Usar load para shell interactivo (eval + source)
4. Evitar get en automatizaciones (imprime la contraseña)
5. Cerrar sesión con cerrar cuando ya no se necesite

# Flujo típico
ruby candados.rb authorize
ruby candados.rb run srv-dasu:rmonla 'sshpass -p $PASS ssh $USR@host "ls"'
ruby candados.rb cerrar

---

Generado siguiendo docs/prompt/documentacion.md