Skip to main content

Connect an agent

The Go agent connects to MiniPAM and executes server-requested modules near the target network. Build it from the repository root:

go build -race -v -o bin/app-agent ./app-agent/cmd

Create an agent identity in the UI, associate it with the correct site, and choose a long random token. Store the same token as a secret on the agent host. Connect to the server's agent WebSocket explicitly:

./bin/app-agent run server \
  --address ws://localhost:8091/ws/agent \
  --key YOUR_AGENT_TOKEN

Use wss:// when TLS is terminated for the server. The server records the worker as online and requests an initial netinfo job after it connects. Detected capabilities and network information appear on the agent record; allowed-import controls can restrict what automatic import jobs may create.

Test without network privileges​

Demo mode replaces network-facing modules with deterministic scenario data, so it does not need raw sockets, pcap, or nmap. The repository includes an embedded demo identity for development:

./bin/app-agent run demo --address ws://localhost:8091/ws/agent

The server must contain an agent identity whose token matches the demo scenario. Use --scenario-dir and --agent to run a custom scenario.

Operational guidance​

  • Run the agent with the least operating-system privilege its enabled modules require.
  • Protect the agent token and rotate it if it is exposed.
  • Prefer TLS (wss://) when the connection leaves a trusted host or network.
  • Set scan targets and timeouts conservatively.
  • Allow-list nmap scripts explicitly; do not enable arbitrary scripts by default.

See Server and agents for the trust and communication model.

Last updated on