@astrofoundry/pi-astro 0.36.1 → 0.37.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.36.1",
3
+ "version": "0.37.1",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -87,6 +87,8 @@ The usual trigger is the owner's **Upgrade Arcane** button under the Arcane Dail
87
87
 
88
88
  Public routes (Supabase, Grimoire, Mealie URLs) are `astro.edge`'s `route-probe`, run from Cortex.
89
89
 
90
+ `["change-origin", "<path>", "<sha256|->", "<utc>"]` answers whether a deployment-file change Wazuh saw on the Arcane VM (`/opt/docker/<project>/compose.yaml`, `docker-compose.yml`, or `pre-deploy.sh`; rule 100020) is ours. `known` when the new content (its SHA-256 from the alert's `syscheck.sha256_after`), or `-` for a deletion, equals a commit of `<project>/<file>` at origin, any author, CI included; or when our `stack-update`, `manager-upgrade`, `manager-rollback`, or `host db-restore` on that stack ran then (the specialists' audit log). Otherwise `unknown`, with the newest commit touching the file. Arcane syncs the files verbatim, so a GitOps deploy always matches. The Discord bridge calls it for every such alert; an `unknown` change pages the owner.
91
+
90
92
  `["project-status"]` (or with a project name) lists projects with their GitOps sync: commit, state, hook state, without error text. `["deployment", "check"|"wait", "<project>", "--commit", "<sha>", "--container", "NAME=sha256:ID", ...]` compares the sync and each container's project, image ID, state, and health; `wait` polls every 10 s up to `--timeout` (default 600 s). Read `status` in the answer.
91
93
 
92
94
  ## Output
@@ -5,7 +5,7 @@ description: How the security specialist reads Wazuh, CrowdSec, and the remote l
5
5
 
6
6
  # Security specialist
7
7
 
8
- VM 106 (`10.0.90.10`, VLAN 90) runs the Wazuh manager (container `observability-wazuh-manager-1`, agents `identity`, `arcane`, `dmz`, `CORTEX`, `NEXUS`, `hermes`, `frontdoor-1337`, `tailscale`), CrowdSec with its local API for the front-door bouncer, and rsyslog, which archives remote logs under `/var/log/remote/<host>/<program>.log` (14 days). Discord receives Wazuh alerts at level 10 or higher and CrowdSec state changes. Two local CrowdSec scenarios matter: `37pla/pomerium-http-probing` (repeated Pomerium denials) and `37pla/frontdoor-sni-scanning` (rejected SNI at the VPS; bans escalate 4h, 24h, 7d, 30d, 90d). The home WAN address is whitelisted every five minutes; a scan test in August 2026 once banned it.
8
+ VM 106 (`10.0.90.10`, VLAN 90) runs the Wazuh manager (container `observability-wazuh-manager-1`, agents `identity`, `arcane`, `dmz`, `CORTEX`, `NEXUS`, `hermes`, `frontdoor-1337`, `tailscale`), CrowdSec with its local API for the front-door bouncer, and rsyslog, which archives remote logs under `/var/log/remote/<host>/<program>.log` (14 days). The Discord bridge on Cortex reads Wazuh through this tool every two minutes and posts urgent alerts at once (level 11 or higher, and rules 100011, 100012, 100020, 100021; a deployment-file change that a GitOps commit or our own operation explains is not urgent), with Investigate and Acknowledge buttons for the owners; everything else goes into the Security Daily Report (06:00) and, on Mondays, the Security Weekly Report. The VM itself no longer posts to Discord. Two local CrowdSec scenarios matter: `37pla/pomerium-http-probing` (repeated Pomerium denials) and `37pla/frontdoor-sni-scanning` (rejected SNI at the VPS; bans escalate 4h, 24h, 7d, 30d, 90d). The home WAN address is whitelisted every five minutes; a scan test in August 2026 once banned it.
9
9
 
10
10
  The `security` tool is read-only. Every call is a fixed command on the guest; `["--help"]` lists them.
11
11
 
