連携アプリ（OAuth・サービスプリンシパル）の権限をどう設計し、棚卸しし、検知するか：ConnectWise事例から作る側・組み込む側の最小権限

// sp-review.ts
export type Credential = { readonly kind: "secret" | "certificate"; readonly startDateTime: string; readonly endDateTime: string };
/** サービスプリンシパルに付与されたアプリケーション権限。ロールIDは、リソースとセットで初めて意味を持つ。 */
export type GrantedAppRole = { readonly resourceAppId: string; readonly appRoleId: string };
export type ServicePrincipalSnapshot = {
  readonly appId: string;
  readonly displayName: string;
  readonly servicePrincipalType: "Application" | "ManagedIdentity" | "Legacy" | "SocialIdp";
  readonly appOwnerOrganizationId: string | null;  // アプリが「登録された」テナント（アプリ以外では null）
  readonly credentials: readonly Credential[];
  readonly grantedAppRoles: readonly GrantedAppRole[];
};
export type Rule =
  | "high_privilege_app_role" | "foreign_app_only_access" | "credential_on_foreign_sp" | "unknown_app_owner"
  | "long_lived_credential" | "expired_credential" | "invalid_credential_date";
export type Severity = "high" | "medium" | "low";
export type Finding = { readonly appId: string; readonly rule: Rule; readonly severity: Severity; readonly detail: string };
export type ReviewPolicy = {
  readonly homeTenantId: string;
  readonly now: Date;
  readonly maxLifetimeDays: { readonly secret: number; readonly certificate: number }; // 自社のローテーション運用から決める数値
  readonly highPrivilegeRoles: ReadonlyMap<string, string>; // roleKey(resourceAppId, appRoleId) -> 権限名。網羅ではない
};

export const MICROSOFT_GRAPH_APP_ID = "00000003-0000-0000-c000-000000000000";
/** GUIDは大文字小文字を区別しない。一度正規化し、表記の違いで規則が黙って無効にならないようにする。 */
export const roleKey = (resourceAppId: string, appRoleId: string): string => `${resourceAppId.toLowerCase()}/${appRoleId.toLowerCase()}`;

/** Graphの文書で、強力であることを確認できる3つのアプリケーション権限。出発点であって、完全な一覧ではない。 */
export const GRAPH_HIGH_PRIVILEGE_ROLES: ReadonlyMap<string, string> = new Map([
  [roleKey(MICROSOFT_GRAPH_APP_ID, "06b708a9-e830-4db3-a914-8e69da51d44f"), "AppRoleAssignment.ReadWrite.All"],
  [roleKey(MICROSOFT_GRAPH_APP_ID, "9e3f62cf-ca93-4989-b6ce-bf83c28f9fe8"), "RoleManagement.ReadWrite.Directory"],
  [roleKey(MICROSOFT_GRAPH_APP_ID, "1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9"), "Application.ReadWrite.All"],
]);

const DAY_MS = 86_400_000;
const RANK: Record<Severity, number> = { high: 0, medium: 1, low: 2 };

/** 設定の誤りは、規則を黙って無効にせず、実行を止める（NaNはどの比較でも偽になる）。 */
function assertValidPolicy(p: ReviewPolicy): void {
  const ok = (n: number) => Number.isFinite(n) && n > 0;
  if (Number.isNaN(p.now.getTime())) throw new RangeError("policy.now is not a valid date");
  if (!ok(p.maxLifetimeDays.secret) || !ok(p.maxLifetimeDays.certificate)) throw new RangeError("policy.maxLifetimeDays must be finite and > 0");
}

