Local Sensor

Componente de recolección de telemetría del host donde corre TraceWall. Es la fuente primaria de visibilidad local.

Qué recopila (campos reales)

Categoría	Campos	Frecuencia	Permisos
Host	`hostname`, `os`, `os_version`, `uptime_seconds`, `boot_time`	60 s	Usuario estándar
CPU	`total_percent`, `per_cpu_percent[]`, `freq_current`, `freq_min`, `freq_max`, `load_avg_1/5/15`	10 s	Usuario estándar
Memoria	`total`, `available`, `used`, `free`, `percent`, `swap_total`, `swap_used`, `swap_percent`	10 s	Usuario estándar
Disco	`partitions[]`: `device`, `mountpoint`, `fstype`, `total`, `used`, `free`, `percent`	30 s	Usuario estándar
Interfaces	`name`, `type` (ethernet/wifi/loopback/tunnel), `ipv4[]`, `ipv6[]`, `mac`, `mtu`, `speed`, `duplex`, `flags` (up/broadcast/running), `stats` (rx/tx bytes/packets/errs/drops)	30 s	Usuario estándar
ARP	`ip`, `mac`, `interface`, `type` (dynamic/static)	60 s	Usuario estándar
Rutas	`destination`, `netmask`, `gateway`, `interface`, `metric`, `protocol` (kernel/static/dhcp)	60 s	Usuario estándar
Procesos	`pid`, `ppid`, `name`, `exe`, `cmdline[]`, `username`, `cpu_percent`, `memory_percent`, `memory_rss`, `create_time`, `status`, `num_threads`, `open_files`, `connections[]`	30 s	Usuario estándar (algunos campos req. Admin)
Servicios	`name`, `display_name`, `status` (running/stopped/paused), `start_type` (auto/manual/disabled), `binary_path`, `pid`	60 s	Usuario estándar
Puertos	`protocol` (tcp/udp), `local_ip`, `local_port`, `remote_ip`, `remote_port`, `state` (listen/established/time_wait), `pid`, `process_name`	30 s	Usuario estándar / Admin (raw sockets)
DNS	`servers[]` (configurados), `cache[]` (recientes), `resolution_latency_ms`	60 s	Usuario estándar

Arquitectura del sensor

┌─────────────────────────────────────────────────────────────┐
│                    MAIN PROCESS (Electron)                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Sensor Manager (Node.js)                           │   │
│  │  - Programa timers por módulo                       │   │
│  │  - Lanza collectors (child_process.fork)            │   │
│  │  - Recibe stdout JSON lines                         │   │
│  │  - Valida schema → Normaliza → Enriquece → SQLite   │   │
│  │  - Emite eventos IPC a Renderer (UI updates)        │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
    ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
    │ Collector   │ │ Collector   │ │ Collector   │
    │ Network     │ │ System      │ │ Process     │
    │ (interfaces,│ │ (cpu, mem,  │ │ (processes, │
    │  ARP, routes)│ │  disk, svc)│ │  ports)     │
    └─────────────┘ └─────────────┘ └─────────────┘
           │               │               │
           └───────────────┼───────────────┘
                           ▼
                  ┌─────────────────┐
                  │  SQLite (WAL)   │
                  │  tracewall.db   │
                  └─────────────────┘

Collectors (procesos hijos)

Collector	Plataforma	Método principal	Dependencias
Network	Win/Lin	`GetAdaptersAddresses` / `getifaddrs` + `ioctl` SIOCGARP + `GetIpForwardTable` / `netlink`	Npcap (Win) para stats detalladas
System	Win/Lin	`GetSystemTimes` + `GlobalMemoryStatusEx` / `sysinfo` + `/proc/stat` + `/proc/meminfo`	Ninguna
Process	Win/Lin	`EnumProcesses` + `OpenProcess` / `/proc/[pid]/stat` + `/proc/[pid]/cmdline`	Admin/root para cmdline completo de otros usuarios
Ports	Win/Lin	`GetExtendedTcpTable` / `ss -tulpn` o `netstat` parse	Npcap (Win) para owner PID en LISTEN; `CAP_NET_ADMIN` (Lin)

