Configuration

Axiom Border reads a single file, configuration.yaml, from the directory given by the AXIOM_CONFIG_DIR environment variable (default: config). An example file, configuration_example.yaml, is supplied alongside it — copy it rather than editing it in place, so you always keep an untouched reference.

cp config/configuration_example.yaml config/configuration.yaml

You will rarely edit the file by hand: the console’s Configuration view and the REST API write this same file — see Changing the configuration below.

sudo systemctl restart axiom-border

Changing the configuration

Three paths write the same file. The web console is the recommended one: it edits the settings a running deployment actually tunes, validates them before writing, and on a managed deployment restarts the service for you. The REST API covers automation and driving a probe without shell access. Editing the file over a shell always works — it is just the least guarded of the three.

​

Web console REST API

Open Configuration in the side menu. The view edits configuration.yaml itself, one group of settings per tab:

Each field is labelled in plain language rather than by its YAML key — nmap: period for schedule, vulnScan: depth for level — and the reference further down this page maps them to the keys they write. The two notices at the top are permanent, not the result of saving: they are there to tell you before you edit that nothing applies until the service restarts, and that the file holds credentials which are preserved for you.

Tab	What it edits
Automatic scans	The securityProbes switches and intervals: enable and schedule for nmap, vulnScan and snmp; the vulnerability scan’s level, severity and OT switches; the interfaces and flushInterval of sniffing
OpenGate	The whole opengate block — connection, collect and provision
MQTT	The whole mqtt block — the embedded broker with its WebSocket and TLS listeners, the internal publisher and the operations client

Everything else — logger, login, influxdb, apiPort, pagination and the per-probe details not listed above, scan targets included — is changed through the API or the file.

Network status has a shortcut straight here: its Automatic scans action opens this view on the first tab, which is where you land when a scheduled scan looks stale or too frequent.

The forms are a window onto the file, not a copy of it. Saving rewrites the whole file but preserves everything the forms do not manage: comments, credentials, and every key outside the three tabs. Leaving a field blank removes its key from the file, returning that setting to its unset behaviour. Durations, ports and cron expressions are checked as you edit, and Save stays disabled while any field holds an invalid value — an invalid document never reaches the probe.

What happens after Save depends on the deployment:

• On a managed deployment, the console asks the deployment manager (Keystone) to restart the service and waits until it reports healthy again — when the green confirmation appears, the change is already live. The console is unresponsive for the few seconds the restart takes.
• On a plain systemd installation, the file is written and an amber banner stays on screen until you restart the service yourself: sudo systemctl restart axiom-border.
• If the automatic restart fails, the write has still succeeded. Restart by hand — keystonectl restart axiom-border, or sudo systemctl restart axiom-border — and the saved configuration applies.

Changing apiPort or the login credential raises an explicit lockout warning: the file is written anyway, so before restarting make sure you can reach the new port or know the new password.

GET /config returns the current YAML and PUT /config replaces it. This exists so a probe can be configured for a customer environment without shell access to the host.

# 1. Authenticate
curl -X POST http://localhost:8083/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<your-password>"}'

# 2. Download the current file as a starting template (authenticated — it contains secrets)
curl -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8083/config -o configuration.yaml

# 3. Edit it, then upload the COMPLETE file
curl -X PUT http://localhost:8083/config \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @configuration.yaml

# 4. Apply
sudo systemctl restart axiom-border

The PUT response reports what happened:

{
  "restartRequired": true,
  "message": "configuration written; restart axiom-border to apply",
  "backup": "/opt/axiom-border/config/configuration.yaml.bak",
  "warnings": ["apiPort changes 8083 -> 9083 (may affect API access after restart)"]
}

Field	Meaning
restartRequired	Always true — configuration only takes effect at startup
message	Confirmation text
backup	Path of the previous file’s backup. Omitted when there was no previous file
warnings	Present only when non-empty. Raised when apiPort or the login credentials change, because either can lock you out

Console and API end in the same validated write, with three guarantees:

• Validation before writing. The document is validated exactly as at startup and checked for the six mandatory fields. Invalid YAML or a missing field returns HTTP 400 and nothing is written.
• Atomic replacement. The file is written to a temporary file in the same directory and renamed.
• Backup of the previous file, forced to 0600 because it contains secrets.

Where the file lives

Overriding any field with an environment variable

Every key can be overridden from the environment by upper-casing it and replacing dots with underscores. A .env file in the working directory is also loaded.

This is the recommended way to handle secrets: keep the tokens and passwords out of the YAML file entirely and inject them through the environment or your secret manager.

Required fields

Only six fields are validated as mandatory. If any is missing, the configuration is rejected:

login.user · login.pass · influxdb.url · influxdb.token · influxdb.org · apiPort

Everything else is optional and has a documented default.

logger

Backend logging, to console and to size-rotated files.

login

The single credential that protects the whole API except /auth/login.

Generate the digest before writing it:

echo -n "yourPassword" | sha256sum

At login, the probe hashes the submitted password and compares it against this value.

influxdb

Connection to the metrics database (InfluxDB 2.x) that stores metrics, audit records, scan results and alarms.

Default bucket set: network_bucket, ssh_bucket, metrics_bucket, usb_bucket, eg_alarms, audit_logs, networktraffic, availability, scanmetrics. The four per-channel event buckets are populated by the oda-lite collector, the rest by the probe itself — see Metrics ingestion.

The probe starts even when the metrics database is unreachable, and every feature that depends on it is inoperative until it recovers. This is deliberate for edge deployments where the database may be a separate node that boots later.

alerts and audit

Top-level keys

pagination

Controls the two read modes over the metrics database. Every field has a default, so the block can be omitted entirely.

trainerDetails

HTTP client settings for the AI container. Only relevant on Linux with a container engine available — see AI capabilities.

Three sub-blocks — metrics, healthCheck and predict — share the same four fields. The {port} literal in each URL is substituted at runtime with the port of the corresponding AI agent.

securityProbes

Security probes run two ways: automatically on an interval (schedule), and manually from the API or UI. Results are stored in local state and in the metrics database — scanmetrics for aggregates, availability for up/down.

securityProbes.nmap

Host discovery, port scanning and optional fingerprinting. Requires the nmap binary on PATH.

securityProbes.vulnScan

Template-based vulnerability scanning, including the embedded OT/ICS suite. The scan engine ships inside the product — there is no scanner binary to install.

level to tag mapping:

Templates directory resolution order: the templatesDir field of the scan request, then securityProbes.vulnScan.templatesDir, then defaultTemplatesDir, then a vulnscan-templates directory next to the product binary. Relative paths resolve against the working directory.

allowTemplateUpdates behaviour:

• true (default, including when the key is absent): best-effort refresh to the latest template release. Being offline or having GitHub blocked does not abort the scan — local templates are kept. An empty directory triggers a full download.
• false: strict offline kill-switch. The network is never touched, even when the directory is empty. If nothing is on disk the scan fails with a clear error.

allowIntrusive governs the write/control layer of the OT suite over both REST and MQTT. A request asking for intrusive mode while this is false is rejected, and the execution ends as failed with an explicit message. The scheduled probe is never intrusive regardless of this flag.

enableOT adds the read-only ot tag to the scheduled sweep even when level would not include it. It never enables the intrusive layer. Some older PLCs are fragile in the face of unexpected connections; enable it only if the OT network tolerates periodic probing.

Recommended steady state for a probe on an industrial segment:

securityProbes:
  vulnScan:
    enabled: true
    level: "medio"
    enableOT: true            # continuous read-only OT visibility
    allowIntrusive: false     # write layer bolted shut
    allowTemplateUpdates: false   # air-gapped: never reach for the network
    defaultTemplatesDir: "/opt/axiom-border/vulnscan-templates"

securityProbes.snmp

With neither oids nor walkRoot set there is nothing for the probe to do.

securityProbes.sniffing

Continuous traffic capture with periodic persistence to the networktraffic bucket.

Interface naming is platform-specific and is the most common source of a probe that captures nothing:

On Windows, the friendly name (Ethernet, Wi-Fi) does not work. Discover the NPF path with nmap --iflist and read the WINDEVICE column.

opengate

