@astrofoundry/pi-astro 0.36.0 → 0.37.0
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/README.md +1 -1
- package/extensions/astro-discord/config.ts +6 -2
- package/extensions/astro-discord/discord.test.ts +18 -0
- package/extensions/astro-discord/index.ts +68 -7
- package/extensions/astro-discord/reports.ts +15 -4
- package/extensions/astro-discord/rest.ts +15 -3
- package/extensions/astro-discord/security-monitor.test.ts +338 -0
- package/extensions/astro-discord/security-monitor.ts +602 -0
- package/extensions/astro-discord/security.test.ts +497 -0
- package/extensions/astro-discord/security.ts +740 -0
- package/extensions/astro-discord/tools-report.test.ts +31 -3
- package/extensions/astro-discord/tools-report.ts +36 -19
- package/package.json +1 -1
- package/skills/arcane/SKILL.md +2 -0
- package/skills/security/SKILL.md +6 -3
- package/specialists/AGENTS.md +2 -1
- package/specialists/README.md +2 -2
- package/specialists/arcane/run.ts +42 -1
- package/specialists/entry/remote/spc-security-obs-entry.sh +1 -1
- package/specialists/lib/change-origin.test.ts +97 -0
- package/specialists/lib/change-origin.ts +121 -0
- package/specialists/security/run.ts +199 -31
- package/specialists/wrappers.test.ts +111 -1
|
@@ -24,6 +24,7 @@ import {
|
|
|
24
24
|
majorChange,
|
|
25
25
|
messageComponents,
|
|
26
26
|
notesFor,
|
|
27
|
+
packageCasks,
|
|
27
28
|
npmGlobalVersion,
|
|
28
29
|
parseToolsButton,
|
|
29
30
|
parseVerdict,
|
|
@@ -105,6 +106,34 @@ const COLLECTED: Collected = {
|
|
|
105
106
|
warnings: [],
|
|
106
107
|
};
|
|
107
108
|
|
|
109
|
+
describe("casks whose installer needs a password", () => {
|
|
110
|
+
const info = {
|
|
111
|
+
formulae: [],
|
|
112
|
+
casks: [
|
|
113
|
+
{ token: "temurin@17", artifacts: [{ uninstall: [] }, { pkg: ["OpenJDK17U.pkg"] }] },
|
|
114
|
+
{ token: "google-chrome", artifacts: [{ app: ["Google Chrome.app"] }, { zap: [] }] },
|
|
115
|
+
],
|
|
116
|
+
};
|
|
117
|
+
const outdated = {
|
|
118
|
+
formulae: [],
|
|
119
|
+
casks: [
|
|
120
|
+
{ name: "google-chrome", installed_versions: ["155.0"], current_version: "156.0" },
|
|
121
|
+
{ name: "temurin@17", installed_versions: ["17.0.20,8"], current_version: "17.0.20.1,1" },
|
|
122
|
+
],
|
|
123
|
+
};
|
|
124
|
+
|
|
125
|
+
it("finds package installers and gives their lines no button", () => {
|
|
126
|
+
expect([...packageCasks(info)]).toEqual(["temurin@17"]);
|
|
127
|
+
const lines = buildLines({ ...COLLECTED, brewInfo: info, brewOutdated: outdated, installer: {}, piInstalled: null, piLatest: null, piAstroInstalled: null, piAstroLatest: null });
|
|
128
|
+
const temurin = lines.find((l) => l.key === "cask:temurin@17");
|
|
129
|
+
const chrome = lines.find((l) => l.key === "cask:google-chrome");
|
|
130
|
+
expect(temurin?.manual).toContain("brew upgrade --cask temurin@17");
|
|
131
|
+
expect(chrome?.manual).toBeUndefined();
|
|
132
|
+
expect(lineText(temurin as ToolLine)).toContain("asks for your password");
|
|
133
|
+
expect(brewHasOutdated(outdated)).toBe(false);
|
|
134
|
+
});
|
|
135
|
+
});
|
|
136
|
+
|
|
108
137
|
describe("versions", () => {
|
|
109
138
|
it("compares dotted versions with revisions and build numbers", () => {
|
|
110
139
|
expect(compareLoose("10.48", "10.47_1")).toBeGreaterThan(0);
|
|
@@ -252,7 +281,6 @@ describe("report layout", () => {
|
|
|
252
281
|
const pages = layoutMessages(report);
|
|
253
282
|
expect(pages.length).toBe(2);
|
|
254
283
|
expect(pages[0].head).toBe(true);
|
|
255
|
-
expect(pages[pages.length - 1].tail).toBe(true);
|
|
256
284
|
expect(pages[pages.length - 1].all).toBe(true);
|
|
257
285
|
expect(pages.flatMap((p) => p.keys)).toEqual(many.map((l) => l.key));
|
|
258
286
|
for (const p of pages) expect(countComponents(messageComponents(report, p))).toBeLessThanOrEqual(40);
|
|
@@ -263,7 +291,7 @@ describe("report layout", () => {
|
|
|
263
291
|
it("says everything is up to date without buttons", () => {
|
|
264
292
|
const report = sampleReport([], false);
|
|
265
293
|
const pages = layoutMessages(report);
|
|
266
|
-
expect(pages).toEqual([{ keys: [], head: true, all: false
|
|
294
|
+
expect(pages).toEqual([{ keys: [], head: true, all: false }]);
|
|
267
295
|
expect(messageComponents(report, pages[0])).toEqual([{ type: 10, content: "**Cortex Tools Report:** everything is up to date (checked 06:00 CEST)." }]);
|
|
268
296
|
});
|
|
269
297
|
|
|
@@ -370,7 +398,7 @@ describe("state files", () => {
|
|
|
370
398
|
|
|
371
399
|
it("keeps the posted report for button checks", () => {
|
|
372
400
|
expect(readPostedReport()).toBeNull();
|
|
373
|
-
const report = { ...sampleReport(buildLines(COLLECTED)), messages: [{ id: "1", keys: ["pi"], head: true, all: false
|
|
401
|
+
const report = { ...sampleReport(buildLines(COLLECTED)), messages: [{ id: "1", keys: ["pi"], head: true, all: false }] };
|
|
374
402
|
writePostedReport(report);
|
|
375
403
|
expect(readPostedReport()).toEqual(report);
|
|
376
404
|
});
|
|
@@ -48,6 +48,8 @@ export interface ToolLine {
|
|
|
48
48
|
state: LineState;
|
|
49
49
|
/** Why the last update failed, or what it ended at. */
|
|
50
50
|
detail?: string;
|
|
51
|
+
/** The update needs the owner's password (a cask whose installer is a macOS package), so the line has no button. */
|
|
52
|
+
manual?: string;
|
|
51
53
|
}
|
|
52
54
|
|
|
53
55
|
/** One posted message of a report and what it shows, so a click can redraw exactly that message. */
|
|
@@ -56,7 +58,6 @@ export interface PostedMessage {
|
|
|
56
58
|
keys: string[];
|
|
57
59
|
head: boolean;
|
|
58
60
|
all: boolean;
|
|
59
|
-
tail: boolean;
|
|
60
61
|
}
|
|
61
62
|
|
|
62
63
|
export interface ToolsReport {
|
|
@@ -154,6 +155,20 @@ export function onRequestFormulae(info: unknown): Map<string, string> {
|
|
|
154
155
|
return out;
|
|
155
156
|
}
|
|
156
157
|
|
|
158
|
+
/**
|
|
159
|
+
* Casks that install a macOS package: `brew upgrade` runs that installer through sudo,
|
|
160
|
+
* which asks for the owner's password, so the bridge cannot run it.
|
|
161
|
+
*/
|
|
162
|
+
export function packageCasks(info: unknown): Set<string> {
|
|
163
|
+
const out = new Set<string>();
|
|
164
|
+
const casks = (info as { casks?: { token?: unknown; artifacts?: unknown }[] } | null)?.casks;
|
|
165
|
+
for (const c of Array.isArray(casks) ? casks : []) {
|
|
166
|
+
if (typeof c.token !== "string" || !Array.isArray(c.artifacts)) continue;
|
|
167
|
+
if (c.artifacts.some((a) => typeof a === "object" && a !== null && "pkg" in a)) out.add(c.token);
|
|
168
|
+
}
|
|
169
|
+
return out;
|
|
170
|
+
}
|
|
171
|
+
|
|
157
172
|
function outdatedEntries(json: unknown, kind: "formulae" | "casks"): { name: string; installed: string; latest: string; pinned: boolean }[] {
|
|
158
173
|
const list = (json as Record<string, OutdatedEntry[] | undefined> | null)?.[kind];
|
|
159
174
|
const out: { name: string; installed: string; latest: string; pinned: boolean }[] = [];
|
|
@@ -228,16 +243,19 @@ export function buildLines(c: Collected): ToolLine[] {
|
|
|
228
243
|
lines.push(line(`brew:${full}`, f.name, f.installed, f.latest, { kind: "brew", name: full }));
|
|
229
244
|
}
|
|
230
245
|
const casks = outdatedEntries(c.brewOutdated, "casks");
|
|
246
|
+
const packages = packageCasks(c.brewInfo);
|
|
231
247
|
for (const k of casks.sort((a, b) => a.name.localeCompare(b.name))) {
|
|
232
248
|
if (k.pinned) continue;
|
|
233
|
-
|
|
249
|
+
const l = line(`cask:${k.name}`, k.name, k.installed, k.latest, { kind: "cask", token: k.name });
|
|
250
|
+
if (packages.has(k.name)) l.manual = `its installer asks for your password; on Cortex: brew upgrade --cask ${k.name}`;
|
|
251
|
+
lines.push(l);
|
|
234
252
|
}
|
|
235
253
|
return lines;
|
|
236
254
|
}
|
|
237
255
|
|
|
238
|
-
/** True when Homebrew lists
|
|
256
|
+
/** True when Homebrew lists an outdated formula, dependencies included and pinned ones aside; casks have their own lines. */
|
|
239
257
|
export function brewHasOutdated(brewOutdated: unknown): boolean {
|
|
240
|
-
return
|
|
258
|
+
return outdatedEntries(brewOutdated, "formulae").some((e) => !e.pinned);
|
|
241
259
|
}
|
|
242
260
|
|
|
243
261
|
/** The newest Node release marked LTS that has a macOS arm64 tarball, from nodejs.org's `index.json`. */
|
|
@@ -561,7 +579,8 @@ export function updateCommand(action: UpdateAction, version: string): Command {
|
|
|
561
579
|
}
|
|
562
580
|
}
|
|
563
581
|
|
|
564
|
-
|
|
582
|
+
/** Formulae only: a cask whose installer needs a password would fail the whole run. */
|
|
583
|
+
export const BREW_ALL: Command = { file: BREW, args: ["upgrade", "--formula"] };
|
|
565
584
|
|
|
566
585
|
/** Pi has an exact previous version on npm to go back to; the installer restores its own, and Homebrew cannot downgrade. */
|
|
567
586
|
export function rollbackCommand(action: UpdateAction, previous: string): Command | null {
|
|
@@ -652,13 +671,15 @@ export function lineText(l: ToolLine): string {
|
|
|
652
671
|
const head = `**${escapeDiscord(l.label)}** ${escapeDiscord(l.installed)} → ${escapeDiscord(l.latest)}${l.major ? " · major version" : ""}`;
|
|
653
672
|
const notes = l.review ? `\n-# ${l.review.verdict ? `${VERDICT_MARK[l.review.verdict]}: ` : "notes: "}${escapeDiscord(l.review.reason)}` : "";
|
|
654
673
|
const detail = l.detail ? `\n-# ${escapeDiscord(l.detail)}` : "";
|
|
655
|
-
|
|
674
|
+
const manual = l.manual ? `\n-# ${escapeDiscord(l.manual)}` : "";
|
|
675
|
+
return `${head}${notes}${detail}${manual}`.slice(0, 1000);
|
|
656
676
|
}
|
|
657
677
|
|
|
658
678
|
function lineSection(l: ToolLine): MessageComponent {
|
|
659
679
|
const id = updateId(l);
|
|
660
|
-
const accessory: MessageComponent =
|
|
661
|
-
|
|
680
|
+
const accessory: MessageComponent = l.manual
|
|
681
|
+
? { type: 2, style: SECONDARY, label: "By hand", custom_id: `tools:none:${l.key}`.slice(0, CUSTOM_ID_MAX), disabled: true }
|
|
682
|
+
: id.length <= CUSTOM_ID_MAX && KEY.test(l.key) && VERSION.test(l.latest)
|
|
662
683
|
? stateButton(l.state, id, "Update")
|
|
663
684
|
: { type: 2, style: SECONDARY, label: "Update by hand", custom_id: `tools:none:${l.key}`.slice(0, CUSTOM_ID_MAX), disabled: true };
|
|
664
685
|
return { type: 9, components: [{ type: 10, content: lineText(l) }], accessory };
|
|
@@ -666,7 +687,7 @@ function lineSection(l: ToolLine): MessageComponent {
|
|
|
666
687
|
|
|
667
688
|
function allSection(report: ToolsReport): MessageComponent {
|
|
668
689
|
const detail = report.brewAllDetail ? `\n-# ${escapeDiscord(report.brewAllDetail)}` : "";
|
|
669
|
-
return { type: 9, components: [{ type: 10, content: `**Homebrew**: upgrade every outdated
|
|
690
|
+
return { type: 9, components: [{ type: 10, content: `**Homebrew**: upgrade every outdated formula, dependencies included${detail}` }], accessory: stateButton(report.brewAll, allId(report.date), "Upgrade everything") };
|
|
670
691
|
}
|
|
671
692
|
|
|
672
693
|
function clock(iso: string, timeZone: string): string {
|
|
@@ -683,7 +704,6 @@ function headText(report: ToolsReport): MessageComponent {
|
|
|
683
704
|
return { type: 10, content: `${head}${warnings}` };
|
|
684
705
|
}
|
|
685
706
|
|
|
686
|
-
const TAIL: MessageComponent = { type: 10, content: "-# Nothing changes until an owner presses a button. A restart waits until nothing runs on that service." };
|
|
687
707
|
const MESSAGE_COMPONENTS = 40;
|
|
688
708
|
|
|
689
709
|
/** The components of one posted message, redrawn from the report's current state. */
|
|
@@ -695,30 +715,27 @@ export function messageComponents(report: ToolsReport, m: Omit<PostedMessage, "i
|
|
|
695
715
|
if (l) out.push(lineSection(l));
|
|
696
716
|
}
|
|
697
717
|
if (m.all) out.push(allSection(report));
|
|
698
|
-
if (m.tail) out.push(TAIL);
|
|
699
718
|
return out;
|
|
700
719
|
}
|
|
701
720
|
|
|
702
|
-
/** Splits the report into messages of at most 40 components each
|
|
721
|
+
/** Splits the report into messages of at most 40 components each, header first. */
|
|
703
722
|
export function layoutMessages(report: ToolsReport): Omit<PostedMessage, "id">[] {
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
const items: Item[] = [{ kind: "head" }, ...report.lines.map((l) => ({ kind: "line" as const, key: l.key })), ...(report.brewOutdated ? [{ kind: "all" as const }] : []), ...(hasButtons ? [{ kind: "tail" as const }] : [])];
|
|
723
|
+
type Item = { kind: "head" } | { kind: "line"; key: string } | { kind: "all" };
|
|
724
|
+
const items: Item[] = [{ kind: "head" }, ...report.lines.map((l) => ({ kind: "line" as const, key: l.key })), ...(report.brewOutdated ? [{ kind: "all" as const }] : [])];
|
|
707
725
|
const pages: Omit<PostedMessage, "id">[] = [];
|
|
708
|
-
let page: Omit<PostedMessage, "id"> = { keys: [], head: false, all: false
|
|
726
|
+
let page: Omit<PostedMessage, "id"> = { keys: [], head: false, all: false };
|
|
709
727
|
let used = 0;
|
|
710
728
|
const size = (item: Item) => (item.kind === "line" || item.kind === "all" ? 3 : 1);
|
|
711
729
|
for (const item of items) {
|
|
712
730
|
if (used + size(item) > MESSAGE_COMPONENTS) {
|
|
713
731
|
pages.push(page);
|
|
714
|
-
page = { keys: [], head: false, all: false
|
|
732
|
+
page = { keys: [], head: false, all: false };
|
|
715
733
|
used = 0;
|
|
716
734
|
}
|
|
717
735
|
used += size(item);
|
|
718
736
|
if (item.kind === "head") page.head = true;
|
|
719
737
|
else if (item.kind === "line") page.keys.push(item.key);
|
|
720
|
-
else
|
|
721
|
-
else page.tail = true;
|
|
738
|
+
else page.all = true;
|
|
722
739
|
}
|
|
723
740
|
pages.push(page);
|
|
724
741
|
return pages;
|
package/package.json
CHANGED
package/skills/arcane/SKILL.md
CHANGED
|
@@ -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
|
package/skills/security/SKILL.md
CHANGED
|
@@ -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
|
|
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 12 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
|
|
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
|
|
package/specialists/AGENTS.md
CHANGED
|
@@ -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`
|
|
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.
|
package/specialists/README.md
CHANGED
|
@@ -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
|
|
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
|
+
}
|