tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update to Skynet v7 - Complete documentation restructure

Browse Source 
- Nueva estructura de carpetas según Skynet v7
- Añadidos schemas SQL completos
- Documentación de entidades, componentes e integraciones
- Modelo de seguridad actualizado
- Infraestructura y operaciones reorganizadas
This commit is contained in:
ARCHITECT
2025-12-29 18:23:41 +00:00
parent ac481fe266
commit 6ea70bd34f
76 changed files with 13029 additions and 4340 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
06_SEGURIDAD/cifrado.md Normal file
View File

@@ -0,0 +1,170 @@
# Cifrado
**Estado:** Especificación
---
## Principio KEY VAULT
```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ "Las llaves nunca viajan con los datos que protegen" │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Envelope Encryption
### Jerarquía de Llaves
```
MASTER KEY (MK)
(HSM / KMS externo)
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
KEK-DATA KEK-SECRETS KEK-SIGNING
(Cifra (Cifra API (Firma
datos) keys) tokens)
│ │ │
▼ ▼ ▼
DEK-1..n API Keys JWT Keys
(Efímeras) (Rotables) (Rotables)
```
---
## Niveles
### 1. MASTER KEY (MK)
| Aspecto | Valor |
|---------|-------|
| Almacenamiento | HSM/KMS externo |
| Exposición | Nunca se expone |
| Rotación | Anual |
| Uso | Deriva KEKs |
### 2. Key Encryption Keys (KEK)
| KEK | Función | Rotación |
|-----|---------|----------|
| KEK-DATA | Cifra datos | 365 días |
| KEK-SECRETS | Cifra API keys | 365 días |
| KEK-SIGNING | Firma tokens | 180 días |
### 3. Data Encryption Keys (DEK)
| Aspecto | Valor |
|---------|-------|
| Generación | Por operación |
| Cifrado | Con KEK correspondiente |
| Rotación | Por uso (efímeras) |
---
## Ventajas de Envelope Encryption
| Ventaja | Descripción |
|---------|-------------|
| **Rotación eficiente** | Rotar KEKs sin re-cifrar todos los datos |
| **Separación** | Diferentes KEKs para diferentes propósitos |
| **Trazabilidad** | Cada nivel tiene su propio ciclo de vida |
| **Seguridad en capas** | Compromiso de DEK no expone otras DEKs |
---
## Cifrado en Reposo
### Base de Datos
| Componente | Cifrado |
|------------|---------|
| PostgreSQL | Transparent Data Encryption (TDE) |
| Backups | AES-256-GCM con KEK-DATA |
| Logs sensibles | AES-256-GCM con KEK-DATA |
### Almacenamiento
| Componente | Cifrado |
|------------|---------|
| Cloudflare R2 | SSE con llaves gestionadas |
| Backups locales | AES-256-GCM |
| Archivos temporales | Cifrado en memoria |
---
## Cifrado en Tránsito
| Conexión | Protocolo |
|----------|-----------|
| HTTPS | TLS 1.3 |
| PostgreSQL | SSL required |
| Redis | TLS |
| SSH | Ed25519 |
---
## Gestión de Llaves
### Ubicación
| Llave | Ubicación |
|-------|-----------|
| MASTER KEY | HSM / KMS externo |
| KEKs | Infisical (cifradas) |
| DEKs | Generadas en runtime |
| API Keys | Infisical |
### Acceso
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Servicio │────▶│ Infisical │────▶│ KEK/DEK │
│ │ │ (API) │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
│ │
│ (nunca en mismo lugar) │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Datos │ │ Llaves │
│ Cifrados │ │ │
└─────────────┘ └─────────────┘
```
---
## Algoritmos
| Uso | Algoritmo |
|-----|-----------|
| Cifrado simétrico | AES-256-GCM |
| Hashing | SHA-256, SHA-512 |
| Firmas | Ed25519, ECDSA |
| KDF | Argon2id |
| TLS | TLS 1.3 |
---
## Rotación de Llaves
| Llave | Proceso |
|-------|---------|
| **MASTER KEY** | Re-derivar todas las KEKs, re-cifrar DEKs |
| **KEK** | Re-cifrar DEKs asociadas |
| **DEK** | Generar nueva, re-cifrar datos específicos |
---
## Auditoría
| Evento | Log |
|--------|-----|
| Acceso a KEK | SENTINEL-LIGHT |
| Uso de DEK | Trace en S-CONTRACT |
| Rotación | Alerta + registro |
| Compromiso | SENTINEL-DEEP + alerta crítica |

119
06_SEGURIDAD/inmutabilidad.md Normal file
View File