Optional cloud integration: inventory reporting (collect) and provisioning (provision). The whole section is inert when enabled: false.

opengate.collect

opengate.provision

mqtt

Three independent blocks: broker is the MQTT broker embedded in the product, client is the internal publisher of executions and alarms, and ops is the client that listens for OpenGate operations and answers them.

mqtt.broker

mqtt.client

Auto-reconnect is always on, retrying every 5 seconds, with a 10 second initial connection timeout. Neither is configurable.

mqtt.ops

If broker, topicSubscribe or topicPublish is empty, the operations module does not start.

Metrics ingestion and audit

Axiom Border’s data comes from two origins. The first one the probe captures by itself: the traffic it sniffs and the scheduled scans it runs against the network around it, with no cooperation from the equipment it watches. The second one is reported to it: every monitored machine runs an oda-lite agent that watches the machine from the inside and sends what it sees.

flowchart TB
    NET["The network around<br>the probe"]:::ext
    MACH["The monitored machines<br><i>an oda-lite agent on each</i>"]:::ext
    NET -->|"sniffing and<br>scheduled scans"| P["<b>Axiom Border</b>"]
    MACH -->|"SSH · USB · interface<br>· health events"| P
    P --> ST[("Metrics store<br><i>history and exports</i>")]
    P --> LP["Live pipeline<br><i>rules · alarms · audit</i>"]
    classDef ext fill:#e9edfa,stroke:#486ac9,color:#101010

Whatever the origin, the data ends in the same two places: the metrics store, which keeps the history behind queries and exports, and the live pipeline, where rules are evaluated, alarms are raised and the audit trail is written. This page follows that flow — the two origins first, then the pipeline, then how to read everything back.

What the probe captures by itself

The network-facing half needs nothing installed on the monitored equipment:

• Traffic capture — continuous sniffing of the configured interfaces, persisted periodically to the networktraffic bucket. Configured under securityProbes.sniffing.
• Scheduled assessments — the discovery, vulnerability and SNMP probes run on their configured intervals, keep the asset inventory current, and record per-scan aggregates (scanmetrics) and host up/down state (availability).

Both are documented in Security assessment. What matters on this page is that their results are data like any other: they land in the store, their executions are audited, and the audit log’s agent filter accepts the probe names (network, vulns, snmp, sniff) alongside the agent channels.

What the agents report

The host-facing half is delivered by oda-lite, a lightweight monitoring agent that ships alongside Axiom Border as a separate component with its own release cycle — the version you have is the one your package includes. It is the whole of the monitoring deployment role: a machine with that role runs only the agent, reporting to a central probe. The probe’s own machine runs one too, so the central host is watched exactly like every other node.

An agent watches four things, and each maps to a channel — the “Guards” of the console views:

Those four names are what the API calls {agentType}: they appear in the read paths (/recent/{agentType}), in the audit log’s agent filter, and as the group routing tag on every event.

flowchart TB
    AG["oda-lite agents<br>on each machine"]:::ext
    OTH["Other reporters<br><i>optional</i>"]:::ext
    AG -->|":9090/agents<br>line protocol"| COL["oda-lite on the probe host<br><i>central profile</i>"]
    OTH -->|":9091/metrics<br>JSON"| COL
    COL -->|"one bucket<br>per channel"| ST[("Metrics store")]
    COL -->|"POST /telegraf"| LP["Live pipeline<br>rules · alarms · audit"]
    classDef ext fill:#e9edfa,stroke:#486ac9,color:#101010

On the probe host, oda-lite runs in its central profile: besides watching its own host, it listens for everyone else on two ports —

Everything it receives — its own guards’ events included — goes two ways at once: each channel is written to its bucket in the metrics store, and every event is forwarded to the probe’s live pipeline, so rules, alarms, audit and the recent feeds see it immediately.

Two operational handles worth knowing:

• The agent is a systemd service on every node: systemctl status oda-lite. Its configuration is generated by the installer at /etc/oda-lite/oda-lite.conf — this is also where the listener ports move if 9090 or 9091 collide with something else.
• Agents buffer briefly and flush every few seconds, so an event appears in the console with at most a few seconds of delay — instantly is the wrong expectation, but a minute is a problem.

Seeing what is reporting in

Supervisions in the console lists the channels the probe is receiving data from. Each card is one channel, with a status dot, the last event it delivered, and the nodes it is monitoring.

This is the first place to look when data is not arriving: a channel with no recent event means the agent has either stopped, or never reached the probe. In the capture above METRIC-Guard is in exactly that state — there is no data to display — which is the same silence that raised the node stopped reporting alarms on Current status. All events opens the full history for that channel.

The live pipeline: rules, alarms and audit

Events reach the probe itself through a single door, POST /telegraf — the same endpoint the collector forwards into. It accepts no authentication, because the processes reporting into it are unattended.

Payload format

The body is {"metrics": [...]} and every metric requires all four fields:

The group tag is the routing key:

Beyond group, the conventional tags are eventType, ip, port and user — these are what rules and queries filter on.

curl -s -X POST http://192.168.1.10:8083/telegraf \
  -H 'Content-Type: application/json' \
  -d '{
    "metrics": [
      {
        "name": "<machine-id>",
        "timestamp": 1746535617,
        "tags": {
          "group": "SSH",
          "eventType": "conn",
          "ip": "192.168.1.80",
          "port": "56390",
          "user": "unknown"
        },
        "fields": { "authevent": 1 }
      },
      {
        "name": "<machine-id>",
        "timestamp": 1746535623,
        "tags": {
          "group": "SSH",
          "eventType": "login_attempt_fail",
          "ip": "192.168.1.80",
          "port": "56390",
          "user": "operator"
        },
        "fields": { "authevent": 1 }
      }
    ]
  }'

The response is 200 with an empty body, or 400 if the JSON does not parse.

Reading data back

There are three ways to read, and choosing the right one is the difference between a responsive UI and a slow one.

Recent feeds — for live views

These answer in microseconds, serving the most recent events the probe already holds without running a historical query. Feed depth is capped by pagination.maxRecentEvents, default 1000.

curl -s -X POST http://192.168.1.10:8083/recent/ssh \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"limit": 50, "orderBy": "desc"}'

{
  "count": 50,
  "warming": false,
  "elements": [ { "_measurement": "<machine-id>", "_time": "2026-05-06T13:27:03.000Z", "eventType": "login_attempt_fail", "user": "operator", "authevent": 1 } ]
}

Optional request fields: limit, uuids to filter by node, and orderBy for presentation order. Note that orderBy only affects how the returned page is sorted — the feed always yields the most recent events, so asc does not page backwards through history.

The warming flag is true while the feed is still being seeded after a restart. Surface it in a UI as a loading state rather than presenting a partial feed as complete.

Three feeds exist: /recent/{agentType} for events, /recent/alarms for alarms, and /recent/auditlog for audit entries. The audit variant takes timeOrder instead of orderBy and adds eventsId and agent filters — the latter also accepting the probe names network, vulns, snmp and sniff.

There is no total or pages in the response. The client paginates locally over what it received.

Paginated ranges — for historical queries

curl -s -X POST http://192.168.1.10:8083/datapagination/ssh \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "from": "2026-08-01T00:00:00Z",
        "to": "2026-08-03T00:00:00Z",
        "page": 1,
        "pageSize": 100,
        "orderBy": "desc"
      }'

A range read is answered in one of two ways, and the response metadata tells you which one you got:

Narrow ranges answer with full random access. Wide ones switch to sequential reading, and nextCursor carries the position of the following page.

{
  "elements": [ "..." ],
  "meta": {
    "total": 3412, "pages": 35, "page": 1, "pageSize": 100,
    "randomAccess": true, "exact": true,
    "range": { "from": "2026-08-01T00:00:00Z", "to": "2026-08-03T00:00:00Z" }
  }
}

To continue a sequential read, send only the cursor field — no from, no to, no page.

Pagination limits are configurable — see Configuration.

Exports — for taking data elsewhere

Streaming CSV, which is the one to use:

curl -s -X POST http://192.168.1.10:8083/data/ssh \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "uuids": ["<machine-id>"],
        "orderby": "desc",
        "range": { "initTime": "2026-08-01T00:00:00Z", "finishTime": "2026-08-03T00:00:00Z" }
      }' -o export.csv

The range is mandatory here, and a range exceeding pagination.rangeExportMaxRows (default 500 000) is rejected with 400 asking you to narrow it. That guard is deliberate.

Parquet, which behaves differently:

curl -s -X POST http://192.168.1.10:8083/parquet/ssh \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"uuids": ["<machine-id>"]}'

Other read helpers

Aliases — making UUIDs readable

Nodes are identified by machine ID, which is unreadable. An alias maps one to a name, and every read endpoint accepts ?alias=true to perform the translation:

curl -s -X POST http://192.168.1.10:8083/alias \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"alias": "plc-line-1", "uuid": "<machine-id>"}'

With ?alias=true, the uuids filter in a request body also accepts alias names, so a client can work entirely in readable names. Note that DELETE /alias takes the alias name, as {"name": "..."}, not the UUID.

Audit

Every significant action is audited to the audit_logs bucket. Two ways to read it:

# Live tail
curl -s -X POST http://192.168.1.10:8083/recent/auditlog \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"limit": 100, "timeOrder": "desc"}'

# Historical, filtered to vulnerability scans
curl -s -X POST http://192.168.1.10:8083/auditlog \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "from": "2026-08-01T00:00:00Z",
        "to": "2026-08-03T00:00:00Z",
        "agent": "vulns",
        "pageSize": 100
      }'

The agent filter accepts the four channel names and the four probe names. Filtering by vulns is how you answer “what was scanned, when, and by whom” — including the warning entry that every intrusive OT scan generates.

Storage layout

Where each kind of data ends up. The four channel buckets are written by the collector; everything else is written by the probe itself:

Buckets are created on first start if absent. Note that no retention policy is applied by default — configure retention in InfluxDB according to your disk budget, or the metrics buckets will grow without bound. An Influx bucket with no retention is a common cause of a probe slowly filling its disk.

Alarms and the rules engine

Axiom Border decides locally. A probe that only forwards data is useless the moment the uplink drops, so alarm evaluation runs on the device, against data it already holds, with no dependency on the platform.

There are two ways to express what should raise an alarm:

Checks cover most of what monitoring needs and need no code. Scripts exist for the cases checks cannot express.

Where you work with alarms

Alerts in the console is the operator’s view: the alarms currently raised, the history of what has been logged, and the Rules configuration button that opens the editor for the rules described below. An autoreload toggle keeps the list current while you watch an incident develop.

Each row names the alarm, the check type behind it, the node it came from, the agent, the severity and a description that includes when the condition was first seen. ACK acknowledges the selected alarm.

Two tabs sit above the table. Recent reads the live feed — the most recent alarms the probe already holds, answered immediately. Range queries a time window from history instead, which is what you want when reconstructing an incident after the fact:

Rules configuration opens the Alarm config screen, which is where both kinds of rule live — the declarative alarm rules in the upper table, and the JavaScript Expert System at the bottom with its own enable switch:

Everything on this page can be done from that screen or from the API, and both paths are shown together wherever they differ.

Checks — declarative rules

A check watches one event type from one agent over a time window, and raises an alarm when its condition holds.

flowchart TB
    EV["Event arrives"] --> MATCH{"Matches<br>a check?"}
    MATCH -->|no| DROP["Stored only"]
    MATCH -->|yes| TYPE{"Check type"}
    TYPE -->|count| CNT{"Count over<br>threshold?"}
    TYPE -->|deadmachine| SILENT{"Silent for<br>the window?"}
    CNT -->|no| WAIT["Keep counting"]
    CNT -->|yes| FIRE["Raise alarm"]
    SILENT -->|yes| FIRE
    FIRE --> COAL{"Alarm<br>already open?"}
    COAL -->|yes| INC["Increment count"]
    COAL -->|no| NEW["New alarm"]

The two check types

deadmachine is the one worth calling out: it alarms on absence, which is how you detect a node that stopped reporting rather than a node reporting something bad.

Creating a check

​

Web console REST API

From Alerts → Rules configuration, use New alarm rule. The wizard walks three steps — Rule config, Alarm config and Summary — and collects exactly the fields described above:

Rule type is the check type, Agent and event choose what to watch, Trigger sets the window and the count, and UUIDs selects the nodes. Only agents actually reporting in are offered, which is why a rule cannot be created before its agent has sent data.

curl -s -X POST http://192.168.1.10:8083/checks \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "checkName": "ssh-bruteforce",
        "agent": "ssh",
        "ctype": "count",
        "event": "login_attempt_fail",
        "freqs": "5m",
        "threshold": 10,
        "level": "critical",
        "alarmName": "SSH brute force attempt",
        "alarmDescription": "More than 10 failed SSH logins in 5 minutes",
        "uuids": ["<machine-id>"],
        "enable": true
      }'

Every field is required on create. freqs is a duration string — 30s, 5m, 1h. level is info, low, medium, high or critical. uuids lists the nodes the check applies to, and accepts alias names when the request carries ?alias=true.

A dead-machine check for the same node:

curl -s -X POST http://192.168.1.10:8083/checks \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "checkName": "node-silent",
        "agent": "metrics",
        "ctype": "deadmachine",
        "event": "cpu",
        "freqs": "10m",
        "threshold": 0,
        "level": "critical",
        "alarmName": "Node stopped reporting",
        "alarmDescription": "No metrics received from the node in 10 minutes",
        "uuids": ["<machine-id>"],
        "enable": true
      }'

Managing checks

To pause a check without losing its definition, set enable: false rather than deleting it.

Alarm coalescing

A brute-force attempt that trips a threshold every five minutes for an hour should be one alarm with a count, not twelve identical alarms. Axiom Border coalesces repeated firings of the same rule against the same node into a single open alarm:

The alarm stays open and accumulating until someone acknowledges it. Acknowledgement is what closes the coalescing window — the next occurrence after an acknowledgement opens a fresh alarm, so the operator gets a new signal rather than a silent increment on something they already dealt with.

Acknowledging

curl -s -X PATCH 'http://192.168.1.10:8083/alarms?alarmid=<alarm-id>' \
  -H "Authorization: Bearer <jwt-token>"

This sets ack=1 and records ackTime. Acknowledging an already-acknowledged alarm returns 400, so a UI can treat that as “someone else got there first” rather than an error worth surfacing loudly.

Reading alarms

# Live feed
curl -s -X POST http://192.168.1.10:8083/recent/alarms \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"limit": 50, "orderBy": "desc"}'

# Historical, paginated
curl -s -X POST http://192.168.1.10:8083/alarms \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"from": "2026-08-01T00:00:00Z", "to": "2026-08-03T00:00:00Z", "pageSize": 100}'

An alarm carries alarmId, alarmName, alarmDescription, criticality, eventType, agent, agentUuid, time, ackTime, and the coalescing trio.

Alarms are stored in the eg_alarms bucket. Evaluation applies a tolerance window set by alerts.offset (default 10 s) to absorb clock skew and ingestion latency — without it, an event landing milliseconds outside a window boundary would be missed.

Rule scripts

For logic that a declarative check cannot express, Axiom Border runs rule scripts written in JavaScript. They are evaluated on the device, server-side, on events you did not trigger.

In the console these are the Expert System, edited from Alerts → Rules configuration → Edit script. The editor opens on a working skeleton, so you can see the shape a script must have before writing one:

Note the Enable switch beside the editor on the Alarm config screen: a saved script does nothing until it is turned on.

How scripts are organised

A script is identified by name, and the name determines when it runs. Scripts named after an agent — ssh, iface, usb, metrics — run on events for that agent. Scripts named after a probe — network, vulns, snmp, sniff — run on that probe’s findings. A general-purpose rulesengine script runs over every ingested batch.

Every script has an enabled state, set with the ?enabled= query parameter when you upload it and reported by GET /scripts. A disabled script is stored but never invoked.

The script contract

A script must define a function called process, which receives the batch of metrics:

function process(metrics) {
  for (var i = 0; i < metrics.length; i++) {
    var metric = metrics[i];
    metric.SetT0();
    // your logic here
    metric.SetT1();
  }
}

