@sagentix-inc/evidence-collector 0.2.1 → 0.3.0

package/collector/src/sources/endpoint_central.js

@@ -0,0 +1,345 @@
+// ManageEngine Endpoint Central (cloud edition) over its REST API (GET only), with a Zoho self client whose refresh
+// token was generated for READ operations only: DesktopCentralCloud.Inventory.READ and DesktopCentralCloud.PatchMgmt.READ.
+// The refresh-token exchange at the Zoho accounts server is the only POST.
+//
+// Auth (manageengine.com/products/desktop-central/help/api/cloud/, read 2026-10-28):
+//   oauth-authentication-self-client-authorization-code-flow.html: a self client in the Zoho API console generates a
+//     code for comma-separated scopes; POST {accounts-server-url}/oauth/v2/token with the query parameters client_id,
+//     client_secret, grant_type=authorization_code, code gives a refresh_token that "won't expire"; the same endpoint with
+//     grant_type=refresh_token and refresh_token gives an access_token valid one hour (expires_in). The parameters are
+//     sent as the page shows them, in the query string, over https.
+//   Scopes are service.scope.operation; every endpoint below lists its scope with the operation READ (api-index.html).
+//   Header: "Authorization: Zoho-oauthtoken <access token>".
+//   oauth-authentication-endpoint-domain.md: nine data centres, EndpointCentral_Server_URI
+//     https://endpointcentral.manageengine.{com,eu,in,com.au,cn,jp,ca,uk,sa} with ZohoAccounts_Server_URI
+//     https://accounts.zoho.{com,eu,in,com.au,cn,jp,ca,uk,sa}. accounts.zoho.com/oauth/serverinfo (read the same day)
+//     gives https://accounts.zohocloud.ca for Canada instead, so ENDPOINT_CENTRAL_ACCOUNTS_URL can override the default.
+//   The token acts as the user who generated it, and "UAC_UNAUTHORIZED - user lacks the required uem-roles" is a 401: the
+//   predefined Guest role has "Read Access" to Inventory and Patch Management (help/access-management/
+//   user_role_and_permission.html, read 2026-10-28).
+//
+// Endpoints and fields (each page under help/api/cloud/, read 2026-10-28):
+//   GET /dcapi/inventory/viewData/scanComputers?toolID=2131     Accept: application/InventoryMobileAPI.v1+json
+//        -> { metadata: { limit, page }, totalRecords, totalPages, Links: { next, prev }, messageResponse: [ { resource_id,
+//             servicetag, os_platform (1 Windows, 2 Mac, 3 Linux), os_version, build_number, installation_status
+//             (21 yet to install, 22 installed, 23 uninstalled, 24 yet to uninstall, 29 installation failure),
+//             agent_last_contact_time (epoch ms), resource_name, domain_netbios_name, ... } ] }   Threshold 120 a minute.
+//   GET /dcapi/inventory/computers/{resourceID}/diskEncryptionStatus     Accept: application/diskEncryptionStatus.v1+json
+//        -> { diskEncryptionStatusDetails: [ { logicalDriveName, encryptionStatus ("Encrypted", "Not Encrypted"),
+//             logicalDiskType, encryptionMethod } ] }   Threshold 120 a minute.
+//   GET /dcapi/inventory/computers/{resourceID}/firewall                 Accept: application/firewallInfo.v1+json
+//        -> { windowsFirewallDetails: [ { domainProfileStatus, privateProfileStatus, publicProfileStatus,
+//             isExternalFirewallEnabled, externalFirewallName } ], externalFirewallDetails: [ { firewallName,
+//             protectionStatus, ... } ] }   Threshold 120 a minute.
+//   GET /dcapi/patch/reports/systemHealth?page&pageLimit                 (scope DesktopCentralCloud.PatchMgmt.READ)
+//        -> { totalPages, Links: { next }, messageResponse: [ { ComputerName, Domain, Health, MissingOsPatches,
+//             Critical, Important, ... } ] }   Threshold 50 a minute.
+//   Each page states "Lock period: 5 minutes" once a threshold is passed, so the per-computer calls are spaced by
+//   --endpoint-central-call-gap-ms (default 600 ms: 100 computers a minute, under 120). Pages follow Links.next, a path
+//   such as "/dcapi/patch/reports/systemHealth?page=2&pageLimit=25", until it is null.
+//   The patch report carries no resource id, so a row is matched to a computer by ComputerName and Domain (the scan
+//   list's resource_name and domain_netbios_name); a name that two computers share is skipped, never guessed.
+//
+// Left out: the screen lock (no Inventory or Patch endpoint reports it), and the on-premises edition: its documented API
+// (/api/1.4/desktop/authentication) signs in with a console user's password, and no page documents the /dcapi
+// endpoints or a read-only API key for it.
+//
+// Personal data: a computer is named by its resource_id and service tag. resource_name, the logged-on user (name), FQDN,
+// IP and MAC addresses, and the patch report's owner and user fields are never put in a result.
+import { cachedToken, tokenRequest } from "./oauth.js";
+import { Emitter, enc, fetchRest, isObj, ok, realSleep, redact, str, why, withRetry, listRead, stampRead } from "./readonly_http.js";
+import { cmpVersion, deviceResource, minOsOption, posInt, showVersion, versionIn } from "./device_common.js";
+export const EC_ENV = {
+    url: "ENDPOINT_CENTRAL_URL", client: "ENDPOINT_CENTRAL_CLIENT_ID", secret: "ENDPOINT_CENTRAL_CLIENT_SECRET",
+    refresh: "ENDPOINT_CENTRAL_REFRESH_TOKEN", accounts: "ENDPOINT_CENTRAL_ACCOUNTS_URL",
+};
+/** Data centre suffixes from the "Multiple data centres" page: endpointcentral.manageengine.<suffix>, accounts.zoho.<suffix>. */
+export const EC_SUFFIXES = ["com", "eu", "in", "com.au", "cn", "jp", "ca", "uk", "sa"];
+export const EC_SCOPES = ["DesktopCentralCloud.Inventory.READ", "DesktopCentralCloud.PatchMgmt.READ"];
+export const EC_CHECKS = ["disk_encryption", "firewall", "os_minimum", "os_patches", "last_contact", "agent_installed"];
+export const DEFAULTS = { contactDays: 14, maxComputers: 500, gapMs: 600, maxMissingOsPatches: 0 };
+export const PATCH_PAGE = 100;
+export const SCAN_PATH = "/dcapi/inventory/viewData/scanComputers?toolID=2131";
+export const healthPath = (page) => `/dcapi/patch/reports/systemHealth?page=${page}&pageLimit=${PATCH_PAGE}`;
+export const encryptionPath = (id) => `/dcapi/inventory/computers/${enc(id)}/diskEncryptionStatus`;
+export const firewallPath = (id) => `/dcapi/inventory/computers/${enc(id)}/firewall`;
+/** The Accept header each endpoint's page marks Mandatory. */
+export function acceptFor(path) {
+    if (path.includes("/viewData/scanComputers"))
+        return "application/InventoryMobileAPI.v1+json";
+    if (path.includes("/diskEncryptionStatus"))
+        return "application/diskEncryptionStatus.v1+json";
+    if (path.includes("/firewall"))
+        return "application/firewallInfo.v1+json";
+    return "application/json";
+}
+/** The data centre suffix of an Endpoint Central cloud URL, or undefined for any other host. */
+export function suffixOf(host) {
+    const m = host.match(/^endpointcentral\.manageengine\.(.+)$/);
+    return m && EC_SUFFIXES.includes(m[1]) ? m[1] : undefined;
+}
+/** An Endpoint Central cloud client from ENDPOINT_CENTRAL_* variables, or what is missing. */
+export function endpointCentralFromEnv(env, fetchFn = fetch) {
+    const url = env[EC_ENV.url], client = env[EC_ENV.client], secret = env[EC_ENV.secret], refresh = env[EC_ENV.refresh];
+    if (!url || !client || !secret || !refresh)
+        return `${EC_ENV.url}, ${EC_ENV.client}, ${EC_ENV.secret} and ${EC_ENV.refresh} are not all set`;
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return `${EC_ENV.url} is not a URL`;
+    }
+    if (u.protocol !== "https:")
+        return `${EC_ENV.url} must be https`;
+    const suffix = suffixOf(u.host);
+    if (!suffix)
+        return `${EC_ENV.url} must be https://endpointcentral.manageengine.<${EC_SUFFIXES.join("|")}> (the cloud edition; on-premises servers are not supported)`;
+    let accounts = `https://accounts.zoho.${suffix}`;
+    if (env[EC_ENV.accounts]) {
+        let a;
+        try {
+            a = new URL(env[EC_ENV.accounts]);
+        }
+        catch {
+            return `${EC_ENV.accounts} is not a URL`;
+        }
+        if (a.protocol !== "https:" || !/^accounts\.(zoho|zohocloud)\.[a-z.]+$/.test(a.host))
+            return `${EC_ENV.accounts} must be a https Zoho accounts server, e.g. https://accounts.zoho.eu`;
+        accounts = a.origin;
+    }
+    const qs = new URLSearchParams({ client_id: client, client_secret: secret, grant_type: "refresh_token", refresh_token: refresh }).toString();
+    let current = "";
+    const token = cachedToken(async () => { const t = await tokenRequest(`${accounts}/oauth/v2/token?${qs}`, {}, fetchFn); current = t.token; return t; });
+    const clients = new Map();
+    const clientFor = (accept) => {
+        let c = clients.get(accept);
+        if (!c) {
+            c = fetchRest({ base: u.origin, fetchFn, headers: async () => ({ authorization: `Zoho-oauthtoken ${await token()}`, accept }) });
+            clients.set(accept, c);
+        }
+        return c;
+    };
+    return {
+        async get(path) {
+            const r = await clientFor(acceptFor(path)).get(path);
+            // fetchRest cuts the whole header value out of an answer; the bare access token is cut here.
+            if (current.length >= 8 && JSON.stringify(r.body ?? "").includes(current)) {
+                const text = JSON.stringify(r.body).split(current).join("[redacted]");
+                return { ...r, body: JSON.parse(text) };
+            }
+            return r;
+        },
+    };
+}
+const rowsOf = (b) => (isObj(b) && Array.isArray(b.messageResponse) ? b.messageResponse.filter(isObj) : undefined);
+const nextOf = (b) => (isObj(b) && isObj(b.Links) ? str(b.Links.next) : undefined);
+/** The scan computers list, following Links.next, up to `max` computers. */
+async function listComputers(api, max) {
+    const items = [];
+    let url = SCAN_PATH;
+    let pages = 0;
+    const seen = new Set();
+    while (url && !seen.has(url)) {
+        seen.add(url);
+        const r = await api.get(url);
+        const got = ok(r) ? rowsOf(r.body) : undefined;
+        if (!got)
+            return { error: r };
+        pages++;
+        items.push(...got);
+        if (items.length >= max)
+            return { items: items.slice(0, max), truncated: items.length > max || !!nextOf(r.body), pages };
+        url = nextOf(r.body);
+    }
+    return { items, truncated: false, pages };
+}
+/** The system health report's rows, by lower-cased "ComputerName|Domain"; a key two rows share maps to null. */
+async function systemHealth(api, maxPages) {
+    const rows = new Map();
+    for (let page = 1; page <= maxPages; page++) {
+        const r = await api.get(healthPath(page));
+        const got = ok(r) ? rowsOf(r.body) : undefined;
+        if (!got)
+            return { error: r };
+        for (const row of got) {
+            const k = `${String(row.ComputerName ?? "").toLowerCase()}|${String(row.Domain ?? "").toLowerCase()}`;
+            rows.set(k, rows.has(k) ? null : row);
+        }
+        const total = isObj(r.body) ? Number(r.body.totalPages) : NaN;
+        if (!got.length || !nextOf(r.body) || (Number.isFinite(total) && page >= total))
+            break;
+    }
+    return { rows };
+}
+const PLATFORM = { "1": "windows", "2": "macos", "3": "linux" };
+const INSTALL = { "21": "yet to install", "22": "installed", "23": "uninstalled", "24": "yet to uninstall", "29": "installation failure" };
+const n = (v) => { const x = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN; return Number.isFinite(x) ? x : undefined; };
+function judgeEncryption(body) {
+    const list = isObj(body) && Array.isArray(body.diskEncryptionStatusDetails) ? body.diskEncryptionStatusDetails.filter(isObj) : undefined;
+    if (!list)
+        return { result: "skipped", detail: "diskEncryptionStatusDetails not reported" };
+    const known = list.filter((d) => d.encryptionStatus === "Encrypted" || d.encryptionStatus === "Not Encrypted");
+    if (!known.length)
+        return { result: "skipped", detail: `no drive reports an encryptionStatus of Encrypted or Not Encrypted (${list.length} listed)` };
+    const off = known.filter((d) => d.encryptionStatus === "Not Encrypted");
+    const name = (d) => String(d.logicalDriveName ?? "?").replace(/[^A-Za-z0-9:/\\._-]/g, "").slice(0, 40);
+    if (off.length)
+        return { result: "fail", detail: `${off.length} of ${known.length} drive(s) Not Encrypted: ${off.slice(0, 5).map(name).join(", ")}; every reported drive must be Encrypted` };
+    return { result: "pass", detail: `all ${known.length} drive(s) report Encrypted (${known.slice(0, 5).map((d) => `${name(d)} ${String(d.encryptionMethod ?? "").slice(0, 20)}`.trim()).join(", ")})` };
+}
+function judgeFirewall(body) {
+    if (!isObj(body))
+        return { result: "skipped", detail: "firewall details not reported" };
+    const win = Array.isArray(body.windowsFirewallDetails) ? body.windowsFirewallDetails.filter(isObj)[0] : undefined;
+    const ext = Array.isArray(body.externalFirewallDetails) ? body.externalFirewallDetails.filter(isObj) : [];
+    const extOn = ext.filter((e) => e.protectionStatus === "Enabled");
+    if (extOn.length)
+        return { result: "pass", detail: `a third-party firewall reports protectionStatus Enabled (${extOn.length} of ${ext.length} listed)` };
+    if (!win)
+        return { result: "skipped", detail: `no Windows Firewall profile and no enabled third-party firewall reported (${ext.length} third-party listed)` };
+    const prof = { domain: str(win.domainProfileStatus), private: str(win.privateProfileStatus), public: str(win.publicProfileStatus) };
+    const shown = Object.entries(prof).map(([k, v]) => `${k} ${v ?? "not reported"}`).join(", ");
+    if (Object.values(prof).every((v) => v === "Enabled"))
+        return { result: "pass", detail: `Windows Firewall profiles: ${shown}` };
+    if (Object.values(prof).some((v) => v === undefined))
+        return { result: "skipped", detail: `Windows Firewall profiles not all reported: ${shown}` };
+    return { result: "fail", detail: `Windows Firewall profiles: ${shown}; all three must be Enabled, and no third-party firewall reports Enabled` };
+}
+export async function endpointCentralChecks(api, server, o, now, sleep) {
+    const out = new Emitter("endpoint_central", `endpoint_central ${server}`);
+    const got = await listComputers(api, o.maxComputers);
+    if ("error" in got) {
+        for (const c of EC_CHECKS)
+            out.skip(c, got.error, "scan computers list");
+        return out.results;
+    }
+    if (!got.items.length) {
+        out.skipAll(EC_CHECKS, "Endpoint Central lists no computer; nothing to judge");
+        return out.results;
+    }
+    const cap = got.truncated ? `; only the first ${o.maxComputers} computers read (--endpoint-central-max-computers)` : "";
+    const from = out.results.length;
+    if (!o.minOs.size)
+        out.add("os_minimum", "skipped", `no minimum OS version given (--endpoint-central-min-os, e.g. windows=10.0.26100 or macos=15.0); ${got.items.length} computer(s) not judged`);
+    const health = await systemHealth(api, Math.ceil(o.maxComputers / PATCH_PAGE) + 2);
+    if ("error" in health)
+        out.skip("os_patches", health.error, "patch system health report");
+    const denied = new Map();
+    let calls = 0;
+    for (const c of got.items) {
+        const id = String(c.resource_id ?? "");
+        const res = deviceResource("endpoint_central computer", id || "?", c.servicetag);
+        const platform = PLATFORM[String(c.os_platform)] ?? "unknown";
+        const ver = str(c.os_version);
+        const where = ` (${platform}${ver ? ` ${ver.slice(0, 30)}` : ""})`;
+        const inst = String(c.installation_status ?? "");
+        if (inst === "22")
+            out.add("agent_installed", "pass", `installation_status 22 (installed)${where}${cap}`, res);
+        else if (INSTALL[inst])
+            out.add("agent_installed", "fail", `installation_status ${inst} (${INSTALL[inst]}); 22 (installed) required${where}`, res);
+        else
+            out.add("agent_installed", "skipped", `installation_status ${inst || "not reported"}${where}`, res);
+        const ms = n(c.agent_last_contact_time);
+        if (ms === undefined || ms <= 0)
+            out.add("last_contact", "skipped", `agent_last_contact_time not reported${where}`, res);
+        else {
+            const age = Math.floor((now.getTime() - ms) / 86_400_000);
+            out.add("last_contact", age <= o.contactDays ? "pass" : "fail", `agent last contact ${age} day(s) ago; at most ${o.contactDays} allowed (--endpoint-central-contact-days)${where}`, res);
+        }
+        if (o.minOs.size) {
+            const floor = o.minOs.get(platform) ?? o.minOs.get("*");
+            const have = versionIn(ver);
+            if (!floor)
+                out.add("os_minimum", "skipped", `no --endpoint-central-min-os floor for ${platform}${where}`, res);
+            else if (!have)
+                out.add("os_minimum", "skipped", `os_version not reported${where}`, res);
+            else {
+                const okv = cmpVersion(have, floor) >= 0;
+                out.add("os_minimum", okv ? "pass" : "fail", `${platform} ${showVersion(have)} ${okv ? "meets" : "is below"} the --endpoint-central-min-os floor ${showVersion(floor)}${where}`, res);
+            }
+        }
+        if (!("error" in health)) {
+            const key = `${String(c.resource_name ?? "").toLowerCase()}|${String(c.domain_netbios_name ?? "").toLowerCase()}`;
+            const row = health.rows.get(key);
+            const missing = row ? n(row.MissingOsPatches) : undefined;
+            if (row === null)
+                out.add("os_patches", "skipped", `two or more patch report rows share this computer's name and domain; not matched${where}`, res);
+            else if (!row)
+                out.add("os_patches", "skipped", `no row for this computer in the patch system health report${where}`, res);
+            else if (missing === undefined)
+                out.add("os_patches", "skipped", `MissingOsPatches not reported (Health ${String(row.Health ?? "not reported").slice(0, 30)})${where}`, res);
+            else {
+                const pass = missing <= o.maxMissingOsPatches;
+                out.add("os_patches", pass ? "pass" : "fail", `${missing} missing OS patch(es) (Critical ${String(row.Critical ?? "?").slice(0, 8)}, Important ${String(row.Important ?? "?").slice(0, 8)}, Health ${String(row.Health ?? "?").slice(0, 30)}); at most ${o.maxMissingOsPatches} allowed (--endpoint-central-max-missing-os-patches)${where}`, res);
+            }
+        }
+        // One disk-encryption and one firewall call per computer with an installed agent, spaced under the 120-a-minute threshold.
+        for (const [check, path, judge] of [["disk_encryption", encryptionPath, judgeEncryption], ["firewall", firewallPath, judgeFirewall]]) {
+            const stop = denied.get(check);
+            if (stop) {
+                out.skip(check, stop, check === "firewall" ? "computer firewall details" : "disk encryption status", res);
+                continue;
+            }
+            if (!id) {
+                out.add(check, "skipped", `no resource_id${where}`, res);
+                continue;
+            }
+            if (inst !== "22") {
+                out.add(check, "skipped", `the agent is not installed (installation_status ${inst || "not reported"}), so inventory has no current value${where}`, res);
+                continue;
+            }
+            if (calls++ > 0 && o.gapMs > 0)
+                await sleep(o.gapMs);
+            const r = await api.get(path(id));
+            if (!ok(r)) {
+                if (r.status === 401 || r.status === 403)
+                    denied.set(check, r);
+                out.add(check, "skipped", `${check === "firewall" ? "computer firewall details" : "disk encryption status"} not readable: ${why(r)}${where}`, res, { method: "config-read", apiError: { status: r.status, message: why(r) } });
+                continue;
+            }
+            const v = judge(r.body);
+            out.add(check, v.result, `${v.detail}${where}`, res);
+        }
+    }
+    stampRead(out.results, from, listRead(got));
+    return out.results;
+}
+export const endpoint_central = {
+    name: "endpoint_central",
+    options: {
+        "endpoint-central-contact-days": { type: "string", help: `days since a computer's last agent contact before last_contact fails (default ${DEFAULTS.contactDays})` },
+        "endpoint-central-min-os": { type: "string", multiple: true, help: "<platform>=<version> floor for os_minimum, platform windows, macos or linux, e.g. windows=10.0.26100 (repeatable; without it the check is skipped)" },
+        "endpoint-central-max-missing-os-patches": { type: "string", help: `missing OS patches a computer may have before os_patches fails (default ${DEFAULTS.maxMissingOsPatches})` },
+        "endpoint-central-max-computers": { type: "string", help: `computers read, at most (default ${DEFAULTS.maxComputers}); each costs two inventory calls` },
+        "endpoint-central-call-gap-ms": { type: "string", help: `pause between per-computer calls, in ms (default ${DEFAULTS.gapMs}: under the documented 120 calls a minute)` },
+    },
+    emits: EC_CHECKS.map((c) => `endpoint_central.${c}`),
+    describe: () => "ManageEngine Endpoint Central cloud server in ENDPOINT_CENTRAL_URL (Zoho self client, Inventory and PatchMgmt READ scopes)",
+    async run(ctx) {
+        const server = (() => { try {
+            return new URL(ctx.env[EC_ENV.url] ?? "").host || "(unknown)";
+        }
+        catch {
+            return "(unknown)";
+        } })();
+        const given = ctx.clients.endpoint_central;
+        const built = given !== undefined ? given : endpointCentralFromEnv(ctx.env);
+        if (!built || typeof built === "string") {
+            const out = new Emitter("endpoint_central", `endpoint_central ${server}`);
+            out.skipAll(EC_CHECKS, typeof built === "string" ? built : `${EC_ENV.refresh} is not set`);
+            return out.results;
+        }
+        const sleep = ctx.clients.sleep ?? realSleep;
+        const api = withRetry(built, sleep);
+        const nonNeg = (v, d) => { const x = typeof v === "string" && v.trim() !== "" ? Number(v) : NaN; return Number.isInteger(x) && x >= 0 ? x : d; };
+        const o = {
+            contactDays: posInt(ctx.opts["endpoint-central-contact-days"], DEFAULTS.contactDays),
+            maxComputers: posInt(ctx.opts["endpoint-central-max-computers"], DEFAULTS.maxComputers),
+            gapMs: nonNeg(ctx.opts["endpoint-central-call-gap-ms"], DEFAULTS.gapMs),
+            maxMissingOsPatches: nonNeg(ctx.opts["endpoint-central-max-missing-os-patches"], DEFAULTS.maxMissingOsPatches),
+            minOs: minOsOption(ctx.opts["endpoint-central-min-os"]),
+        };
+        return redact(await endpointCentralChecks(api, server, o, ctx.now, sleep), [ctx.env[EC_ENV.secret], ctx.env[EC_ENV.refresh]]);
+    },
+};

