@sagentix-inc/evidence-collector 0.3.5 → 0.4.1

package/collector/src/doctor.js

@@ -0,0 +1,382 @@
+// `collector doctor`: a smoke test a customer runs before the first real run (2026-11-07). For each configured source it
+// checks the credentials are there and makes ONE cheap read per permission the source needs, then prints pass or fail
+// with the fix: the exact scope, role or permission named in that source's own header (its provider-docs citations).
+// It collects nothing and sends nothing: no check-in, no push, no run report. File-based sources check their files are
+// readable; engines check their executable is on PATH without running it; the host sources check the platform.
+//
+// Every read below is one the source itself makes (same path, with a page size of 1 where the API takes one), so a
+// pass here means the same call will be allowed during a run. GET only, except GCP's :getIamPolicy, a read the GCP
+// source makes as a POST.
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import { isObj, realSleep, why, withRetry } from "./sources/readonly_http.js";
+import { oktaFromEnv, OKTA_ENV } from "./sources/okta.js";
+import { entraFromEnv, ENTRA_ENV } from "./sources/entra.js";
+import { jumpcloudFromEnv, JUMPCLOUD_ENV } from "./sources/jumpcloud.js";
+import { GOOGLE_ENV, googleFromEnv } from "./sources/google_workspace.js";
+import { OAUTH_ENV } from "./sources/google_oauth.js";
+import { githubFromEnv, GITHUB_TOKEN_ENV } from "./sources/github.js";
+import { vercelFromEnv, VERCEL_TOKEN_ENV } from "./sources/vercel.js";
+import { pagerdutyFromEnv, PAGERDUTY_ENV } from "./sources/pagerduty.js";
+import { stripeFromEnv, STRIPE_ENV } from "./sources/stripe.js";
+import { resendFromEnv, RESEND_ENV } from "./sources/resend.js";
+import { fleetFromEnv, FLEET_ENV } from "./sources/fleet.js";
+import { intuneFromEnv, INTUNE_ENV } from "./sources/intune.js";
+import { jamfFromEnv, JAMF_ENV, inventoryPath, VERSIONS as JAMF_VERSIONS } from "./sources/jamf.js";
+import { kandjiFromEnv, KANDJI_ENV } from "./sources/kandji.js";
+import { defenderFromEnv, DEFENDER_ENV } from "./sources/defender_endpoint.js";
+import { ws1FromEnv, WS1_ENV } from "./sources/workspace_one.js";
+import { configmgrFromEnv, CONFIGMGR_ENV } from "./sources/configmgr.js";
+import { googleDevicesFromEnv } from "./sources/google_endpoints.js";
+import { ivantiMdmFromEnv, IVANTI_MDM_ENV, metadataPath } from "./sources/ivanti_mdm.js";
+import { ninjaoneFromEnv, NINJAONE_ENV } from "./sources/ninjaone.js";
+import { endpointCentralFromEnv, EC_ENV, SCAN_PATH } from "./sources/endpoint_central.js";
+import { bamboohrFromEnv, BAMBOOHR_ENV, employeesPath } from "./sources/bamboohr.js";
+import { ripplingFromEnv, RIPPLING_ENV } from "./sources/rippling.js";
+import { fetchCloudflareApi, TOKEN_ENV as CF_TOKEN_ENV } from "./sources/cloudflare/api.js";
+import { Aws, callerAccount, envCredentials, fetchAwsTransport, queryReq, awsWhy } from "./sources/aws/api.js";
+import { API as AZURE_API, ARM, armGet, fetchAzure, tokenFromEnv as azureToken } from "./sources/azure/api.js";
+import { Gcp, GCP_KEY_ENV, GCP_TOKEN_ENV, fetchGcpTransport, gcpKeyToken } from "./sources/gcp/api.js";
+import { fetchJira, JIRA_ENV } from "./sources/jira.js";
+const one = (v) => (typeof v === "string" ? v : Array.isArray(v) ? v[0] : undefined);
+const many = (v) => (Array.isArray(v) ? v : typeof v === "string" ? [v] : []).flatMap((s) => s.split(",")).map((s) => s.trim()).filter(Boolean);
+const sleepOf = (ctx) => ctx.clients.sleep ?? realSleep;
+/** The verdict on one answer to `call`: the fix names `permission` on a 403, `creds` on a 401. `label` names the
+ *  permission shortly for the pass line. */
+export function judge(label, call, r, creds, permission) {
+    const what = call;
+    if (r.status >= 200 && r.status < 300)
+        return { what, verdict: "pass", detail: `HTTP ${r.status} (needs ${label})` };
+    const detail = r.message;
+    if (r.status === 401)
+        return { what, verdict: "fail", detail, fix: `the credential was refused: check ${creds} (expired, revoked, or for another tenant)` };
+    if (r.status === 403)
+        return { what, verdict: "fail", detail, fix: `grant ${permission}` };
+    if (r.status === 404)
+        return { what, verdict: "fail", detail, fix: `not found: check the organization, team, project or URL given (or the feature is not on this plan); needs ${permission}` };
+    if (r.status === 429)
+        return { what, verdict: "fail", detail, fix: "rate limited even after retries: run the doctor again in a few minutes" };
+    if (r.status === 0)
+        return { what, verdict: "fail", detail, fix: "no answer: check the network path from this runner (proxy, firewall, DNS) and the URL in the credentials" };
+    return { what, verdict: "fail", detail, fix: `the provider answered HTTP ${r.status}; try again later, then check its status page` };
+}
+const credsCheck = (ok, creds, why) => ok ? { what: "credentials", verdict: "pass", detail: `${creds}: present` }
+    : { what: "credentials", verdict: "fail", detail: why ?? `${creds}: not set`, fix: `set ${creds} (in the vault, the CI secrets or the environment)` };
+/** A REST source: the client the source builds (or the one injected), then one GET per [path, permission]. */
+function rest(o) {
+    return async (ctx) => {
+        const given = ctx.clients[o.key];
+        const built = given !== undefined ? (given ?? "no client") : o.build(ctx);
+        if (typeof built === "string")
+            return [credsCheck(false, o.creds, built)];
+        const api = withRetry(built, sleepOf(ctx));
+        const out = [credsCheck(true, o.creds)];
+        for (const [path, permission] of o.calls(ctx)) {
+            let r;
+            try {
+                r = await api.get(path);
+            }
+            catch (e) {
+                r = { status: 0, headers: {}, body: { message: String(e) } };
+            }
+            out.push(judge(permission, `GET ${path.split("?")[0]}`, { status: r.status, message: why(r) }, o.creds, permission));
+            // A refused credential refuses every call: one line says it.
+            if (r.status === 401)
+                break;
+        }
+        return out;
+    };
+}
+/** Each named file is there and readable. `need` lists options of which one must be given. */
+function files(need, optional = []) {
+    return async (ctx) => {
+        const out = [];
+        const given = need.filter((k) => many(ctx.opts[k]).length);
+        if (!given.length)
+            out.push({ what: "input", verdict: "fail", detail: `no --${need.join(" or --")} given`, fix: `give --${need[0]} <file> (in the config file or on the command line)` });
+        for (const k of [...given, ...optional.filter((x) => many(ctx.opts[x]).length)]) {
+            for (const p of many(ctx.opts[k])) {
+                try {
+                    accessSync(p, constants.R_OK);
+                    const st = statSync(p);
+                    out.push({ what: `--${k}`, verdict: "pass", detail: `${p}: readable, ${st.isDirectory() ? "a folder" : `${st.size} bytes`}, modified ${st.mtime.toISOString().slice(0, 10)}` });
+                }
+                catch (e) {
+                    out.push({ what: `--${k}`, verdict: "fail", detail: `${p}: ${e.code ?? String(e)}`, fix: "produce the file before the collector runs (the engine's step in the workflow), or fix the path" });
+                }
+            }
+        }
+        return out;
+    };
+}
+/** Whether an executable is on PATH (or at the path given), found without running it. */
+export function onPath(bin, env, platform = process.platform) {
+    const exts = platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+    const candidates = isAbsolute(bin) || bin.includes("/") ? [bin] : (env.PATH ?? "").split(delimiter).filter(Boolean).map((d) => join(d, bin));
+    for (const c of candidates)
+        for (const x of exts) {
+            try {
+                accessSync(c + x, constants.X_OK);
+                if (statSync(c + x).isFile())
+                    return c + x;
+            }
+            catch { /* next */ }
+        }
+    return undefined;
+}
+const binCheck = (bin, env, install) => {
+    const at = onPath(bin, env);
+    return at ? { what: "executable", verdict: "pass", detail: `${bin}: ${at}` } : { what: "executable", verdict: "fail", detail: `${bin}: not on PATH`, fix: install };
+};
+const graphCreds = (pre) => `${pre.tenant}, ${pre.client} and ${pre.secret} or ${pre.cert} (or their ENTRA_* twins)`;
+const ENTRA_CREDS = `${ENTRA_ENV.tenant}, ${ENTRA_ENV.client} and ${ENTRA_ENV.secret} or ${ENTRA_ENV.cert}`;
+const GOOGLE_CREDS = `${GOOGLE_ENV.keyFile} and ${GOOGLE_ENV.admin} (service account with domain-wide delegation), or ${OAUTH_ENV.clientFile} after \`collector google-login\``;
+const googleCustomer = (env) => env[GOOGLE_ENV.customer] || "my_customer";
+export const PROBES = {
+    // ── Identity and code ────────────────────────────────────────────────────────────────────────────
+    okta: rest({ key: "okta", creds: `${OKTA_ENV.domain} with ${OKTA_ENV.token} (a Read-Only Administrator's token) or ${OKTA_ENV.access}`, build: (c) => oktaFromEnv(c.env),
+        calls: () => [["/api/v1/policies?type=PASSWORD", "okta.policies.read"], ["/api/v1/authenticators", "okta.authenticators.read (Identity Engine)"],
+            ["/api/v1/iam/assignees/users?limit=1", "okta.roles.read"], ["/api/v1/users?limit=1", "okta.users.read"], ["/api/v1/logs?limit=1", "okta.logs.read"]] }),
+    entra: rest({ key: "entra", creds: ENTRA_CREDS, build: (c) => entraFromEnv(c.env),
+        calls: () => [["/policies/authorizationPolicy", "the application permission Policy.Read.All"],
+            ["/identity/conditionalAccess/policies?$top=1", "the application permission Policy.Read.All (Conditional Access needs Entra ID P1)"],
+            ["/roleManagement/directory/roleAssignments?$top=1", "the application permission RoleManagement.Read.Directory"],
+            ["/users?$top=1&$select=id", "the application permission User.Read.All"],
+            ["/auditLogs/directoryAudits?$top=1", "the application permission AuditLog.Read.All"],
+            ["/reports/authenticationMethods/userRegistrationDetails?$top=1", "the application permission AuditLog.Read.All (the report needs Entra ID P1 or P2)"],
+            ["/subscribedSkus", "the application permission LicenseAssignment.Read.All"]] }),
+    jumpcloud: rest({ key: "jumpcloud", creds: `${JUMPCLOUD_ENV.key} (an administrator with the Read Only role)`,
+        build: (c) => jumpcloudFromEnv(c.env, { region: one(c.opts["jumpcloud-region"]), orgId: one(c.opts["jumpcloud-org-id"]) }),
+        calls: () => [["/organizations?limit=1", "the API key scope organizations.readonly"], ["/systemusers?limit=1&skip=0", "the API key scope users.readonly"],
+            ["/v2/authn/policies?limit=1&skip=0", "the API key scope authn.readonly"], ["/systems?limit=1&skip=0", "the API key scope systems.readonly"]] }),
+    google_workspace: rest({ key: "google", creds: GOOGLE_CREDS, build: (c) => googleFromEnv(c.env),
+        calls: (c) => [[`/admin/directory/v1/users?customer=${encodeURIComponent(googleCustomer(c.env))}&maxResults=1&projection=basic`, "the scope https://www.googleapis.com/auth/admin.directory.user.readonly in domain-wide delegation"],
+            ["/admin/reports/v1/activity/users/all/applications/admin?maxResults=1", "the scope https://www.googleapis.com/auth/admin.reports.audit.readonly in domain-wide delegation"]] }),
+    github: rest({ key: "github", creds: `${GITHUB_TOKEN_ENV} (a fine-grained token, read-only)`, build: (c) => githubFromEnv(c.env),
+        calls: (c) => {
+            const org = one(c.opts["github-org"]);
+            if (!org)
+                return [["/rate_limit", "no permission (the token is only checked; give --github-org to check the organization's)"]];
+            const o = encodeURIComponent(org);
+            return [[`/orgs/${o}`, "membership of the organization"], [`/orgs/${o}/members?role=admin&per_page=1`, "the fine-grained permission Organization: Members (read)"],
+                [`/orgs/${o}/actions/permissions`, "the fine-grained permission Organization: Administration (read)"],
+                [`/orgs/${o}/repos?type=all&per_page=1`, "the fine-grained permission Repository: Metadata (read), on all repositories"]];
+        } }),
+    vercel: rest({ key: "vercel", creds: VERCEL_TOKEN_ENV, build: (c) => vercelFromEnv(c.env),
+        calls: (c) => {
+            const team = one(c.opts["vercel-team"]);
+            const tq = team ? `teamId=${encodeURIComponent(team)}` : "";
+            return [...(team ? [[`/v2/teams/${encodeURIComponent(team)}`, "a token scoped to the team, from a member who can read its settings"]] : []),
+                [`/v10/projects?limit=1${tq ? `&${tq}` : ""}`, "a token scoped to the team (or account) that owns the projects"]];
+        } }),
+    pagerduty: rest({ key: "pagerduty", creds: `${PAGERDUTY_ENV.token} (a read-only API key)`, build: (c) => pagerdutyFromEnv(c.env),
+        calls: () => [["/services?limit=1", "services.read"], ["/incidents?limit=1", "incidents.read"], ["/escalation_policies?limit=1", "escalation_policies.read"],
+            ["/incident_workflows?limit=1", "incident_workflows.read"]] }),
+    stripe: rest({ key: "stripe", creds: `${STRIPE_ENV.token} (a restricted key, rk_...)`, build: (c) => stripeFromEnv(c.env),
+        calls: () => [["/v1/webhook_endpoints?limit=1", "the restricted key permission Webhook Endpoints: Read"]] }),
+    resend: rest({ key: "resend", creds: RESEND_ENV.token, build: (c) => resendFromEnv(c.env),
+        calls: () => [["/domains?limit=1", "a key with full_access (Resend has no read-only key)"], ["/api-keys?limit=1", "a key with full_access (Resend has no read-only key)"]] }),
+    // ── HR ───────────────────────────────────────────────────────────────────────────────────────────
+    bamboohr: rest({ key: "bamboohr", creds: `${BAMBOOHR_ENV.key} and --bamboohr-company`, build: (c) => bamboohrFromEnv(c.env, one(c.opts["bamboohr-company"])),
+        calls: () => [[employeesPath("active", ["status"]).replace(/page%5Blimit%5D=\d+/, "page%5Blimit%5D=1"), "an API key of a user allowed to see employees' status (BambooHR access level)"]] }),
+    rippling: rest({ key: "rippling", creds: RIPPLING_ENV.token, build: (c) => ripplingFromEnv(c.env),
+        calls: () => [["/workers/?limit=1", "the token scope to read workers (workers:read)"]] }),
+    // ── Devices ──────────────────────────────────────────────────────────────────────────────────────
+    fleet: rest({ key: "fleet", creds: `${FLEET_ENV.url} and ${FLEET_ENV.token} (an API-only user with the global Observer role)`, build: (c) => fleetFromEnv(c.env),
+        calls: () => [["/hosts?page=0&per_page=1&order_key=id&order_direction=asc&populate_policies=true", "the global Observer role"]] }),
+    intune: rest({ key: "intune", creds: graphCreds(INTUNE_ENV), build: (c) => intuneFromEnv(c.env),
+        calls: () => [["/deviceManagement/managedDevices?$top=1&$select=id", "the application permission DeviceManagementManagedDevices.Read.All"],
+            ["/deviceManagement/deviceCompliancePolicies?$top=1", "the application permission DeviceManagementConfiguration.Read.All"]] }),
+    jamf: rest({ key: "jamf", creds: `${JAMF_ENV.url}, ${JAMF_ENV.client} and ${JAMF_ENV.secret} (an API client)`, build: (c) => jamfFromEnv(c.env),
+        calls: () => [[inventoryPath(JAMF_VERSIONS[0], 0).replace(/page-size=\d+/, "page-size=1"), "the API role privilege Read Computers"],
+            ["/v2/mdm/commands?page=0&page-size=1", "the API role privilege View MDM command information in Jamf Pro API"]] }),
+    kandji: rest({ key: "kandji", creds: `${KANDJI_ENV.url} and ${KANDJI_ENV.token}`, build: (c) => kandjiFromEnv(c.env),
+        calls: () => [["/v1/devices?platform=Mac&limit=1&offset=0", "the token permission List Devices"],
+            ["/v1/prism/application_firewall?device_families=Mac&limit=1&cursor=", "the token permission Prism: Application firewall"]] }),
+    defender_endpoint: rest({ key: "defender_endpoint", creds: graphCreds(DEFENDER_ENV), build: (c) => defenderFromEnv(c.env),
+        calls: () => [["/api/machines?$top=1", "the WindowsDefenderATP application permission Machine.Read.All"],
+            ["/api/vulnerabilities/machinesVulnerabilities?$top=1", "the WindowsDefenderATP application permission Vulnerability.Read.All"],
+            ["/api/recommendations?$top=1", "the WindowsDefenderATP application permission SecurityRecommendation.Read.All"]] }),
+    workspace_one: async (ctx) => {
+        const given = ctx.clients.workspace_one;
+        const b = given !== undefined ? (given === null ? "no client" : "get" in given ? given : given.v3) : ((w) => (typeof w === "string" ? w : w.v3))(ws1FromEnv(ctx.env));
+        return rest({ key: "\0", creds: `${WS1_ENV.url}, ${WS1_ENV.tokenUrl}, ${WS1_ENV.client} and ${WS1_ENV.secret} (an OAuth client)`, build: () => b,
+            calls: () => [["/mdm/devices/search?page=0&page_size=1", "the role permission REST > Devices > REST API Devices Read"]] })(ctx);
+    },
+    configmgr: rest({ key: "configmgr", creds: `${CONFIGMGR_ENV.provider} (run on a domain-joined Windows host as a Read-only Analyst)`, build: (c) => configmgrFromEnv(c.env),
+        calls: () => [["/SMS_CombinedDeviceResources?$top=1", "the Configuration Manager security role Read-only Analyst"]] }),
+    google_endpoints: rest({ key: "google_endpoints", creds: `${GOOGLE_ENV.keyFile} and ${GOOGLE_ENV.admin} (service account with domain-wide delegation)`, build: (c) => googleDevicesFromEnv(c.env),
+        calls: (c) => [[`/v1/devices?customer=${encodeURIComponent(`customers/${googleCustomer(c.env)}`)}&pageSize=1&view=USER_ASSIGNED_DEVICES`, "the scope https://www.googleapis.com/auth/cloud-identity.devices.readonly in domain-wide delegation"]] }),
+    ivanti_mdm: rest({ key: "ivanti_mdm", creds: `${IVANTI_MDM_ENV.url}, ${IVANTI_MDM_ENV.user} and ${IVANTI_MDM_ENV.password} (an admin with the Device Read Only role)`, build: (c) => ivantiMdmFromEnv(c.env),
+        calls: () => [[metadataPath, "the admin role Device Read Only (API access enabled for the user)"]] }),
+    ninjaone: rest({ key: "ninjaone", creds: `${NINJAONE_ENV.url}, ${NINJAONE_ENV.client} and ${NINJAONE_ENV.secret} (an API Services client app)`, build: (c) => ninjaoneFromEnv(c.env),
+        calls: () => [["/v2/devices?pageSize=1", "the client app scope Monitoring"], ["/v2/queries/operating-systems?pageSize=1", "the client app scope Monitoring"]] }),
+    endpoint_central: rest({ key: "endpoint_central", creds: `${EC_ENV.url}, ${EC_ENV.client}, ${EC_ENV.secret} and ${EC_ENV.refresh} (a Zoho self client)`, build: (c) => endpointCentralFromEnv(c.env),
+        calls: () => [[SCAN_PATH, "the scope DesktopCentralCloud.Inventory.READ and a role with Inventory read access"],
+            ["/dcapi/patch/reports/systemHealth?page=1&pageLimit=1", "the scope DesktopCentralCloud.PatchMgmt.READ and a role with Patch Management read access"]] }),
+    // ── Clouds and ticketing ─────────────────────────────────────────────────────────────────────────
+    cloudflare: async (ctx) => {
+        const token = ctx.env[CF_TOKEN_ENV];
+        const given = ctx.clients.cloudflare;
+        const api = given !== undefined ? given : token ? fetchCloudflareApi(token, fetch, undefined, sleepOf(ctx)) : null;
+        if (!api)
+            return [credsCheck(false, CF_TOKEN_ENV)];
+        const out = [credsCheck(true, CF_TOKEN_ENV)];
+        const get = async (path, permission) => {
+            let r;
+            try {
+                r = await api.get(path);
+            }
+            catch (e) {
+                r = { status: 0, body: { errors: [{ message: String(e) }] } };
+            }
+            const errs = isObj(r.body) && Array.isArray(r.body.errors) ? r.body.errors.map((e) => (isObj(e) ? String(e.message ?? "") : "")).filter(Boolean).join("; ") : "";
+            out.push(judge(permission, `GET ${path.split("?")[0]}`, { status: r.status, message: `HTTP ${r.status}${errs ? `: ${errs.slice(0, 200)}` : ""}` }, CF_TOKEN_ENV, permission));
+        };
+        for (const z of many(ctx.opts.zone).slice(0, 1))
+            await get(`/zones/${encodeURIComponent(z)}`, "the token permission Zone: Zone Read");
+        if (!many(ctx.opts.zone).length)
+            await get("/zones?per_page=5&page=1", "the token permission Zone: Zone Read");
+        for (const a of many(ctx.opts.account))
+            await get(`/accounts/${encodeURIComponent(a)}/members?per_page=5&page=1`, "the token permission Account: Account Settings Read");
+        return out;
+    },
+    aws: async (ctx) => {
+        const region = many(ctx.opts["aws-regions"])[0] || ctx.env.AWS_REGION || ctx.env.AWS_DEFAULT_REGION || "us-east-1";
+        const creds = "AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or AWS_ROLE_ARN with AWS_WEB_IDENTITY_TOKEN_FILE";
+        let t = ctx.clients.aws;
+        if (t === null)
+            return [credsCheck(false, creds)];
+        if (t === undefined) {
+            const c = await envCredentials(ctx.env, region);
+            if (!c)
+                return [credsCheck(false, creds)];
+            if ("error" in c)
+                return [credsCheck(false, creds, c.error)];
+            t = fetchAwsTransport(c);
+        }
+        const api = new Aws(t);
+        const out = [];
+        const who = await callerAccount(api, region);
+        if ("error" in who)
+            return [{ what: "credentials", verdict: "fail", detail: `sts:GetCallerIdentity: ${who.error}`, fix: `check ${creds} (expired session or wrong account)` }];
+        out.push({ what: "credentials", verdict: "pass", detail: `sts:GetCallerIdentity: account ${who.account}` });
+        const r = await api.send(queryReq("iam", "us-east-1", "GetAccountSummary", "2010-05-08"));
+        out.push(judge("iam:GetAccountSummary", "iam GetAccountSummary", { status: r.status, message: awsWhy(r) }, creds, "the AWS managed policy SecurityAudit (or iam:GetAccountSummary) to the role"));
+        return out;
+    },
+    azure: async (ctx) => {
+        const creds = "AZURE_ACCESS_TOKEN, or AZURE_TENANT_ID and AZURE_CLIENT_ID with AZURE_FEDERATED_TOKEN_FILE or AZURE_CLIENT_SECRET";
+        const given = ctx.clients.azure;
+        const t = given !== undefined ? given : ((tok) => (tok ? fetchAzure(tok) : null))(azureToken(ctx.env));
+        if (!t)
+            return [credsCheck(false, creds)];
+        const out = [credsCheck(true, creds)];
+        const subs = many(ctx.opts["azure-subscription"]);
+        for (const url of subs.length ? subs.map((s) => `${ARM}/subscriptions/${encodeURIComponent(s)}?api-version=${AZURE_API.subscriptions}`) : [`${ARM}/subscriptions?api-version=${AZURE_API.subscriptions}`]) {
+            const r = await armGet(t, url);
+            out.push(judge("Reader", `GET ${new URL(url).pathname}`, { status: r.status, message: `HTTP ${r.status}` }, creds, "the Reader role (and Security Reader) on the subscription to the app"));
+        }
+        return out;
+    },
+    gcp: async (ctx) => {
+        const creds = `${GCP_TOKEN_ENV}, or ${GCP_KEY_ENV}`;
+        const token = ctx.env[GCP_TOKEN_ENV];
+        const keyed = token ? undefined : gcpKeyToken(ctx.env);
+        const t = ctx.clients.gcp !== undefined ? ctx.clients.gcp : token ? fetchGcpTransport(token) : typeof keyed === "function" ? fetchGcpTransport(keyed) : null;
+        if (!t)
+            return [credsCheck(false, creds, typeof keyed === "string" ? keyed : undefined)];
+        const projects = many(ctx.opts["gcp-project"]);
+        const out = [credsCheck(true, creds)];
+        if (!projects.length)
+            out.push({ what: "input", verdict: "fail", detail: "no --gcp-project given", fix: "give --gcp-project <id>" });
+        const api = new Gcp(t);
+        for (const p of projects) {
+            const r = await api.call("POST", `https://cloudresourcemanager.googleapis.com/v1/projects/${encodeURIComponent(p)}:getIamPolicy`, { options: { requestedPolicyVersion: 3 } });
+            out.push(judge("roles/iam.securityReviewer", `POST projects/${p}:getIamPolicy`, { status: r.status, message: `HTTP ${r.status}` }, creds, "roles/iam.securityReviewer and roles/viewer on the project to the service account"));
+        }
+        return out;
+    },
+    jira: async (ctx) => {
+        const creds = `${JIRA_ENV.base}, ${JIRA_ENV.email} and ${JIRA_ENV.token}`;
+        let t = ctx.clients.jira;
+        if (t === null)
+            return [credsCheck(false, creds)];
+        if (t === undefined) {
+            const base = ctx.env[JIRA_ENV.base], email = ctx.env[JIRA_ENV.email], token = ctx.env[JIRA_ENV.token];
+            if (!base || !email || !token)
+                return [credsCheck(false, creds)];
+            try {
+                t = fetchJira(base, email, token);
+            }
+            catch (e) {
+                return [credsCheck(false, creds, e.message)];
+            }
+        }
+        const out = [credsCheck(true, creds)];
+        const jql = Object.entries(ctx.opts).find(([k, v]) => k.startsWith("jira-") && k.endsWith("-jql") && typeof v === "string")?.[1];
+        const path = `/rest/api/3/search/jql?jql=${encodeURIComponent(jql ?? "order by created DESC")}&maxResults=1&fields=key`;
+        const r = await t.get(path);
+        out.push(judge("Browse projects", "GET /rest/api/3/search/jql", { status: r.status, message: `HTTP ${r.status}` }, creds, "the project permission Browse projects on the projects the JQL names"));
+        return out;
+    },
+    // ── Files, engines and hosts ─────────────────────────────────────────────────────────────────────
+    lms: files(["training-csv"], ["roster-csv"]),
+    scubagoggles: files(["scubagoggles-results"]),
+    scubagear: files(["scubagear-results"]),
+    trivy: files(["trivy-report"]),
+    grype: files(["grype-report"]),
+    syft: files(["sbom-file"]),
+    gitleaks: files(["gitleaks-report"]),
+    scorecard: files(["scorecard-result"]),
+    kubescape: files(["kubescape-report"]),
+    checkov: files(["checkov-report"]),
+    vulnscan: files(["vulnscan-report"], ["vulnscan-inventory"]),
+    prowler: async (ctx) => {
+        const providers = many(ctx.opts["prowler-provider"]);
+        const out = [providers.length ? { what: "input", verdict: "pass", detail: `providers ${providers.join(", ")}` }
+                : { what: "input", verdict: "fail", detail: "no --prowler-provider given", fix: "give --prowler-provider aws (or azure, gcp, kubernetes, m365, github, googleworkspace, okta, cloudflare)" }];
+        if (one(ctx.opts["prowler-output"]))
+            return [...out, ...await files(["prowler-output"])(ctx)];
+        if (ctx.clients.prowler)
+            return [...out, { what: "executable", verdict: "pass", detail: "a test runner stands in for prowler" }];
+        return [...out, binCheck(one(ctx.opts["prowler-bin"]) ?? "prowler", ctx.env, "install Prowler (pip install prowler, or the runner image) or pass --prowler-bin; the provider's own credentials are checked by Prowler itself")];
+    },
+    stig: async (ctx) => {
+        if (one(ctx.opts["cinc-report"]) || one(ctx.opts["stig-input-file"]))
+            return files(["cinc-report", "stig-input-file"])(ctx);
+        const out = [];
+        if (!many(ctx.opts["stig-target"]).length)
+            out.push({ what: "input", verdict: "fail", detail: "no --stig-target or --cinc-report given", fix: "give --stig-target ssh://user@host with --stig-profile, or --cinc-report <file>" });
+        if (ctx.clients.cinc)
+            out.push({ what: "executable", verdict: "pass", detail: "a test runner stands in for cinc-auditor" });
+        else
+            out.push(binCheck(one(ctx.opts["cinc-bin"]) ?? "cinc-auditor", ctx.env, "install Cinc Auditor (or use the runner image), or pass --cinc-bin"));
+        return out;
+    },
+    macos: async (ctx) => [ctx.clients.macos || process.platform === "darwin"
+            ? { what: "platform", verdict: "pass", detail: "macOS: this Mac's own settings are read with its own tools" }
+            : { what: "platform", verdict: "fail", detail: `this computer runs ${process.platform}`, fix: "run the macos source on the Mac to check (a LaunchAgent from sos-app's setup)" }],
+    windows: async (ctx) => [ctx.clients.windows || process.platform === "win32"
+            ? { what: "platform", verdict: "pass", detail: "Windows: this PC's own settings are read with PowerShell" }
+            : { what: "platform", verdict: "fail", detail: `this computer runs ${process.platform}`, fix: "run the windows source on the PC to check (a scheduled task from sos-app's setup)" }],
+    web: async (ctx) => {
+        const urls = many(ctx.opts["web-url"]), proofs = new Set(many(ctx.opts["web-proof"]).map((p) => p.split("=")[0].toLowerCase()));
+        if (!urls.length && !many(ctx.opts["web-privacy-url"]).length)
+            return [{ what: "input", verdict: "fail", detail: "no --web-url given", fix: "give --web-url https://<host>/ with --web-proof <host>=<token> from sos-app" }];
+        return urls.map((u) => {
+            let host = "";
+            try {
+                host = new URL(u).hostname.toLowerCase();
+            }
+            catch {
+                return { what: "--web-url", verdict: "fail", detail: `${u}: not a URL`, fix: "give an https URL" };
+            }
+            if (proofs.has(host) || ctx.opts["web-skip-proof"] === true)
+                return { what: "--web-url", verdict: "pass", detail: `${host}: proof token given (checked against DNS or the well-known file during the run)` };
+            return { what: "--web-url", verdict: "fail", detail: `${host}: no --web-proof`, fix: `give --web-proof ${host}=<the token sos-app issued for this host>` };
+        });
+    },
+};
+/** The fix for a source's refused call, for the run's own messages (cli.ts): "check it with collector doctor". */
+export const doctorHint = (source) => `run \`collector doctor --config <file> --source ${source}\` to see which permission is missing`;