SetT0() and SetT1() bracket your processing and are what populate the timing fields in the audit record. They are not required for the rule to work, but including them is the convention and it makes slow rules visible.

Available globals

Each metric exposes: GetTagByName(key), GetFieldByName(key), ExistsField(key), GetMetricName(), GetAliasName(), GetAgentType(), GetMonitoredEvents(), GetEventValues(), GetTime(), SetT0(), SetT1() and String().

A worked example, raising an alarm when a scan finds a risky port open:

var RISKY_PORTS = { 23: "telnet", 21: "ftp", 3389: "rdp", 445: "smb", 5900: "vnc" };

function process(metrics) {
  for (var i = 0; i < metrics.length; i++) {
    var m = metrics[i];
    m.SetT0();

    if (m.GetTagByName("kind") === "port" && m.GetFieldByName("portStatus") === "open") {
      var port = m.GetFieldByName("portNumber");
      if (RISKY_PORTS[port]) {
        newAlarm(m, "critical",
          "Risky service " + RISKY_PORTS[port] + " exposed on port " + port,
          "Risky port open", "port_discovery");
      }
    }

    m.SetT1();
  }
}

The tags and fields available per probe are documented in the header comment of each deployed script, so read the script with GET /scripts/{scriptname} before writing rules against it.

Managing scripts

# Upload a rule for SSH events
curl -s -X POST 'http://192.168.1.10:8083/scripts/ssh?enabled=true' \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: text/plain' \
  --data-binary @ssh-rule.js

# Read back what is deployed
curl -s http://192.168.1.10:8083/scripts/ssh \
  -H "Authorization: Bearer <jwt-token>"

Uploading through the API is the recommended path — it works on a probe you have no shell access to, and it is the same mechanism the web console uses.

gojaTimeout: "8s"

Scripts can call the AI model

A script can invoke inference against a deployed AI capability, using the predict endpoint configured under trainerDetails.predict. This is what connects anomaly detection to alarm generation: the model scores an event, and the script decides whether that score warrants an alarm.

Timeouts and retries for that call come from trainerDetails.predict — default 10 s, one retry. Note that the call is bounded by gojaTimeout as well, so a predict timeout longer than the script timeout cannot complete. Keep gojaTimeout comfortably above the predict timeout if your rules use inference.

See AI capabilities for deploying a model in the first place.

Security probe results reach the rules engine too

Security probe findings are evaluated by the rules engine and audited exactly like agent metrics. A scan finding can therefore raise an alarm the same way a metric can — a newly discovered host, a critical vulnerability, a port that opened when it should not have. See Security probes.

Choosing between a check and a script

Reach for a check when the condition is “this event, this many times, this window”. It is declarative, visible in the API, and cannot fail in interesting ways.

Reach for a script when you need to remember something between events, combine two signals, compute a value, or ask the model. The cost is that scripts are code: they need a timeout that works, they fail in ways checks do not, and they are harder to audit at a glance.

If a check can express it, use the check.

Where alarms go next

Locally, alarms land in eg_alarms and surface through the feeds above and in the web console.

If OpenGate integration is enabled, alarms and executions also publish over the embedded MQTT broker and are forwarded to the platform, which is how a fleet of probes becomes a single operational picture. See MQTT and OpenGate operations.

Security probes

Axiom Border assesses the network it sits on with four probes. They share one execution model, one audit trail and one accumulated view of results, so the findings of each one reinforce the others instead of living in separate reports.

Each runs two ways: automatically on a configurable interval, and manually on demand from the API or the web UI. Results are kept locally as probe state and written to InfluxDB as metrics, and every execution is audited.

flowchart TB
    DISC["Network discovery<br><i>live hosts and ports</i>"]
    DISC --> VULN["Vulnerabilities"]
    DISC --> SNMP["SNMP identity"]
    DISC --> CAP["Traffic capture"]
    VULN --> INV
    SNMP --> INV
    CAP --> INV
    DISC --> INV[("Consolidated<br>inventory")]
    INV --> ALARM["Alarms and<br>audit trail"]

Network discovery establishes the baseline and the other three enrich it. That ordering matters: a vulnerability scan with no targets scans every host in the baseline, so a discovery scan must have run first for it to have anything to do. Newly discovered hosts also trigger a vulnerability scan on their own, grouped together after a short delay, so new assets get assessed without waiting for the next interval.

Where you see the results

Network status in the console is the operational view of everything on this page: the discovered hosts with their addresses, when each was first and last seen, and per-host actions for its open ports, its vulnerabilities and its SNMP data. The charts below summarise findings by severity, hosts by status, and how many hosts carry vulnerabilities at all.

The header names the last assessment that ran and how it finished, so you can tell at a glance whether what you are looking at is current.

Each row carries its own actions. Scan opens the Ports panel for that host — what it is listening on, with the service the scan identified and when the port was first and last seen:

Vulnerabilities opens the findings for that host. Each row names the check that fired and explains what it confirmed, which is what makes a finding actionable rather than just a label:

Both panels carry a re-scan button, so you can reassess a single host without launching a sweep of the whole range.

The shared execution model

Every probe launch is asynchronous: the request is accepted, you get an identifier back immediately, and the work continues in the background.

curl -s -X POST http://192.168.1.10:8083/security/scan/network \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"targets": ["192.168.1.0/24"], "service": true}'

{ "uuid": "4a79214d-3deb-4ae8-933f-9874cbdc1128", "status": "inprogress" }

Poll GET /security/executions/{uuid} until the status leaves inprogress, landing on finished or failed. An execution record carries two payloads that are easy to confuse: currentOutput is the result of that run alone, while currentStatus is the consolidated view of the affected hosts. To list completed runs, filter by finished.

Network discovery and port scanning

The discovery probe. It finds live hosts, enumerates ports, and optionally identifies services and operating systems.

curl -s -X POST http://192.168.1.10:8083/security/scan/network \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "targets": ["192.168.1.0/24"],
        "portFilter": "1-1024,502,2404,20000,47808",
        "timing": "T3",
        "service": true,
        "os": false,
        "timeout": "30m"
      }'

The portFilter above is worth copying if you have industrial equipment: it covers the common IT range plus the Modbus, IEC-104, DNP3 and BACnet ports, so the OT assets show up in the baseline that the vulnerability probe will later work from.

Practical notes:

• os: true needs root, because OS fingerprinting implies a SYN scan over raw sockets. Without it, leave OS detection off.
• udp: true is slow. Restrict udpPorts rather than sweeping.
• Only one discovery scan runs at a time. A second request returns 409 Conflict unless you pass ?force=true, which cancels the running one and marks it failed with cancelled due to forced run.
• The default portFilter is the full 1-65535 range. On a /24 at cautious timing that is a long scan — narrow it.

Scheduled behaviour is configured under securityProbes.nmap — from the console’s Configuration view, or in the file. See Configuration.

Vulnerability scanning

Template-based scanning, in two distinct halves. The web and CVE half uses the standard upstream template tree and needs that tree present on disk. The OT/ICS half uses Axiom Border’s own suite of 57 industrial protocol checks, which are installed with the product and work with no internet access.

curl -s -X POST http://192.168.1.10:8083/security/scan/vulns \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"targets": ["192.168.1.50"], "level": "medio", "severity": "high,critical"}'

Depth is chosen with level, which takes one of four values — ligero, medio, profundo or ot. Always use one of those four: each selects a different set of checks, and the mapping table in Configuration is worth reading before you pick one.

Industrial protocol scanning has its own page, because the safety model deserves the space:

→ OT/ICS vulnerability scanning — Modbus/TCP, IEC 60870-5-104, DNP3, BACnet/IP and OPC UA, with the two-lock model that governs write operations.

ls /opt/axiom-border/vulnscan-templates/

SNMP — interrogation and profiles

Two operations: a GET of specific OIDs, and a walk from a root OID.

Symbolic names work as well as numeric OIDs — sysDescr is resolved through the bundled MIB catalogue, which matters on an air-gapped probe where you cannot look an OID up.