export function reviewServicePrincipals(inventory: readonly ServicePrincipalSnapshot[], policy: ReviewPolicy): Finding[] {
  assertValidPolicy(policy);
  const home = policy.homeTenantId.toLowerCase();
  const findings: Finding[] = [];
  for (const sp of inventory) {
    const add = (rule: Rule, severity: Severity, detail: string) => findings.push({ appId: sp.appId, rule, severity, detail });

    const powerful = sp.grantedAppRoles.flatMap((r) => policy.highPrivilegeRoles.get(roleKey(r.resourceAppId, r.appRoleId)) ?? []);
    if (powerful.length > 0) add("high_privilege_app_role", "high", `holds ${powerful.join(", ")}`);

    // 登録テナントは、アプリ由来のプリンシパルでだけ意味を持つ（マネージドIDには登録テナントがない）。
    if (sp.servicePrincipalType === "Application") {
      if (sp.appOwnerOrganizationId === null) add("unknown_app_owner", "medium", "application-backed principal without appOwnerOrganizationId");
      else if (sp.appOwnerOrganizationId.toLowerCase() !== home) {
        if (sp.grantedAppRoles.length > 0)
          add("foreign_app_only_access", "medium", `${sp.grantedAppRoles.length} application permission(s) on an app registered in another tenant`);
        // ヒューリスティック：ベンダーのアプリの資格情報は、通常ベンダー自身のテナントにある。ここに追加された資格情報は、
        // Microsoftが報告した永続化の手口（MITRE T1098.001）そのものなので、外部登録のプリンシパル上の資格情報は人の目で見る。
        if (sp.credentials.length > 0)
          add("credential_on_foreign_sp", "high", `${sp.credentials.length} credential(s) present on an app registered in another tenant`);
      }
    }

    for (const c of sp.credentials) {
      const start = Date.parse(c.startDateTime), end = Date.parse(c.endDateTime);
      if (Number.isNaN(start) || Number.isNaN(end) || end < start) { add("invalid_credential_date", "medium", `unusable ${c.kind} dates`); continue; } // 判定不能は報告する
      if (end < policy.now.getTime()) { add("expired_credential", "low", `${c.kind} expired and still present`); continue; }
      const days = (end - start) / DAY_MS, max = policy.maxLifetimeDays[c.kind];
      if (days > max) add("long_lived_credential", "medium", `${c.kind} valid for ${Math.round(days)} days (policy: ${max})`);
    }
  }
  // 実行のたびに差分が取れるよう、順序を決定的にする。
  return findings.sort((a, b) => RANK[a.severity] - RANK[b.severity] || a.appId.localeCompare(b.appId) || a.rule.localeCompare(b.rule));
}

// ---- 監査ログ側 -------------------------------------------------------------------------------------
// Entraの監査ログ（activityDisplayName / initiatedBy / targetResources）から正規化したもの。生の行を `kind` に対応づけることと、
// 両方のIDを同じ種類の識別子（appId）に揃えることは、テナント固有の作業で、ここでは行わない。
// 片方がオブジェクトID、もう片方がappIdだと、下の自己付与の比較は黙って一度も成立しない。
export type AuditEvent = {
  readonly at: string;
  readonly kind: "role_member_added" | "app_role_assigned" | "credential_added";
  readonly actorAppId: string | null;   // null = 人が実行。これらの規則では評価しない（盗まれた管理者は、ここでは見えない）
  readonly targetAppId: string;
};
export type AuditPolicy = { readonly allowedCredentialWriters: ReadonlySet<string>; readonly allowedPrivilegeGrantors: ReadonlySet<string> };
export type AuditAlert = { readonly rule: "self_privilege_grant" | "privilege_grant_by_app" | "unexpected_credential_writer"; readonly severity: Severity; readonly event: AuditEvent };

export function reviewAuditEvents(events: readonly AuditEvent[], policy: AuditPolicy): AuditAlert[] {
  const alerts: AuditAlert[] = [];
  for (const e of events) {
    const actor = e.actorAppId?.toLowerCase();
    if (actor === undefined) continue;
    if (e.kind === "credential_added") {
      if (!policy.allowedCredentialWriters.has(actor)) alerts.push({ rule: "unexpected_credential_writer", severity: "medium", event: e });
    } else if (actor === e.targetAppId.toLowerCase()) alerts.push({ rule: "self_privilege_grant", severity: "high", event: e });
    else if (!policy.allowedPrivilegeGrantors.has(actor)) alerts.push({ rule: "privilege_grant_by_app", severity: "medium", event: e });
  }
  return alerts;
}

// sp-review.test.ts — node --test sp-review.test.ts
import test from "node:test";
import assert from "node:assert/strict";
import { GRAPH_HIGH_PRIVILEGE_ROLES, MICROSOFT_GRAPH_APP_ID, reviewAuditEvents, reviewServicePrincipals, type AuditEvent, type ReviewPolicy, type ServicePrincipalSnapshot } from "./sp-review.ts";