Normalización y enriquecimiento

Validación → JSON Schema por tipo; inválidos → audit_log + drop
Claves de fusión → interface: name+mac, process: pid+create_time, port: proto+local_ip+local_port
Enriquecimiento:
- OUI lookup (MAC → vendor) — base local IEEE OUI
- Reverse DNS (cache 1h, async)
- Geolocalización RFC1918 (privado) / IP pública (si Exposure)
- Etiqueta subred/gateway (desde rutas)
Persistencia → assets, interfaces, processes, ports, routes, arp, dns tables

Almacenamiento (SQLite — tablas sensor)

-- Interfaces de red
CREATE TABLE interfaces (
  id TEXT PRIMARY KEY,          -- iface_name@host
  name TEXT, type TEXT, mac TEXT,
  ipv4 TEXT, ipv6 TEXT, mtu INTEGER,
  speed_mbps INTEGER, duplex TEXT,
  flags TEXT, rx_bytes BIGINT, tx_bytes BIGINT,
  rx_packets BIGINT, tx_packets BIGINT,
  rx_errors BIGINT, tx_errors BIGINT,
  rx_drops BIGINT, tx_drops BIGINT,
  last_seen INTEGER, source TEXT DEFAULT 'sensor'
);

-- ARP
CREATE TABLE arp_entries (
  id TEXT PRIMARY KEY,          -- ip@iface
  ip TEXT, mac TEXT, iface TEXT,
  type TEXT,                    -- dynamic/static
  last_seen INTEGER, source TEXT DEFAULT 'sensor'
);

-- Rutas
CREATE TABLE routes (
  id TEXT PRIMARY KEY,          -- dst/mask@gw@iface
  destination TEXT, netmask TEXT, gateway TEXT,
  interface TEXT, metric INTEGER, protocol TEXT,
  last_seen INTEGER, source TEXT DEFAULT 'sensor'
);

-- Procesos (snapshot periódico)
CREATE TABLE processes (
  id TEXT PRIMARY KEY,          -- pid@create_time@host
  pid INTEGER, ppid INTEGER, name TEXT, exe TEXT,
  cmdline TEXT, username TEXT,
  cpu_percent REAL, mem_percent REAL, mem_rss BIGINT,
  create_time INTEGER, status TEXT, num_threads INTEGER,
  open_files INTEGER, connections TEXT, -- JSON
  last_seen INTEGER, source TEXT DEFAULT 'sensor'
);

-- Servicios
CREATE TABLE services (
  id TEXT PRIMARY KEY,          -- name@host
  name TEXT, display_name TEXT,
  status TEXT, start_type TEXT,
  binary_path TEXT, pid INTEGER,
  last_seen INTEGER, source TEXT DEFAULT 'sensor'
);

-- Puertos
CREATE TABLE ports (
  id TEXT PRIMARY KEY,          -- proto@local_ip@local_port@pid
  protocol TEXT, local_ip TEXT, local_port INTEGER,
  remote_ip TEXT, remote_port INTEGER,
  state TEXT, pid INTEGER, process_name TEXT,
  last_seen INTEGER, source TEXT DEFAULT 'sensor'
);

-- DNS
CREATE TABLE dns_config (
  id TEXT PRIMARY KEY,          -- host
  servers TEXT,                 -- JSON array
  cache TEXT,                   -- JSON array
  resolution_latency_ms REAL,
  last_seen INTEGER, source TEXT DEFAULT 'sensor'
);

Configuración (Settings → Sensor)