curl -s -X POST http://192.168.1.10:8083/security/scan/snmp \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "target": "192.168.1.50",
        "oids": ["sysDescr", "sysName", "sysObjectID"],
        "timeout": "15s"
      }'

Profiles and associations

Rather than passing credentials with every request, store them once as a profile and bind them to hosts with an association:

# Create a v3 profile
curl -s -X POST http://192.168.1.10:8083/security/snmp/profiles \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "plc-floor-v3",
        "version": "3",
        "username": "<snmp-user>",
        "securityLevel": "authPriv",
        "authProtocol": "SHA",
        "authPass": "<auth-passphrase>",
        "privProtocol": "AES",
        "privPass": "<priv-passphrase>"
      }'

# Bind it to a host
curl -s -X POST http://192.168.1.10:8083/security/snmp/associations \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"ipAddress": "192.168.1.50", "profileName": "plc-floor-v3"}'

Resolution order when a scan runs: the request’s profileName wins, then the per-IP association, then the configured default. A target that resolves to no profile fails with snmp omitted targets due to missing profile: <ip>.

Supported versions are v1, v2c and v3. For v3, defaults when fields are left empty are authPriv with SHA and AES.

Traffic capture

Two modes, both capturing IPv4 traffic through libpcap:

• Continuous, driven by configuration. When securityProbes.sniffing.interfaces is non-empty, capture starts automatically and persists flow counters to the networktraffic bucket every flushInterval.
• On demand, via the API, for a bounded duration, merged into the latest scan result.

curl -s -X POST http://192.168.1.10:8083/security/scan/sniff \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "interfaces": ["eth0"],
        "bpf": "tcp port 502",
        "duration": "5m",
        "promiscuous": true
      }'

The BPF filter above captures Modbus traffic only, which is a good way to confirm an industrial segment is actually active before scanning it.

Capture contributes bytesIn/bytesOut and packetsIn/packetsOut counters plus samples to each host in the merged result.

The merged result view

Individual executions tell you what one probe found. GET /security/results/last tells you what is known about a host, merged across all four probes:

curl -s 'http://192.168.1.10:8083/security/results/last?ipAddress=192.168.1.50' \
  -H "Authorization: Bearer <jwt-token>"

Each host carries ipAddress, hostname, macAddress, os, manufacturer, status, firstSeen and updatedAt, then the per-probe contributions: ports from discovery, vulnerabilities from the vulnerability scan, snmp entries from the SNMP probe, and sniffing counters from traffic capture. This is the view worth putting on a dashboard.

The firstSeen and updatedAt pair is what turns the baseline into change detection: a host with a recent firstSeen is new to the network.

Feeding results into rules

Probe results are available to the rules engine, so a scan finding can raise an alarm the same way a metric can — a new host appearing, a critical vulnerability, a port opening that should not be open. See Alarms and rules.

Results also flow to InfluxDB as metrics under the SECSCAN group with a probe tag, and are queryable through POST /auditlog with agent set to network, vulns, snmp or sniff.

Index

• OT/ICS Vulnerability Scanning

MIB catalogue and OID resolution

An OID like .1.3.6.1.4.1.6574.2.1.1.5 means nothing on its own. Turning it into diskTemperature requires a MIB, and on an air-gapped probe you cannot look one up.

Axiom Border therefore ships the catalogue with the product: over 12,500 MIB modules in JSON format covering the vendors you are likely to meet in the field. Symbolic names work anywhere numeric OIDs work, and returned values come back with readable names attached.

The JSON tree is what the probe uses, and its location is configurable through securityProbes.snmp.mibDir (default MIBS/JSON-FORMAT). The ASN.1 tree is a convenience: copy it to /usr/share/snmp/mibs if you want snmpwalk and friends on the host to resolve names too.

Vendors

Vendor is derived from the module name: everything before the first hyphen, lowercased. So SYNOLOGY-DISK-MIB belongs to vendor synology, and A3COM-HUAWEI-DEVICE-MIB to a3com. A module name with no hyphen becomes its own vendor. This is a heuristic, not metadata from the file — it works because MIB naming conventions are near-universal, but do not expect it to be perfect on unusual modules.

Browsing the catalogue

List vendors and modules

curl -s http://192.168.1.10:8083/security/mibs \
  -H "Authorization: Bearer <jwt-token>"

{
  "root": "MIBS/JSON-FORMAT",
  "vendors": [
    { "vendor": "synology", "modules": ["SYNOLOGY-DISK-MIB", "SYNOLOGY-SYSTEM-MIB"], "moduleCount": 7 }
  ]
}

This is inexpensive regardless of catalogue size.

Search for a symbol

curl -s 'http://192.168.1.10:8083/security/mibs/search?q=diskTemp&vendor=synology&limit=50' \
  -H "Authorization: Bearer <jwt-token>"

{
  "query": "diskTemp",
  "vendor": "synology",
  "limit": 50,
  "matches": [
    {
      "vendor": "synology",
      "module": "SYNOLOGY-DISK-MIB",
      "name": "diskTemperature",
      "oid": "1.3.6.1.4.1.6574.2.1.1.6",
      "class": "objecttype",
      "description": "Temperature of the disk"
    }
  ]
}

q is mandatory and matched as a case-insensitive substring against object names. Always pass vendor when you can — with it the search is limited to that vendor’s modules; without it the search covers the whole catalogue and takes considerably longer.

limit of zero or less means unlimited. Results are ordered by vendor, then module, then name.

Inspect a module

curl -s http://192.168.1.10:8083/security/mibs/SYNOLOGY-DISK-MIB \
  -H "Authorization: Bearer <jwt-token>"

{
  "module": "SYNOLOGY-DISK-MIB",
  "vendor": "synology",
  "objects": [
    { "name": "diskID", "oid": "1.3.6.1.4.1.6574.2.1.1.2", "class": "objecttype", "description": "..." }
  ]
}

Module names are exact and case-sensitive — they are the filename without the .json extension. An unknown module returns 404.

How resolution works

Two directions matter, and they behave differently: symbols become OIDs before the request goes out, and OIDs get names again on the way back.

Inbound: symbols become OIDs before the request

When a scan request contains symbolic names, they are resolved before anything is sent on the wire:

1. A small built-in table of the universal system OIDs — sysDescr, sysObjectID, sysName, sysLocation, sysContact.
2. Anything already numeric passes through untouched.
3. Everything else is looked up in the vendor’s modules.

flowchart TB
    S["Requested name<br>sysDescr"] --> C1{"Built-in<br>system OID?"}
    C1 -->|"no"| C2{"Already<br>numeric?"}
    C2 -->|"no"| C3{"In the vendor's<br>modules?"}
    C3 -->|"no"| FAIL["Execution fails<br>unresolved oids"]:::danger
    C1 -->|"yes"| OK["Numeric OID<br>sent on the wire"]
    C2 -->|"yes"| OK
    C3 -->|"yes"| OK
    classDef danger fill:#fff0ed,stroke:#ff664e,color:#101010

The vendor hint

Symbol resolution needs to know which vendor’s modules to search. Axiom Border works it out in order:

1. The mib field of the scan request.
2. securityProbes.snmp.mib from configuration.
3. Inferred from the host’s manufacturer as recorded by a previous nmap scan.

The third is the useful one: run a network scan first, and the manufacturer discovered from the MAC address becomes the vendor hint automatically. Explicit rules exist for common vendors — Synology, Cisco, HP, Huawei, Juniper, D-Link — with a fallback to the first token of the manufacturer name.

Note that the hint is only consulted when a request actually contains non-numeric symbols. All-numeric requests need no vendor at all.

Outbound: OIDs become names on the response

Every OID that comes back is put through the same four steps, in order, and the first match wins:

1. The built-in table of universal system OIDs.
2. The vendor’s modules, trimming up to two trailing segments — which is how indexed OIDs such as ifDescr.3 resolve to ifDescr.
3. The SNMPv2 module.
4. A set of generic modules — if, ip, tcp, udp, host, entity, sysappl, ucd, net — by exact match.

If nothing matches, the name field of the result is literally unknown. The value is still returned — only the label is missing.

Using symbols in scans

Symbolic names work in both SNMP operations. A GET with symbols:

curl -s -X POST http://192.168.1.10:8083/security/scan/snmp \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "target": "192.168.1.50",
        "mib": "synology",
        "oids": ["sysDescr", "sysName", "diskTemperature"]
      }'

And a walk from a symbolic root:

curl -s -X POST http://192.168.1.10:8083/security/scan/snmp/walk \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"target": "192.168.1.50", "mib": "synology", "walkRoot": "diskTable"}'

A walkRoot symbol that does not resolve fails that target with snmp: walkRoot symbol not found vendor=<vendor> walkRoot=<root>.

Values in results

Each SNMP result entry carries the numeric oid, the resolved name (or unknown), the formatted value and a status.

Values are formatted by type: numbers as numbers, IP addresses in dotted form, and byte strings as text when they are printable UTF-8, otherwise as 0x<hex> — so binary values are legible rather than mangled. The status is up, or error carrying the SNMP condition name for NoSuchObject, NoSuchInstance and EndOfMibView.

Extending the catalogue

To add a vendor’s MIB, drop its JSON module into the configured mibDir. New modules are picked up automatically, and changing mibDir reloads the catalogue from the new location.

If the catalogue fails to load — a bad path, unreadable files — the probe logs a warning and continues with an empty catalogue. It does not refuse to start. Symbol resolution will then fail for everything except the built-in system OIDs, which is a good signature for this particular misconfiguration: numeric OIDs work, sysDescr works, everything else does not.

AI capabilities

Axiom Border can run machine-learning models on the probe, in containers, to detect anomalies in the metrics it ingests. A model trains locally on local data, exposes an inference endpoint on loopback, and rules call it to decide whether an event is worth an alarm.

The point is the same as everywhere else in the product: no cloud round trip, no data leaving the site.

Where you manage it

AI capabilities in the console lists the models configured on the probe. On a fresh installation it is empty, because model images are supplied separately from the product:

From here you create a capability, follow its training state, and read the quality metrics the model reports about itself. Create new AI trainer opens the wizard that collects the same parameters as the API call shown further down:

The equivalent API calls are shown alongside each step below.

The lifecycle

flowchart TB
    TAR["Model image tarball<br>supplied separately"]:::ext -->|"stage on disk"| IMG["Image imported<br>for one agent type"]
    IMG -->|"POST /iacap"| EXPORT["Training data<br>exported"]
    EXPORT --> DEPLOY["Container deployed"]
    DEPLOY --> HEALTH{"Health check"}
    HEALTH -->|"not yet"| HEALTH
    HEALTH -->|"responds"| READY["status: ready"]
    READY -->|"retrain due"| TRAIN["status: training"]
    TRAIN --> READY
    READY -->|"predict"| INFER["Inference<br>from rules"]
    classDef ext fill:#e9edfa,stroke:#486ac9,color:#101010

Each agent type has a fixed loopback port, which is how a rule reaches the right model:

Each model listens on the host’s loopback address, so rules reach it at 127.0.0.1:<port>.

Loading an image

Model images are not part of the installation bundle — they are distributed separately as OCI tarballs, and resources/iaimages/ ships empty as a placeholder.

Place the tarball in that directory, then import it:

# See what is on disk
curl -s http://192.168.1.10:8083/containerd/listdiskiaimages \
  -H "Authorization: Bearer <jwt-token>"

# Import it, bound to an agent type
curl -s -X POST 'http://192.168.1.10:8083/containerd/loadImage?agent=metrics&fileondisk=model-metrics.tar.gz' \
  -H "Authorization: Bearer <jwt-token>"

You can also upload the tarball directly as a multipart form field named file, without staging it on disk first.

On import the image is tagged axiom-border:<agent>. Loading from the host with nerdctl works too, and is the documented path in Operation and maintenance:

sudo nerdctl --namespace axiom-border image load -i model-metrics.tar.gz

Deploying a capability

curl -s -X POST http://192.168.1.10:8083/iacap/metrics \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{
        "retrainFreqMinutes": 1440,
        "ruleEnabled": true
      }'

Deployment does four things in order: exports the training data from the metrics database to a Parquet file, deploys the container with that data available to it, waits for the container’s health endpoint, then marks the capability ready, collects the model metrics and enables the rule script.

A retrainFreqMinutes below 10 is rejected with freq must be at least 10m0s. A capability already existing for that agent is rejected too — remove it first.

The health wait uses trainerDetails.healthCheck, which defaults to 20 attempts at 5 second intervals, giving roughly 100 seconds for the container to come up. A slow-starting model may need that raised; see Configuration.

Checking status

curl -s http://192.168.1.10:8083/iacap \
  -H "Authorization: Bearer <jwt-token>"

Returns 204 when no capability is deployed. Otherwise, per capability: iaName, enabled, status, retraining, retrainFreqMinutes, lastExecution, nextExecution, fileFrom (the tarball it came from) and metrics — the model’s own quality metrics, fetched from the container.

Status values

Training

Retraining runs automatically on the configured interval. To force a run:

curl -s http://192.168.1.10:8083/iacap/metrics/execute \
  -H "Authorization: Bearer <jwt-token>"

This is rejected while a training run is already in progress, and it waits for any scheduled run to finish rather than colliding with it. An on-demand run updates the last-executed timestamp but does not shift the schedule — the next scheduled run happens when it was always going to.

To cancel a run in progress:

curl -s http://192.168.1.10:8083/iacap/metrics/cancel \
  -H "Authorization: Bearer <jwt-token>"

Cancellation stops the health-check retry loop rather than killing the container mid-computation. The capability lands in one of the two cancelled states above depending on whether retraining is scheduled.

Each training run re-exports the data, restarts the container, and waits for health again — so a training run means a brief window where inference is unavailable. Rules calling predict during that window will get an error, which they should handle rather than treating as an anomaly.

Changing the schedule

curl -s -X PUT http://192.168.1.10:8083/iacap/metrics \
  -H "Authorization: Bearer <jwt-token>" \
  -H 'Content-Type: application/json' \
  -d '{"retrainFreqMinutes": 720, "ruleEnabled": true}'

Rejected while training is in progress. The same 10-minute minimum applies, and zero disables retraining.

Removing a capability

curl -s -X DELETE http://192.168.1.10:8083/iacap/metrics \
  -H "Authorization: Bearer <jwt-token>"

Best-effort cleanup: the container, the image, the rule script, the exported data directory and the database record, plus stopping the retraining schedule. Note that this returns 200 even when parts of the cleanup failed, with the errors in the response body — read it rather than assuming success.

Calling inference from rules

This is where the capability earns its place. A rule script fetches recent metrics, builds a feature vector, asks the model to score it, and raises an alarm when the model says anomaly:

function process(metrics) {
  for (var i = 0; i < metrics.length; i++) {
    var metric = metrics[i];
    metric.SetT0();

    var payload = JSON.stringify({
      sent_vars:     metric.GetFieldByName("sent_vars"),
      prepared_vars: metric.GetFieldByName("prepared_vars"),
      ram_usage:     metric.GetFieldByName("ram_usage")
    });

    var response = newPredict(payload, "metrics");
    var result   = JSON.parse(response);

    if (result.prediction === 1) {
      newAlarm(metric, "critical", "New anomaly detected", "Anomaly", "AI Capability");
    }

    metric.SetT1();
  }
}

Two globals are available to scripts for this: newPredict(payloadJSON, agentType) calls the model’s inference endpoint, and newGetMetrics(agentType) fetches the model’s own metrics. Both target the loopback port for that agent, and both are configured under trainerDetails.

The rule script for an agent is enabled through ruleEnabled when deploying the capability, and can be managed directly through the /scripts endpoints. See Alarms and rules.

Surviving a restart

Capabilities are part of the probe’s local state, and startup restores them: containers are resumed, model metrics are re-fetched, and retraining schedules resume from their stored next-run time.

One case is treated deliberately: a capability that was training when the process stopped is considered cancelled rather than resumed, because the training run did not finish. It moves to the appropriate cancelled state and waits for its next scheduled run.

Failures during this restoration are logged and do not prevent startup.

Configuration reference

The relevant block is trainerDetails — container name, TLS material, and the three endpoint definitions for health, metrics and inference. See Configuration.

