@sagentix-inc/evidence-collector 0.3.5 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +137 -9
  2. package/apps/sos-app/src/data/checks/aws.json +12 -0
  3. package/apps/sos-app/src/data/checks/azure.json +18 -0
  4. package/apps/sos-app/src/data/checks/bamboohr.json +40 -0
  5. package/apps/sos-app/src/data/checks/entra.json +1 -1
  6. package/apps/sos-app/src/data/checks/gcp.json +12 -0
  7. package/apps/sos-app/src/data/checks/intune.json +7 -1
  8. package/apps/sos-app/src/data/checks/jamf.json +8 -2
  9. package/apps/sos-app/src/data/checks/kandji.json +7 -1
  10. package/apps/sos-app/src/data/checks/rippling.json +40 -0
  11. package/apps/sos-app/src/data/checks/vulnscan.json +27 -0
  12. package/apps/sos-app/src/data/checks/web.json +31 -1
  13. package/collector/package.json +1 -1
  14. package/collector/src/cli.js +344 -37
  15. package/collector/src/config.js +12 -0
  16. package/collector/src/doctor.js +382 -0
  17. package/collector/src/policies.js +160 -0
  18. package/collector/src/pool.js +19 -0
  19. package/collector/src/report.js +88 -16
  20. package/collector/src/sources/aws/checks.js +64 -0
  21. package/collector/src/sources/aws.js +6 -1
  22. package/collector/src/sources/azure/api.js +4 -0
  23. package/collector/src/sources/azure/checks.js +91 -1
  24. package/collector/src/sources/azure.js +8 -2
  25. package/collector/src/sources/bamboohr.js +133 -0
  26. package/collector/src/sources/cloudflare/api.js +24 -4
  27. package/collector/src/sources/device_common.js +42 -0
  28. package/collector/src/sources/directory.js +198 -0
  29. package/collector/src/sources/engines.js +2 -1
  30. package/collector/src/sources/entra.js +4 -3
  31. package/collector/src/sources/gcp/project.js +47 -3
  32. package/collector/src/sources/gcp.js +5 -2
  33. package/collector/src/sources/github.js +46 -8
  34. package/collector/src/sources/google_oauth.js +3 -3
  35. package/collector/src/sources/google_workspace.js +4 -3
  36. package/collector/src/sources/hris_common.js +189 -0
  37. package/collector/src/sources/index.js +3 -0
  38. package/collector/src/sources/intune.js +40 -3
  39. package/collector/src/sources/jamf.js +65 -8
  40. package/collector/src/sources/kandji.js +46 -7
  41. package/collector/src/sources/oauth.js +22 -0
  42. package/collector/src/sources/prowler.js +178 -52
  43. package/collector/src/sources/readonly_http.js +27 -5
  44. package/collector/src/sources/rippling.js +114 -0
  45. package/collector/src/sources/shared-cloud.js +14 -6
  46. package/collector/src/sources/vulnscan.js +386 -0
  47. package/collector/src/sources/web.js +106 -11
  48. package/collector/src/sources/web_privacy.js +266 -0
  49. package/package.json +1 -1
@@ -1,19 +1,39 @@
1
1
  // Read-only Cloudflare API v4 client. It has a GET method and nothing else, so a bug here cannot
2
2
  // change the customer's account. Tests pass a fake client; nothing in tests touches the network.
3
+ import { realSleep, withRetry } from "../readonly_http.js";
3
4
  export const CF_API_BASE = "https://api.cloudflare.com/client/v4";
4
5
  export const TOKEN_ENV = "CLOUDFLARE_API_TOKEN_READONLY";
