Observability Agent
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 tobindAddress— 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 thevectoruser toadmso 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.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshHost | string | SSH hostname or IP of the target host |
| sshUser | string | SSH user (default root) |
| sshPort | number | SSH port (default 22) |
| nodePort | number | node_exporter port |
| blackboxPort | number | blackbox port |
Resources
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) —
vectorVersionwas interpolated unescaped intoinstall'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+$) onvectorVersioninGlobalArgsSchema, validated before its.default("0.46.1"). - Fixed (HIGH) —
bindAddresswas interpolated unescaped intostatus's two curl metrics URLs, making the nominally read-onlystatusmethod also a remote code-execution vector. Closed with a host allowlist regex (^[A-Za-z0-9.-]{1,253}$) onbindAddressinGlobalArgsSchema, validated before its.default("0.0.0.0").nodePort/blackboxPortwere alreadyz.number().int()and therefore never reachable. - Fixed (MEDIUM, folded in for free) — the bindAddress-newline config
injection (a hostile
bindAddresscontaining\ncould inject a secondARGS=line into the node_exporter/blackbox defaults files) is closed by the same strictbindAddressregex above, since it also rejects newlines. - Added the repo-canonical
shellEscsingle-quote-wrap helper (copied verbatim fromfirecracker/extensions/models/firecracker.ts) and wrapped the two remaining curl interpolation sites —install's vector.debURL andstatus'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, andinstall/statusstill build the identical curl URLs for valid input (now additionally single-quoted). - Still open (deferred, different fields/fix paths — tracked in
observability-agent-rce): MEDIUMbindWaitUnitsystemd-directive injection (#3); MEDIUMhostLabel/logFiles/logsEndpointVRL/YAML config injection (#4b-d); LOWbtoa()non-Latin1 crash (#5); LOWinventorydoc drift (#6); LOWsshUser/sshHostssh-argv option-injection note. observability_agent_adversarial_test.ts: flipped the two HIGH characterization pins (vectorVersion, bindAddress) and the MEDIUM bindAddress-newline pin to assertglobalArguments.parsenow REJECTS the hostile payloads, added positive-acceptance tests for legitvectorVersion(0.46.1, 0.47.0) andbindAddress(0.0.0.0, 192.0.2.10, a hostname), and repointed the safe write-target-path test to a benignbindAddress(keeping the still-unvalidatedhostLabel/logsEndpoint/bindWaitUnitfields hostile, preserving that test's intent). All five suites green: 56 tests, property suite green atFC_NUM_RUNS=5000.
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.
- 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