@@ -0,0 +1,119 @@
# Inmutabilidad
**Versión:** 1.0
**Estado:** Definición
---
## Principio
```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Los datos de entrada y salida nunca se modifican. │
│ La trazabilidad siempre es posible. │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Componentes Inmutables
| Componente | Mutabilidad | Eliminación |
|------------|-------------|-------------|
| Secretaría (Clara/Margaret) | **Inmutable** | Prohibida |
| Contable (Feldman) | **Inmutable** | Prohibida |
---
## Componentes Editables
| Componente | Mutabilidad | Eliminación |
|------------|-------------|-------------|
| Producción (Alfred/Jared) | Editable | Permitida |
| Administración (Mason) | Editable | Siempre (tras consolidar) |
---
## Cadena de Hashes
### Encadenamiento
```
Bloque 1 Bloque 2 Bloque 3
┌────────────┐ ┌────────────┐ ┌────────────┐
│h_bloque: A │──────►│hash_prev: A│──────►│hash_prev: B│
│content: X │ │h_bloque: B │ │h_bloque: C │
│ │ │content: Y │ │content: Z │
└────────────┘ └────────────┘ └────────────┘
```
### Verificación
```python
def verificar_cadena_completa():
bloques = obtener_todos_bloques_ordenados()
for i, bloque in enumerate(bloques):
# Verificar hash de contenido
if not verificar_integridad(bloque):
return False, f"Integridad fallida en bloque {i}"
# Verificar encadenamiento
if i > 0:
if bloque.hash_previo != bloques[i-1].h_bloque:
return False, f"Encadenamiento roto en bloque {i}"
return True, "Cadena válida"
```
---
## Reglas de Validación
| Regla | Nombre | Descripción |
|-------|--------|-------------|
| M-001 | Hash único | h_bloque no existe previamente |
| M-002 | Encadenamiento | hash_previo apunta a bloque existente |
| M-003 | Integridad | hash_contenido = SHA-256(contenido) |
---
## Trazabilidad
Cualquier registro en Feldman puede rastrearse hasta Secretaría:
```
Bloque (Feldman)
│
└── h_entrada ──► Contenedor (Secretaría)
│
├── timestamp
├── origen
├── usuario
└── archivos_hashes ──► R2
```
---
## Auditoría
Sentinel verifica periódicamente:
| Modo | Frecuencia | Verificación |
|------|------------|--------------|
| LIGHT | 5 min | Últimos bloques |
| DEEP | 1 hora | Cadena completa |
---
## Blockchain Ready
La estructura de bloques encadenados está preparada para:
- Publicación en blockchain (Polygon)
- Merkle tree para verificación
- Smart contracts para sellado
**Estado:** Preparado pero no implementado.

135
06_SEGURIDAD/modelo-amenazas.md Normal file
View File

@@ -0,0 +1,135 @@
# Modelo de Amenazas
**Versión:** 1.0
**Estado:** Definición
---
## Activos Críticos
| Activo | Criticidad | Descripción |
|--------|------------|-------------|
| Bloques consolidados | Alta | Datos inmutables de Feldman |
| Cadena de hashes | Alta | Integridad del sistema |
| Credenciales | Alta | Acceso a servicios |
| Datos de usuario | Media | Información personal/empresarial |
| Configuración | Media | Parámetros del sistema |
---
## Amenazas Identificadas
### T1: Manipulación de Datos
| Aspecto | Valor |
|---------|-------|
| Descripción | Alteración de bloques consolidados |
| Impacto | Crítico |
| Probabilidad | Baja |
| Mitigación | Inmutabilidad, cadena de hashes, auditoría |
### T2: Acceso No Autorizado
| Aspecto | Valor |
|---------|-------|
| Descripción | Acceso a datos sin permiso |
| Impacto | Alto |
| Probabilidad | Media |
| Mitigación | Autenticación, autorización, cifrado |
### T3: Pérdida de Datos
| Aspecto | Valor |
|---------|-------|
| Descripción | Pérdida de información por fallo |
| Impacto | Alto |
| Probabilidad | Media |
| Mitigación | Backups, replicación, DR |
### T4: Compromiso de Credenciales
| Aspecto | Valor |
|---------|-------|
| Descripción | Robo de API keys o contraseñas |
| Impacto | Alto |
| Probabilidad | Media |
| Mitigación | Infisical, rotación, least privilege |
### T5: Denegación de Servicio
| Aspecto | Valor |
|---------|-------|
| Descripción | Indisponibilidad del sistema |
| Impacto | Medio |
| Probabilidad | Baja |
| Mitigación | Rate limiting, CDN, redundancia |
---
## Matriz de Riesgos
```
IMPACTO
Bajo Medio Alto Crítico
┌────────┬────────┬────────┬────────┐
Alta │ │ │ T2 │ │
├────────┼────────┼────────┼────────┤
P Media │ │ T5 │ T3,T4 │ │
R ├────────┼────────┼────────┼────────┤
O Baja │ │ │ │ T1 │
B ├────────┼────────┼────────┼────────┤
Muy │ │ │ │ │
Baja │ │ │ │ │
└────────┴────────┴────────┴────────┘
```
---
## Controles
### Preventivos
| Control | Amenazas |
|---------|----------|
| Cifrado en reposo | T1, T2 |
| Cifrado en tránsito | T2 |
| Autenticación MFA | T2, T4 |
| Rotación de secretos | T4 |
| Principio least privilege | T2, T4 |
### Detectivos
| Control | Amenazas |
|---------|----------|
| Sentinel LIGHT | T1 |
| Sentinel DEEP | T1 |
| Logs de acceso | T2 |
| Alertas de anomalías | T2, T5 |
### Correctivos
| Control | Amenazas |
|---------|----------|
| Backups | T3 |
| DR plan | T3, T5 |
| Revocación de credenciales | T4 |
---
## Respuesta a Incidentes
### Proceso
1. **Detectar** - Sentinel, logs, alertas
2. **Contener** - Aislar sistema afectado
3. **Erradicar** - Eliminar amenaza
4. **Recuperar** - Restaurar servicio
5. **Documentar** - Lecciones aprendidas
### Contactos
| Rol | Responsabilidad |
|-----|-----------------|
| Administrador | Primera respuesta |
| Propietario | Decisiones de negocio |
| Backup | Restauración de datos |

101
06_SEGURIDAD/respuesta-incidentes.md Normal file
View File

@@ -0,0 +1,101 @@
# Respuesta a Incidentes
**Estado:** Activo
---
## Respuesta a Compromiso de Credencial
| Tiempo | Acción |
|--------|--------|
| **INMEDIATO** | Revocar credencial comprometida en el servicio origen |
| **T+5min** | Generar y desplegar nueva credencial |
| **T+15min** | Auditar logs de acceso para evaluar impacto |
| **T+1h** | Documentar incidente y actualizar procedimientos |
---
## Niveles de Severidad
| Severidad | Descripción | Tiempo Respuesta |
|-----------|-------------|------------------|
| **CRITICAL** | Master Key, KEK comprometida | Inmediato |
| **HIGH** | API Key producción, DB credential | < 5 min |
| **MEDIUM** | Service token, webhook | < 30 min |
| **LOW** | Token de desarrollo | < 24h |
---
## Acciones por Tipo de Incidente
### Compromiso de API Key
```
1. Revocar en el servicio (Anthropic, OpenRouter, etc.)
2. Generar nueva key
3. Actualizar en Infisical
4. Verificar servicios
5. Revisar logs
```
### Compromiso de DB Credential
```
1. Cambiar contraseña en PostgreSQL
2. Actualizar en Infisical
3. Reiniciar servicios dependientes
4. Revisar accesos anómalos
```
### Compromiso de SSH Key
```
1. Revocar en authorized_keys
2. Generar nuevo par de llaves
3. Actualizar en todos los servidores
4. Revisar logs de acceso SSH
```
### Compromiso de KEK/Master Key
```
1. ALERTA CRÍTICA inmediata
2. Rotar TODAS las credenciales derivadas
3. Re-cifrar datos con nueva KEK
4. Auditoría completa de accesos
5. Análisis forense
```
---
## Post-Incidente
| Paso | Descripción |
|------|-------------|
| 1 | Documentar timeline completo |
| 2 | Identificar causa raíz |
| 3 | Actualizar procedimientos |
| 4 | Comunicar a stakeholders si aplica |
| 5 | Implementar medidas preventivas |
---
## Contactos de Emergencia
| Rol | Canal |
|-----|-------|
| Admin principal | Slack #alerts |
| Backup admin | ntfy + Email |
| Escalación | PagerDuty |
---
## Checklist de Incidente
- [ ] Credencial revocada
- [ ] Nueva credencial generada
- [ ] Servicios verificados
- [ ] Logs revisados
- [ ] Impacto evaluado
- [ ] Incidente documentado
- [ ] Stakeholders notificados (si aplica)

62
06_SEGURIDAD/rotacion.md Normal file
View File

@@ -0,0 +1,62 @@
# Política de Rotación
**Estado:** Activo
---
## Matriz por Tipo de Credencial
| Tipo | Rotación | Ejemplos | Responsable |
|------|----------|----------|-------------|
| `API_KEY` | 90 días | OpenRouter, Groq, Cloudflare | Automatizado + Revisión |
| `DB_CREDENTIAL` | 30 días | PostgreSQL, Redis | Automatizado |
| `SERVICE_TOKEN` | 7 días | n8n, Nextcloud, Slack webhooks | Automatizado |
| `CERTIFICATE` | 90 días | SSL/TLS (Let's Encrypt) | Traefik auto-renovación |
| `SIGNING_KEY` | 180 días | JWT, KEK-SIGNING | Manual + Notificación |
| `ENCRYPTION_KEY` | 365 días | AES-256, KEK-DATA | Manual + Auditoría |
| `SSH_CREDENTIAL` | 180 días | Llaves SSH servidores | Manual + Backup |
---
## Procedimiento de Rotación
```
1. SENTINEL genera alerta 7 días antes de expiración
2. Generar nueva credencial en el servicio
3. Actualizar en Infisical (versión anterior se mantiene 24h para rollback)
4. Verificar funcionamiento de servicios dependientes
5. Revocar credencial anterior en el servicio origen
```
---
## Alertas de Rotación
| Tiempo restante | Severidad | Acción |
|-----------------|-----------|--------|
| 7 días | MEDIUM | Email a admin |
| 24 horas | HIGH | Email + Slack |
| Expirada | CRITICAL | Email + Slack + PagerDuty |
---
## Calendario de Rotación
| Frecuencia | Credenciales |
|------------|--------------|
| **Semanal** | SERVICE_TOKEN (webhooks, tokens temporales) |
| **Mensual** | DB_CREDENTIAL (PostgreSQL, Redis) |
| **Trimestral** | API_KEY, CERTIFICATE |
| **Semestral** | SIGNING_KEY, SSH_CREDENTIAL |
| **Anual** | ENCRYPTION_KEY, MASTER_KEY |
---
## Automatización
| Tarea | Herramienta |
|-------|-------------|
| Alertas expiración | SENTINEL |
| Renovación certificados | Traefik + Let's Encrypt |
| Rotación DB credentials | Script + Infisical API |
| Notificaciones | ntfy + Slack |

115
06_SEGURIDAD/secretos.md Normal file
View File

@@ -0,0 +1,115 @@
# Gestión de Secretos
**Gestor:** Infisical
**Estado:** Operativo
---
## Principio
```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ Las llaves nunca viajan con los datos que protegen. │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Infisical
| Parámetro | Valor |
|-----------|-------|
| URL | http://{ip}:8082 |
| Proyectos | anthropic, servers, databases, r2 |
| Acceso | Machine Identities |
---
## Proyectos
| Proyecto | Contenido |
|----------|-----------|
| **anthropic** | API keys de IA |
| **servers** | SSH, accesos servidores |
| **databases** | Credenciales PostgreSQL, Redis |
| **r2** | Keys de Cloudflare R2 |
---
## Categorías de Secretos
| Categoría | Ejemplos |
|-----------|----------|
| APIs IA | OpenRouter, Groq, Anthropic, OpenAI |
| Bases de datos | PostgreSQL, Redis |
| Almacenamiento | Storj, R2, Arweave |
| Infraestructura | n8n, Nextcloud, Windmill |
| Blockchain | Polygon, NOTARIO |
| Comunicaciones | Resend, Slack, ntfy |
| DNS/CDN | Cloudflare, Let's Encrypt |
| GPU | RunPod |
| Servidores | SSH credentials |
| Cifrado | Master Key, KEKs |
---
## Matriz de Rotación
| Tipo | Rotación | Ejemplos |
|------|----------|----------|
| API_KEY | 90 días | OpenRouter, Groq, Cloudflare |
| DB_CREDENTIAL | 30 días | PostgreSQL, Redis |
| SERVICE_TOKEN | 7 días | n8n, Nextcloud, Slack |
| CERTIFICATE | 90 días | SSL/TLS (auto) |
| SIGNING_KEY | 180 días | JWT, KEK-SIGNING |
| ENCRYPTION_KEY | 365 días | AES-256, KEK-DATA |
| SSH_CREDENTIAL | 180 días | Llaves SSH |
---
## Acceso por Instancia
Cada instancia tiene su propia Machine Identity:
```
ARCHITECT → Machine Identity: architect_prod
DECK → Machine Identity: deck_prod
CORP → Machine Identity: corp_prod
HST → Machine Identity: hst_prod
```
---
## Uso en Código
```python
from infisical import InfisicalClient
client = InfisicalClient(
client_id=os.environ["INFISICAL_CLIENT_ID"],
client_secret=os.environ["INFISICAL_CLIENT_SECRET"]
)
# Obtener secreto
api_key = client.get_secret(
project_id="anthropic",
environment="production",
secret_name="ANTHROPIC_API_KEY"
)
```
---
## Nunca en Código
Los siguientes NUNCA deben estar en repositorios:
- API keys
- Contraseñas de BD
- Tokens de acceso
- Llaves privadas
- Certificados
Siempre usar Infisical o variables de entorno.