@@ -14,11 +14,13 @@ The `security` tool is read-only. Every call is a fixed command on the guest; `[
14
14
  | `status` | unit states and running containers |
15
15
  | `attention` | JSON: `bouncer` (count, oldest pull age), `wazuh_agents` (active/total, list), `recent_high_alerts` (24 h, level ≥ 10), `health_issues` |
16
16
  | `agents` | `agent_control -l` |
17
- | `alerts <days> [ip]` | summary: `count`, `uniqueIps`, `repeatIps`, `daily`, `topIps` (10), `scenarios`, `latest` (20 compact alerts: `at`, `ip`, `scenario`, `events`, `decisions`, `country`, `as`); with `ip`, `latest` holds every alert of that address |
17
+ | `alerts <days> [ip]` | summary: `count`, `uniqueIps`, `repeatIps`, `daily`, `topIps` (10), `scenarios`, `latest` (20 compact alerts: `at`, `ip`, `scenario`, `events`, `decisions`, `country`, `as`), `bans` (alerts per whole ban length), `escalated` (bans longer than 4 h: repeat offenders), `countries` and `networks` (top 5); with `ip`, `latest` holds every alert of that address |
18
18
  | `decisions` | `count` and one row per active decision (`value`, `scope`, `type`, `duration`, `scenario`, `origin`, `alertId`, `country`) |
19
19
  | `bouncers` | bouncers JSON (`name`, `last_pull`, `revoked`) |
20
20
  | `metrics` | `cscli metrics -o json` |
21
21
  | `wazuh-alerts <days> <minLevel>` | summary: count, groups by rule and agent, latest 20 (log line truncated to 200 chars) |
22
+ | `wazuh-events <minutes> <minLevel>` | every alert of the last N minutes at or above a level, oldest first, without vulnerability findings: `id`, `timestamp`, `agent`, `rule`, `level`, `description`, `groups`, and for file integrity `path`, `event`, `sha256`; `srcip`; `log` (300 chars); at most the newest 1000 (`omitted` counts the rest) |
23
+ | `wazuh-vuln-events <days>` | every vulnerability finding of the window, oldest first: `timestamp`, `agent`, `cve`, `status`, `package`, `version`, `severity`, `score`, `condition` |
22
24
  | `wazuh-vulns <days> [agent]` | vulnerability alerts only: `open` (latest event per agent, package, installed version and CVE that is still Active), `openWithoutFixVersion`, `active` and `solved` counts, and `items` (every event, newest first) with `cve`, `severity`, `score`, `status`, `package`, installed `version`, `condition`, `references` |
23
25
  | `wazuh-log <lines>` | manager container log |
24
26
  | `remote-hosts` | `host/program.log` names in the archive |
@@ -39,7 +41,8 @@ The `security` tool is read-only. Every call is a fixed command on the guest; `[
39
41
  - Front-door stream log line: `client - [time] "sni" status bytes_sent bytes_received session_time "upstream"`; upstream `-` means the SNI was rejected.
40
42
  - Wazuh rule `100010` (level 10) is a pending Debian reboot; `100011` is the RADIUS CRL threshold.
41
43
  - Wazuh rules `23503` to `23506` are vulnerability findings by severity; `23502` and `23507` mark one solved. A finding is not evidence of exploitation.
42
- - Read findings with `wazuh-vulns` and judge by `open`, not by the alert that reached Discord: Discord shows level 10 and above, and a Solved event is level 3, so a CVE can be closed one second after the message that announced it. If the CVE is absent from `open`, it is closed; say when it was solved.
44
+ - Read findings with `wazuh-vulns` and judge by `open`: a Solved event is level 3, so a CVE can be closed one second after the finding was reported. If the CVE is absent from `open`, it is closed; say when it was solved.
45
+ - Messages that start with "🚨 Security alert", "Security Daily Report:", or "Security Weekly Report:" come from the bridge, built from this tool without you. An Investigate click starts you in the alert's thread with the alert as data: read only, delegate read-only questions to the owning specialist, name the evidence.
43
46
  - `condition` "Package less than X" names the fixed version. `condition` "Package default status" means Wazuh's feed lists the source package as affected in this Debian release with no fixed version yet, so it flags every installed version, including a fresh security update. When the owner confirms the installed version equals the security-origin candidate and the package changelog names the CVE, the host is patched and the finding waits for Wazuh's content update; report it that way.
44
47
  - After a package upgrade, Wazuh re-evaluates: Solved events for the old version and Active events for the new one arrive in the same second. Pair them by CVE before concluding anything.
45
48
 
@@ -44,7 +44,8 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
44
44
  - Pi executes sibling tool calls in parallel, so two wrapper processes of the same specialist can run at once. `lib/lock.ts` (`withLock`, a directory lock under `~/.specialists/work/locks`, stale after 10 minutes) serialises shared resources; `edge` holds `edge-tunnel` around the fixed IAP port and the gcloud configuration directory. `arcane` holds `arcane-gitops` (stale after 3 hours) around `git`, `manager-upgrade`, and `stack-update`, because an update keeps the checkout for up to about two hours; the other `repo.ts` checkouts are not locked yet.
45
45
  - `edge` retries one SSH call through the IAP tunnel when the first connection is closed during setup (`isTransientSshFailure`: exit 255 with "closed by remote host" or a reset), except `reboot`. The IAP tunnel is `lib/tunnel.ts`: `gcloud compute start-iap-tunnel <instance> 22 --local-host-port=localhost:<port>` (a documented flag; the hidden `--listen-on-stdin` is not used), ready when the port accepts a connection, closed after the ssh call. `gcloud auth activate-service-account` runs before every tunnel with `CLOUDSDK_CONFIG` under `~/.specialists/work/gcloud` and `CLOUDSDK_PYTHON` from the config, because the Homebrew cask ships no interpreter.
46
46
  - `dns` builds every Technitium call from `TECHNITIUM_READS` and `TECHNITIUM_WRITES`; `key=value` record parameters pass through by name (`token` and `node` refused) because the API documents dozens of type-specific parameters. Writes are refused on the secondary in code: the catalog zone is the only replication path.
47
- - `security` parses Wazuh alert lines locally (`summariseWazuh`, `summariseVulns`) so the guest never needs `jq`; `wazuh-vulns` is a local view over the same `wazuh-alerts` dump, not a guest command.
47
+ - `security` parses Wazuh alert lines locally (`summariseWazuh`, `summariseVulns`) so the guest never needs `jq`; `wazuh-vulns`, `wazuh-events` (every non-vulnerability alert of the last N minutes at or above a level, with the alert id and the FIM path, change, and `sha256_after`; at most the newest 1000), and `wazuh-vuln-events` (every vulnerability finding, compact) are local views over the same `wazuh-alerts` dump, not guest commands. `alerts` adds each ban's whole length (time left plus the alert's age, to the hour), the escalated bans (longer than CrowdSec's default 4 hours), and the top countries and networks. The Discord bridge's security checks use these through the entry point (`extensions/astro-discord/security-monitor.ts`).
48
+ - `arcane change-origin <path> <sha256|-> <utc>` (`lib/change-origin.ts`) fetches origin, hashes the file in the newest 30 commits touching `<project>/<file>` up to 15 minutes after the change, and reads the last 16 MiB of the audit log for our `stack-update`, `manager-upgrade`, `manager-rollback`, or `host db-restore` on that stack (from a minute before its start to ten minutes after its end). It takes no checkout lock: like `update-report`'s holds read, it only fetches and reads objects, never the working tree. On 2026-10-21 the "Old md5sum" values of the live 100020 alerts matched the repository's previous Grimoire commits, which confirms that Arcane syncs these files verbatim.
48
49
  - TLS pinning for self-signed consoles is `lib/pinned.ts` (`pinnedRequest`); `network` and `proxmox` use it with a `*CertSha256` config value obtained once through the wrapper's `fingerprint` command.
49
50
  - `proxmox` writes are typed commands, never a generic POST: power actions and snapshot changes go through `runTask`, which polls `/nodes/<node>/tasks/<upid>/status` until `stopped` and fails on any `exitstatus` but `OK`. `--confirm` is stripped by `needsConfirm` for every interrupting action. `SET_KEYS` mirrors the privileges of the `SpecialistGuest` role; the API refuses anything the role lacks, the wrapper refuses earlier.
50
51
  - `backup` and `inference` are pure forced-command wrappers with per-command timeouts (`timeoutMs` in the tables) because runs such as `vzdump-run` take many minutes; the gate's `timeoutMs` in `specialists.json` must exceed the longest of them.
@@ -4,12 +4,12 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
4
4
 
5
5
  | Agent | Area | What it can do |
6
6
  |---|---|---|
7
- | `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; `update-report` (fresh check of every stack with running and latest release versions); `release-notes <stack>/<service>` (GitHub notes between the two versions); `project-status`, `deployment check|wait`; `stack-update <stack>` (a stack's pending image updates through GitOps, redeploy, checks, and rollback; across a major version only with `--confirm`, owner approval; held stacks in the repository's `update-holds.json` are refused); `manager-upgrade <version>` and `manager-rollback <stamp>` (the documented manager upgrade, owner approval); `host <command>`: sanitized host checks (memory, stats, logs, OOM, kernel OOM, audit, capacity, storage, Docker usage, service and queue checks) and `db-list|db-dump|db-restore` for Mealie and Paperless through user `spc-arcane` on VM 100; Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync |
7
+ | `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; `update-report` (fresh check of every stack with running and latest release versions); `release-notes <stack>/<service>` (GitHub notes between the two versions); `change-origin <path> <sha256|-> <utc>` (whether a deployment-file change Wazuh saw is a GitOps commit or one of our operations); `project-status`, `deployment check|wait`; `stack-update <stack>` (a stack's pending image updates through GitOps, redeploy, checks, and rollback; across a major version only with `--confirm`, owner approval; held stacks in the repository's `update-holds.json` are refused); `manager-upgrade <version>` and `manager-rollback <stamp>` (the documented manager upgrade, owner approval); `host <command>`: sanitized host checks (memory, stats, logs, OOM, kernel OOM, audit, capacity, storage, Docker usage, service and queue checks) and `db-list|db-dump|db-restore` for Mealie and Paperless through user `spc-arcane` on VM 100; Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync |
8
8
  | `astro.identity` | Zitadel; Pomerium, nginx, lego on VM 104; `02-pulsar-proxmox/dmz/` in the homelab repository | Any Zitadel API call (v2, management, admin, auth) with responses redacted; `dmz status|journal|config-template|render|pomerium-restart|nginx-reload|lego-renew|deploy-config`; `git` on the homelab checkout, writes limited to `02-pulsar-proxmox/dmz/` |
9
9
  | `astro.network` | UniFi, FreeRADIUS (LXC 108), Tailscale (LXC 105) | Read UniFi sites, devices, clients, networks, zones, firewall policies, WANs; create, update, delete firewall policies; RADIUS and Tailscale checks on Pulsar |
10
10
  | `astro.dns` | Technitium primary (Synapse) and secondary (LXC 107); Cloudflare zones `37pla.net`, `monadeo.com` | Read zones and records on both resolvers, resolve, stats; create and delete zones, add, update, delete records on the primary; Cloudflare zones and record add, update, delete |
11
11
  | `astro.edge` | Frontdoor VPS (`frontdoor-1337`) over an IAP tunnel; `00-frontdoor-vps/` in the homelab repository | `probe` the public path; `route-probe` (status of the Supabase, Grimoire, and Mealie public routes from Cortex); `vps status|nginx-conf|nginx-test|journal|wg|bouncer|updates|package|changelog|auto-upgrades|deploy-nginx|reboot --confirm`; `git` on the homelab checkout, writes limited to `00-frontdoor-vps/` |
12
- | `astro.security` | Wazuh, CrowdSec, rsyslog archive on VM 106 | Read-only: `status`, `attention`, `agents`, `alerts`, `decisions`, `bouncers`, `metrics`, `wazuh-alerts`, `wazuh-vulns`, `wazuh-log`, `remote-hosts`, `remote-log`, `journal` |
12
+ | `astro.security` | Wazuh, CrowdSec, rsyslog archive on VM 106 | Read-only: `status`, `attention`, `agents`, `alerts`, `decisions`, `bouncers`, `metrics`, `wazuh-alerts`, `wazuh-vulns`, `wazuh-events`, `wazuh-vuln-events`, `wazuh-log`, `remote-hosts`, `remote-log`, `journal` |
13
13
  | `astro.backup` | vzdump, the shared Restic repository (Pulsar host config, Arcane app backups), GCS offsite from LXC 102 | Status, journals, and manual runs of every layer; `restic-snapshots|stats|ls`, `restic-restore` into `/var/tmp/spc-restore` on Pulsar, `restore-clean` |
14
14
  | `astro.proxmox` | Proxmox VE on Pulsar | API token: `guests`, `guest`, `get <path>`, `tasks`; `start`, `shutdown|reboot|stop --confirm`; snapshots create, delete, rollback; `set` of CPU, memory, options, network. Pulsar key: `host-status`, `host-journal`, `updates`, `guest-exec <vmid> <status|journal|df|updates>` |
15
15
  | `astro.inference` | llama.cpp on Nexus, Europa health | `nexus-status|start|stop|restart|log|disk`; `europa-health` |
@@ -3,6 +3,7 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "no
3
3
  import { tmpdir } from "node:os";
4
4
  import { dirname, join } from "node:path";
5
5
  import { buildHostRemote, compareAudit, HOST_COMMANDS, type AuditFile } from "../lib/arcane-host.ts";
6
+ import { type CommitVersion, coveringOperation, judgeChange, parseChangeQuery, readTail } from "../lib/change-origin.ts";
6
7
  import { failedChecks, MANAGER_COMPOSE, MANAGER_IMAGE, normalizeVersion, olderThan, pinCompose, projectSync, syncReady, utcStamp, type VerifyCheck } from "../lib/arcane-manager.ts";
7
8
  import { readConfig } from "../lib/config.ts";
8
9
  import { containerFacts, deploymentChecks, listRows, parseDeploymentArgs, syncFacts, type DeploymentExpectation } from "../lib/deployment.ts";
@@ -11,7 +12,7 @@ import { withLock } from "../lib/lock.ts";
11
12
  import { main } from "../lib/main.ts";
12
13
  import { buildUpdateReport, parseTag, resolveRef, stackServices, type CheckEntry, type UpdateRow } from "../lib/image-updates.ts";
13
14
  import { printJson, printRaw } from "../lib/output.ts";
14
- import { specialistsHome } from "../lib/paths.ts";
15
+ import { auditLogPath, specialistsHome } from "../lib/paths.ts";
15
16
  import { run, type RunResult } from "../lib/proc.ts";
16
17
  import { HttpRegistry, parseImageRef } from "../lib/registry.ts";
17
18
  import { releaseNotesFor } from "../lib/releases.ts";
@@ -110,6 +111,11 @@ ${Object.entries(HOST_COMMANDS)
110
111
  Compose change reverts it and redeploys; a pull alone cannot be undone. Refuses held
111
112
  stacks, stopped stacks, and arcane (manager-upgrade). An update across a major version
112
113
  needs --confirm, which asks an owner for approval.
114
+ change-origin <path> <sha256|-> <utc>
115
+ whether a deployment file change Wazuh saw (/opt/docker/<project>/compose.yaml,
116
+ docker-compose.yml, pre-deploy.sh) is ours: known when the new content, or the deletion,
117
+ is a commit of <project>/<file> in the GitOps repository, or when our stack-update,
118
+ manager-upgrade, manager-rollback, or host db-restore on that stack ran then (audit log)
113
119
  release-notes <stack>[/<service>]
114
120
  GitHub release notes between the running and the latest version of one service's image,
115
121
  found through the image's org.opencontainers.image.source label
@@ -263,6 +269,40 @@ async function releaseNotes(config: ArcaneConfig, args: string[]): Promise<numbe
263
269
  });