const HOME = "11111111-1111-1111-1111-111111111111", VENDOR = "99999999-9999-9999-9999-999999999999";
const APP_RW = { resourceAppId: MICROSOFT_GRAPH_APP_ID, appRoleId: "1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9" }; // Application.ReadWrite.All on Microsoft Graph
const policy: ReviewPolicy = { homeTenantId: HOME, now: new Date("2026-11-04T00:00:00Z"), maxLifetimeDays: { secret: 180, certificate: 730 }, highPrivilegeRoles: GRAPH_HIGH_PRIVILEGE_ROLES };
const sp = (o: Partial<ServicePrincipalSnapshot> & { appId: string }): ServicePrincipalSnapshot =>
  ({ displayName: "x", servicePrincipalType: "Application", appOwnerOrganizationId: HOME, credentials: [], grantedAppRoles: [], ...o });
const rules = (inv: ServicePrincipalSnapshot[], p = policy) => reviewServicePrincipals(inv, p).map((f) => f.rule);

test("a high-privilege role is matched on resource + role id, case-insensitively", () => {
  assert.deepEqual(rules([sp({ appId: "a", grantedAppRoles: [APP_RW] })]), ["high_privilege_app_role"]);
  assert.deepEqual(rules([sp({ appId: "a", grantedAppRoles: [{ resourceAppId: MICROSOFT_GRAPH_APP_ID.toUpperCase(), appRoleId: APP_RW.appRoleId.toUpperCase() }] })]), ["high_privilege_app_role"]);
  assert.deepEqual(rules([sp({ appId: "a", grantedAppRoles: [{ resourceAppId: "some-other-resource", appRoleId: APP_RW.appRoleId }] })]), []); // same GUID, different resource
});
test("a vendor-registered app is flagged for app-only access, not for delegated-only", () => {
  assert.deepEqual(rules([sp({ appId: "v1", appOwnerOrganizationId: VENDOR })]), []);
  assert.deepEqual(rules([sp({ appId: "v2", appOwnerOrganizationId: VENDOR.toUpperCase(), grantedAppRoles: [{ resourceAppId: "r", appRoleId: "x" }] })]), ["foreign_app_only_access"]);
  assert.deepEqual(rules([sp({ appId: "h", appOwnerOrganizationId: HOME.toUpperCase(), grantedAppRoles: [{ resourceAppId: "r", appRoleId: "x" }] })]), []); // casing must not make a home app 'foreign'
});
test("any credential on a vendor-registered principal is flagged high; the same credential on a home app is not", () => {
  const c = [{ kind: "certificate" as const, startDateTime: "2026-10-01T00:00:00Z", endDateTime: "2027-01-01T00:00:00Z" }];
  assert.deepEqual(rules([sp({ appId: "v", appOwnerOrganizationId: VENDOR, credentials: c })]), ["credential_on_foreign_sp"]);
  assert.deepEqual(rules([sp({ appId: "h", credentials: c })]), []);
});
test("managed identities are not 'foreign'; an application without an owner id is reported", () => {
  assert.deepEqual(rules([sp({ appId: "m", servicePrincipalType: "ManagedIdentity", appOwnerOrganizationId: null, grantedAppRoles: [{ resourceAppId: "r", appRoleId: "x" }] })]), []);
  assert.deepEqual(rules([sp({ appId: "n", appOwnerOrganizationId: null })]), ["unknown_app_owner"]);
  assert.deepEqual(rules([sp({ appId: "m2", servicePrincipalType: "ManagedIdentity", appOwnerOrganizationId: null, grantedAppRoles: [APP_RW] })]), ["high_privilege_app_role"]); // privilege rule still applies
});
test("secret AND certificate lifetimes are judged; expired credentials are hygiene", () => {
  const f = rules([sp({ appId: "c", credentials: [
    { kind: "secret", startDateTime: "2026-10-01T00:00:00Z", endDateTime: "2027-10-01T00:00:00Z" },       // 365d > 180d
    { kind: "secret", startDateTime: "2026-10-01T00:00:00Z", endDateTime: "2026-12-01T00:00:00Z" },       // ok
    { kind: "certificate", startDateTime: "2026-10-01T00:00:00Z", endDateTime: "2030-10-01T00:00:00Z" },  // > 730d
    { kind: "certificate", startDateTime: "2026-10-01T00:00:00Z", endDateTime: "2027-10-01T00:00:00Z" },  // 365d: over the SECRET limit, within the CERTIFICATE limit -> must NOT be flagged
    { kind: "secret", startDateTime: "2025-01-01T00:00:00Z", endDateTime: "2025-06-01T00:00:00Z" },       // expired
  ] })]);
  assert.deepEqual([...f].sort(), ["expired_credential", "long_lived_credential", "long_lived_credential"]);
});
test("unusable dates (garbage, or end before start) are reported, never silently passed", () => {
  const bad = (s: string, e: string) => rules([sp({ appId: "d", credentials: [{ kind: "secret", startDateTime: s, endDateTime: e }] })]);
  assert.deepEqual(bad("garbage", "2027-01-01T00:00:00Z"), ["invalid_credential_date"]);
  assert.deepEqual(bad("2027-01-01T00:00:00Z", "2026-12-01T00:00:00Z"), ["invalid_credential_date"]);
});
test("a broken policy throws instead of quietly disabling a rule", () => {
  assert.throws(() => rules([], { ...policy, maxLifetimeDays: { secret: Number.NaN, certificate: 730 } }), RangeError);
  assert.throws(() => rules([], { ...policy, maxLifetimeDays: { secret: 180, certificate: 0 } }), RangeError);
  assert.throws(() => rules([], { ...policy, now: new Date("nope") }), RangeError);
});
test("output order is deterministic and the input is not mutated", () => {
  const inv = [sp({ appId: "z", grantedAppRoles: [APP_RW] }), sp({ appId: "b", grantedAppRoles: [APP_RW] })];
  const before = JSON.stringify(inv);
  assert.deepEqual(reviewServicePrincipals(inv, policy).map((x) => x.appId), ["b", "z"]);
  assert.equal(JSON.stringify(inv), before);
  assert.deepEqual(reviewServicePrincipals([], policy), []);
});