Parámetro	Rango	Defecto	Impacto
Telemetría local	On/Off	On	No desactivar salvo diagnóstico
Intervalo polling interfaces/ARP/rutas	10–300 s	30 s	Menor = más fresco, más CPU/DB
Intervalo polling procesos/servicios	10–300 s	30 s	Menor = más procesos visibles
Intervalo polling puertos	10–300 s	30 s	Requiere Npcap/CAP_NET_RAW
Incluir procesos de sistema	On/Off	Off	On = más ruido, más completo
Resolver hostnames (reverse DNS)	On/Off	Off	On = latencia en LAN grande; cache 1h
Captura paquetes (Exposure)	On/Off	On	Requiere Npcap (Win) / CAP_NET_RAW (Lin)

Métricas de salud del sensor

Métrica	Saludable	Degradado	Crítico
Latencia ciclo completo	< 2 s	2–5 s	> 5 s
Tasa éxito módulos	100%	95–99%	< 95%
Interfaces UP detectadas	= físicas reales	-1	≤ 1 (solo loopback)
Gateway en rutas	Sí	—	No
Procesos muestreados	> 50	10–50	< 10
Puertos LISTEN detectados	> 5	1–5	0
Errores consecutivos	0	1–3	≥ 4

Permisos requeridos

Plataforma	Operación	Permiso mínimo	Elevación para completo
Windows	Interfaces, ARP, Rutas	Usuario estándar	Admin para contadores perf / cmdline otros usuarios
Windows	Puertos (owner PID)	Usuario estándar	Npcap + Admin para `GetExtendedTcpTable` completo
Windows	Procesos (cmdline, open_files)	Usuario estándar	Admin para procesos SYSTEM/otros usuarios
Linux	Interfaces, ARP, Rutas	Usuario estándar	—
Linux	Procesos (cmdline, fd)	Usuario estándar	`CAP_SYS_PTRACE` o root para `/proc/[pid]/cmdline` ajenos
Linux	Puertos (owner PID)	Usuario estándar	`CAP_NET_ADMIN` para `ss -tulpn` completo

Errores comunes y diagnóstico

Error / Log	Causa	Verificación	Fix
`ENOENT: no such file /proc/net/arp`	Contenedor sin `/proc`	`ls /proc/net/arp`	No soportado en contenedor
`Npcap not installed` (Win)	Falta driver	`sc query npcap`	Instalar Npcap modo WinPcap API-compat
`Access denied` en `OpenProcess`	Sin Admin	`whoami /groups`	Ejecutar como Admin o aceptar datos limitados
`CAP_NET_RAW missing` (Lin)	Sin capability	`getcap /opt/tracewall/tracewall`	`sudo setcap cap_net_raw+eip /opt/tracewall/tracewall`
`Interface stats all zero`	Contadores deshabilitados (Win)	`lodctr /q`	`lodctr /e:PerfLib`
`DNS resolution timeout`	Sin conectividad a DNS	`nslookup google.com`	Verificar DNS config / firewall
`Sensor health: DEGRADED`	Módulo fallando	Logs `sensor.log`	Reiniciar app; revisar módulo específico

Limitaciones

Límite	Detalle
Sin agente remoto	Solo host local; otros hosts vía integraciones
No captura paquetes completa	Solo stats interfaces; Exposure usa raw sockets puntuales
Procesos efímeros	Intervalos 30s → pierden procesos < 1s
Contenedores	Ve interfaces `veth*`, `docker0`; no aisla por namespace
IPv6 temporal	Privacy extensions → MAC no correlacionable estable
Windows containers / WSL2	No soportado; sensor ve host Windows, no Linux interno

Páginas relacionadas

Command Center — Tarjeta Sensor en dashboard
Assets & Inventory — Fuente primaria de assets
Network Topology — Gateway, interfaces, rutas
Exposure Intelligence — Puertos/TLS usan captura raw
Configuración: Sensor — Ajustes detallados
Requisitos del sistema — Npcap, permisos
Solución de problemas: Sensor inactivo
Solución de problemas: Interfaces no detectadas