264
270
  }
265
271
 
272
+ /** Clock difference between the committing machine and Wazuh that a match still allows. */
273
+ const COMMIT_SLACK_MS = 15 * 60_000;
274
+ const AUDIT_TAIL_BYTES = 16 * 1024 * 1024;
275
+
276
+ /** Reads origin's history of the file and our audit log; changes neither the checkout's working tree nor anything else. */
277
+ async function changeOrigin(config: ArcaneConfig, args: string[]): Promise<number> {
278
+ const query = parseChangeQuery(args);
279
+ const spec = repoSpec(config);
280
+ const dir = await ensureCheckout(spec);
281
+ await git(spec, dir, ["fetch", "--quiet", "origin", config.gitopsBranch]);
282
+ const until = new Date(query.at + COMMIT_SLACK_MS).toISOString();
283
+ const log = await git(spec, dir, ["log", `origin/${config.gitopsBranch}`, `--until=${until}`, "-n", "30", "--format=%H%x09%cI%x09%s", "--", query.repoPath]);
284
+ const versions: CommitVersion[] = [];
285
+ for (const line of log.split("\n").filter(Boolean)) {
286
+ const [sha, at, ...subject] = line.split("\t");
287
+ let sha256: string | null;
288
+ try {
289
+ sha256 = createHash("sha256").update(await git(spec, dir, ["show", `${sha}:${query.repoPath}`])).digest("hex");
290
+ } catch {
291
+ // The commit that deletes the file has no blob at that path.
292
+ sha256 = null;
293
+ }
294
+ versions.push({ sha, at, subject: subject.join("\t").slice(0, 200), sha256 });
295
+ }
296
+ let audit: string;
297
+ try {
298
+ audit = readTail(auditLogPath(), AUDIT_TAIL_BYTES);
299
+ } catch {
300
+ audit = "";
301
+ }
302
+ printJson(judgeChange(query, versions, coveringOperation(audit, query.project, query.at)));
303
+ return 0;
304
+ }
305
+
266
306
  // ---------------------------------------------------------------- Arcane VM
