Agent CLI and configuration

The agent binary is minipam-agent. To build and install it, see Install an agent.

Commands

Command	Use
minipam-agent run server	Connect to MiniPAM and run discovery work. This is the normal mode.
minipam-agent run demo	Connect to MiniPAM and replay recorded demo data.
minipam-agent run netinfo	Print this host's network information, without a server.
minipam-agent run ping	Ping an address locally.
minipam-agent run netscan	Run an ARP scan on one interface locally.
minipam-agent run arp-scan	List interfaces, or ARP-scan a CIDR, locally.
minipam-agent run nmap-enrichment	Run nmap enrichment against targets locally.
minipam-agent version	Print the version.

The local commands are useful to test permissions and nmap on a host before connecting it.

Global flags:

Flag	Default	Meaning
--log-level	info	debug, info, warn, or error
--log-colored	true	Colour log output. Set false for files and journals.

Logs go to standard error.

run server

minipam-agent run server --address ws://minipam.lan:8091/ws/agent --key TOKEN --config config.yaml

• -a, --address: Server WebSocket URL. Always ws://HOST:PORT/ws/agent, or wss:// behind HTTPS. Always set it; the built-in default is out of date.
• --key: The token you entered when you created the agent in MiniPAM.
• -c, --config: Configuration file (default config.yaml). Required: the agent will not start without it.

run demo

• -a, --address: Server WebSocket URL (default ws://localhost:8091/ws/agent)
• --scenario-dir: A directory of demo scenario files. Without it, the built-in scenario is used (agent token demo-agent-token).
• --agent: Which agent from the scenario to play. Required with --scenario-dir.
• --seed: Override the scenario's timing seed.
• --validate-only: Check the scenario and exit without connecting.

Local test commands

minipam-agent run netinfo
minipam-agent run ping --address 192.168.1.1 --count 4
minipam-agent run arp-scan --list
sudo minipam-agent run arp-scan --interface eth0 --cidr 192.168.1.0/24
sudo minipam-agent run netscan --interface eth0 --resolve-vendor
minipam-agent run nmap-enrichment --target 192.168.1.10 --script http-title --config config.yaml

run nmap-enrichment also accepts --additional-ports, --service-detection (default on), --os-detection, and --timeout (default 2m).

Configuration file

The configuration file sets what the nmap enrichment and port probe modules are allowed to do. The other modules have no settings. Unknown keys are rejected, so a typo stops the agent instead of being ignored.

This is the file the installer writes to /etc/minipam/config.yaml:

config.yaml

agent:
  modules:
    nmap-enrichment:
      enabled: true
      # OS detection needs root; the service runs as the unprivileged minipam user.
      allow-privileged-detail: false
      max-targets: 64
      timeout: 2m
      port-mode: default
      allowed-scripts:
        - http-title
        - http-headers
        - http-server-header
        - ssl-cert
        - ssh-hostkey
        - smb-os-discovery
        - nbstat
    port-probe:
      enabled: true
      timeout: 2s

nmap-enrichment

• enabled (default true): Offer nmap enrichment to the server. Needs nmap installed.
• allow-privileged-detail (default false): Allow OS detection and the Deep inspection depth. Needs root.
• max-targets (default 64): Most hosts in one request.
• timeout (default 2m): Longest a request may run.
• port-mode (default default): default (nmap's top 1000), fast (top 100), top_ports, or custom
• top-ports: Number of ports when port-mode: top_ports.
• custom-ports: Port list when port-mode: custom, such as 22,80,443,8000-8100.
• allowed-scripts (default the seven above): NSE scripts the server may request. Anything else is refused.
• timing-template: nmap -T0 to -T5.
• version-intensity: nmap version detection intensity, 0 to 9.
• max-retries, host-timeout, min-rate, max-rate: Passed to nmap as the matching options.

The server never passes raw nmap arguments. It can only choose within these limits.

port-probe

Key	Default	Meaning
enabled	true	Offer port probes to the server. Needs nmap.
timeout	2s	How long to wait for each port.

Service settings

When installed as a service, the agent is started by /usr/local/lib/minipam/run-agent, which reads /etc/minipam/agent.env:

Variable	Default	Meaning
MINIPAM_MODE	server	server or demo
MINIPAM_SERVER	ws://localhost:8091/ws/agent	Server WebSocket URL
MINIPAM_KEY	—	Agent token. Required in server mode.
MINIPAM_CONFIG	/etc/minipam/config.yaml	Configuration file
MINIPAM_LOG_LEVEL	info	Log level
MINIPAM_SCENARIO_DIR	/opt/minipam/demo-scenarios	Demo scenarios, in demo mode
MINIPAM_DEMO_AGENT	demo-agent	Demo agent name, in demo mode

Edit the file and restart the service (sudo systemctl restart minipam-agent), or rerun the installer with new --server and --key values.

Platforms

Release packages cover Linux on amd64 and 32-bit ARM (armv6). They are static, so they run on both glibc and musl distributions. For anything else, including 64-bit ARM, build from source with go build on that system. The agent is developed and tested on Linux.