package/collector/src/policies.js

@@ -0,0 +1,160 @@
+// THE ORGANIZATION'S POLICIES, PUSHED FROM WHERE IT KEEPS THEM (Stéphane, 2026-11-05: "the collector would point to the
+// location where the policies are stored - then the collector push them to the app - and the app match them
+// automatically to the proper security controls").
+//
+//   collector policies --config collector.config.json      reads the config's "policies" block
+//
+// Each PDF, Word or text file in the folders goes to sos-app's signed document door (POST /api/collect/document,
+// apps/sos-app/src/routes/documents.ts) with target {policy: "auto"}: sos-app reads its title and text, matches it to a
+// NIST SP 800-53 control family and files it as that family's draft policy for a person to approve, or says why not.
+// Signed with a 'documents' key, never the collector key, so a collector key in CI never files documents. Files are only
+// read; sending the same bytes again files nothing (sos-app answers "duplicate"). Nothing is deleted or moved.
+import { createHash } from "node:crypto";
+import { constants as fsConstants, copyFileSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import { signBody } from "./keys.js";
+export const DOCUMENTS_KEY_ENV = "SAGENTIX_DOCUMENTS_KEY";
+export const DOCUMENT_PATH = "/api/collect/document";
+export const POLICY_TYPES = {
+    ".pdf": "application/pdf",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".txt": "text/plain", ".md": "text/plain",
+};
+const MAX_BYTES = 10 * 1024 * 1024;
+/** One file per policy when the same name comes in several formats (POL-06.pdf, .docx, .md): the PDF first, the document
+ *  of record a reader opens, then Word, then text (Sagentix's folder holds all three, 2026-11-05). */
+export const FORMAT_ORDER = [".pdf", ".docx", ".md", ".txt"];
+/** The policy files in the folders, sorted, one level deep (no hidden files, no sub-folders: an archive folder stays out). */
+export function policyFiles(dirs) {
+    const all = allPolicyFiles(dirs), best = new Map();
+    const rank = (n) => FORMAT_ORDER.indexOf(extname(n).toLowerCase());
+    for (const f of all) {
+        const key = join(dirname(f.path), basename(f.name, extname(f.name)).toLowerCase());
+        const had = best.get(key);
+        if (!had || rank(f.name) < rank(had.name))
+            best.set(key, f);
+    }
+    return [...best.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function allPolicyFiles(dirs) {
+    const out = [];
+    for (const d of dirs) {
+        for (const name of readdirSync(d).sort()) {
+            const type = POLICY_TYPES[extname(name).toLowerCase()];
+            if (!type || name.startsWith(".") || name.startsWith("~$"))
+                continue;
+            const path = join(d, name);
+            if (statSync(path).isFile())
+                out.push({ path, name, type });
+        }
+    }
+    return out;
+}
+const b64url = (b) => Buffer.from(b).toString("base64url");
+/** Pushes every policy file; one outcome per file. `organization` is the key's organization id (sos-app checks it). */
+export async function pushPolicies(o) {
+    const url = new URL(DOCUMENT_PATH, o.endpoint).toString();
+    const results = [];
+    for (const f of policyFiles(o.dirs)) {
+        const bytes = readFileSync(f.path);
+        if (bytes.byteLength > MAX_BYTES || bytes.byteLength === 0) {
+            results.push({ file: f.name, status: 0, outcome: "skipped", detail: "empty or over 10 MB" });
+            continue;
+        }
+        const manifest = {
+            format: "sagentix-document/1", issuedAt: o.now().toISOString(), organization: o.organization, target: { policy: "auto" },
+            filename: f.name.slice(0, 120), contentType: f.type, sha256: createHash("sha256").update(bytes).digest("hex"), size: bytes.byteLength, kind: "policy",
+        };
+        const mBytes = new TextEncoder().encode(JSON.stringify(manifest));
+        let res;
+        try {
+            res = await o.fetch(url, { method: "POST", body: bytes, headers: { "content-type": f.type, "x-sagentix-key-id": o.keyId,
+                    "x-sagentix-signature": signBody(o.pem, mBytes), "x-sagentix-document": b64url(mBytes) } });
+        }
+        catch (e) {
+            results.push({ file: f.name, status: 0, outcome: "refused", detail: String(e?.message ?? e) });
+            continue;
+        }
+        const text = await res.text();
+        let j = {};
+        try {
+            j = JSON.parse(text);
+        }
+        catch { /* not JSON */ }
+        const fam = typeof j.family === "string" ? j.family.toUpperCase() : "";
+        if (res.status === 201 && j.family)
+            results.push({ file: f.name, status: 201, outcome: "filed", detail: `${fam} version ${j.version}, a draft for approval` });
+        else if (res.status === 201)
+            results.push({ file: f.name, status: 201, outcome: "evidence", detail: `policy evidence on ${String(j.control ?? "?").toUpperCase()}` });
+        else if (res.status === 200 && j.duplicate)
+            results.push({ file: f.name, status: 200, outcome: "duplicate", detail: fam ? `${fam} version ${j.version}, unchanged` : "unchanged" });
+        else if (j.code === "policy_unmatched")
+            results.push({ file: f.name, status: res.status, outcome: "unmatched", detail: String(j.error ?? "") });
+        else if (j.code === "policy_family_taken")
+            results.push({ file: f.name, status: res.status, outcome: "taken", detail: String(j.error ?? "") });
+        else
+            results.push({ file: f.name, status: res.status, outcome: "refused", detail: String(j.error ?? text).slice(0, 300) });
+    }
+    return results;
+}
+export const PULL_PATH = "/api/collect/policies/approved";
+export const APPROVED_DIR = "approved";
+/** The organization's approved policies, read with the documents key (sos-app src/routes/documents.ts pullApprovedPolicies). */
+export async function pullApproved(o) {
+    const m = new TextEncoder().encode(JSON.stringify({ format: "sagentix-policies-pull/1", issuedAt: o.now().toISOString(), organization: o.organization }));
+    const res = await o.fetch(new URL(PULL_PATH, o.endpoint).toString(), { method: "POST", headers: { "x-sagentix-key-id": o.keyId,
+            "x-sagentix-signature": signBody(o.pem, m), "x-sagentix-document": b64url(m) } });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`sos-app answered HTTP ${res.status} for the approved policies: ${text.slice(0, 200)}`);
+    return JSON.parse(text).policies;
+}
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+/** Writes each approved version into <first folder>/approved/ (Stéphane, 2026-11-05: an approved policy must never be
+ *  overwritten by the next push, and the folder should hold the text in force). A version made in sos-app is written as
+ *  Markdown; an approved uploaded file is copied from the folder when the folder holds those exact bytes. Each name
+ *  carries its version (…v3.md), so nothing is ever overwritten; earlier approved copies stay as history. The push never
+ *  reads sub-folders, so these copies are never sent back. */
+export function writeApproved(dirs, approved) {
+    const out = [];
+    if (!dirs.length)
+        return out;
+    const target = join(dirs[0], APPROVED_DIR);
+    const local = allPolicyFiles(dirs).map((f) => ({ ...f, sha: createHash("sha256").update(readFileSync(f.path)).digest("hex") }));
+    for (const p of approved) {
+        const fromFile = p.origin === "uploaded" ? local.find((f) => f.sha === p.sha256) : undefined;
+        const stem = fromFile ? basename(fromFile.name, extname(fromFile.name)) : p.filename ? basename(p.filename, extname(p.filename)) : `${p.family}-${slug(p.title)}`;
+        const name = `${stem}.v${p.version}${fromFile ? extname(fromFile.name).toLowerCase() : ".md"}`;
+        const dest = join(target, name);
+        // One exclusive create each (flag "wx", COPYFILE_EXCL), never a check then a write (CodeQL js/file-system-race):
+        // a file already there is the answer "present", and nothing is ever overwritten.
+        const present = (e) => e?.code === "EEXIST";
+        if (p.body !== undefined) {
+            mkdirSync(target, { recursive: true });
+            try {
+                writeFileSync(dest, `<!-- ${p.title}, version ${p.version}, approved ${p.approvedAt} in Sagentix Comply. This is the text in force: edit a copy of it in the folder above. -->\n\n${p.body}`, { flag: "wx" });
+                out.push({ file: name, outcome: "written", detail: `${p.family.toUpperCase()} version ${p.version}, the text approved in sos-app` });
+            }
+            catch (e) {
+                if (!present(e))
+                    throw e;
+                out.push({ file: name, outcome: "present", detail: `${p.family.toUpperCase()} version ${p.version}, already here` });
+            }
+        }
+        else if (fromFile) {
+            mkdirSync(target, { recursive: true });
+            try {
+                copyFileSync(fromFile.path, dest, fsConstants.COPYFILE_EXCL);
+                out.push({ file: name, outcome: "written", detail: `${p.family.toUpperCase()} version ${p.version}, your approved file` });
+            }
+            catch (e) {
+                if (!present(e))
+                    throw e;
+                out.push({ file: name, outcome: "present", detail: `${p.family.toUpperCase()} version ${p.version}, already here` });
+            }
+        }
+        else
+            out.push({ file: name, outcome: "missing", detail: `${p.family.toUpperCase()} version ${p.version} is an uploaded file this folder no longer holds (SHA-256 ${p.sha256.slice(0, 12)}…)` });
+    }
+    return out;
+}

package/collector/src/pool.js

@@ -0,0 +1,19 @@
+// A bounded pool: runs `work` over the items with at most `limit` in flight, and returns each outcome at its item's
+// index, so a caller that takes them in order gets the same order a serial loop would (cli.ts --concurrency, Prowler).
+export async function pool(items, limit, work) {
+    const out = new Array(items.length);
+    let next = 0;
+    const lane = async () => {
+        for (let i = next++; i < items.length; i = next++) {
+            try {
+                out[i] = { status: "fulfilled", value: await work(items[i], i) };
+            }
+            catch (reason) {
+                out[i] = { status: "rejected", reason };
+            }
+        }
+    };
+    const n = Math.max(1, Math.min(Math.floor(limit) || 1, items.length));
+    await Promise.all(Array.from({ length: n }, lane));
+    return out;
+}