Descripción general

Integraciones — Descripción general

TraceWall se conecta a infraestructura externa mediante conectores de solo lectura. Cada integración es una configuración que define: endpoint, credenciales cifradas, alcance, intervalo de polling y filtros.

Conectores disponibles

Conector	Tipo	Protocolo/Puerto	Datos principales	Estado
FortiGate	Firewall / Network Security	HTTPS 443 (REST)	Config, políticas, interfaces, rutas, logs, IPS, AV	🔄 En validación
Palo Alto	Firewall / Network Security	HTTPS 443 (XML API)	Config, reglas, interfaces, User-ID, logs, WildFire	🔄 En validación
Wazuh	SIEM / Endpoint Security	HTTPS 55000 (REST)	Agentes, alertas, eventos, vulnerabilidades, FIM	🔄 En validación
Zabbix	Monitoring / Inventory	HTTPS 443 / 80 (JSON-RPC)	Hosts, items, triggers, métricas, mapas	🔄 En validación
SNMP	Network Discovery / Telemetry	UDP 161 (v2c/v3)	Interfaces, sistema, MIB-II, IF-MIB, IP-MIB	✅ Implementado
Syslog	Event Ingestion	UDP 514 / TCP 514 / TLS 6514	Logs crudos de dispositivos/servicios	✅ Implementado

Nota: Los conectores FortiGate, Palo Alto, Wazuh, Zabbix están en validación. La documentación describe el diseño y preparación; verifica el Changelog para confirmar disponibilidad en tu release.

Principios de diseño

Solo lectura — Ningún conector modifica configuración remota. No hay POST/PUT/DELETE a APIs de gestión.
Credenciales locales — Secrets (API keys, tokens, community strings, user/pass) se cifran solo en la máquina (DPAPI Windows / libsecret Linux). Nunca salen de TraceWall.
Polling controlado — Intervalo configurable (defecto 300s). Rate limits respetados. Backoff exponencial en errores.
Alcance mínimo — El operador define qué VDOMs, host groups, rule IDs, OIDs, facilities procesar.
Observabilidad — Cada integración tiene: health check, logs dedicados, métricas de polling (latencia, errores, rows).

Flujo de integración

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Settings →     │────▶│  Integración     │────▶│  Main Process   │
│  Integraciones  │     │  (config JSON)   │     │  Scheduler      │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                          │
                        ┌─────────────────────────────────┘
                        ▼
              ┌─────────────────────┐
              │  Polling Worker     │
              │  (proceso hijo o    │
              │   async loop)       │
              └──────────┬──────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
   ┌────────────┐ ┌────────────┐ ┌────────────┐
   │  API REST  │ │  SNMP Get  │ │  Syslog    │
   │  (HTTPS)   │ │  / Walk    │ │  Listener  │
   └─────┬──────┘ └─────┬──────┘ └─────┬──────┘
         │              │              │
         └──────────────┼──────────────┘
                        ▼
              ┌─────────────────────┐
              │  Normalizador       │
              │  (esquema unificado)│
              └──────────┬──────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
   ┌────────────┐ ┌────────────┐ ┌────────────┐
   │  Assets    │ │  Events    │ │  Topology  │
   │  (invent.) │ │  (SIEM)    │ │  (graph)   │
   └────────────┘ └────────────┘ └────────────┘

Configuración típica por conector

FortiGate

{
  "name": "FW-Perimeter-FGT",
  "type": "fortigate",
  "host": "192.0.2.10",
  "port": 443,
  "vdom": "root",
  "credentials": { "api_token": "***" },
  "verify_tls": true,
  "poll_interval_sec": 300,
  "scope": {
    "config": true,
    "policy": true,
    "interface": true,
    "route": true,
    "log_ids": ["traffic", "utm", "event"]
  }
}

Palo Alto

{
  "name": "FW-Core-PAN",
  "type": "paloalto",
  "host": "192.0.2.20",
  "port": 443,
  "credentials": { "api_key": "***" },
  "verify_tls": true,
  "poll_interval_sec": 300,
  "scope": {
    "config": true,
    "rulebase": true,
    "interfaces": true,
    "log_types": ["traffic", "threat", "url", "wildfire"]
  }
}

Wazuh

{
  "name": "SIEM-Wazuh-Mgr",
  "type": "wazuh",
  "host": "198.51.100.30",
  "port": 55000,
  "credentials": { "username": "tracewall_ro", "password": "***" },
  "verify_tls": true,
  "poll_interval_sec": 60,
  "scope": {
    "agents": true,
    "alerts": { "min_level": 5, "rule_groups": ["web-attack", "auth-fail"] },
    "fim": true,
    "vulnerabilities": true
  }
}

Zabbix

