Server and agent architecture

The server owns configuration, inventory, users, jobs, and history. Agents connect outward to the server over a WebSocket and wait for allowed work. This makes it possible to place an agent beside a remote or segmented network without putting the central server on every broadcast domain.

Communication paths

• The browser uses REST APIs for normal data operations.
• Server-sent events stream selected job and interface updates to the browser.
• Agents maintain bidirectional WebSocket connections to receive commands and stream results.

Jobs preserve the request, status, duration, parent/child relationships, failures, and structured logs. The UI can follow those logs while work is running and use completed netinfo or netscan results as import sources.

Agent modules

The current agent includes:

• netinfo for hostname, interface, address, route, gateway, and resolver information;
• ARP-based netscan for local-network host discovery and OUI vendor enrichment;
• ping for reachability checks;
• TCP and UDP port probes;
• optional nmap enrichment for service detection, configurable port profiles, OS detection, and allow-listed NSE scripts.

Not every module is available on every operating system or privilege level. The agent advertises its capabilities so the server can avoid treating all workers as identical.

Trust boundary

An agent can perform network operations where it runs. Protect its token, grant the host only the privileges required by enabled modules, and restrict sensitive modules. For example, nmap NSE scripts are allow-listed in agent configuration because scripts differ significantly in cost and behavior.

Connectivity

The agent initiates its server connection. Ensure it can resolve and reach the server's WebSocket endpoint, and account for TLS termination or reverse-proxy timeouts when deploying beyond a trusted local environment.