The health, metrics and inference endpoints are meant to be reached over loopback only. Keep them bound to 127.0.0.1 and do not expose those ports beyond the host.

MQTT and OpenGate operations

Axiom Border carries its own MQTT broker, so a probe is a message bus as well as a monitoring probe. Three independent pieces make up the messaging layer:

On top of that sits the optional OpenGate integration, which reports inventory upward (collect) and registers devices (provision).

The local bus, first: scans publish their lifecycle, and anything that can connect to the broker can follow it.

flowchart TB
    SCAN["Security scans"] -->|"started<br>finishedok<br>failed"| EVC["Event client"]
    EVC --> BROKER["Embedded broker<br>TCP 1883 · WS 1888<br>TLS 8883"]
    BROKER --> UI["Embedded web UI"]
    BROKER --> SUB["External<br>subscribers"]:::ext
    classDef ext fill:#e9edfa,stroke:#486ac9,color:#101010

Then the platform side, where OpenGate drives scans and receives inventory.

flowchart TB
    PLAT["OpenGate platform"]:::ext -->|"operation"| OPS["Operations client<br>odm/operation"]
    OPS -->|"launches"| SCAN2["Security scan"]
    OPS -->|"response"| PLAT
    INV["Provision and collect<br>inventory reports"] -->|"HTTP or MQTT"| PLAT
    classDef ext fill:#e9edfa,stroke:#486ac9,color:#101010

The embedded broker

Enabled by default on TCP port 1883, with a WebSocket listener on 1888 at path /ws that the web UI uses. TLS is available on 8883 when configured, including mutual TLS with client certificate verification.

Configuration lives under mqtt.broker; see Configuration. Note that the WebSocket listener always binds on all interfaces.

Execution lifecycle events

Every security scan publishes its lifecycle to a single topic, mqtt.client.topic, which defaults to axiom-border/executions. This is the alternative to polling the executions API.

{
  "mode": "manual",
  "uuid": "4a79214d-3deb-4ae8-933f-9874cbdc1128",
  "event": "finishedok",
  "type": "networkscan",
  "elapsedTime": "5m18s",
  "details": "success"
}

Note that type here is networkscan, while the REST API reports the same scan as nmap. Map the two values if you correlate the event stream with the executions API.

Events are published on scan start, on completion, and on startup recovery for executions interrupted by a restart.

Events are published with the configured QoS (default 1) and retain flag (default true), and the client reconnects every 5 seconds while the broker is unreachable.

OpenGate operations over MQTT

The operations client lets the OpenGate platform trigger scans on the probe remotely. It subscribes to mqtt.ops.topicSubscribe (default odm/operation) and replies on mqtt.ops.topicPublish (default odm/response/{device-id}, with the device ID substituted at runtime).

Request envelope

{
  "operation": {
    "request": {
      "timestamp": 1730000000000,
      "name": "hostVulnScan",
      "id": "<operation-id>",
      "deviceId": "<device-id>",
      "parameters": { }
    }
  }
}

name, id and deviceId are all mandatory. A request missing any of them, or one that does not parse, is logged and silently ignored — no response is published. An unknown operation name does get a response, with ERROR_PROCESSING and Unsupported operation.

Response envelope

{
  "operation": {
    "response": {
      "name": "hostVulnScan",
      "timestamp": 1730000001000,
      "resultCode": "SUCCESSFUL",
      "resultDescription": "Success",
      "deviceId": "<device-id>",
      "id": "<operation-id>"
    }
  },
  "version": "1.0"
}

There are exactly two result codes: SUCCESSFUL and ERROR_PROCESSING.

The four operations

Both surfaces drive the same scan engine, so they share the same locking, history and safety gates. The differences are in what each surface exposes.

hostVulnScan takes targets, timeout, level, severity and intrusive — all optional. It does not expose templatesDir, so the configured resolution cascade always applies. The intrusive flag is gated by securityProbes.vulnScan.allowIntrusive exactly as over REST.

{
  "targets": ["192.168.1.0/24"],
  "level": "ot",
  "severity": "high,critical",
  "timeout": "10m",
  "intrusive": false
}

hostNetworkScan takes targets, timeout, timing and portFilter. Four options are fixed for MQTT-launched scans: port scanning is always on, OS detection is always on (which requires privileges), service detection is always off, and UDP is always off. There is no force equivalent either, so a scan launched while another manual network scan is running is rejected with ERROR_PROCESSING and manual network scan already running.

hostSnmpScan and hostSnmpWalkScan take targets, port, timeout, credentials in an snmp object, and either oids (mandatory for the GET) or walkRoot (defaulting to the enterprises subtree .1.3.6.1.4.1).

{
  "targets": ["192.168.1.50"],
  "port": 161,
  "timeout": "5m",
  "oids": ["sysDescr", "sysName"],
  "snmp": {
    "snmpVersion": "v2c",
    "community": "<snmp-community>"
  }
}

OpenGate provision and collect

Separate from operations, the integration reports upward on a schedule. The whole section is inert unless opengate.enabled is true.

Scheduling and throttling

A five-field cron expression (default */30 * * * *) drives both, with descriptors such as @hourly accepted. An empty or invalid expression means the integration does not run at all — check the log for a warning if nothing is happening.

minPeriod (default 30 minutes) is a floor: if the cron expression would fire more often than that, the schedule falls back to a fixed interval of minPeriod and logs a warning. Cycles never overlap — a cycle due while the previous one is still running is skipped and logged.

Provision

Provisioning registers discovered hosts with the platform. It builds an Excel workbook — one row per host, with device ID, addressing, state and the location metadata from opengate.collect.address — and uploads it to the bulk endpoint.

The upload requires exactly 201 Created; anything else aborts the provision. The result is then polled up to pollMaxAttempts times (default 10, every 5 seconds), and only counts as success when the platform reports every submitted host as successful.

Provision is HTTP only — there is no MQTT variant.

Collect

Collect sends the accumulated per-host inventory: identity, ports, vulnerabilities and SNMP entries, with timestamps.

{
  "deviceId": "192.168.1.50-00.11.22.33.44.55",
  "ipAddress": "192.168.1.50",
  "macAddress": "00:11:22:33:44:55",
  "specificType": "HOST",
  "hostname": "plc-line-1",
  "os": "Linux 4.x",
  "manufacturer": "Siemens AG",
  "status": "up",
  "ports": [ { "portNumber": 502, "protocol": "tcp", "service": "mbap", "status": "open" } ],
  "vulnerabilities": { "hasVulns": true, "catList": "medium,high", "highDetect": "high", "vulnList": [ ] },
  "snmp": [ { "oid": ".1.3.6.1.2.1.1.1.0", "name": "sysDescr", "value": "..." } ]
}

Transport is chosen by collect.mode: mqtt, or http for anything else including an empty value. Over HTTP the payload is posted with the X-ApiKey header; over MQTT it is published to collect.mqtt.topic, falling back to opengate.apiKey as the password when no MQTT password is set.

Chunking. With collect.sendByParts: true, each host is split into several messages: a header with the scalar fields plus one chunked block at a time — ports, then SNMP, then vulnerabilities — sized by collect.partSize.* (default 100 each). This matters on metered or constrained links where a host with hundreds of findings would otherwise produce one oversized message. With chunking off, each host is a single message.

A failed chunk is logged and the cycle continues with the next one, so one bad message does not abort the whole report.

Device identity

The device ID is derived per host as <ip>-<MAC with dots>, for example 192.168.1.50-00.11.22.33.44.55. Hosts without a discoverable MAC get the placeholder AA.BB.CC.DD.EE.FF. This is the same format accepted by GET /security/results/last?deviceId=, so an ID seen in the platform can be looked up on the probe directly.

Before each cycle, hosts missing a MAC or hostname get a quick nmap ping scan to fill the gaps, bounded by macDiscoveryTimeout (default 10 s).

Configuration reference

Everything here is configured under the mqtt and opengate blocks. See Configuration for the field-by-field tables, including the TLS options and the retry parameters for both provision and collect.

Operation and maintenance

Service commands

Each role installs a different set of units. The standard systemd verbs apply to all of them:

sudo systemctl status axiom-border
sudo systemctl restart axiom-border
sudo systemctl is-active axiom-border
sudo systemctl is-enabled axiom-border

The units, depending on role: axiom-border, axiom-influxdb, containerd, oda-lite.

Where the logs live

This is the single most useful thing to know when something misbehaves, because the important detail is not in the journal:

Everything at once, which is often what you want:

sudo journalctl -u axiom-border -u axiom-influxdb -u containerd -u oda-lite \
  --since "5 minutes ago" --no-pager

Log levels

Axiom Border — the logger block of configuration.yaml. Set logLevel to DEBUG, INFO, WARN or ERROR, then restart the service. See Configuration.

oda-lite agent — /etc/oda-lite/oda-lite.conf, [agent] section: log_level and debug. Restart the service afterwards.

InfluxDB and containerd — the level comes from binary flags in the unit file. Changing it means editing the unit, and is not recommended.

Rotation and disk usage

Axiom Border’s own log rotates through the logger settings: maxSize (MB per file, default 20), maxBackups (default 20) and compress (gzip the rotated files).

The journald drop-in installed by the bundle is global — SystemMaxUse=500M and MaxFileSec=1day apply to the entire host journal, not only to Axiom Border. On a host sharing other workloads, adjust it or replace it with per-unit drop-ins.

journalctl --disk-usage
sudo journalctl --vacuum-size=500M
sudo journalctl --vacuum-time=7d

To see what is consuming space:

du -sh /var/log/oda-lite /opt/axiom-border/logs /var/log/journal/

Backup and restore

Stop the service first, for a consistent snapshot:

sudo systemctl stop axiom-border
sudo tar -czf /path/backup-axiom-border-$(date +%F).tar.gz \
  /opt/axiom-border/config /opt/axiom-border/db.dat /var/lib/influxdb2
sudo systemctl start axiom-border

Restore is the inverse:

sudo systemctl stop axiom-border
sudo tar -xzf backup-axiom-border-<date>.tar.gz -C /
sudo systemctl start axiom-border

Offline maintenance

Refreshing the web and CVE vulnerability templates

The OT/ICS suite ships with the product and needs no maintenance. The web and CVE templates do, and on an air-gapped probe the refresh is manual: generate a snapshot of the upstream nuclei-templates tree on a machine with internet, transfer it, then swap it in.

# On a machine with internet
nuclei -update-templates -ut /tmp/nuclei-templates
tar -czf nuclei-templates-$(date +%F).tar.gz -C /tmp nuclei-templates

# On the probe
sudo systemctl stop axiom-border
sudo mv /opt/axiom-border/vulnscan-templates /opt/axiom-border/vulnscan-templates.old
sudo tar -xzf nuclei-templates-<date>.tar.gz -C /tmp
sudo mv /tmp/nuclei-templates /opt/axiom-border/vulnscan-templates
sudo systemctl start axiom-border

Keep .old until you have confirmed a few successful scans, then delete it. Templates are read when the service starts, so a restart is required after swapping them.

Loading AI images

AI images are not part of the bundle — they are distributed separately as OCI tarballs, and resources/iaimages/ ships empty as a placeholder.

sudo nerdctl --namespace axiom-border image load -i <image>.tar
sudo nerdctl --namespace axiom-border image ls

Upgrading

Extract the new bundle of the same role on the target and run upgrade.sh. It aborts if the bundle role does not match the installed role — changing role requires uninstall followed by install.

sudo ./upgrade.sh

What it does: verifies the previous installation and role match, stops the role’s services (leaving InfluxDB and containerd running, so data in flight is not disturbed), takes timestamped backups of the binary and db.dat, replaces the binary and updatable assets, starts the service, and health-checks it.

Preserved across upgrade: config/, db.dat, .influx-creds, parquet/, logs/, /var/lib/influxdb2/, resources/iaimages/ and the oda-lite configuration.

Replaced: the binary, MIBS/, resources/gojascripts/, vulnscan-templates/, the documentation and the lifecycle scripts.

Uninstalling

sudo /opt/axiom-border/uninstall.sh

It stops and disables the role’s services, removes only the units it created, removes the journald and sshd drop-ins, and asks whether to keep the data — InfluxDB data, db.dat, logs and configuration.yaml. Answer non-interactively with AXIOM_KEEP_DATA=true|false.

It removes shared binaries only where the manifest marks them as installed by this deployment. It does not remove nmap, rsyslog or network-manager even if it installed them — those are host infrastructure and are left to the operator. It does not revert the netplan switch by default.

Running it on a clean system is safe and idempotent: it reports there is nothing to uninstall and exits 0.

AXIOM_RESTORE_NETPLAN=1 warns about possible connectivity loss. In practice an established SSH session usually survives, since the TCP connection is not torn down and the IP is retained — but do not count on it over a link you cannot recover from out-of-band.

Troubleshooting by symptom

Quick triage

Detailed cases

The service will not start. Three usual causes: the binary lost its execute bit (chmod +x /opt/axiom-border/axiom-border), a required port is occupied, or the YAML is invalid. Validate the configuration directly:

python3 -c "import yaml; yaml.safe_load(open('/opt/axiom-border/config/configuration.yaml'))"

Login fails with the correct password. login.pass must be the SHA-256 digest, not the plaintext. Recalculate and restart:

echo -n "<your-password>" | sha256sum | awk '{print $1}'

A port is in use. Identify the holder, then either stop it or move the Axiom Border port:

sudo ss -tlnp | grep -E ':(8083|1883|1888|8086|9090|9091) '

Ports 8083, 1883 and 1888 move via apiPort, mqtt.broker.port and mqtt.broker.ws.port. Ports 9090 and 9091 move in /etc/oda-lite/oda-lite.conf.

Vulnerability scans return zero findings, suspiciously. The web template directory is probably empty or incomplete:

ls /opt/axiom-border/vulnscan-templates/ | head

It should list per-protocol directories such as http/, network/ and ssl/. CVE templates live under http/cves/, not at the root. Refresh them as described above. OT/ICS findings are unaffected, because that suite ships with the product.

Sniffing captures nothing. Check the interface exists (ip -o link show), that the service runs as root (systemctl show axiom-border -p User), and that there is actually traffic (sudo tcpdump -i <iface> -c 10).

The UI loads but every API call returns 401. The JWT is missing or expired. Clear the browser’s localStorage and log in again.

nmap probes hang or take very long. A large target range with poor reachability, a high timeout, or udp: true with many ports. Narrow the range, lower the timeout, disable UDP.

High memory usage. Check for an AI capability working a large dataset, an Influx bucket with no retention policy, or logLevel: DEBUG left on.

“Orphaned installation detected.” Bundle artefacts exist without an .install-manifest. Three ways out: AXIOM_CLEAN_RESIDUALS=1 sudo bash install.sh moves the leftovers aside, sudo bash upgrade.sh preserves data, sudo bash uninstall.sh cleans best-effort.

upgrade.sh exits with code 2 reporting a rollback. The new binary failed its health check and the old one is back in service. Diagnose with the journal, the application log and the install log, then retry with a corrected bundle.

The monitoring node floods the journal with “connection refused” to port 9090. The central node is not up, a firewall blocks it, or the URL is wrong. The agent keeps retrying and buffers metrics while it waits, so a short outage loses nothing — a long one eventually will.

Error executing 'netstat': exit status 1. Minimal Ubuntu Server images lack net-tools. Not blocking — the other plugins continue:

sudo apt-get install -y net-tools && sudo systemctl restart oda-lite

NetworkManager is active but interfaces show as unmanaged. The netplan renderer was not switched over. Re-run install.sh --switch-to-network-manager; it detects the current state and completes the switch without reinstalling NetworkManager.

/etc/oda-lite/oda-lite.conf.new contains literal ${VARIABLE} placeholders. The file is an unexpanded template. Do not copy it over the live configuration — the agent would not start. Delete it and re-run the upgrade with the current bundle.

scp or tar -xzf fail with Permission denied in /tmp. Some base images ship /tmp with wrong permissions. It should be drwxrwxrwt:

ls -ld /tmp
sudo chmod 1777 /tmp