Skip to main content

Observability Agent

@magistr/observability-agentv2026.08.19.1· 23d agoMODELS
01README

Install and configure a host-native metrics + logs agent on a remote Debian/Ubuntu host over SSH, for a VictoriaMetrics (pull) + VictoriaLogs (push via Vector) backend.

Model:

  • @magistr/observability/agent — drives one target host over SSH. Methods:
    • install — apt-installs prometheus-node-exporter + prometheus-blackbox-exporter and installs vector from the pinned .deb (idempotent).
    • configure — writes exporter defaults (bound to bindAddress — set it to a WireGuard tunnel IP to keep exporters off the public interface), a blackbox module set (http_2xx / http_public / icmp), grants blackbox CAP_NET_RAW for ICMP probes, and configures Vector to tail nginx + syslog and ship to VictoriaLogs' Elasticsearch-bulk endpoint. Adds the vector user to adm so it can read the logs.
    • status — systemd state of all three services + whether each exporter is answering on its bound address.

The home VictoriaMetrics scrapes bindAddress:9100 (node) and bindAddress:9115 (blackbox) over the tunnel; Vector pushes logs to VictoriaLogs. Pairs with @magistr/victoriametrics for querying.

02Models1
@magistr/observability/agentv2026.08.19.1extensions/models/observability_agent.ts

Global Arguments

ArgumentTypeDescription
sshHoststringSSH hostname or IP of the target host
sshUserstringSSH user (default root)
sshPortnumberSSH port (default 22)
nodePortnumbernode_exporter port
blackboxPortnumberblackbox port
fn install()
Install prometheus-node-exporter, prometheus-blackbox-exporter, and vector on the target host (idempotent).
fn configure()
Write exporter + Vector configs (exporters bound to bindAddress), grant blackbox CAP_NET_RAW for ICMP, add the vector user to the adm group so it can read logs, then enable + restart all services.
fn status()
Report systemd state of the three agent services and whether each exporter is answering on its bound address.
fn inventory()
Full host inventory over SSH: every running systemd service, every TCP/UDP listening socket with its owning process, and a process-name rollup. Use to audit exactly what is running/exposed on a host.

Resources

install(infinite)— Installed agent package versions
config(infinite)— Applied agent configuration
status(infinite)— Live health of the agent services + listeners
inventory(infinite)— Complete host inventory: running systemd services, all TCP/UDP listeners with owning process, and process rollup
03Previous Versions2
2026.08.01.1

2026.08.01.1

Fixes two HIGH remote-RCE bugs closed as observability-agent-rce (LOCAL @magistr/issue-lifecycle bug model — never the Lab, per this repo's tracking convention). observability_agent.ts is no longer byte-frozen; the model version moves from 2026.07.02.3 to 2026.08.01.1.

  • Fixed (HIGH)vectorVersion was interpolated unescaped into install's double-quoted curl URL, allowing remote code execution as whatever user SSH logs in as (root by default). Closed with a semver allowlist regex (^\d+\.\d+\.\d+$) on vectorVersion in GlobalArgsSchema, validated before its .default("0.46.1").
  • Fixed (HIGH)bindAddress was interpolated unescaped into status's two curl metrics URLs, making the nominally read-only status method also a remote code-execution vector. Closed with a host allowlist regex (^[A-Za-z0-9.-]{1,253}$) on bindAddress in GlobalArgsSchema, validated before its .default("0.0.0.0"). nodePort/blackboxPort were already z.number().int() and therefore never reachable.
  • Fixed (MEDIUM, folded in for free) — the bindAddress-newline config injection (a hostile bindAddress containing \n could inject a second ARGS= line into the node_exporter/blackbox defaults files) is closed by the same strict bindAddress regex above, since it also rejects newlines.
  • Added the repo-canonical shellEsc single-quote-wrap helper (copied verbatim from firecracker/extensions/models/firecracker.ts) and wrapped the two remaining curl interpolation sites — install's vector .deb URL and status's two metrics URLs — as defense-in-depth on top of the allowlist regexes.
  • Both fixes are behavior-preserving for every legit value: the existing defaults (0.46.1, 0.0.0.0) already satisfy their new regex, and install/status still build the identical curl URLs for valid input (now additionally single-quoted).
  • Still open (deferred, different fields/fix paths — tracked in observability-agent-rce): MEDIUM bindWaitUnit systemd-directive injection (#3); MEDIUM hostLabel/logFiles/logsEndpoint VRL/YAML config injection (#4b-d); LOW btoa() non-Latin1 crash (#5); LOW inventory doc drift (#6); LOW sshUser/sshHost ssh-argv option-injection note.
  • observability_agent_adversarial_test.ts: flipped the two HIGH characterization pins (vectorVersion, bindAddress) and the MEDIUM bindAddress-newline pin to assert globalArguments.parse now REJECTS the hostile payloads, added positive-acceptance tests for legit vectorVersion (0.46.1, 0.47.0) and bindAddress (0.0.0.0, 192.0.2.10, a hostname), and repointed the safe write-target-path test to a benign bindAddress (keeping the still-unvalidated hostLabel/logsEndpoint/ bindWaitUnit fields hostile, preserving that test's intent). All five suites green: 56 tests, property suite green at FC_NUM_RUNS=5000.
2026.07.02.3

Release 2026.07.16.2 — align model versions with manifests

Maintenance release across the @magistr extensions. For most packages this carries no functional change: the only edit is the model's version: field, brought back in line with its manifest version so the published model type version and the package version no longer drift.

Functional changes in this release are limited to:

  • anime-cron: normalizeTitle now strips a ": subtitle" suffix and a trailing parenthesized year before comparison, fixing dedup false-misses where the torrent title carries a subtitle or year that the AniList romaji does not.

  • arckit: first publish. Standalone ArcKit port — a 12-phase architecture governance state machine with 65 bundled templates, driven by a bundled skill.

Also tracks three extensions (kaiten, observability-agent, music-library) that previously existed only as untracked working-tree directories, recovered from stashes.

04Stats
A
100 / 100
Downloads
0
Archive size
14.6 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License declared1/1earned
  • Verified public repository2/2earned
05Platforms
06Labels