facult 2.6.0 → 2.7.1

package/src/audit/static.ts

@@ -2,14 +2,26 @@ import { mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { facultStateDir, readFacultConfig } from "../paths";
+import { loadManagedState } from "../manage";
+import { isInlineMcpSecretValue } from "../mcp-config";
+import {
+  facultContextRootDir,
+  facultRootDir,
+  facultStateDir,
+  readFacultConfig,
+} from "../paths";
 import type { ScanResult } from "../scan";
 import { scan } from "../scan";
 import {
   extractCodexTomlMcpServerBlocks,
   sanitizeCodexTomlMcpText,
 } from "../util/codex-toml";
+import { type GitPathExposure, getGitPathExposure } from "../util/git";
 import { parseJsonLenient } from "../util/json";
+import {
+  applyAuditSuppressionsToStaticReport,
+  loadAuditSuppressions,
+} from "./suppressions";
 import {
   type AuditFinding,
   type AuditItemResult,
@@ -440,14 +452,96 @@ function isSecretEnvKey(key: string): boolean {
   return SECRET_ENV_KEY_RE.test(key);
 }
 
+function managedInlineSecretFinding(args: {
+  configPath: string;
+  envKey: string;
+  exposure: GitPathExposure;
+  serverName: string;
+}): AuditFinding | null {
+  const location = `${args.configPath}:${args.serverName}:env:${args.envKey}`;
+  const evidence = `${args.envKey}=<redacted>`;
+
+  if (
+    args.exposure.state === "outside-repo" ||
+    args.exposure.state === "ignored"
+  ) {
+    return null;
+  }
+
+  if (args.exposure.state === "tracked") {
+    return {
+      severity: "critical",
+      ruleId: "mcp-env-inline-secret",
+      message:
+        "Managed MCP config includes an inline secret in a git-tracked file. Move the secret out of the repo or gitignore the rendered target.",
+      location,
+      evidence,
+    };
+  }
+
+  return {
+    severity: "high",
+    ruleId: "mcp-env-inline-secret",
+    message:
+      "Managed MCP config includes an inline secret in a repo-local file that is not gitignored. It may be committed accidentally.",
+    location,
+    evidence,
+  };
+}
+
+function canonicalInlineSecretFinding(args: {
+  configPath: string;
+  envKey: string;
+  exposure: GitPathExposure;
+  serverName: string;
+}): AuditFinding {
+  const location = `${args.configPath}:${args.serverName}:env:${args.envKey}`;
+  const evidence = `${args.envKey}=<redacted>`;
+
+  if (args.exposure.state === "tracked") {
+    return {
+      severity: "critical",
+      ruleId: "mcp-env-inline-secret",
+      message:
+        "MCP server env includes an inline secret in a git-tracked file. Move it into local-only config or env indirection.",
+      location,
+      evidence,
+    };
+  }
+
+  if (args.exposure.state === "untracked") {
+    return {
+      severity: "high",
+      ruleId: "mcp-env-inline-secret",
+      message:
+        "MCP server env includes an inline secret in a repo-local file that is not gitignored. It may be committed accidentally.",
+      location,
+      evidence,
+    };
+  }
+
+  return {
+    severity: "high",
+    ruleId: "mcp-env-inline-secret",
+    message:
+      "MCP server env includes what looks like a secret value (consider using indirection instead of inlining).",
+    location,
+    evidence,
+  };
+}
+
 function structuredMcpChecks({
   serverName,
   configPath,
   definition,
+  exposure,
+  isManagedOutput,
 }: {
   serverName: string;
   configPath: string;
   definition: unknown;
+  exposure: GitPathExposure;
+  isManagedOutput: boolean;
 }): AuditFinding[] {
   const findings: AuditFinding[] = [];
 
@@ -514,15 +608,23 @@ function structuredMcpChecks({
     const secretKeys = Object.keys(env).filter((k) => isSecretEnvKey(k));
     for (const k of secretKeys) {
       const v = env[k];
-      if (typeof v === "string" && v.trim()) {
-        findings.push({
-          severity: "high",
-          ruleId: "mcp-env-inline-secret",
-          message:
-            "MCP server env includes what looks like a secret value (consider using indirection instead of inlining).",
-          location: `${configPath}:${serverName}:env:${k}`,
-          evidence: `${k}=<redacted>`,
-        });
+      if (isInlineMcpSecretValue(v)) {
+        const finding = isManagedOutput
+          ? managedInlineSecretFinding({
+              configPath,
+              envKey: k,
+              exposure,
+              serverName,
+            })
+          : canonicalInlineSecretFinding({
+              configPath,
+              envKey: k,
+              exposure,
+              serverName,
+            });
+        if (finding) {
+          findings.push(finding);
+        }
       }
     }
   }
@@ -713,6 +815,21 @@ export async function runStaticAudit(opts?: {
       ? { kind: "mcp", name: nameArg.slice("mcp:".length) }
       : { kind: "skill", name: nameArg }
     : null;
+  const managedRoots = uniqueSorted([
+    facultRootDir(home),
+    facultContextRootDir({ home, cwd: opts?.cwd }),
+  ]);
+  const managedStates = await Promise.all(
+    managedRoots.map((rootDir) =>
+      loadManagedState(home, rootDir).catch(() => null)
+    )
+  );
+  const managedMcpConfigPaths = new Set(
+    managedStates
+      .flatMap((state) => Object.values(state?.tools ?? {}))
+      .map((entry) => entry.mcpConfig)
+      .filter((path): path is string => typeof path === "string")
+  );
 
   const results: AuditItemResult[] = [];
 
@@ -860,6 +977,8 @@ export async function runStaticAudit(opts?: {
   for (const cfg of Array.from(uniqMcpConfigs.values()).sort((a, b) =>
     a.path.localeCompare(b.path)
   )) {
+    const exposure = await getGitPathExposure(cfg.path);
+    const isManagedOutput = managedMcpConfigPaths.has(cfg.path);
     const isToml = cfg.format === "toml" || cfg.path.endsWith(".toml");
 
     if (isToml) {
@@ -981,6 +1100,8 @@ export async function runStaticAudit(opts?: {
         serverName,
         configPath: cfg.path,
         definition,
+        exposure,
+        isManagedOutput,
       });
 
       const findings = [...ruleFindings, ...structured].sort((a, b) => {
@@ -1006,27 +1127,7 @@ export async function runStaticAudit(opts?: {
   }
 
   const minSeverity = opts?.minSeverity ?? undefined;
-  const bySeverity: Record<Severity, number> = {
-    low: 0,
-    medium: 0,
-    high: 0,
-    critical: 0,
-  };
-  let totalFindings = 0;
-  let flaggedItems = 0;
-
-  for (const r of results) {
-    const all = r.findings;
-    totalFindings += all.length;
-    if (!r.passed) {
-      flaggedItems += 1;
-    }
-    for (const f of all) {
-      bySeverity[f.severity] += 1;
-    }
-  }
-
-  const report: StaticAuditReport = {
+  let report: StaticAuditReport = {
     timestamp: new Date().toISOString(),
     mode: "static",
     minSeverity,
@@ -1034,12 +1135,28 @@ export async function runStaticAudit(opts?: {
     results,
     summary: {
       totalItems: results.length,
-      totalFindings,
-      bySeverity,
-      flaggedItems,
+      totalFindings: results.reduce(
+        (sum, result) => sum + result.findings.length,
+        0
+      ),
+      bySeverity: results.reduce<Record<Severity, number>>(
+        (acc, result) => {
+          for (const finding of result.findings) {
+            acc[finding.severity] += 1;
+          }
+          return acc;
+        },
+        { low: 0, medium: 0, high: 0, critical: 0 }
+      ),
+      flaggedItems: results.filter((result) => !result.passed).length,
     },
   };
 
+  report = applyAuditSuppressionsToStaticReport(
+    report,
+    await loadAuditSuppressions(home)
+  );
+
   const auditDir = join(facultStateDir(home), "audit");
   await ensureDir(auditDir);
   await Bun.write(

package/src/audit/status.ts

@@ -0,0 +1,21 @@
+import type { AuditFinding } from "./types";
+import { SEVERITY_ORDER } from "./types";
+
+export type StoredAuditStatus = "pending" | "passed" | "flagged";
+
+export function computeStoredAuditStatus(
+  findings: Pick<AuditFinding, "severity" | "ruleId">[]
+): StoredAuditStatus {
+  if (findings.some((finding) => finding.ruleId === "agent-error")) {
+    return "pending";
+  }
+  const worst = findings.reduce(
+    (max, finding) => Math.max(max, SEVERITY_ORDER[finding.severity]),
+    -1
+  );
+  return worst >= SEVERITY_ORDER.high ? "flagged" : "passed";
+}
+
+export function isStoredAuditStatusPassed(status: StoredAuditStatus): boolean {
+  return status === "passed";
+}

package/src/audit/suppressions.ts

@@ -0,0 +1,266 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { facultStateDir } from "../paths";
+import type { AgentAuditReport } from "./agent";
+import { computeStoredAuditStatus, isStoredAuditStatusPassed } from "./status";
+import type {
+  AuditFinding,
+  AuditItemResult,
+  Severity,
+  StaticAuditReport,
+} from "./types";
+
+const RULE_ID_PREFIX_RE = /^(static|agent):/;
+
+export interface AuditSuppressionEntry {
+  key: string;
+  createdAt: string;
+  type: AuditItemResult["type"];
+  item: string;
+  path: string;
+  finding: {
+    severity: Severity;
+    ruleId: string;
+    message: string;
+    location?: string;
+  };
+  note?: string;
+}
+
+export interface AuditSuppressionStore {
+  version: 1;
+  updatedAt: string;
+  entries: AuditSuppressionEntry[];
+}
+
+function normalizeRuleId(ruleId: string): string {
+  return ruleId.replace(RULE_ID_PREFIX_RE, "");
+}
+
+function normalizedFindingSignature(args: {
+  type: AuditItemResult["type"];
+  item: string;
+  path: string;
+  finding: Pick<AuditFinding, "severity" | "ruleId" | "message" | "location">;
+}): string {
+  return JSON.stringify({
+    type: args.type,
+    item: args.item,
+    path: args.path,
+    severity: args.finding.severity,
+    ruleId: normalizeRuleId(args.finding.ruleId),
+    message: args.finding.message,
+    location: args.finding.location ?? "",
+  });
+}
+
+function suppressionsPath(homeDir: string): string {
+  return join(facultStateDir(homeDir), "audit", "suppressions.json");
+}
+
+export function createAuditSuppressionEntry(args: {
+  result: AuditItemResult;
+  finding: AuditFinding;
+  createdAt?: string;
+  note?: string;
+}): AuditSuppressionEntry {
+  const createdAt = args.createdAt ?? new Date().toISOString();
+  return {
+    key: normalizedFindingSignature({
+      type: args.result.type,
+      item: args.result.item,
+      path: args.result.path,
+      finding: args.finding,
+    }),
+    createdAt,
+    type: args.result.type,
+    item: args.result.item,
+    path: args.result.path,
+    finding: {
+      severity: args.finding.severity,
+      ruleId: args.finding.ruleId,
+      message: args.finding.message,
+      location: args.finding.location,
+    },
+    note: args.note?.trim() ? args.note.trim() : undefined,
+  };
+}
+
+async function loadAuditSuppressionStore(
+  homeDir: string
+): Promise<AuditSuppressionStore> {
+  const path = suppressionsPath(homeDir);
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    return {
+      version: 1,
+      updatedAt: new Date(0).toISOString(),
+      entries: [],
+    };
+  }
+  try {
+    const parsed = (await file.json()) as Partial<AuditSuppressionStore>;
+    return {
+      version: 1,
+      updatedAt:
+        typeof parsed.updatedAt === "string"
+          ? parsed.updatedAt
+          : new Date(0).toISOString(),
+      entries: Array.isArray(parsed.entries)
+        ? parsed.entries.filter(
+            (entry): entry is AuditSuppressionEntry =>
+              !!entry &&
+              typeof entry === "object" &&
+              typeof (entry as AuditSuppressionEntry).key === "string"
+          )
+        : [],
+    };
+  } catch {
+    return {
+      version: 1,
+      updatedAt: new Date(0).toISOString(),
+      entries: [],
+    };
+  }
+}
+
+async function writeAuditSuppressionStore(
+  homeDir: string,
+  store: AuditSuppressionStore
+) {
+  const path = suppressionsPath(homeDir);
+  await mkdir(join(facultStateDir(homeDir), "audit"), { recursive: true });
+  await Bun.write(path, `${JSON.stringify(store, null, 2)}\n`);
+}
+
+export async function loadAuditSuppressions(
+  homeDir = homedir()
+): Promise<AuditSuppressionEntry[]> {
+  return (await loadAuditSuppressionStore(homeDir)).entries;
+}
+
+export async function recordAuditSuppressions(args: {
+  selected: { result: AuditItemResult; finding: AuditFinding }[];
+  homeDir?: string;
+  note?: string;
+}): Promise<{ added: number; total: number }> {
+  const homeDir = args.homeDir ?? homedir();
+  const store = await loadAuditSuppressionStore(homeDir);
+  const next = new Map(store.entries.map((entry) => [entry.key, entry]));
+  const createdAt = new Date().toISOString();
+
+  for (const selection of args.selected) {
+    const entry = createAuditSuppressionEntry({
+      result: selection.result,
+      finding: selection.finding,
+      createdAt,
+      note: args.note,
+    });
+    next.set(entry.key, entry);
+  }
+
+  const entries = [...next.values()].sort((a, b) => a.key.localeCompare(b.key));
+  await writeAuditSuppressionStore(homeDir, {
+    version: 1,
+    updatedAt: createdAt,
+    entries,
+  });
+
+  return {
+    added: Math.max(0, entries.length - store.entries.length),
+    total: entries.length,
+  };
+}
+
+export function applyAuditSuppressionsToResults(args: {
+  results: AuditItemResult[];
+  suppressions: AuditSuppressionEntry[];
+}): AuditItemResult[] {
+  if (args.suppressions.length === 0) {
+    return args.results;
+  }
+  const suppressedKeys = new Set(args.suppressions.map((entry) => entry.key));
+  return args.results.map((result) => {
+    const findings = result.findings.filter(
+      (finding) =>
+        !suppressedKeys.has(
+          normalizedFindingSignature({
+            type: result.type,
+            item: result.item,
+            path: result.path,
+            finding,
+          })
+        )
+    );
+    const status = computeStoredAuditStatus(findings);
+    return {
+      ...result,
+      passed: isStoredAuditStatusPassed(status),
+      findings,
+    };
+  });
+}
+
+function summarizeResults(results: AuditItemResult[]): {
+  totalItems: number;
+  totalFindings: number;
+  bySeverity: Record<Severity, number>;
+  flaggedItems: number;
+} {
+  const bySeverity: Record<Severity, number> = {
+    low: 0,
+    medium: 0,
+    high: 0,
+    critical: 0,
+  };
+  let totalFindings = 0;
+  let flaggedItems = 0;
+
+  for (const result of results) {
+    totalFindings += result.findings.length;
+    if (!result.passed && result.findings.length > 0) {
+      flaggedItems += 1;
+    }
+    for (const finding of result.findings) {
+      bySeverity[finding.severity] += 1;
+    }
+  }
+
+  return {
+    totalItems: results.length,
+    totalFindings,
+    bySeverity,
+    flaggedItems,
+  };
+}
+
+export function applyAuditSuppressionsToStaticReport(
+  report: StaticAuditReport,
+  suppressions: AuditSuppressionEntry[]
+): StaticAuditReport {
+  const results = applyAuditSuppressionsToResults({
+    results: report.results,
+    suppressions,
+  });
+  return {
+    ...report,
+    results,
+    summary: summarizeResults(results),
+  };
+}
+
+export function applyAuditSuppressionsToAgentReport(
+  report: AgentAuditReport,
+  suppressions: AuditSuppressionEntry[]
+): AgentAuditReport {
+  const results = applyAuditSuppressionsToResults({
+    results: report.results,
+    suppressions,
+  });
+  return {
+    ...report,
+    results,
+    summary: summarizeResults(results),
+  };
+}