267
307
 
268
308
  const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
@@ -701,6 +741,7 @@ export async function command(args: string[]): Promise<number> {
701
741
  if (args[0] === "git") return checkoutLocked(() => repoCommand(repoSpec(config), args.slice(1)));
702
742
  if (args[0] === "update-report") return updateReport(config, args.slice(1));
703
743
  if (args[0] === "release-notes") return releaseNotes(config, args.slice(1));
744
+ if (args[0] === "change-origin") return changeOrigin(config, args.slice(1));
704
745
  if (args[0] === "host") return hostCommand(config, args.slice(1));
705
746
  if (args[0] === "project-status") return projectStatus(config, args.slice(1));
706
747
  if (args[0] === "deployment") return deployment(config, args.slice(1));
@@ -15,7 +15,7 @@ wazuh=observability-wazuh-manager-1
15
15
 
16
16
  case "$name" in
17
17
  status)
18
- for s in rsyslog crowdsec nftables docker security-attention.timer update-home-whitelist.timer; do
18
+ for s in rsyslog crowdsec nftables docker update-home-whitelist.timer; do
19
19
  printf '%-32s %s\n' "$s" "$(systemctl is-active "$s" || true)"
20
20
  done
21
21
  sudo -n docker ps --format '{{.Names}} {{.Status}}' ;;