package/collector/src/sources/gcp/api.js

@@ -1,9 +1,45 @@
 // Read-only Google Cloud REST client. GET only, plus POST to `:getIamPolicy` and `:getAncestry` (reads that Google
 // exposes as POST); the fetch client refuses any other POST, so a bug here cannot change a project.
 // The bearer token comes from GOOGLE_OAUTH_ACCESS_TOKEN (google-github-actions/auth with
-// token_format: access_token). Tests pass a fake transport; nothing in tests touches the network.
+// token_format: access_token), or, on a server or in a container (2026-10-28: Docker is the default runner, and an
+// hour-long token cannot be scheduled), from a read-only service account's key file named by GCP_SA_KEY_FILE: the
+// collector signs a JWT as the service account itself (no `sub`) and exchanges it for an hour's token, scope
+// cloud-platform (the default of google-github-actions/auth); the service account's read-only roles bound what it reads.
+// Tests pass a fake transport; nothing in tests touches the network.
+import { readFileSync } from "node:fs";
 import { isObj, str, withRetry, httpWhy } from "../shared-cloud.js";
+import { cachedToken, googleAssertion, tokenRequest } from "../oauth.js";
+import { isGoogleTokenUri } from "../google_workspace.js";
 export const GCP_TOKEN_ENV = "GOOGLE_OAUTH_ACCESS_TOKEN";