const ev = (o: Partial<AuditEvent> & Pick<AuditEvent, "kind" | "targetAppId">): AuditEvent => ({ at: "2026-11-04T00:00:00Z", actorAppId: null, ...o });
const none = { allowedCredentialWriters: new Set<string>(), allowedPrivilegeGrantors: new Set<string>() };
test("an app granting a role to ITSELF is high; to ANOTHER principal is medium unless the grantor is allow-listed", () => {
  const a = reviewAuditEvents([
    ev({ kind: "role_member_added", actorAppId: "app-1", targetAppId: "APP-1" }),   // self (case-insensitive)
    ev({ kind: "app_role_assigned", actorAppId: "app-1", targetAppId: "app-2" }),   // app -> other
    ev({ kind: "app_role_assigned", actorAppId: "provisioner", targetAppId: "app-2" }),
  ], { ...none, allowedPrivilegeGrantors: new Set(["provisioner"]) });
  assert.deepEqual(a.map((x) => [x.rule, x.severity]), [["self_privilege_grant", "high"], ["privilege_grant_by_app", "medium"]]);
});
test("credential additions by an app outside the allow-list are flagged", () => {
  const a = reviewAuditEvents([
    ev({ kind: "credential_added", actorAppId: "deploy-bot", targetAppId: "app-1" }),
    ev({ kind: "credential_added", actorAppId: "rogue", targetAppId: "app-1" }),
  ], { ...none, allowedCredentialWriters: new Set(["deploy-bot"]) });
  assert.deepEqual(a.map((x) => [x.rule, x.event.actorAppId]), [["unexpected_credential_writer", "rogue"]]);
});
test("KNOWN LIMIT, pinned on purpose: events initiated by a human (actorAppId = null) are not evaluated", () => {
  assert.deepEqual(reviewAuditEvents([ev({ kind: "credential_added", targetAppId: "app-1" }), ev({ kind: "role_member_added", targetAppId: "app-1" })], none), []);
});