@@ -0,0 +1,97 @@
1
+ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
2
+ import { tmpdir } from "node:os";
3
+ import { join } from "node:path";
4
+ import { describe, expect, it } from "vitest";
5
+ import { coveringOperation, judgeChange, parseChangeQuery, readTail } from "./change-origin.ts";
6
+
7
+ const SHA = "a".repeat(64);
8
+ const AT = "2026-10-20T12:50:12.142+0000";
9
+
10
+ describe("change-origin arguments", () => {
11
+ it("accepts a watched deployment file, a SHA-256 or -, and Wazuh's timestamp", () => {
12
+ expect(parseChangeQuery(["/opt/docker/grimoire/compose.yaml", SHA, AT])).toEqual({ path: "/opt/docker/grimoire/compose.yaml", project: "grimoire", repoPath: "grimoire/compose.yaml", sha256: SHA, at: Date.parse("2026-10-20T12:50:12.142Z") });
13
+ expect(parseChangeQuery(["/opt/docker/paperless/pre-deploy.sh", "-", "2026-10-20T12:50:12Z"]).sha256).toBeNull();
14
+ expect(parseChangeQuery(["/opt/docker/x/docker-compose.yml", SHA, "2026-10-20T14:50:12+02:00"]).at).toBe(Date.parse("2026-10-20T12:50:12Z"));
15
+ });
16
+
17
+ it("refuses anything else", () => {
18
+ expect(() => parseChangeQuery(["/opt/docker/grimoire/compose.yaml", SHA])).toThrow(/change-origin <path>/);
19
+ expect(() => parseChangeQuery(["/etc/sudoers", SHA, AT])).toThrow(/path must be/);
20
+ expect(() => parseChangeQuery(["/opt/docker/../etc/compose.yaml", SHA, AT])).toThrow(/path must be/);
21
+ expect(() => parseChangeQuery(["/opt/docker/.gitops-backup-1/compose.yaml", SHA, AT])).toThrow(/path must be/);
22
+ expect(() => parseChangeQuery(["/opt/docker/grimoire/.env", SHA, AT])).toThrow(/path must be/);
23
+ expect(() => parseChangeQuery(["/opt/docker/grimoire/compose.yaml", "ABC", AT])).toThrow(/sha256/);
24
+ expect(() => parseChangeQuery(["/opt/docker/grimoire/compose.yaml", SHA, "yesterday"])).toThrow(/utc/);
25
+ expect(() => parseChangeQuery(["/opt/docker/grimoire/compose.yaml", SHA, "2026-10-20T12:50:12"])).toThrow(/utc/);
26
+ });
27
+ });
28
+
29
+ describe("audit operations", () => {
30
+ const line = (ts: string, argv: string[], durationMs: number, service = "arcane") => JSON.stringify({ ts, service, caller: "discord-178096425509453824", argv, code: 0, durationMs });
31
+ const audit = [
32
+ line("2026-10-20T12:55:00.000Z", ["stack-update", "grimoire"], 10 * 60_000),
33
+ line("2026-10-20T12:56:00.000Z", ["host", "db-restore", "mealie", "20261020T120000Z"], 60_000),
34
+ line("2026-10-20T12:57:00.000Z", ["manager-upgrade", "2.17.0"], 5 * 60_000),
35
+ line("2026-10-20T12:58:00.000Z", ["project-status"], 1000),
36
+ line("2026-10-20T12:59:00.000Z", ["wazuh-events", "10", "10"], 1000, "security"),
37
+ "not json",
38
+ ].join("\n");
39
+
40
+ it("finds the operation on that stack whose run covers the change", () => {
41
+ expect(coveringOperation(audit, "grimoire", Date.parse("2026-10-20T12:50:12Z"))).toEqual({ command: "stack-update grimoire", caller: "discord-178096425509453824", from: "2026-10-20T12:45:00.000Z", to: "2026-10-20T12:55:00.000Z" });
42
+ expect(coveringOperation(audit, "grimoire", Date.parse("2026-10-20T13:04:00Z"))?.command).toBe("stack-update grimoire");
43
+ expect(coveringOperation(audit, "grimoire", Date.parse("2026-10-20T13:06:00Z"))).toBeNull();
44
+ expect(coveringOperation(audit, "grimoire", Date.parse("2026-10-20T12:43:00Z"))).toBeNull();
45
+ expect(coveringOperation(audit, "mealie", Date.parse("2026-10-20T12:55:30Z"))?.command).toBe("host db-restore mealie 20261020T120000Z");
46
+ expect(coveringOperation(audit, "arcane", Date.parse("2026-10-20T12:53:00Z"))?.command).toBe("manager-upgrade 2.17.0");
47
+ expect(coveringOperation(audit, "paperless", Date.parse("2026-10-20T12:55:00Z"))).toBeNull();
48
+ });
49
+
50
+ it("reads only the end of a large log", () => {
51
+ const dir = mkdtempSync(join(tmpdir(), "spc-audit-"));
52
+ try {
53
+ const path = join(dir, "audit.log");
54
+ writeFileSync(path, `${"x".repeat(100)}\n${audit}`);
55
+ expect(readTail(path, 50).length).toBe(50);
56
+ expect(readTail(path, 1_000_000).startsWith("x")).toBe(true);
57
+ } finally {
58
+ rmSync(dir, { recursive: true, force: true });
59
+ }
60
+ });
61
+ });
62
+
63
+ describe("change verdict", () => {
64
+ const query = parseChangeQuery(["/opt/docker/grimoire/compose.yaml", SHA, AT]);
65
+ const versions = [
66
+ { sha: "21d8d1b72c93a1158b63ff3e987671555f200d74", at: "2026-10-20T12:46:51Z", subject: "Deploy Grimoire v0.27.55", sha256: SHA },
67
+ { sha: "1db7e63c03cbf3cd5a2cd2bb99d32fb741c2608b", at: "2026-10-20T12:37:38Z", subject: "Deploy Grimoire v0.27.54", sha256: "b".repeat(64) },
68
+ ];
69
+
70
+ it("is known when the new content is a committed version", () => {
71
+ expect(judgeChange(query, versions, null)).toEqual({
72
+ path: query.path,
73
+ repoPath: "grimoire/compose.yaml",
74
+ at: "2026-10-20T12:50:12.142Z",
75
+ verdict: "known",
76
+ reason: "the new content matches GitOps commit 21d8d1b72c93 (2026-10-20T12:46:51Z): Deploy Grimoire v0.27.55",
77
+ commit: { sha: versions[0].sha, at: versions[0].at, subject: versions[0].subject },
78
+ });
79
+ });
80
+
81
+ it("is known when one of our operations ran then, and unknown otherwise", () => {
82
+ const other = { ...query, sha256: "c".repeat(64) };
83
+ const op = { command: "stack-update grimoire", caller: "discord-1", from: "2026-10-20T12:45:00.000Z", to: "2026-10-20T12:55:00.000Z" };
84
+ expect(judgeChange(other, versions, op)).toMatchObject({ verdict: "known", reason: "our stack-update grimoire (caller discord-1) ran from 2026-10-20T12:45:00.000Z to 2026-10-20T12:55:00.000Z", operation: op });
85
+ expect(judgeChange(other, versions, null)).toMatchObject({
86
+ verdict: "unknown",
87
+ reason: "no GitOps commit has this content of grimoire/compose.yaml; the newest commit touching it is 21d8d1b72c93 (2026-10-20T12:46:51Z); no specialist operation on grimoire ran then",
88
+ });
89
+ expect(judgeChange(other, [], null).reason).toContain("no commit touches it");
90
+ });
91
+
92
+ it("judges a deletion against commits that deleted the file", () => {
93
+ const deleted = { ...query, sha256: null };
94
+ expect(judgeChange(deleted, versions, null)).toMatchObject({ verdict: "unknown", reason: expect.stringContaining("no GitOps commit deleted grimoire/compose.yaml") });
95
+ expect(judgeChange(deleted, [{ sha: "d".repeat(40), at: "2026-10-20T12:46:00Z", subject: "Remove grimoire", sha256: null }], null)).toMatchObject({ verdict: "known", reason: expect.stringContaining("the deletion matches GitOps commit dddddddddddd") });
96
+ });
97
+ });
@@ -0,0 +1,121 @@
1
+ import { closeSync, fstatSync, openSync, readSync } from "node:fs";
2
+ import { UsageError } from "./errors.ts";
3
+
4
+ /** The deployment files Wazuh rule 100020 watches: `/opt/docker/<project>/<file>`, synced from `<project>/<file>` of the GitOps repository. */
5
+ const DEPLOYMENT_FILE = /^\/opt\/docker\/([A-Za-z0-9][A-Za-z0-9_.-]{0,127})\/(compose\.ya?ml|docker-compose\.ya?ml|pre-deploy\.sh)$/;
6
+ const SHA256 = /^[0-9a-f]{64}$/;
7
+ const UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:?\d{2})$/;
8
+
9
+ export interface ChangeQuery {
10
+ path: string;
11
+ project: string;
12
+ repoPath: string;
13
+ /** SHA-256 of the file after the change; null for a deletion. */
14
+ sha256: string | null;
15
+ at: number;
16
+ }
17
+
18
+ /** `change-origin <path> <sha256|-> <utc>`, checked. */
19
+ export function parseChangeQuery(args: string[]): ChangeQuery {
20
+ if (args.length !== 3) throw new UsageError("change-origin <path> <sha256|-> <utc>");
21
+ const [path, sha, when] = args;
22
+ const m = DEPLOYMENT_FILE.exec(path);
23
+ if (!m) throw new UsageError("path must be /opt/docker/<project>/compose.yaml, docker-compose.yml, or pre-deploy.sh");
24
+ if (sha !== "-" && !SHA256.test(sha)) throw new UsageError("sha256 must be 64 lowercase hex characters, or - for a deleted file");
25
+ // Wazuh writes +0000; Date.parse needs the colon in the offset.
26
+ const at = UTC.test(when) ? Date.parse(when.replace(/([+-]\d{2})(\d{2})$/, "$1:$2")) : Number.NaN;
27
+ if (Number.isNaN(at)) throw new UsageError("utc must be an ISO 8601 time with a zone, such as 2026-10-20T12:50:12.142+0000");
28
+ return { path, project: m[1], repoPath: `${m[1]}/${m[2]}`, sha256: sha === "-" ? null : sha, at };
29
+ }
30
+
31
+ export interface Operation {
32
+ command: string;
33
+ caller: string;
34
+ from: string;
35
+ to: string;
36
+ }
37
+
38
+ /** Commands of ours that change a stack's deployment files, and the stack each one names. */
39
+ function operationStack(argv: unknown): string | null {
40
+ if (!Array.isArray(argv) || !argv.every((a) => typeof a === "string")) return null;
41
+ const args = argv as string[];
42
+ if (args[0] === "stack-update") return args.find((a, i) => i > 0 && !a.startsWith("-")) ?? null;
43
+ if (args[0] === "manager-upgrade" || args[0] === "manager-rollback") return "arcane";
44
+ if (args[0] === "host" && args[1] === "db-restore") return args[2] ?? null;
45
+ return null;
46
+ }
47
+
48
+ /** Slack around an operation: the alert can come a little before the audit line's start (clock) or after its end (Wazuh's scan). */
49
+ const BEFORE_MS = 60_000;
50
+ const AFTER_MS = 10 * 60_000;
51
+
52
+ /** The arcane operation from the audit log whose run covers the change, if any; `ts` is written when the call ends. */
53
+ export function coveringOperation(auditText: string, project: string, at: number): Operation | null {
54
+ let found: Operation | null = null;
55
+ for (const line of auditText.split("\n")) {
56
+ if (!line.startsWith("{")) continue;
57
+ let entry: { ts?: unknown; service?: unknown; caller?: unknown; argv?: unknown; durationMs?: unknown };
58
+ try {
59
+ entry = JSON.parse(line) as typeof entry;
60
+ } catch {
61
+ continue;
62
+ }
63
+ if (entry.service !== "arcane" || operationStack(entry.argv) !== project || typeof entry.ts !== "string" || typeof entry.durationMs !== "number") continue;
64
+ const end = Date.parse(entry.ts);
65
+ const start = end - entry.durationMs;
66
+ if (Number.isNaN(end) || at < start - BEFORE_MS || at > end + AFTER_MS) continue;
67
+ found = { command: (entry.argv as string[]).join(" "), caller: String(entry.caller), from: new Date(start).toISOString(), to: entry.ts };
68
+ }
69
+ return found;
70
+ }
71
+
72
+ /** The last `maxBytes` of a file: the audit log only grows, and a change is checked minutes after it happened. */
73
+ export function readTail(path: string, maxBytes: number): string {
74
+ const fd = openSync(path, "r");
75
+ try {
76
+ const size = fstatSync(fd).size;
77
+ const length = Math.min(size, maxBytes);
78
+ const buffer = Buffer.alloc(length);
79
+ readSync(fd, buffer, 0, length, size - length);
80
+ return buffer.toString("utf-8");
81
+ } finally {
82
+ closeSync(fd);
83
+ }
84
+ }
85
+
86
+ export interface CommitVersion {
87
+ sha: string;
88
+ at: string;
89
+ subject: string;
90
+ /** SHA-256 of the file in that commit; null when the commit deleted it. */
91
+ sha256: string | null;
92
+ }
93
+
94
+ export interface ChangeOrigin {
95
+ path: string;
96
+ repoPath: string;
97
+ at: string;
98
+ verdict: "known" | "unknown";
99
+ reason: string;
100
+ commit?: { sha: string; at: string; subject: string };
101
+ operation?: Operation;
102
+ }
103
+
104
+ /**
105
+ * Known when the file's new content (or its deletion) is a committed version of
106
+ * `<project>/<file>`, or when one of our arcane operations on that stack ran at
107
+ * that time. `versions` are the commits touching the file, newest first.
108
+ */
109
+ export function judgeChange(query: ChangeQuery, versions: readonly CommitVersion[], operation: Operation | null): ChangeOrigin {
110
+ const base = { path: query.path, repoPath: query.repoPath, at: new Date(query.at).toISOString() };
111
+ const match = versions.find((v) => v.sha256 === query.sha256);
112
+ if (match) {
113
+ const what = query.sha256 === null ? "the deletion" : "the new content";
114
+ return { ...base, verdict: "known", reason: `${what} matches GitOps commit ${match.sha.slice(0, 12)} (${match.at}): ${match.subject}`, commit: { sha: match.sha, at: match.at, subject: match.subject } };
115
+ }
116
+ if (operation) return { ...base, verdict: "known", reason: `our ${operation.command} (caller ${operation.caller}) ran from ${operation.from} to ${operation.to}`, operation };
117
+ const newest = versions[0];
118
+ const last = newest ? `the newest commit touching it is ${newest.sha.slice(0, 12)} (${newest.at})` : "no commit touches it";
119
+ const what = query.sha256 === null ? "no GitOps commit deleted" : "no GitOps commit has this content of";
120
+ return { ...base, verdict: "unknown", reason: `${what} ${query.repoPath}; ${last}; no specialist operation on ${query.project} ran then` };
121
+ }