+export const GCP_KEY_ENV = "GCP_SA_KEY_FILE";
+export const GCP_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const GOOGLE_TOKEN = "https://oauth2.googleapis.com/token";
+/** An access token from the key file in GCP_SA_KEY_FILE, renewed when it ends; why not, as text; undefined when unset. */
+export function gcpKeyToken(env, fetchFn = fetch) {
+    const file = env[GCP_KEY_ENV];
+    if (!file)
+        return undefined;
+    let key;
+    try {
+        key = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        return `${GCP_KEY_ENV} is not a readable service account key (${e.code ?? "bad JSON"})`;
+    }
+    if (typeof key.client_email !== "string" || typeof key.private_key !== "string")
+        return `${GCP_KEY_ENV} has no client_email or private_key`;
+    // Google's key format page shows token_uri "https://accounts.google.com/o/oauth2/token", and its OAuth page says the
+    // assertion's aud "is always https://oauth2.googleapis.com/token" (both read 2026-10-28): the older address goes there.
+    const named = key.token_uri ?? GOOGLE_TOKEN;
+    const tokenUri = named === "https://accounts.google.com/o/oauth2/token" ? GOOGLE_TOKEN : named;
+    // The key file names its own token endpoint; a tampered file could send the signed assertion elsewhere.
+    if (!isGoogleTokenUri(tokenUri))
+        return `${GCP_KEY_ENV} names a token_uri outside googleapis.com over HTTPS`;
+    return cachedToken(() => tokenRequest(tokenUri, {
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion: googleAssertion({ ...key, token_uri: tokenUri }, undefined, [GCP_SCOPE], Math.floor(Date.now() / 1000)),
+    }, fetchFn));
+}
 /**
  * The two reads Google exposes as POST: :getIamPolicy, and Resource Manager v1 projects.getAncestry ("Gets a list of
  * ancestors in the resource hierarchy for the Project ... The caller must have read permissions for this Project",
@@ -18,7 +54,7 @@ export function fetchGcpTransport(token, fetchFn = fetch) {
             }
             const res = await fetchFn(url, {
                 method,
-                headers: { authorization: `Bearer ${token}`, accept: "application/json", ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+                headers: { authorization: `Bearer ${typeof token === "string" ? token : await token()}`, accept: "application/json", ...(body !== undefined ? { "content-type": "application/json" } : {}) },
                 ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
             });
             const headers = {};

package/collector/src/sources/gcp.js

@@ -1,7 +1,7 @@
 // Google Cloud: per-project checks over Google's REST APIs with a read-only service account's access
-// token (GOOGLE_OAUTH_ACCESS_TOKEN). Every call is a GET, except POST :getIamPolicy and :getAncestry, which read.
+// token (GOOGLE_OAUTH_ACCESS_TOKEN, or minted from the key file in GCP_SA_KEY_FILE; see gcp/api.ts). Every call is a GET, except POST :getIamPolicy and :getAncestry, which read.
 import { Results, allSkipped, list, scrub } from "./shared-cloud.js";
-import { GCP_TOKEN_ENV, Gcp, fetchGcpTransport } from "./gcp/api.js";
+import { GCP_KEY_ENV, GCP_TOKEN_ENV, Gcp, fetchGcpTransport, gcpKeyToken } from "./gcp/api.js";
 import { DEFAULT_KEY_MAX_AGE_DAYS, DEFAULT_ORG_CONSTRAINTS, GCP_CHECKS, projectChecks } from "./gcp/project.js";
 export const gcp = {
     name: "gcp",
@@ -18,11 +18,13 @@ export const gcp = {
     async run(ctx) {
         const projects = list(ctx.opts["gcp-project"]);
         const token = ctx.env[GCP_TOKEN_ENV];
-        const t = ctx.clients.gcp !== undefined ? ctx.clients.gcp : token ? fetchGcpTransport(token) : null;
+        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 (!projects.length)
             return allSkipped("gcp", GCP_CHECKS, "project (none listed)", "no --gcp-project given");
         if (!t)
-            return projects.flatMap((p) => allSkipped("gcp", GCP_CHECKS, `project ${p}`, `${GCP_TOKEN_ENV} is not set`));
+            return projects.flatMap((p) => allSkipped("gcp", GCP_CHECKS, `project ${p}`, typeof keyed === "string" ? keyed : `${GCP_TOKEN_ENV} or ${GCP_KEY_ENV} is not set`));
         const constraints = list(ctx.opts["gcp-org-constraints"]);
         const maxAge = Number(ctx.opts["gcp-key-max-age-days"] ?? DEFAULT_KEY_MAX_AGE_DAYS);
         const api = new Gcp(t);

package/collector/src/sources/google_endpoints.js

@@ -0,0 +1,171 @@
+// Google endpoint management: the devices a Google Workspace or Cloud Identity customer manages (Windows, macOS,
+// Linux and ChromeOS desktops reporting through Endpoint Verification, and Android and iOS phones), read through the
+// Cloud Identity Devices API with GET only. Same credential as google_workspace: the service account in
+// GOOGLE_SA_KEY_FILE acting as GOOGLE_ADMIN_EMAIL through domain-wide delegation, with one more read-only scope.
+//
+// Pages, all read 2026-10-28:
+//   GET https://cloudidentity.googleapis.com/v1/devices        devices.list (docs.cloud.google.com/identity/docs/
+//       reference/rest/v1/devices/list, last updated 2025-12-16): customer "customers/my_customer" for your own
+//       organization; pageSize "at most 20 ... The maximum value is 100"; pageToken, "Empty if there are no more
+//       results" in nextPageToken; view USER_ASSIGNED_DEVICES "all devices with at least one user registered on the
+//       device ... all device information, except for asset tags". Scopes: cloud-identity.devices.readonly (or the
+//       read-write ones, never asked for here).
+//   Device fields (discovery document cloudidentity v1, revision 20261026): name "devices/{device}", serialNumber,
+//       deviceType (ANDROID, IOS, GOOGLE_SYNC, WINDOWS, MAC_OS, LINUX, CHROME_OS, GOOGLEBOOK), osVersion ("Android
+//       8.1.0"), lastSyncTime ("Most recent time when device synced with this service"), encryptionState
+//       (ENCRYPTED, NOT_ENCRYPTED, UNSUPPORTED_BY_DEVICE, ENCRYPTION_STATE_UNSPECIFIED), compromisedState (COMPROMISED,
+//       UNCOMPROMISED, COMPROMISED_STATE_UNSPECIFIED), endpointVerificationSpecificAttributes.additionalSignals, whose
+//       non-configurable attributes include is_os_native_firewall_enabled. The `name` description says "Device API
+//       scopes require that you use domain-wide delegation to access the API".
+//   docs.cloud.google.com/identity/docs/how-to/setup-devices (last updated 2026-10-26): "Authenticating directly to
+//       the Devices API using a service account isn't supported", so a service account with domain-wide delegation
+//       acting as an admin (with_subject) is the documented path.
+//   docs.cloud.google.com/endpoint-verification/docs/device-information (last updated 2026-10-26):
+//       is_os_native_firewall_enabled "indicates whether the operating system's built-in firewall is enabled", on
+//       macOS, ChromeOS, Windows and Linux; device os_version examples "MacOS 13.4.0", "ChromeOs 14541.0.0",
+//       "Windows 10.0.19045".
+// Left out, with the reason:
+//   Screen lock: is_secured_with_screenlock is an access-level attribute on that page, but the Devices API Device
+//   resource has no such field, so it is not readable here.
+//   Android security patch (securityPatchTime): Android only; not judged.
+//   Rate limits: no Devices API quota page was found; a 429 or 403 rateLimitExceeded is retried (readonly_http.ts).
+//   The browser sign-in of google_workspace (google_oauth.ts) asks for the Admin SDK scopes only, so this source
+//   needs the service-account path.
+//
+// Personal data: a device is named by its id (from name) and serial. hostname, otherAccounts, wifiMacAddresses,
+// imei, meid, assetTag and every browser profile attribute are never read into a result.
+import { readFileSync } from "node:fs";
+import { cachedToken, googleAssertion, tokenRequest } from "./oauth.js";
+import { OAUTH_ENV } from "./google_oauth.js";
+import { GOOGLE_ENV, isGoogleTokenUri } from "./google_workspace.js";
+import { Emitter, enc, fetchRest, getAll, isObj, realSleep, redact, str, withRetry, listRead, stampRead } from "./readonly_http.js";
+import { ageDays, cmpVersion, deviceResource, minOsOption, posInt, showVersion, versionIn } from "./device_common.js";
+export const DEVICES_BASE = "https://cloudidentity.googleapis.com";
+export const DEVICES_SCOPE = "https://www.googleapis.com/auth/cloud-identity.devices.readonly";
+export const GE_CHECKS = ["disk_encryption", "firewall", "os_minimum", "last_sync", "compromised"];
+export const DEFAULTS = { syncDays: 14, maxDevices: 5000 };
+export const PAGE = 100;
+export const devicesPath = (customer, pageToken) => `/v1/devices?customer=${enc(`customers/${customer}`)}&pageSize=${PAGE}&view=USER_ASSIGNED_DEVICES${pageToken ? `&pageToken=${enc(pageToken)}` : ""}`;
+/** deviceType → the names --google-endpoints-min-os accepts for it (the lower-cased enum value always works). */
+const ALIASES = { MAC_OS: ["macos"], CHROME_OS: ["chromeos"], WINDOWS: [], LINUX: [], ANDROID: [], IOS: [] };
+/** A Cloud Identity client whose token holds only DEVICES_SCOPE, as GOOGLE_ADMIN_EMAIL, or what is missing. */
+export function googleDevicesFromEnv(env, fetchFn = fetch) {
+    const file = env[GOOGLE_ENV.keyFile], admin = env[GOOGLE_ENV.admin];
+    if (!file && env[OAUTH_ENV.clientFile])
+        return `the browser sign-in does not ask for ${DEVICES_SCOPE}; this source needs the service-account path (${GOOGLE_ENV.keyFile} with domain-wide delegation)`;
+    if (!file || !admin)
+        return `${GOOGLE_ENV.keyFile} and ${GOOGLE_ENV.admin} are not both set`;
+    let key;
+    try {
+        key = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        return `${GOOGLE_ENV.keyFile} is not a readable service account key (${e.code ?? "bad JSON"})`;
+    }
+    if (typeof key.client_email !== "string" || typeof key.private_key !== "string")
+        return `${GOOGLE_ENV.keyFile} has no client_email or private_key`;
+    const tokenUri = key.token_uri ?? "https://oauth2.googleapis.com/token";
+    // The key file names its own token endpoint; a tampered file could send the signed assertion elsewhere.
+    if (!isGoogleTokenUri(tokenUri))
+        return `${GOOGLE_ENV.keyFile} names a token_uri outside googleapis.com over HTTPS`;
+    const token = cachedToken(() => tokenRequest(tokenUri, {
+        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+        assertion: googleAssertion(key, admin, [DEVICES_SCOPE], Math.floor(Date.now() / 1000)),
+    }, fetchFn));
+    return fetchRest({ base: DEVICES_BASE, fetchFn, headers: async () => ({ authorization: `Bearer ${await token()}` }) });
+}
+const sub = (o, k) => (isObj(o[k]) ? o[k] : {});
+export async function googleEndpointChecks(api, customer, o, now) {
+    const out = new Emitter("google_endpoints", `google endpoints customer ${customer}`);
+    const maxPages = Math.ceil(o.maxDevices / PAGE);
+    const got = await getAll(api, devicesPath(customer), (b) => (isObj(b) ? (Array.isArray(b.devices) ? b.devices : []) : undefined), (r) => { const t = isObj(r.body) ? str(r.body.nextPageToken) : undefined; return t ? devicesPath(customer, t) : undefined; }, maxPages);
+    const need = `the service account's domain-wide delegation needs ${DEVICES_SCOPE}, acting as ${GOOGLE_ENV.admin}`;
+    if ("error" in got) {
+        for (const c of GE_CHECKS)
+            out.skip(c, got.error, `Cloud Identity devices (${need})`);
+        return out.results;
+    }
+    const devices = got.items.filter(isObj).slice(0, o.maxDevices);
+    const truncated = got.truncated || got.items.length > o.maxDevices;
+    if (!devices.length) {
+        out.skipAll(GE_CHECKS, "Cloud Identity lists no device with a registered user; nothing to judge");
+        return out.results;
+    }
+    const cap = truncated ? `; only the first ${o.maxDevices} devices read (--google-endpoints-max-devices)` : "";
+    const from = out.results.length;
+    if (!o.minOs.size)
+        out.add("os_minimum", "skipped", `no minimum OS version given (--google-endpoints-min-os, e.g. mac_os=15.0, windows=10.0.26100, chrome_os=16000); ${devices.length} device(s) not judged`);
+    for (const d of devices) {
+        const id = String(d.name ?? "?").replace(/^devices\//, "");
+        const res = deviceResource("google device", id, d.serialNumber);
+        const type = str(d.deviceType) ?? "DEVICE_TYPE_UNSPECIFIED";
+        const where = ` (${type}, ${str(d.osVersion) ?? "OS version not reported"})`;
+        const es = str(d.encryptionState);
+        if (es === "ENCRYPTED")
+            out.add("disk_encryption", "pass", `encryptionState is ENCRYPTED${where}${cap}`, res);
+        else if (es === "NOT_ENCRYPTED")
+            out.add("disk_encryption", "fail", `encryptionState is NOT_ENCRYPTED; ENCRYPTED required${where}`, res);
+        else
+            out.add("disk_encryption", "skipped", `encryptionState is ${es ?? "not reported"}, which does not show encryption${where}`, res);
+        // Firewall: only Endpoint Verification reports it, in additionalSignals.
+        const ev = d.endpointVerificationSpecificAttributes;
+        const fw = isObj(ev) ? sub(ev, "additionalSignals").is_os_native_firewall_enabled : undefined;
+        if (typeof fw === "boolean")
+            out.add("firewall", fw ? "pass" : "fail", `Endpoint Verification is_os_native_firewall_enabled is ${fw}${where}`, res);
+        else
+            out.add("firewall", "skipped", `${isObj(ev) ? "Endpoint Verification reports no is_os_native_firewall_enabled" : "not an Endpoint Verification device, so no firewall signal"}${where}`, res);
+        if (o.minOs.size) {
+            const floor = [type.toLowerCase(), ...(ALIASES[type] ?? [])].map((k) => o.minOs.get(k)).find(Boolean) ?? o.minOs.get("*");
+            const have = versionIn(d.osVersion);
+            if (!floor)
+                out.add("os_minimum", "skipped", `no --google-endpoints-min-os floor for ${type}${where}`, res);
+            else if (!have)
+                out.add("os_minimum", "skipped", `osVersion not reported${where}`, res);
+            else {
+                const okv = cmpVersion(have, floor) >= 0;
+                out.add("os_minimum", okv ? "pass" : "fail", `osVersion ${showVersion(have)} ${okv ? "meets" : "is below"} the --google-endpoints-min-os floor ${showVersion(floor)}${where}`, res);
+            }
+        }
+        const age = ageDays(d.lastSyncTime, now);
+        if (age === undefined)
+            out.add("last_sync", "skipped", `lastSyncTime not reported${where}`, res);
+        else
+            out.add("last_sync", age <= o.syncDays ? "pass" : "fail", `last synced ${age} day(s) ago; at most ${o.syncDays} allowed (--google-endpoints-sync-days)${where}`, res);
+        const cs = str(d.compromisedState);
+        if (cs === "UNCOMPROMISED")
+            out.add("compromised", "pass", `compromisedState is UNCOMPROMISED${where}`, res);
+        else if (cs === "COMPROMISED")
+            out.add("compromised", "fail", `compromisedState is COMPROMISED${where}`, res);
+        else
+            out.add("compromised", "skipped", `compromisedState is ${cs ?? "not reported"}${where}`, res);
+    }
+    stampRead(out.results, from, listRead({ items: devices, truncated, pages: got.pages })); // a capped list leaves devices unseen
+    return out.results;
+}
+export const googleEndpoints = {
+    name: "google_endpoints",
+    options: {
+        "google-endpoints-sync-days": { type: "string", help: `days since a device last synced before last_sync fails (default ${DEFAULTS.syncDays})` },
+        "google-endpoints-min-os": { type: "string", multiple: true, help: "<deviceType>=<version> floor for os_minimum, e.g. mac_os=15.0, windows=10.0.26100, chrome_os=16000, android=15, ios=18.0 (repeatable; without it the check is skipped)" },
+        "google-endpoints-max-devices": { type: "string", help: `devices read, at most (default ${DEFAULTS.maxDevices})` },
+    },
+    emits: GE_CHECKS.map((c) => `google_endpoints.${c}`),
+    describe: () => "Google endpoint management for the customer in GOOGLE_CUSTOMER_ID (default my_customer), Cloud Identity Devices API",
+    async run(ctx) {
+        const customer = ctx.env[GOOGLE_ENV.customer] || "my_customer";
+        const given = ctx.clients.google_endpoints;
+        const built = given !== undefined ? given : googleDevicesFromEnv(ctx.env);
+        if (!built || typeof built === "string") {
+            const out = new Emitter("google_endpoints", `google endpoints customer ${customer}`);
+            out.skipAll(GE_CHECKS, typeof built === "string" ? built : "no Cloud Identity client");
+            return out.results;
+        }
+        const api = withRetry(built, ctx.clients.sleep ?? realSleep);
+        const o = {
+            syncDays: posInt(ctx.opts["google-endpoints-sync-days"], DEFAULTS.syncDays),
+            maxDevices: posInt(ctx.opts["google-endpoints-max-devices"], DEFAULTS.maxDevices),
+            minOs: minOsOption(ctx.opts["google-endpoints-min-os"]),
+        };
+        return redact(await googleEndpointChecks(api, customer, o, ctx.now), []);
+    },
+};