5
- export function fetchCloudflareApi(token, fetchFn = fetch, base = CF_API_BASE) {
6
- return {
6
+ /**
7
+ * GET only. A 429 is retried up to 4 times and a 502, 503, 504 or network failure up to twice, waiting Retry-After
8
+ * when given (Cloudflare's rate limit is 1,200 requests per five minutes per user,
9
+ * https://developers.cloudflare.com/fundamentals/api/reference/limits/, read 2026-11-07), else 1 s doubling.
10
+ */
11
+ export function fetchCloudflareApi(token, fetchFn = fetch, base = CF_API_BASE, sleep = realSleep) {
12
+ const raw = {
7
13
  async get(path) {
8
14
  const res = await fetchFn(`${base}${path}`, { method: "GET", headers: { authorization: `Bearer ${token}`, accept: "application/json" } });
15
+ const headers = {};
16
+ res.headers?.forEach((v, k) => { headers[k.toLowerCase()] = v; });
17
+ // Should an answer ever echo the token, it is cut out before anything reads it (as fetchRest does).
18
+ const text = token.length >= 8 ? (await res.text()).split(token).join("[redacted]") : await res.text();
9
19
  let body = null;
10
20
  try {
11
- body = await res.json();
21
+ body = text ? JSON.parse(text) : null;
12
22
  }
13
23
  catch {
14
24
  body = null;
15
25
  }
16
- return { status: res.status, body };
26
+ return { status: res.status, headers, body };
27
+ },
28
+ };
29
+ const api = withRetry(raw, sleep);
30
+ return {
31
+ async get(path) {
32
+ const r = await api.get(path);
33
+ // A thrown failure comes back as status 0, in the shape safeGet gives it.
34
+ if (r.status === 0 && isObj(r.body) && typeof r.body.message === "string")
35
+ return { status: 0, body: { success: false, errors: [{ message: r.body.message }] } };
36
+ return { status: r.status, body: r.body };
17
37
  },
18
38
  };
19
39
  }
@@ -68,3 +68,45 @@ export const posInt = (v, dflt) => {
68
68
  };
69
69
  /** Values of a repeatable string option. */
70
70
  export const many = (v) => (Array.isArray(v) ? v.map(String) : typeof v === "string" ? [v] : []).flatMap((s) => s.split(",")).map((s) => s.trim()).filter(Boolean);
71
+ // ── Wipe and retire records (2026-11-07; SOC 2 CC6.5, SP 800-53 mp-6 and sr-12): a device leaving service is wiped or
72
+ // retired by a recorded MDM action that finished. Each source reads its own action log into WipeAction rows.
73
+ export const WIPE_DEFAULTS = { periodDays: 365, graceDays: 7 };
74
+ /**
75
+ * One result per device with a wipe, retire or removal action in the period: pass when a wipe or retire finished; fail
76
+ * when it failed, stayed pending past the grace days, or the device was only removed from management with no wipe or
77
+ * retire recorded; skipped while a recent one is pending. Returns how many devices it judged.
78
+ */
79
+ export function judgeWipes(actions, o, add) {
80
+ const by = new Map();
81
+ for (const a of actions) {
82
+ const t = Date.parse(a.requested);
83
+ if (!Number.isFinite(t) || t < o.since || t > o.now.getTime())
84
+ continue;
85
+ by.set(a.resource, [...(by.get(a.resource) ?? []), a]);
86
+ }
87
+ const show = (a) => `${a.action} ${a.stateRaw}, requested ${a.requested.slice(0, 10)}${a.completed ? `, completed ${a.completed.slice(0, 10)}` : ""}`;
88
+ for (const [res, xs] of by) {
89
+ xs.sort((a, b) => Date.parse(a.requested) - Date.parse(b.requested));
90
+ const wipes = xs.filter((a) => !a.removalOnly);
91
+ const done = wipes.find((a) => a.state === "done");
92
+ if (done) {
93
+ add(res, "pass", `${show(done)}${o.where}`);
94
+ continue;
95
+ }
96
+ if (!wipes.length) {
97
+ add(res, "fail", `removed from management (${xs.map(show).join("; ")}) with no wipe or retire recorded${o.where}`);
98
+ continue;
99
+ }
100
+ const last = wipes[wipes.length - 1];
101
+ if (last.state === "failed") {
102
+ add(res, "fail", `${show(last)}; a finished wipe or retire is required${o.where}`);
103
+ continue;
104
+ }
105
+ const age = Math.floor((o.now.getTime() - Date.parse(last.requested)) / DAY_MS);
106
+ if (age > o.graceDays)
107
+ add(res, "fail", `${show(last)}, not finished after ${age} days (at most ${o.graceDays} allowed)${o.where}`);
108
+ else
109
+ add(res, "skipped", `${show(last)}, pending for ${age} day(s); judged once it finishes or ${o.graceDays} days pass${o.where}`);
110
+ }
111
+ return by.size;
112
+ }
@@ -0,0 +1,198 @@
1
+ // The identity provider's side of the HR leaver check (hris.ts): given the work email of a person who left, is their
2
+ // account still active, and when was it disabled or deleted? It reuses the identity sources' own clients and the
3
+ // credentials the customer already gave them (okta.ts, entra.ts, google_workspace.ts, jumpcloud.ts), so it adds no
4
+ // permission and no check of its own: the identity sources keep their checks, and this answers one question per person.
5
+ // GET only. A person is looked up by email; the email goes to the customer's own identity provider and never into a result.
6
+ //
7
+ // Endpoints, fields and permissions (all read 2026-11-07):
8
+ // Okta GET /api/v1/users?search=profile.email eq "<email>" okta.users.read
9
+ // "Returned users include those with the DEPROVISIONED status" (search); status is one of ACTIVE,
10
+ // DEPROVISIONED, LOCKED_OUT, PASSWORD_EXPIRED, PROVISIONED, RECOVERY, STAGED, SUSPENDED; statusChanged is
11
+ // "The timestamp when the status of the user last changed".
12
+ // https://developer.okta.com/docs/api/openapi/okta-management/management/tags/user/other/listusers
13
+ // Entra GET /users?$filter=mail eq '<email>' or userPrincipalName eq '<email>'&$select=id,accountEnabled User.Read.All
14
+ // No user property records when accountEnabled became false, so the time comes from
15
+ // GET /auditLogs/directoryAudits?$filter=activityDisplayName eq 'Disable account' and targetResources/any(t:t/id eq '<id>')
16
+ // (AuditLog.Read.All; targetResources "Supports $filter (eq) for id and displayName"; kept 7 days on Entra ID
17
+ // Free, 30 on P1 or P2). A user not found is looked for among deleted users,
18
+ // GET /directory/deletedItems/microsoft.graph.user?$filter=mail eq '<email>'&$select=id,deletedDateTime (User.Read.All,
19
+ // kept 30 days after deletion).
20
+ // https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0
21
+ // https://learn.microsoft.com/en-us/graph/api/resources/directoryaudit?view=graph-rest-1.0
22
+ // https://learn.microsoft.com/en-us/graph/api/directory-deleteditems-list?view=graph-rest-1.0
23
+ // https://learn.microsoft.com/en-us/entra/identity/monitoring-health/reference-reports-data-retention
24
+ // Google GET /admin/directory/v1/users/<email> admin.directory.user.readonly
25
+ // suspended ("Indicates if user is suspended"), suspensionTime ("User's account suspension time"), archived.
26
+ // A deleted user is not returned; its time comes from the Reports API, GET /admin/reports/v1/activity/users/all/
27
+ // applications/admin?eventName=DELETE_USER&filters=USER_EMAIL==<email> (admin.reports.audit.readonly; id.time;
28
+ // admin log events kept 6 months).
29
+ // https://developers.google.com/workspace/admin/directory/reference/rest/v1/users
30
+ // https://developers.google.com/workspace/admin/reports/reference/rest/v1/activities/list
31
+ // https://developers.google.com/workspace/admin/reports/v1/appendix/activity/admin-user-settings
32
+ // JumpCloud GET /api/systemusers?filter=email:$eq:<email>&fields=_id suspended state users.readonly
33
+ // suspended, state (STAGED, ACTIVATED, SUSPENDED). No field dates a suspension, and Directory Insights, which
34
+ // does, is POST only (https://docs.jumpcloud.com/api/insights/directory/1.0/index.html), so a JumpCloud answer
35
+ // is the state alone. https://docs.jumpcloud.com/api/1.0/index.html
36
+ import { entraFromEnv } from "./entra.js";
37
+ import { googleFromEnv } from "./google_workspace.js";
38
+ import { jumpcloudFromEnv } from "./jumpcloud.js";
39
+ import { oktaFromEnv } from "./okta.js";
40
+ import { arr, enc, isObj, ok, realSleep, str, why, withRetry } from "./readonly_http.js";
41
+ export const IDPS = ["okta", "entra", "google_workspace", "jumpcloud"];
42
+ const q = (s) => s.replace(/'/g, "''"); // OData string literal
43
+ const dq = (s) => s.replace(/["\\]/g, ""); // Okta search literal: an email has neither
44
+ const first = (b, key = "value") => {
45
+ const xs = Array.isArray(b) ? b : isObj(b) ? arr(b[key]) : [];
46
+ return xs.find(isObj);
47
+ };
48
+ const err = (r, what) => ({ state: "error", why: `${what}: ${why(r)}` });
49
+ export function oktaDirectory(api) {
50
+ return {
51
+ idp: "okta",
52
+ async lookup(email) {
53
+ const r = await api.get(`/api/v1/users?search=${enc(`profile.email eq "${dq(email)}"`)}&limit=2`);
54
+ if (!ok(r) || !Array.isArray(r.body))
55
+ return err(r, "Okta user search");
56
+ const u = first(r.body);
57
+ if (!u)
58
+ return { state: "absent" };
59
+ const id = String(u.id ?? "?"), status = str(u.status);
60
+ if (status === "DEPROVISIONED" || status === "SUSPENDED")
61
+ return { state: "disabled", id, at: str(u.statusChanged), how: `Okta status ${status}` };
62
+ return { state: "active", id };
63
+ },
64
+ };
65
+ }
66
+ export function entraDirectory(api) {
67
+ return {
68
+ idp: "entra",
69
+ async lookup(email) {
70
+ const e = q(email);
71
+ const r = await api.get(`/users?$filter=${enc(`mail eq '${e}' or userPrincipalName eq '${e}'`)}&$select=id,accountEnabled`);
72
+ if (!ok(r))
73
+ return err(r, "Entra user lookup");
74
+ const u = first(r.body);
75
+ if (u) {
76
+ const id = String(u.id ?? "?");
77
+ if (u.accountEnabled !== false)
78
+ return { state: "active", id };
79
+ const a = await api.get(`/auditLogs/directoryAudits?$filter=${enc(`activityDisplayName eq 'Disable account' and targetResources/any(t:t/id eq '${q(id)}')`)}&$top=1`);
80
+ const ev = ok(a) ? first(a.body) : undefined;
81
+ return { state: "disabled", id, at: ev ? str(ev.activityDateTime) : undefined, how: "Entra accountEnabled false" };
82
+ }
83
+ const d = await api.get(`/directory/deletedItems/microsoft.graph.user?$filter=${enc(`mail eq '${e}'`)}&$select=id,deletedDateTime`);
84
+ const du = ok(d) ? first(d.body) : undefined;
85
+ if (du)
86
+ return { state: "deleted", id: String(du.id ?? "?"), at: str(du.deletedDateTime), how: "Entra deleted user" };
87
+ return { state: "absent" };
88
+ },
89
+ };
90
+ }
91
+ export function googleDirectory(api) {
92
+ return {
93
+ idp: "google_workspace",
94
+ async lookup(email) {
95
+ const r = await api.get(`/admin/directory/v1/users/${enc(email)}`);
96
+ if (ok(r) && isObj(r.body)) {
97
+ const id = String(r.body.id ?? "?");
98
+ if (r.body.suspended === true)
99
+ return { state: "disabled", id, at: str(r.body.suspensionTime), how: "Google suspended" };
100
+ if (r.body.archived === true)
101
+ return { state: "disabled", id, how: "Google archived" };
102
+ return { state: "active", id };
103
+ }
104
+ if (r.status !== 404)
105
+ return err(r, "Google user lookup");
106
+ const a = await api.get(`/admin/reports/v1/activity/users/all/applications/admin?eventName=DELETE_USER&filters=${enc(`USER_EMAIL==${email}`)}&maxResults=1`);
107
+ const ev = ok(a) ? first(a.body, "items") : undefined;
108
+ if (ev)
109
+ return { state: "deleted", at: isObj(ev.id) ? str(ev.id.time) : undefined, how: "Google DELETE_USER event" };
110
+ return { state: "absent" };
111
+ },
112
+ };
113
+ }
114
+ export function jumpcloudDirectory(api) {
115
+ return {
116
+ idp: "jumpcloud",
117
+ async lookup(email) {
118
+ const r = await api.get(`/systemusers?filter=${enc(`email:$eq:${email}`)}&fields=${enc("_id suspended state")}&limit=2`);
119
+ if (!ok(r) || !isObj(r.body))
120
+ return err(r, "JumpCloud user lookup");
121
+ const u = first(r.body, "results");
122
+ if (!u)
123
+ return { state: "absent" };
124
+ const id = String(u._id ?? "?");
125
+ if (u.suspended === true || u.state === "SUSPENDED")
126
+ return { state: "disabled", id, how: "JumpCloud suspended (no time recorded)" };
127
+ return { state: "active", id };
128
+ },
129
+ };
130
+ }
131
+ // One directory per identity provider for the whole run (2026-11-07): BambooHR and Rippling joined with the same provider
132
+ // share it, and a leaver both name is looked up once. Keyed by the run's clients object, which every source of one run
133
+ // shares (cli.ts) and each test builds afresh.
134
+ const directories = new WeakMap();
135
+ /** A directory whose answers are kept per email for the rest of the run; an error is not kept, so the next asker tries again. */
136
+ export function memoDirectory(d) {
137
+ const seen = new Map();
138
+ return {
139
+ idp: d.idp,
140
+ lookup(email) {
141
+ const k = email.toLowerCase();
142
+ let p = seen.get(k);
143
+ if (!p) {
144
+ p = d.lookup(email).then((a) => { if (a.state === "error")
145
+ seen.delete(k); return a; });
146
+ seen.set(k, p);
147
+ }
148
+ return p;
149
+ },
150
+ };
151
+ }
152
+ /** The directory for an identity provider, built from the client a test injected or that provider's own variables; else why not. */
153
+ export function directoryFor(idp, ctx) {
154
+ const key = `${idp}\n${String(ctx.opts["jumpcloud-region"] ?? "")}\n${String(ctx.opts["jumpcloud-org-id"] ?? "")}`;
155
+ let byIdp = directories.get(ctx.clients);
156
+ if (!byIdp) {
157
+ byIdp = new Map();
158
+ directories.set(ctx.clients, byIdp);
159
+ }
160
+ let d = byIdp.get(key);
161
+ if (d === undefined) {
162
+ d = buildDirectory(idp, ctx);
163
+ if (typeof d !== "string")
164
+ d = memoDirectory(d);
165
+ byIdp.set(key, d);
166
+ }
167
+ return d;
168
+ }
169
+ function buildDirectory(idp, ctx) {
170
+ const sleep = ctx.clients.sleep ?? realSleep;
171
+ const pick = (key, build) => {
172
+ const given = ctx.clients[key];
173
+ const b = given !== undefined ? given : build();
174
+ if (!b)
175
+ return `no ${idp} client`;
176
+ return typeof b === "string" ? b : withRetry(b, sleep);
177
+ };
178
+ const o = ctx.opts;
179
+ let api;
180
+ switch (idp) {
181
+ case "okta":
182
+ api = pick("okta", () => oktaFromEnv(ctx.env));
183
+ return typeof api === "string" ? api : oktaDirectory(api);
184
+ case "entra":
185
+ api = pick("entra", () => entraFromEnv(ctx.env));
186
+ return typeof api === "string" ? api : entraDirectory(api);
187
+ case "google_workspace":
188
+ api = pick("google", () => googleFromEnv(ctx.env));
189
+ return typeof api === "string" ? api : googleDirectory(api);
190
+ case "jumpcloud":
191
+ api = pick("jumpcloud", () => jumpcloudFromEnv(ctx.env, { region: typeof o["jumpcloud-region"] === "string" ? o["jumpcloud-region"] : undefined,
192
+ orgId: typeof o["jumpcloud-org-id"] === "string" ? o["jumpcloud-org-id"] : undefined }));
193
+ return typeof api === "string" ? api : jumpcloudDirectory(api);
194
+ default: return `unknown identity provider "${idp}"; one of ${IDPS.join(", ")}`;
195
+ }
196
+ }
197
+ /** The secrets the identity providers' clients read, for scrubbing results. */
198
+ export const IDP_SECRETS = (env) => [env.OKTA_API_TOKEN, env.OKTA_ACCESS_TOKEN, env.ENTRA_CLIENT_SECRET, env.JUMPCLOUD_API_KEY];
@@ -8,4 +8,5 @@ import { pagerduty } from "./pagerduty.js";
8
8
  import { stig } from "./stig.js";
9
9
  import { kubescape } from "./kubescape.js";
10
10
  import { checkov } from "./checkov.js";
11
- export const ENGINE_SOURCES = [scubagoggles, scubagear, trivy, grype, syft, gitleaks, scorecard, pagerduty, stig, kubescape, checkov];
11
+ import { vulnscan } from "./vulnscan.js";
12
+ export const ENGINE_SOURCES = [scubagoggles, scubagear, trivy, grype, syft, gitleaks, scorecard, pagerduty, stig, kubescape, checkov, vulnscan];
@@ -80,7 +80,7 @@
80
80
  //
81
81
  // Personal data: results carry counts and Entra object ids, never user principal names or names.
82
82
  import { readFileSync } from "node:fs";
83
- import { cachedToken, entraClientAssertion, tokenRequest } from "./oauth.js";
83
+ import { cachedToken, entraClientAssertion, sharedToken, tokenRequest } from "./oauth.js";
84
84
  import { DAY_MS, Emitter, arr, enc, fetchRest, firstIds, getAll, intOpt, isObj, ok, realSleep, redact, str, why, withRetry, listRead } from "./readonly_http.js";
85
85
  export const GRAPH_BASE = "https://graph.microsoft.com/v1.0";
86
86
  export const ENTRA_ENV = { tenant: "ENTRA_TENANT_ID", client: "ENTRA_CLIENT_ID", secret: "ENTRA_CLIENT_SECRET", cert: "ENTRA_CLIENT_CERT_FILE" };
@@ -109,7 +109,8 @@ export function entraFromEnv(env, fetchFn = fetch, target = { base: GRAPH_BASE,
109
109
  if (!tenant || !client || (!secret && !certFile))
110
110
  return `${ENTRA_ENV.tenant}, ${ENTRA_ENV.client} and ${ENTRA_ENV.secret} or ${ENTRA_ENV.cert} are not all set`;
111
111
  const url = `https://login.microsoftonline.com/${enc(tenant)}/oauth2/v2.0/token`;
112
- const token = cachedToken(() => {
112
+ // Shared with every other client of this app and scope in the run (Intune, the HR leaver join): one token request.
113
+ const token = sharedToken(fetchFn, ["entra", tenant, client, target.scope, secret ?? "", certFile ?? ""], () => cachedToken(() => {
113
114
  const form = { grant_type: "client_credentials", client_id: client, scope: target.scope };
114
115
  if (certFile) {
115
116
  form.client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
@@ -118,7 +119,7 @@ export function entraFromEnv(env, fetchFn = fetch, target = { base: GRAPH_BASE,
118
119
  else
119
120
  form.client_secret = secret;
120
121
  return tokenRequest(url, form, fetchFn);
121
- });
122
+ }));
122
123
  return fetchRest({ base: target.base, fetchFn, headers: async () => ({ authorization: `Bearer ${await token()}` }) });
123
124
  }
124
125
  const enabled = (p) => p.state === "enabled";
@@ -15,6 +15,8 @@
15
15
  // GET storage v1 b?project={p} roles/viewer (storage.buckets.list)
16
16
  // GET storage v1 b/{bucket}/iam roles/iam.securityReviewer (storage.buckets.getIamPolicy)
17
17
  // GET sqladmin v1 projects/{p}/instances roles/viewer (cloudsql.instances.list)
18
+ // GET sqladmin v1 projects/{p}/instances/{i}/backupRuns roles/viewer (cloudsql.backupRuns.list)
19
+ // GET logging v2 projects/{p}/locations/-/buckets roles/logging.viewer (logging.buckets.list)
18
20
  // GET compute v1 projects/{p}/global/firewalls roles/viewer (compute.firewalls.list)
19
21
  // GET compute v1 projects/{p}/aggregated/subnetworks roles/viewer (compute.subnetworks.list)
20
22
  // GET serviceusage v1 projects/{p}/services/securitycenter.googleapis.com roles/viewer (serviceusage.services.get)
@@ -24,7 +26,7 @@ import { Gcp, gWhy, okStatus } from "./api.js";
24
26
  export const GCP_CHECKS = [
25
27
  "data_access_audit_logs", "org_policy_enforced", "sa_keys_rotated", "bucket_not_public",
26
28
  "cloudsql_no_public_ip", "cloudsql_ssl_required", "firewall_no_open_admin_ports", "scc_api_enabled",
27
- "kms_rotation", "vpc_flow_logs", "vm_os_vulnerabilities",
29
+ "kms_rotation", "vpc_flow_logs", "vm_os_vulnerabilities", "cloudsql_backup_runs_succeeded", "log_bucket_retention",
28
30
  ];
29
31
  /** Oldest a VM's OS Config vulnerability report may be. */
30
32
  export const MAX_VULN_REPORT_DAYS = 7;
@@ -44,9 +46,11 @@ const COMPUTE = "https://compute.googleapis.com/compute/v1";
44
46
  const SERVICEUSAGE = "https://serviceusage.googleapis.com/v1";
45
47
  const KMS = "https://cloudkms.googleapis.com/v1";
46
48
  const OSCONFIG = "https://osconfig.googleapis.com/v1";
49
+ const LOGGING = "https://logging.googleapis.com/v2";
47
50
  const enc = encodeURIComponent;
48
51
  const OPEN = new Set(["0.0.0.0/0", "::/0"]);
49
52
  const PUBLIC_MEMBERS = new Set(["allUsers", "allAuthenticatedUsers"]);
53
+ export const DEFAULT_BACKUP_WINDOW_DAYS = 7, DEFAULT_LOG_RETENTION_DAYS = 365;
50
54
  const skipFor = (out, check, resource, what, r) => out.skip(check, resource, `${what} not readable: ${gWhy(r)}`);
51
55
  /** The log types of an IAM policy's allServices auditConfig. */
52
56
  const allServicesTypes = (policy) => {
@@ -130,7 +134,8 @@ export async function projectChecks(api, project, o, out) {
130
134
  }
131
135
  await serviceAccountKeys(api, project, o, out);
132
136
  await buckets(api, project, out);
133
- await cloudSql(api, project, out);
137
+ await cloudSql(api, project, o, out);
138
+ await logBuckets(api, project, o, out);
134
139
  await firewalls(api, project, out);
135
140
  const su = await api.get(`${SERVICEUSAGE}/${p}/services/securitycenter.googleapis.com`);
136
141
  if (!okStatus(su))
@@ -259,16 +264,18 @@ async function buckets(api, project, out) {
259
264
  out.add("bucket_not_public", res, roles.length ? "fail" : "pass", `publicAccessPrevention is ${j(pap ?? "unset")}; ${roles.length} role binding(s) grant allUsers or allAuthenticatedUsers${roles.length ? ` (${roles.slice(0, 10).join(", ")})` : ""}; none allowed`);
260
265
  }
261
266
  }
262
- async function cloudSql(api, project, out) {
267
+ async function cloudSql(api, project, o, out) {
263
268
  const pr = `project ${project}`;
264
269
  const s = await api.getAll(`${SQL}/projects/${enc(project)}/instances`, "items");
265
270
  if ("error" in s) {
266
271
  skipFor(out, "cloudsql_no_public_ip", pr, "Cloud SQL instances", s.error);
272
+ skipFor(out, "cloudsql_backup_runs_succeeded", pr, "Cloud SQL instances", s.error);
267
273
  return skipFor(out, "cloudsql_ssl_required", pr, "Cloud SQL instances", s.error);
268
274
  }
269
275
  const list = s.items.filter(isObj);
270
276
  if (!list.length) {
271
277
  out.skip("cloudsql_no_public_ip", pr, "the project has no Cloud SQL instance");
278
+ out.skip("cloudsql_backup_runs_succeeded", pr, "the project has no Cloud SQL instance");
272
279
  return out.skip("cloudsql_ssl_required", pr, "the project has no Cloud SQL instance");
273
280
  }
274
281
  for (const i of list) {
@@ -280,6 +287,43 @@ async function cloudSql(api, project, out) {
280
287
  const mode = str(ip.sslMode);
281
288
  const enforced = mode ? ["ENCRYPTED_ONLY", "TRUSTED_CLIENT_CERTIFICATE_REQUIRED"].includes(mode) : ip.requireSsl === true;
282
289
  out.add("cloudsql_ssl_required", res, enforced ? "pass" : "fail", `sslMode is ${j(mode ?? "unset")}, requireSsl is ${j(ip.requireSsl)}; ENCRYPTED_ONLY or TRUSTED_CLIENT_CERTIFICATE_REQUIRED (or requireSsl true when sslMode is unset) required`);
290
+ await backupRuns(api, project, String(i.name ?? ""), res, o, out);
291
+ }
292
+ }
293
+ // Cloud SQL Admin API v1 backupRuns.list (GET projects/{p}/instances/{i}/backupRuns; cloudsql.backupRuns.list, in
294
+ // roles/cloudsql.viewer and roles/viewer): the latest finished run in the window must be SUCCESSFUL. A failed run
295
+ // followed by a successful one is recovered.
296
+ async function backupRuns(api, project, instance, res, o, out) {
297
+ const r = await api.getAll(`${SQL}/projects/${enc(project)}/instances/${enc(instance)}/backupRuns?maxResults=100`, "items", 3);
298
+ if ("error" in r)
299
+ return skipFor(out, "cloudsql_backup_runs_succeeded", res, "backup runs", r.error);
300
+ const since = o.now.getTime() - o.backupWindowDays * 86_400_000;
301
+ const runs = r.items.filter(isObj).map((x) => ({ status: String(x.status ?? ""), at: Date.parse(String(x.windowStartTime ?? x.enqueuedTime ?? x.startTime ?? "")) || 0 }))
302
+ .filter((x) => x.at >= since && ["SUCCESSFUL", "FAILED", "SKIPPED", "DELETION_FAILED"].includes(x.status)).sort((a, b) => b.at - a.at);
303
+ if (!runs.length)
304
+ return out.add("cloudsql_backup_runs_succeeded", res, "fail", `no finished backup run in the last ${o.backupWindowDays} days; a SUCCESSFUL latest run required (automated backups may be off: see cloudsql_instance_automated_backups)`);
305
+ const failed = runs.filter((x) => x.status !== "SUCCESSFUL").length;
306
+ out.add("cloudsql_backup_runs_succeeded", res, runs[0].status === "SUCCESSFUL" ? "pass" : "fail", `${runs.length} run(s) in the last ${o.backupWindowDays} days, ${failed} not successful; latest ${runs[0].status} on ${new Date(runs[0].at).toISOString().slice(0, 10)}; latest SUCCESSFUL required`);
307
+ }
308
+ // Cloud Logging API v2 projects.locations.buckets.list (GET projects/{p}/locations/-/buckets; logging.buckets.list, in
309
+ // roles/logging.viewer): each log bucket's retentionDays must reach the required period. _Required is fixed by Google
310
+ // (400 days) and is reported, not judged; _Default and buckets the organization made are judged.
311
+ async function logBuckets(api, project, o, out) {
312
+ const pr = `project ${project}`;
313
+ const r = await api.getAll(`${LOGGING}/projects/${enc(project)}/locations/-/buckets`, "buckets");
314
+ if ("error" in r)
315
+ return skipFor(out, "log_bucket_retention", pr, "log buckets", r.error);
316
+ const judged = r.items.filter(isObj).filter((b) => !String(b.name ?? "").endsWith("/buckets/_Required") && b.lifecycleState !== "DELETE_REQUESTED");
317
+ if (!judged.length)
318
+ return out.skip("log_bucket_retention", pr, "no log bucket other than _Required");
319
+ for (const b of judged) {
320
+ const name = String(b.name ?? "?").replace(/^projects\/[^/]+\//, "");
321
+ const days = Number(b.retentionDays);
322
+ if (!Number.isFinite(days)) {
323
+ out.skip("log_bucket_retention", `log bucket ${project}/${name}`, "retentionDays not returned");
324
+ continue;
325
+ }
326
+ out.add("log_bucket_retention", `log bucket ${project}/${name}`, days >= o.logRetentionDays ? "pass" : "fail", `retentionDays ${days}${b.locked === true ? " (locked)" : ""}; at least ${o.logRetentionDays} required`);
283
327
  }
284
328
  }
285
329
  /** Admin ports (22, 3389) a firewall `allowed` entry opens. */
@@ -2,13 +2,15 @@
2
2
  // 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.
3
3
  import { Results, allSkipped, list, scrub } from "./shared-cloud.js";
4
4
  import { GCP_KEY_ENV, GCP_TOKEN_ENV, Gcp, fetchGcpTransport, gcpKeyToken } from "./gcp/api.js";
5
- import { DEFAULT_KEY_MAX_AGE_DAYS, DEFAULT_ORG_CONSTRAINTS, GCP_CHECKS, projectChecks } from "./gcp/project.js";
5
+ import { DEFAULT_BACKUP_WINDOW_DAYS, DEFAULT_KEY_MAX_AGE_DAYS, DEFAULT_LOG_RETENTION_DAYS, DEFAULT_ORG_CONSTRAINTS, GCP_CHECKS, projectChecks } from "./gcp/project.js";
6
6
  export const gcp = {
7
7
  name: "gcp",
8
8
  options: {
9
9
  "gcp-project": { type: "string", multiple: true, help: "GCP project id (repeatable or comma-separated); required" },
10
10
  "gcp-org-constraints": { type: "string", help: `boolean org policy constraints that must be enforced (default ${DEFAULT_ORG_CONSTRAINTS.join(",")})` },
11
11
  "gcp-key-max-age-days": { type: "string", help: `oldest a user-managed service account key may be (default ${DEFAULT_KEY_MAX_AGE_DAYS})` },
12
+ "gcp-backup-window-days": { type: "string", help: `days of Cloud SQL backup runs read; the latest must be SUCCESSFUL (default ${DEFAULT_BACKUP_WINDOW_DAYS})` },
13
+ "gcp-log-retention-days": { type: "string", help: `least log bucket retention accepted, in days (default ${DEFAULT_LOG_RETENTION_DAYS})` },
12
14
  },
13
15
  emits: GCP_CHECKS.map((c) => `gcp.${c}`),
14
16
  describe(opts) {
@@ -27,13 +29,14 @@ export const gcp = {
27
29
  return projects.flatMap((p) => allSkipped("gcp", GCP_CHECKS, `project ${p}`, typeof keyed === "string" ? keyed : `${GCP_TOKEN_ENV} or ${GCP_KEY_ENV} is not set`));
28
30
  const constraints = list(ctx.opts["gcp-org-constraints"]);
29
31
  const maxAge = Number(ctx.opts["gcp-key-max-age-days"] ?? DEFAULT_KEY_MAX_AGE_DAYS);
32
+ const days = (k, d) => { const n = Number(typeof ctx.opts[k] === "string" ? ctx.opts[k] : NaN); return Number.isFinite(n) && n > 0 ? n : d; };
30
33
  const api = new Gcp(t);
31
34
  const out = new Results("gcp");
32
35
  for (const p of projects) {
33
36
  await projectChecks(api, p, {
34
37
  orgConstraints: constraints.length ? constraints : DEFAULT_ORG_CONSTRAINTS,
35
38
  keyMaxAgeDays: Number.isFinite(maxAge) && maxAge > 0 ? maxAge : DEFAULT_KEY_MAX_AGE_DAYS,
36
- now: ctx.now,
39
+ now: ctx.now, backupWindowDays: days("gcp-backup-window-days", DEFAULT_BACKUP_WINDOW_DAYS), logRetentionDays: days("gcp-log-retention-days", DEFAULT_LOG_RETENTION_DAYS),
37
40
  }, out);
38
41
  }
39
42
  return scrub(out.results, [token]);
@@ -1,5 +1,6 @@
1
1
  // GitHub organization and its repositories over the REST API (GET only), with a fine-grained personal
2
- // access token or a GitHub App installation token in GITHUB_TOKEN.
2
+ // access token or a GitHub App installation token in GITHUB_TOKEN. Repositories of another owner
3
+ // (--github-also-repo) use GITHUB_TOKEN_<OWNER> when it is set (2026-11-05).
3
4
  //
4
5
  // Endpoint → fine-grained permission, read (docs.github.com/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens,
5
6
  // read 2026-10-20, no updated date shown; each endpoint below is listed there under the permission named):
@@ -30,6 +31,7 @@
30
31
  // and retries. Personal data: counts and numeric GitHub user ids only.
31
32
  import { DAY_MS, Emitter, arr, enc, fetchRest, firstIds, getAll, intOpt, isObj, linkNext, ok, realSleep, redact, str, why, withRetry, } from "./readonly_http.js";
32
33
  export const GITHUB_BASE = "https://api.github.com";
34
+ const GITHUB_ORIGIN = new URL(GITHUB_BASE).origin;
33
35
  export const GITHUB_TOKEN_ENV = "GITHUB_TOKEN";
34
36
  export const DEFAULTS = { maxOwners: 3, maxOutsideCollaborators: 0, alertDays: 30, maxRepos: 200 };
35
37
  export const CODEOWNERS_PATHS = [".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"];
@@ -44,11 +46,40 @@ export const REPO_CHECKS = [
44
46
  ];
45
47
  const arrayBody = (b) => (Array.isArray(b) ? b : undefined);
46
48
  const list = (api, path, maxPages = 50) => getAll(api, path, arrayBody, (r) => linkNext(r.headers), maxPages);
49
+ /** The variable holding a token for one owner's repositories: GITHUB_TOKEN_<OWNER>, upper case, other characters "_".
50
+ * A fine-grained token belongs to one owner (an organization or a user), so repositories of a second owner, named with
51
+ * --github-also-repo, need a token of their own (Sagentix, 2026-11-05: the organization plus three personal repositories). */
52
+ export const ownerTokenEnv = (owner) => `${GITHUB_TOKEN_ENV}_${owner.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
53
+ /** Every GitHub token in the environment, to scrub from results. */
54
+ export const githubSecrets = (env) => Object.entries(env).filter(([k]) => k === GITHUB_TOKEN_ENV || k.startsWith(`${GITHUB_TOKEN_ENV}_`)).map(([, v]) => v);
47
55
  export function githubFromEnv(env, fetchFn = fetch) {
48
56
  const token = env[GITHUB_TOKEN_ENV];
49
57
  if (!token)
50
58
  return `${GITHUB_TOKEN_ENV} is not set`;
51
- return fetchRest({ base: GITHUB_BASE, fetchFn, headers: async () => ({ authorization: `Bearer ${token}`, accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28" }) });
59
+ const client = (t) => fetchRest({ base: GITHUB_BASE, fetchFn, headers: async () => ({ authorization: `Bearer ${t}`, accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28" }) });
60
+ const main = client(token), byOwner = new Map();
61
+ // A request about /repos/{owner}/… or /orgs/{owner}/… goes out with that owner's token when one is set, else GITHUB_TOKEN.
62
+ return {
63
+ get(url) {
64
+ // A next-page link arrives as a full URL (Link header), a first call as a path. Parsed, never prefix-matched
65
+ // (CodeQL js/incomplete-url-substring-sanitization): only api.github.com's own path picks a per-owner token.
66
+ let path = url;
67
+ try {
68
+ const u = new URL(url, GITHUB_BASE);
69
+ path = u.origin === GITHUB_ORIGIN ? u.pathname : "";
70
+ }
71
+ catch {
72
+ path = "";
73
+ }
74
+ const owner = /^\/(?:repos|orgs|users)\/([^/?#]+)/.exec(path)?.[1];
75
+ const own = owner ? env[ownerTokenEnv(decodeURIComponent(owner))] : undefined;
76
+ if (!owner || !own)
77
+ return main.get(url);
78
+ if (!byOwner.has(owner))
79
+ byOwner.set(owner, client(own));
80
+ return byOwner.get(owner).get(url);
81
+ },
82
+ };
52
83
  }
53
84
  async function orgChecks(api, o, out) {
54
85
  const org = enc(o.org);
@@ -280,16 +311,21 @@ export async function githubChecks(api, o, now, warn = () => { }) {
280
311
  if ("error" in r) {
281
312
  for (const c of REPO_CHECKS)
282
313
  out.skip(c, r.error, "the organization's repositories", `repo ${o.org}/(list)`);
283
- return out.results;
314
+ if (!o.also?.length)
315
+ return out.results;
284
316
  }
285
- const live = r.items.filter(isObj).filter((x) => x.archived !== true && x.disabled !== true).map((x) => String(x.full_name));
317
+ const live = "error" in r ? [] : r.items.filter(isObj).filter((x) => x.archived !== true && x.disabled !== true).map((x) => String(x.full_name));
286
318
  if (live.length > o.maxRepos)
287
319
  warn(`github: ${live.length} repositories; checking the first ${o.maxRepos} (--github-max-repos, or name them with --github-repo)`);
288
320
  repos = live.slice(0, o.maxRepos);
289
- if (!repos.length)
321
+ if (!repos.length && !("error" in r))
290
322
  for (const c of REPO_CHECKS)
291
323
  out.add(c, "skipped", "the organization has no active repository the token can see", `repo ${o.org}/(none)`);
292
324
  }
325
+ // Repositories of another owner, checked in addition to the organization's (--github-also-repo owner/name).
326
+ for (const extra of o.also ?? [])
327
+ if (extra.includes("/") && !repos.includes(extra))
328
+ repos.push(extra);
293
329
  for (const full of repos)
294
330
  await repoChecks(api, full, o, now, out);
295
331
  return out.results;
@@ -300,6 +336,7 @@ export const github = {
300
336
  options: {
301
337
  "github-org": { type: "string", help: "GitHub organization to check (required for this source)" },
302
338
  "github-repo": { type: "string", multiple: true, help: "repository name or owner/name; default: every active repository of the organization" },
339
+ "github-also-repo": { type: "string", multiple: true, help: "owner/name of a repository outside the organization, checked as well; its token comes from GITHUB_TOKEN_<OWNER> when set" },
303
340
  "github-max-repos": { type: "string", help: `repositories checked when none is named (default ${DEFAULTS.maxRepos})` },
304
341
  "github-max-owners": { type: "string", help: `organization owners allowed (default ${DEFAULTS.maxOwners})` },
305
342
  "github-max-outside-collaborators": { type: "string", help: `outside collaborators allowed (default ${DEFAULTS.maxOutsideCollaborators})` },
@@ -309,7 +346,8 @@ export const github = {
309
346
  describe(opts) {
310
347
  const org = typeof opts["github-org"] === "string" ? opts["github-org"] : "(no --github-org)";
311
348
  const r = listOpt(opts["github-repo"]);
312
- return `organization ${org} / ${r.length ? `repos ${r.join(",")}` : "every active repository"}`;
349
+ const also = listOpt(opts["github-also-repo"]);
350
+ return `organization ${org} / ${r.length ? `repos ${r.join(",")}` : "every active repository"}${also.length ? ` + ${also.join(",")}` : ""}`;
313
351
  },
314
352
  async run(ctx) {
315
353
  const org = typeof ctx.opts["github-org"] === "string" ? ctx.opts["github-org"] : "";
@@ -324,12 +362,12 @@ export const github = {
324
362
  }
325
363
  const api = withRetry(built, ctx.clients.sleep ?? realSleep);
326
364
  const o = {
327
- org, repos: listOpt(ctx.opts["github-repo"]),
365
+ org, repos: listOpt(ctx.opts["github-repo"]), also: listOpt(ctx.opts["github-also-repo"]),
328
366
  maxRepos: intOpt(ctx.opts["github-max-repos"], DEFAULTS.maxRepos),
329
367
  maxOwners: intOpt(ctx.opts["github-max-owners"], DEFAULTS.maxOwners),
330
368
  maxOutsideCollaborators: intOpt(ctx.opts["github-max-outside-collaborators"], DEFAULTS.maxOutsideCollaborators),
331
369
  alertDays: intOpt(ctx.opts["github-alert-days"], DEFAULTS.alertDays),
332
370
  };
333
- return redact(await githubChecks(api, o, ctx.now, ctx.warn), [ctx.env[GITHUB_TOKEN_ENV]]);
371
+ return redact(await githubChecks(api, o, ctx.now, ctx.warn), githubSecrets(ctx.env));
334
372
  },
335
373
  };
@@ -19,7 +19,7 @@
19
19
  import { randomBytes, createHash } from "node:crypto";
20
20
  import { closeSync, fstatSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
21
21
  import { dirname, join } from "node:path";
22
- import { cachedToken, tokenRequest } from "./oauth.js";
22
+ import { cachedToken, sharedToken, tokenRequest } from "./oauth.js";
23
23
  export const GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
24
24
  export const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
25
25
  export const OAUTH_ENV = { clientFile: "GOOGLE_OAUTH_CLIENT_FILE", tokenFile: "GOOGLE_OAUTH_TOKEN_FILE" };
@@ -113,7 +113,7 @@ export function googleOAuthFromEnv(env, scopes, fetchFn = fetch) {
113
113
  const refresh = readTokenFile(tokenPath(env), client, scopes);
114
114
  if (typeof refresh !== "string")
115
115
  return refresh.error;
116
- return cachedToken(async () => {
116
+ return sharedToken(fetchFn, ["google-user", clientFile, client.clientId, refresh, ...scopes], () => cachedToken(async () => {
117
117
  try {
118
118
  return await tokenRequest(GOOGLE_TOKEN_URL, {
119
119
  grant_type: "refresh_token", refresh_token: refresh, client_id: client.clientId,
@@ -125,5 +125,5 @@ export function googleOAuthFromEnv(env, scopes, fetchFn = fetch) {
125
125
  // invalid_grant: revoked, unused for six months, or pushed out by newer tokens; only a new sign-in mends it.
126
126
  throw new Error(/invalid_grant/.test(m) ? `${m}: the sign-in was revoked or has expired; run \`collector google-login\` again` : m);
127
127
  }
128
- });
128
+ }));
129
129
  }
@@ -22,7 +22,7 @@
22
22
  // GOOGLE_ADMIN_EMAIL): an install whose domain-wide delegation lacks the scope, or whose admin is not a super
23
23
  // admin, gets drive_external_sharing_restricted skipped and keeps every other check.
24
24
  import { readFileSync } from "node:fs";
25
- import { cachedToken, googleAssertion, tokenRequest } from "./oauth.js";
25
+ import { cachedToken, googleAssertion, sharedToken, tokenRequest } from "./oauth.js";
26
26
  import { OAUTH_ENV, googleOAuthFromEnv } from "./google_oauth.js";
27
27
  import { DAY_MS, Emitter, enc, fetchRest, firstIds, getAll, intOpt, isObj, ok, realSleep, redact, str, why, withRetry, listRead, stampRead } from "./readonly_http.js";
28
28
  export const ADMIN_BASE = "https://admin.googleapis.com";
@@ -77,10 +77,11 @@ export function googleFromEnv(env, fetchFn = fetch) {
77
77
  // The key file names its own token endpoint; a tampered file could send the signed assertion elsewhere.
78
78
  if (!isGoogleTokenUri(tokenUri))
79
79
  return `${GOOGLE_ENV.keyFile} names a token_uri outside googleapis.com over HTTPS`;
80
- const token = cachedToken(() => tokenRequest(tokenUri, {
80
+ // Shared with the HR leaver join, which builds this same client (directory.ts): one token request per run.
81
+ const token = sharedToken(fetchFn, ["google-sa", tokenUri, key.client_email, admin, ...GOOGLE_SCOPES], () => cachedToken(() => tokenRequest(tokenUri, {
81
82
  grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
82
83
  assertion: googleAssertion(key, admin, GOOGLE_SCOPES, Math.floor(Date.now() / 1000)),
83
- }, fetchFn));
84
+ }, fetchFn)));
84
85
  return fetchRest({ base: ADMIN_BASE, fetchFn, headers: async () => ({ authorization: `Bearer ${await token()}` }) });
85
86
  }
86
87
  /** A client for the Cloud Identity Policy API with a token that holds only POLICY_SCOPE. */