{
  "name": "Mon-Zabbix-Prod",
  "type": "zabbix",
  "host": "203.0.113.40",
  "port": 443,
  "path": "/api_jsonrpc.php",
  "credentials": { "api_token": "***" },
  "verify_tls": true,
  "poll_interval_sec": 300,
  "scope": {
    "host_groups": ["Linux Servers", "Network Devices"],
    "templates": ["Linux by Zabbix Agent", "Cisco IOS SNMP"],
    "items": ["cpu.util", "mem.avail", "net.if.in", "net.if.out"],
    "triggers": true
  }
}

SNMP

{
  "name": "Net-SNMP-Core",
  "type": "snmp",
  "targets": ["192.0.2.1", "192.0.2.2", "198.51.100.10"],
  "version": "v3",
  "credentials": {
    "username": "tracewall_ro",
    "auth_protocol": "SHA",
    "auth_pass": "***",
    "priv_protocol": "AES",
    "priv_pass": "***"
  },
  "poll_interval_sec": 600,
  "scope": {
    "oids": [
      "1.3.6.1.2.1.1",      // system
      "1.3.6.1.2.1.2",      // interfaces
      "1.3.6.1.2.1.4.20",   // ipNetToMedia (ARP)
      "1.3.6.1.2.1.4.21",   // ipRouteTable
      "1.3.6.1.2.1.17"      // bridge (MAC table)
    ]
  }
}

Syslog

{
  "name": "Syslog-Collector",
  "type": "syslog",
  "listen": {
    "udp": 514,
    "tcp": 514,
    "tls": 6514
  },
  "tls": {
    "cert_file": "/opt/tracewall/certs/syslog.pem",
    "key_file": "/opt/tracewall/certs/syslog.key",
    "ca_file": "/opt/tracewall/certs/ca.pem",
    "verify_client": false
  },
  "parsers": ["rfc5424", "rfc3164", "cef", "leef"],
  "scope": {
    "facilities": ["auth", "authpriv", "daemon", "local0-local7"],
    "filter": "severity >= notice"
  }
}

Seguridad de credenciales

Plataforma	Mecanismo	Detalle
Windows	DPAPI (CryptProtectData)	Cifrado por usuario + máquina opcional. Solo el usuario que guardó el secret puede descifrarlo.
Linux	libsecret (Secret Service)	Backend: `gnome-keyring`, `kwallet`, `keepassxc`. Requiere session D-Bus.

Nunca se almacenan en config.json en claro. El JSON guarda solo un identificador opaco (cred_id) que Main resuelve al leer del almacén seguro.

Health check y diagnóstico

Cada integración expone en Settings → Integraciones:

Métrica	Qué indica
Estado	🟢 Conectado / 🟡 Degradado / 🔴 Error / ⚫ Deshabilitado
Último poll OK	Timestamp epoch
Errores consecutivos	Contador; ≥3 → 🔴
Latencia última (ms)	Tiempo API request→response
Filas ingestadas	Assets / Events / Topology en último ciclo
Log dedicado	`integration_<name>.log` en carpeta logs

Botones: [Probar conexión] [Ver logs] [Reintentar ahora] [Deshabilitar] [Eliminar]

Limitaciones conocidas

Conector	Limitación
FortiGate	Solo VDOM `root` en v1; multi-VDOM roadmap
Palo Alto	Requiere API key generada en PAN-OS; no PAN-OS 11.x nuevo auth todavía
Wazuh	Solo API REST; sin conexión directa a indexer (OpenSearch)
Zabbix	Solo read API; no active checks / trapper
SNMP	v2c community string en clear en config (mitigar: SNMPv3)
Syslog	Parsers fijos; logs no estándar → raw_json only

Páginas de esta sección

Página	Qué cubre
FortiGate	Preparación, API token, VDOMs, logs, validación
Palo Alto	API key, rulebase, interfaces, TLS, validación
Wazuh	API endpoint, roles read-only, alertas, FIM, vulns
Zabbix	API token, host groups, templates, items, triggers
SNMP	v2c/v3, OIDs, MIBs, credenciales, rate limits
Syslog	UDP/TCP/TLS, parsers, facilities, filtrado
Seguridad de credenciales	DPAPI/libsecret, rotación, auditoría, backup
Diagnóstico de integraciones	Health, logs, errores comunes, rate limits, TLS

Páginas relacionadas

Settings: Integraciones — UI de configuración
Assets & Inventory — Datos normalizados en inventario
Events / SIEM — Eventos ingeridos
Network Topology — Rutas, VPNs, zonas desde FW
Exposure Intelligence — Targets desde integraciones
Command Center — Badges de estado integraciones
Solución de problemas: Integración sin conexión
Solución de problemas: Error TLS
Seguridad: Credenciales — Almacenamiento seguro