Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(adoption): measure the funnel, and stop claiming telemetry that goes nowhere (#656)

Beenu Arora492d5269131f
diff --git a/.github/workflows/adoption-snapshot.yml b/.github/workflows/adoption-snapshot.yml
new file mode 100644
index 000000000..5ab9628e0
--- /dev/null
+++ b/.github/workflows/adoption-snapshot.yml
@@ -0,0 +1,57 @@
+name: Adoption snapshot
+
+# Nobody could answer "of the people who arrive, how many end up using this?".
+# The CLI's opt-in telemetry endpoint does not resolve, and the packages that
+# would have reported were never published, so there was no signal at all
+# between a visitor landing on the README and a contributor opening a PR.
+#
+# This reads what is already public — GitHub traffic, release downloads, npm
+# and PyPI download counts — and commits a dated row. No collector to run, no
+# data asked of users, and a missing source is recorded as "not measured"
+# rather than zero.
+
+on:
+ schedule:
+ - cron: '0 5 1 * *'
+ workflow_dispatch:
+
+permissions:
+ contents: write
+
+concurrency:
+ group: adoption-snapshot
+ cancel-in-progress: false
+
+jobs:
+ snapshot:
+ name: Collect and commit
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.12'
+
+ # GITHUB_TOKEN carries push access for this repo, which the traffic API
+ # requires. Without it views/clones come back 403 and land as
+ # "not measured".
+ - name: Collect snapshot
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: python3 scripts/adoption_snapshot.py --write
+
+ - name: Commit if anything moved
+ run: |
+ set -euo pipefail
+ if git diff --quiet -- docs/adoption; then
+ echo "::notice title=adoption::No change since the last snapshot."
+ exit 0
+ fi
+ git config user.name "github-actions[bot]"
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+ git add docs/adoption
+ git commit -m "chore(adoption): monthly snapshot"
+ git push
diff --git a/docs/adoption/README.md b/docs/adoption/README.md
new file mode 100644
index 000000000..defcb5724
--- /dev/null
+++ b/docs/adoption/README.md
@@ -0,0 +1,47 @@
+# Adoption snapshot
+
+Collected by `scripts/adoption_snapshot.py`, refreshed monthly by
+`.github/workflows/adoption-snapshot.yml`. Everything here comes from
+public GitHub and registry APIs — the project ships no usage telemetry
+that phones home.
+
+A value of **not measured** means the source could not be read on that
+run. It does not mean zero. The two get conflated constantly and the
+difference matters: one is a fact about users, the other is a fact
+about our tooling.
+
+## Latest — 2026-09-21
+
+### Reach
+
+- Stars: 2,361
+- Forks: 259
+- Unique visitors (14d): 1,541
+- Unique cloners (14d): 377
+
+### Conversion
+
+- Contributors: 13
+- Release asset downloads (all time): 52
+
+### Package downloads (last month)
+
+- npm `aisoc`: not measured
+- npm `@aisoc/mcp`: not measured
+- npm `@aisoc/sdk`: not measured
+- PyPI `aisoc-sandbox`: not measured
+- PyPI `aisoc-cli`: not measured
+- PyPI `aisoc-sdk`: not measured
+- PyPI `aisoc-plugin-sdk`: not measured
+- PyPI `aisoc-detections`: not measured
+
+### Why some values are missing
+
+- npm aisoc: not published yet
+- npm @aisoc/mcp: not published yet
+- npm @aisoc/sdk: not published yet
+- pypi aisoc-sandbox: registry did not answer (HTTP 429)
+- pypi aisoc-cli: registry did not answer (HTTP 429)
+- pypi aisoc-sdk: registry did not answer (HTTP 429)
+- pypi aisoc-plugin-sdk: not published yet
+- pypi aisoc-detections: not published yet
diff --git a/docs/adoption/snapshot.json b/docs/adoption/snapshot.json
new file mode 100644
index 000000000..0dddae157
--- /dev/null
+++ b/docs/adoption/snapshot.json
@@ -0,0 +1,43 @@
+{
+ "history": [
+ {
+ "date": "2026-09-21",
+ "repo": "beenuar/AiSOC",
+ "github": {
+ "stars": 2361,
+ "forks": 259,
+ "watchers": 37,
+ "open_issues": 12,
+ "views_14d": 4333,
+ "unique_views_14d": 1541,
+ "clones_14d": 1236,
+ "unique_clones_14d": 377,
+ "contributors": 13,
+ "releases": 9,
+ "release_asset_downloads": 52
+ },
+ "npm": {
+ "aisoc": null,
+ "@aisoc/mcp": null,
+ "@aisoc/sdk": null
+ },
+ "pypi": {
+ "aisoc-sandbox": null,
+ "aisoc-cli": null,
+ "aisoc-sdk": null,
+ "aisoc-plugin-sdk": null,
+ "aisoc-detections": null
+ },
+ "notes": [
+ "npm aisoc: not published yet",
+ "npm @aisoc/mcp: not published yet",
+ "npm @aisoc/sdk: not published yet",
+ "pypi aisoc-sandbox: registry did not answer (HTTP 429)",
+ "pypi aisoc-cli: registry did not answer (HTTP 429)",
+ "pypi aisoc-sdk: registry did not answer (HTTP 429)",
+ "pypi aisoc-plugin-sdk: not published yet",
+ "pypi aisoc-detections: not published yet"
+ ]
+ }
+ ]
+}
diff --git a/packages/aisoc-lite/TELEMETRY.md b/packages/aisoc-lite/TELEMETRY.md
index 6a1166255..d43b325de 100644
--- a/packages/aisoc-lite/TELEMETRY.md
+++ b/packages/aisoc-lite/TELEMETRY.md
@@ -48,7 +48,19 @@ The payload builder is unit-tested (`src/telemetry.test.ts`) to assert that no a
## Where it goes
-If enabled, the payload is POSTed to `https://telemetry.tryaisoc.com/v1/cli` (override with `AISOC_TELEMETRY_ENDPOINT`). The request has a 2-second timeout and can never fail or slow down the CLI — errors are silently ignored.
+**Nowhere, unless you point it somewhere.** There is no default endpoint and
+the project operates no collector. Enabling telemetry without setting
+`AISOC_TELEMETRY_ENDPOINT` performs no network call at all.
+
+If you do set an endpoint — for your own collector, in your own infrastructure
+— the payload above is POSTed to it with a 2-second timeout. The request can
+never fail or slow down the CLI; errors are silently ignored.
+
+> This used to default to a hosted collector that no longer resolves, which
+> meant an opted-in payload was discarded while this page claimed it was
+> collected. Quietly dropping data someone consented to send is a worse trust
+> failure than not collecting it, so sending now requires an explicit
+> destination.
## Why we ask at all
diff --git a/packages/aisoc-lite/src/telemetry.test.ts b/packages/aisoc-lite/src/telemetry.test.ts
index 4b3c09837..553ce84d2 100644
--- a/packages/aisoc-lite/src/telemetry.test.ts
+++ b/packages/aisoc-lite/src/telemetry.test.ts
@@ -1,5 +1,5 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { resolveTelemetry, buildPayload } from "./telemetry.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { resolveTelemetry, buildPayload, sendTelemetry } from "./telemetry.js";
import { triageBatch } from "./verdict/engine.js";
import { loadDemoAlerts } from "./fixtures/index.js";
@@ -47,3 +47,20 @@ describe("buildPayload — aggregate only, no alert content", () => {
);
});
});
+
+describe("sendTelemetry — no endpoint means no network call", () => {
+ // The default endpoint used to be a hosted collector that no longer
+ // resolves, so an opted-in payload was silently discarded while
+ // TELEMETRY.md said it was collected. There is now no default, and this
+ // pins that: enabling telemetry without naming a destination must make
+ // zero network calls rather than fire into a black hole.
+ it("does not call fetch when AISOC_TELEMETRY_ENDPOINT is unset", async () => {
+ const spy = vi.spyOn(globalThis, "fetch");
+ const result = triageBatch(loadDemoAlerts());
+ const sent = await sendTelemetry(buildPayload(result, "demo", "0.0.0-test"));
+
+ expect(sent).toBe(false);
+ expect(spy).not.toHaveBeenCalled();
+ spy.mockRestore();
+ });
+});
diff --git a/packages/aisoc-lite/src/telemetry.ts b/packages/aisoc-lite/src/telemetry.ts
index ecc522912..1c162f659 100644
--- a/packages/aisoc-lite/src/telemetry.ts
+++ b/packages/aisoc-lite/src/telemetry.ts
@@ -12,7 +12,17 @@
import type { TriageResult } from "./verdict/types.js";
-const ENDPOINT = process.env.AISOC_TELEMETRY_ENDPOINT || "https://telemetry.tryaisoc.com/v1/cli";
+/**
+ * There is deliberately no default endpoint.
+ *
+ * This previously defaulted to a hosted collector that does not resolve, so an
+ * opted-in user's payload was POSTed into a black hole while TELEMETRY.md told
+ * them it was being collected. Silently discarding data someone consented to
+ * send is a worse trust failure than not collecting it, so sending now
+ * requires an endpoint to be named explicitly. Self-hosters can point this at
+ * their own collector; the project itself runs none.
+ */
+const ENDPOINT = process.env.AISOC_TELEMETRY_ENDPOINT || "";
export interface TelemetryDecision {
enabled: boolean;
@@ -64,8 +74,14 @@ export function buildPayload(result: TriageResult, source: string, version: stri
};
}
-/** Fire-and-forget send. Never blocks or fails the CLI; silent on error. */
+/**
+ * Fire-and-forget send. Never blocks or fails the CLI; silent on error.
+ *
+ * Returns false without any network call when no endpoint is configured, so
+ * "enabled but going nowhere" is distinguishable from "sent".
+ */
export async function sendTelemetry(payload: TelemetryPayload): Promise<boolean> {
+ if (!ENDPOINT) return false;
try {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 2000);
diff --git a/scripts/adoption_snapshot.py b/scripts/adoption_snapshot.py
new file mode 100644
index 000000000..ca2357945
--- /dev/null
+++ b/scripts/adoption_snapshot.py
@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""Collect a dated adoption snapshot from data GitHub and the registries publish.
+
+The project has no usage telemetry it can actually read: the CLI's opt-in
+endpoint (`telemetry.tryaisoc.com`) does not resolve, and the packages that
+would report were never published. That left nobody able to answer the only
+question that matters for adoption — of the people who arrive, how many end up
+using the thing.
+
+This closes the gap without asking users for anything and without standing up a
+collector, by reading what is already public:
+
+ * GitHub traffic (views / clones), stars, forks, contributors, discussions
+ * release asset download counts
+ * npm per-package download counts
+ * PyPI per-package download counts
+
+Honesty rule: a source that cannot be read is recorded as ``null`` with a note
+saying why. It is never recorded as zero, because "nobody downloaded it" and
+"we could not ask" are different facts and conflating them is how a dashboard
+starts lying.
+
+Usage:
+ python3 scripts/adoption_snapshot.py --write # update the committed snapshot
+ python3 scripts/adoption_snapshot.py # print JSON, change nothing
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import pathlib
+import urllib.error
+import urllib.request
+
+REPO = os.environ.get("AISOC_SNAPSHOT_REPO", "beenuar/AiSOC")
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+OUT_JSON = REPO_ROOT / "docs" / "adoption" / "snapshot.json"
+OUT_MD = REPO_ROOT / "docs" / "adoption" / "README.md"
+
+NPM_PACKAGES = ["aisoc", "@aisoc/mcp", "@aisoc/sdk"]
+PYPI_PACKAGES = [
+ "aisoc-sandbox",
+ "aisoc-cli",
+ "aisoc-sdk",
+ "aisoc-plugin-sdk",
+ "aisoc-detections",
+]
+
+UA = "aisoc-adoption-snapshot"
+
+
+def _get(url: str, token: str | None = None, timeout: int = 25):
+ """Return parsed JSON, or a (None, reason) pair on any failure."""
+ headers = {"User-Agent": UA, "Accept": "application/vnd.github+json"}
+ if token:
+ headers["Authorization"] = f"Bearer {token}"
+ req = urllib.request.Request(url, headers=headers)
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return json.loads(resp.read().decode()), None
+ except urllib.error.HTTPError as exc:
+ return None, f"HTTP {exc.code}"
+ except Exception as exc: # noqa: BLE001 - the reason is the payload
+ return None, f"{type(exc).__name__}"
+
+
+def collect() -> dict:
+ token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+ notes: list[str] = []
+ snap: dict = {
+ "date": dt.date.today().isoformat(),
+ "repo": REPO,
+ "github": {},
+ "npm": {},
+ "pypi": {},
+ "notes": notes,
+ }
+
+ repo, err = _get(f"https://api.github.com/repos/{REPO}", token)
+ if repo:
+ snap["github"].update(
+ stars=repo.get("stargazers_count"),
+ forks=repo.get("forks_count"),
+ watchers=repo.get("subscribers_count"),
+ open_issues=repo.get("open_issues_count"),
+ )
+ else:
+ notes.append(f"repo metadata unavailable ({err})")
+
+ # Traffic needs push access. On a fork or with a read-only token this 403s,
+ # which is a legitimate "could not ask" rather than zero traffic.
+ for kind in ("views", "clones"):
+ data, err = _get(f"https://api.github.com/repos/{REPO}/traffic/{kind}", token)
+ if data:
+ snap["github"][f"{kind}_14d"] = data.get("count")
+ snap["github"][f"unique_{kind}_14d"] = data.get("uniques")
+ else:
+ snap["github"][f"{kind}_14d"] = None
+ snap["github"][f"unique_{kind}_14d"] = None
+ notes.append(f"traffic/{kind} unavailable ({err}; needs push access)")
+
+ contributors, err = _get(
+ f"https://api.github.com/repos/{REPO}/contributors?per_page=100", token
+ )
+ snap["github"]["contributors"] = len(contributors) if contributors else None
+ if contributors is None:
+ notes.append(f"contributors unavailable ({err})")
+
+ releases, err = _get(f"https://api.github.com/repos/{REPO}/releases?per_page=100", token)
+ if releases is not None:
+ snap["github"]["releases"] = len(releases)
+ snap["github"]["release_asset_downloads"] = sum(
+ a.get("download_count", 0) for r in releases for a in r.get("assets", [])
+ )
+ else:
+ snap["github"]["releases"] = None
+ snap["github"]["release_asset_downloads"] = None
+ notes.append(f"releases unavailable ({err})")
+
+ # A 404 means the package does not exist yet, which is a fact about the
+ # project. Anything else means the registry would not answer, which is a
+ # fact about this run. Reporting both as "unavailable" would hide the
+ # difference.
+ def _why(err: str | None) -> str:
+ if err == "HTTP 404":
+ return "not published yet"
+ return f"registry did not answer ({err or 'no data'})"
+
+ for pkg in NPM_PACKAGES:
+ quoted = pkg.replace("/", "%2F")
+ data, err = _get(f"https://api.npmjs.org/downloads/point/last-month/{quoted}")
+ if data and isinstance(data.get("downloads"), int):
+ snap["npm"][pkg] = data["downloads"]
+ else:
+ snap["npm"][pkg] = None
+ notes.append(f"npm {pkg}: {_why(err)}")
+
+ for pkg in PYPI_PACKAGES:
+ data, err = _get(f"https://pypistats.org/api/packages/{pkg}/recent")
+ if data and isinstance(data.get("data"), dict):
+ snap["pypi"][pkg] = data["data"].get("last_month")
+ else:
+ snap["pypi"][pkg] = None
+ notes.append(f"pypi {pkg}: {_why(err)}")
+
+ return snap
+
+
+def render_markdown(history: list[dict]) -> str:
+ latest = history[-1]
+ g = latest["github"]
+
+ def fmt(value) -> str:
+ return "not measured" if value is None else f"{value:,}"
+
+ lines = [
+ "# Adoption snapshot",
+ "",
+ "Collected by `scripts/adoption_snapshot.py`, refreshed monthly by",
+ "`.github/workflows/adoption-snapshot.yml`. Everything here comes from",
+ "public GitHub and registry APIs — the project ships no usage telemetry",
+ "that phones home.",
+ "",
+ "A value of **not measured** means the source could not be read on that",
+ "run. It does not mean zero. The two get conflated constantly and the",
+ "difference matters: one is a fact about users, the other is a fact",
+ "about our tooling.",
+ "",
+ f"## Latest — {latest['date']}",
+ "",
+ "### Reach",
+ "",
+ f"- Stars: {fmt(g.get('stars'))}",
+ f"- Forks: {fmt(g.get('forks'))}",
+ f"- Unique visitors (14d): {fmt(g.get('unique_views_14d'))}",
+ f"- Unique cloners (14d): {fmt(g.get('unique_clones_14d'))}",
+ "",
+ "### Conversion",
+ "",
+ f"- Contributors: {fmt(g.get('contributors'))}",
+ f"- Release asset downloads (all time): {fmt(g.get('release_asset_downloads'))}",
+ "",
+ "### Package downloads (last month)",
+ "",
+ ]
+
+ for pkg, count in latest["npm"].items():
+ lines.append(f"- npm `{pkg}`: {fmt(count)}")
+ for pkg, count in latest["pypi"].items():
+ lines.append(f"- PyPI `{pkg}`: {fmt(count)}")
+
+ if latest.get("notes"):
+ lines += ["", "### Why some values are missing", ""]
+ lines += [f"- {n}" for n in latest["notes"]]
+
+ if len(history) > 1:
+ lines += [
+ "",
+ "## History",
+ "",
+ "| Date | Stars | Unique cloners (14d) | Contributors | npm `aisoc` |",
+ "| --- | --- | --- | --- | --- |",
+ ]
+ for row in history[-12:]:
+ rg = row["github"]
+ lines.append(
+ f"| {row['date']} | {fmt(rg.get('stars'))} | "
+ f"{fmt(rg.get('unique_clones_14d'))} | {fmt(rg.get('contributors'))} | "
+ f"{fmt(row.get('npm', {}).get('aisoc'))} |"
+ )
+
+ lines.append("")
+ return "\n".join(lines)
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--write", action="store_true", help="update the committed snapshot files"
+ )
+ args = parser.parse_args()
+
+ snapshot = collect()
+
+ if not args.write:
+ print(json.dumps(snapshot, indent=2))
+ return 0
+
+ OUT_JSON.parent.mkdir(parents=True, exist_ok=True)
+ history: list[dict] = []
+ if OUT_JSON.exists():
+ try:
+ history = json.loads(OUT_JSON.read_text()).get("history", [])
+ except json.JSONDecodeError:
+ history = []
+
+ # One row per day; re-running the same day replaces rather than duplicates.
+ history = [row for row in history if row.get("date") != snapshot["date"]]
+ history.append(snapshot)
+ history.sort(key=lambda row: row["date"])
+
+ OUT_JSON.write_text(json.dumps({"history": history}, indent=2) + "\n")
+ OUT_MD.write_text(render_markdown(history))
+ print(f"wrote {OUT_JSON} ({len(history)} rows) and {OUT_MD}")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/aisoc-demo.ts b/scripts/aisoc-demo.ts
index 611831380..adf3a6e59 100644
--- a/scripts/aisoc-demo.ts
+++ b/scripts/aisoc-demo.ts
@@ -40,7 +40,14 @@
* 3 = success but exceeded --budget-ms (acceptance regression)
*/
import { execSync, spawnSync } from "node:child_process";
-import { writeFileSync } from "node:fs";
+import {
+ copyFileSync,
+ existsSync,
+ mkdirSync,
+ readdirSync,
+ statSync,
+ writeFileSync,
+} from "node:fs";
import { createConnection, createServer } from "node:net";
import { join } from "node:path";
import { platform } from "node:os";
@@ -943,6 +950,21 @@ function printPhaseTable(report: RunReport): void {
}
function emitReport(flags: Flags, report: RunReport): void {
+ // Always leave a local record of the last run, even without --results-file.
+ //
+ // "The demo didn't work" is the single most common report and the hardest to
+ // act on, because by the time someone opens an issue the stack is gone. This
+ // costs nothing, never leaves the machine, and `pnpm aisoc:doctor --bundle`
+ // picks it up so a bug report carries the phase timings that show where the
+ // boot actually stalled.
+ try {
+ const dir = join(ROOT, ".aisoc");
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(join(dir, "last-demo-run.json"), JSON.stringify(report, null, 2) + "\n");
+ } catch {
+ // A missing run record must never be the reason a demo "fails".
+ }
+
if (!flags.resultsFile) return;
try {
writeFileSync(flags.resultsFile, JSON.stringify(report, null, 2) + "\n");
@@ -956,8 +978,6 @@ function emitReport(flags: Flags, report: RunReport): void {
// ---------- Phase 2 quick-win: visual asset capture ----------
-import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync } from "node:fs";
-
const WEB_DIR = join(ROOT, "apps", "web");
const DEMO_PUBLIC_DIR = join(WEB_DIR, "public", "demo");
const SCREENSHOTS_PUBLIC_DIR = join(WEB_DIR, "public", "screenshots");
diff --git a/scripts/aisoc-doctor.ts b/scripts/aisoc-doctor.ts
index a7de2c66f..bea233954 100644
--- a/scripts/aisoc-doctor.ts
+++ b/scripts/aisoc-doctor.ts
@@ -9,12 +9,17 @@
* 4. Demo data is seeded (alerts > 0)
* 5. WebSocket realtime is reachable
*
- * Usage: pnpm aisoc:doctor
+ * Usage: pnpm aisoc:doctor [--bundle]
+ *
+ * --bundle also write a redacted diagnostics bundle (platform, versions,
+ * check results, container state, redacted log tail, and the
+ * NAMES of the env vars that are set — never their values) that
+ * is safe to attach to a public issue.
*
* Exit code 0 = OK, 1 = at least one FAIL.
*/
import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { createConnection } from "node:net";
import { join } from "node:path";
@@ -379,8 +384,95 @@ async function checkWeb() {
}
}
+// ---------- Diagnostics bundle ----------
+//
+// Most "the demo didn't work" reports arrive with no way to tell which of the
+// dozen moving parts failed, and the obvious fix — "paste your logs" — invites
+// people to paste credentials into a public issue. `--bundle` collects the
+// same evidence a maintainer would ask for, with secrets stripped, into one
+// file that is safe to attach.
+
+/** Mask anything that looks like a credential, wherever it appears. */
+function redact(text: string): string {
+ return (
+ text
+ // KEY=value / "key": "value" for any key whose name smells sensitive.
+ .replace(
+ /((?:secret|token|password|passwd|api[_-]?key|access[_-]?key|private[_-]?key|credential|authorization|bearer)\w*\s*[=:]\s*")([^"]+)(")/gi,
+ "$1<redacted>$3"
+ )
+ .replace(
+ /((?:SECRET|TOKEN|PASSWORD|PASSWD|API[_-]?KEY|ACCESS[_-]?KEY|PRIVATE[_-]?KEY|CREDENTIAL)\w*\s*=\s*)(\S+)/gi,
+ "$1<redacted>"
+ )
+ // Vendor key shapes that carry no key name next to them.
+ .replace(/\b(sk-[A-Za-z0-9_-]{16,})\b/g, "<redacted-openai-key>")
+ .replace(/\b(xox[abprs]-[A-Za-z0-9-]{10,})\b/g, "<redacted-slack-token>")
+ .replace(/\b(gh[pousr]_[A-Za-z0-9]{20,})\b/g, "<redacted-github-token>")
+ .replace(/\b(AKIA[0-9A-Z]{16})\b/g, "<redacted-aws-key-id>")
+ .replace(/\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, "<redacted-jwt>")
+ // Connection strings: keep the shape, drop the password.
+ .replace(/(:\/\/[^:/@\s]+:)([^@\s]+)(@)/g, "$1<redacted>$3")
+ );
+}
+
+function writeBundle(): string {
+ const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+ const path = join(ROOT, `aisoc-doctor-bundle-${stamp}.json`);
+
+ // Env var NAMES only — never values. Knowing which keys are set is the
+ // diagnostic signal; the values are exactly what must not leave the machine.
+ let envKeys: string[] = [];
+ const envPath = join(ROOT, ".env");
+ if (existsSync(envPath)) {
+ envKeys = readFileSync(envPath, "utf8")
+ .split("\n")
+ .map((line) => line.trim())
+ .filter((line) => line && !line.startsWith("#") && line.includes("="))
+ .map((line) => line.split("=")[0]);
+ }
+
+ const bundle = {
+ generatedAt: new Date().toISOString(),
+ note:
+ "Generated by `pnpm aisoc:doctor --bundle`. Values of environment " +
+ "variables are never included; only their names. Logs are passed " +
+ "through a credential redactor. Review before sharing.",
+ platform: {
+ os: process.platform,
+ arch: process.arch,
+ node: process.version,
+ pnpm: tryRun("pnpm --version"),
+ docker: tryRun("docker --version"),
+ compose: tryRun("docker compose version --short"),
+ },
+ repo: {
+ commit: tryRun("git rev-parse --short HEAD"),
+ branch: tryRun("git rev-parse --abbrev-ref HEAD"),
+ dirty: tryRun("git status --porcelain") ? true : false,
+ version: existsSync(join(ROOT, "VERSION"))
+ ? readFileSync(join(ROOT, "VERSION"), "utf8").trim()
+ : null,
+ },
+ checks,
+ envKeysPresent: envKeys,
+ // Written by `pnpm aisoc:demo` on every run. Phase timings are usually
+ // enough on their own to show where a failed boot actually stalled.
+ lastDemoRun: existsSync(join(ROOT, ".aisoc", "last-demo-run.json"))
+ ? JSON.parse(readFileSync(join(ROOT, ".aisoc", "last-demo-run.json"), "utf8"))
+ : null,
+ containers: redact(tryRun("docker compose ps --format json") ?? ""),
+ logsTail: redact(tryRun("docker compose logs --tail 200 --no-color") ?? ""),
+ };
+
+ writeFileSync(path, JSON.stringify(bundle, null, 2));
+ return path;
+}
+
// ---------- Run ----------
async function main() {
+ const wantBundle = process.argv.includes("--bundle");
+
console.log(c.bold("AiSOC Doctor") + c.dim(" — pre-flight check"));
await checkEnv();
await checkDocker();
@@ -388,6 +480,15 @@ async function main() {
await checkApi();
await checkWeb();
+ if (wantBundle) {
+ const path = writeBundle();
+ console.log(c.bold("\nDiagnostics bundle"));
+ console.log(` ${path}`);
+ console.log(
+ c.dim(" Env var values excluded, logs redacted. Skim it, then attach it to your issue.")
+ );
+ }
+
// Summary
const fails = checks.filter((c) => c.status === "FAIL").length;
const warns = checks.filter((c) => c.status === "WARN").length;