fix: classify credential gated component audits

Signed-off-by: zebbern <185730623+zebbern@users.noreply.github.com>

Author: zebbern

scripts/__tests__/security-component-audit-utils.test.ts

@@ -3,6 +3,7 @@ import {
   SECURITY_COMPONENT_IDS,
   createSecurityComponentFingerprint,
   renderSecurityComponentLedgerFreshness,
+  shouldSkipSecurityComponentLiveAudit,
   summarizeSecurityComponentLedgerFreshness,
   SECURITY_COMPONENT_LIVE_FIXTURES,
 } from '../security-component-audit-utils';
@@ -28,4 +29,91 @@ describe('security-component-audit-utils', () => {
     expect(summary.items[0]?.status).toBe('missing');
     expect(renderSecurityComponentLedgerFreshness(summary)).toContain('CURRENT');
   });
+
+  it('skips credential-gated fixtures with missing secrets even when force is requested', () => {
+    const fixture = SECURITY_COMPONENT_LIVE_FIXTURES['security.virustotal.lookup'];
+    const fingerprint = createSecurityComponentFingerprint('security.virustotal.lookup', fixture);
+    const originalValue = process.env.VIRUSTOTAL_API_KEY;
+    delete process.env.VIRUSTOTAL_API_KEY;
+
+    try {
+      const skipped = shouldSkipSecurityComponentLiveAudit({
+        ledger: undefined,
+        componentId: 'security.virustotal.lookup',
+        fingerprint,
+        force: true,
+        fixture,
+      });
+
+      expect(skipped).toMatchObject({
+        componentId: 'security.virustotal.lookup',
+        fingerprint,
+        tier: 'C',
+        status: 'skipped',
+        error: 'Requires VirusTotal API key',
+      });
+    } finally {
+      if (originalValue === undefined) {
+        delete process.env.VIRUSTOTAL_API_KEY;
+      } else {
+        process.env.VIRUSTOTAL_API_KEY = originalValue;
+      }
+    }
+  });
+
+  it('lets forced credential-gated fixtures run when all required secrets are present', () => {
+    const fixture = SECURITY_COMPONENT_LIVE_FIXTURES['security.virustotal.lookup'];
+    const fingerprint = createSecurityComponentFingerprint('security.virustotal.lookup', fixture);
+    const originalValue = process.env.VIRUSTOTAL_API_KEY;
+    process.env.VIRUSTOTAL_API_KEY = 'present';
+
+    try {
+      const skipped = shouldSkipSecurityComponentLiveAudit({
+        ledger: undefined,
+        componentId: 'security.virustotal.lookup',
+        fingerprint,
+        force: true,
+        fixture,
+      });
+
+      expect(skipped).toBeUndefined();
+    } finally {
+      if (originalValue === undefined) {
+        delete process.env.VIRUSTOTAL_API_KEY;
+      } else {
+        process.env.VIRUSTOTAL_API_KEY = originalValue;
+      }
+    }
+  });
+
+  it('skips missing required secrets even without a custom skip reason', () => {
+    const fixture = {
+      tier: 'C' as const,
+      inputs: {},
+      params: {},
+      requiresSecrets: ['CUSTOM_REQUIRED_SECRET'],
+    };
+    const fingerprint = createSecurityComponentFingerprint('sentris.subfinder.run', fixture);
+    const originalValue = process.env.CUSTOM_REQUIRED_SECRET;
+    delete process.env.CUSTOM_REQUIRED_SECRET;
+
+    try {
+      const skipped = shouldSkipSecurityComponentLiveAudit({
+        ledger: undefined,
+        componentId: 'sentris.subfinder.run',
+        fingerprint,
+        force: true,
+        fixture,
+      });
+
+      expect(skipped?.status).toBe('skipped');
+      expect(skipped?.error).toBe('Missing required secrets: CUSTOM_REQUIRED_SECRET');
+    } finally {
+      if (originalValue === undefined) {
+        delete process.env.CUSTOM_REQUIRED_SECRET;
+      } else {
+        process.env.CUSTOM_REQUIRED_SECRET = originalValue;
+      }
+    }
+  });
 });

scripts/security-component-audit-utils.ts

@@ -46,7 +46,9 @@ export interface SecurityComponentAuditCliOptions {
   sequential: boolean;
 }
 
-export function parseSecurityComponentAuditCliOptions(argv: string[]): SecurityComponentAuditCliOptions {
+export function parseSecurityComponentAuditCliOptions(
+  argv: string[],
+): SecurityComponentAuditCliOptions {
   const componentIds = new Set<string>();
   let force = false;
   let ledgerCheckOnly = false;
@@ -334,9 +336,7 @@ export function summarizeSecurityComponentLedgerFreshness(
     const entry = ledger?.entries[componentId];
 
     if (fixture.skipReason || (fixture.requiresSecrets?.length ?? 0) > 0) {
-      const hasSecrets = (fixture.requiresSecrets ?? []).every(
-        (name) => process.env[name]?.trim(),
-      );
+      const hasSecrets = (fixture.requiresSecrets ?? []).every((name) => process.env[name]?.trim());
       if (!hasSecrets) {
         return {
           componentId,
@@ -403,10 +403,7 @@ export function summarizeSecurityComponentLedgerFreshness(
   });
 
   const allCurrent = items.every(
-    (item) =>
-      item.status === 'current' ||
-      item.status === 'skipped' ||
-      item.status === 'missing',
+    (item) => item.status === 'current' || item.status === 'skipped' || item.status === 'missing',
   );
 
   return { allCurrent, items };
@@ -423,9 +420,10 @@ export function renderSecurityComponentLedgerFreshness(summary: {
         `- ${item.componentId} [${item.tier}] ${item.status}${item.verifiedAt ? ` (${item.verifiedAt})` : ''}: ${item.rationale}`,
     );
 
-  return [`Security component ledger: ${summary.allCurrent ? 'CURRENT' : 'NEEDS ATTENTION'}`, ...lines].join(
-    '\n',
-  );
+  return [
+    `Security component ledger: ${summary.allCurrent ? 'CURRENT' : 'NEEDS ATTENTION'}`,
+    ...lines,
+  ].join('\n');
 }
 
 export function shouldSkipSecurityComponentLiveAudit(options: {
@@ -435,21 +433,29 @@ export function shouldSkipSecurityComponentLiveAudit(options: {
   force: boolean;
   fixture: SecurityComponentAuditFixture;
 }): SecurityComponentLedgerEntry | undefined {
-  if (options.force) {
-    return undefined;
-  }
+  const requiredSecrets = options.fixture.requiresSecrets ?? [];
+  const missingRequiredSecrets = requiredSecrets.filter((name) => !process.env[name]?.trim());
+  const missingCredentialGate =
+    missingRequiredSecrets.length > 0 ||
+    (requiredSecrets.length === 0 && options.fixture.skipReason !== undefined);
 
-  if (options.fixture.skipReason && !(options.fixture.requiresSecrets ?? []).some((name) => process.env[name]?.trim())) {
+  if (missingCredentialGate) {
     return {
       componentId: options.componentId,
       fingerprint: options.fingerprint,
       tier: options.fixture.tier,
       status: 'skipped',
-      error: options.fixture.skipReason,
+      error:
+        options.fixture.skipReason ??
+        `Missing required secrets: ${missingRequiredSecrets.join(', ')}`,
       verifiedAt: new Date().toISOString(),
     };
   }
 
+  if (options.force) {
+    return undefined;
+  }
+
   const existing = options.ledger?.entries[options.componentId];
   if (existing?.fingerprint === options.fingerprint && existing.status === 'passed') {
     return existing;

scripts/security-component-live-audit.ts

@@ -40,7 +40,12 @@ if (cli.ledgerCheckOnly) {
   process.exit(process.exitCode ?? 0);
 }
 
-const outputRoot = join(process.cwd(), '.cache', 'security-component-audits', new Date().toISOString().slice(0, 10));
+const outputRoot = join(
+  process.cwd(),
+  '.cache',
+  'security-component-audits',
+  new Date().toISOString().slice(0, 10),
+);
 mkdirSync(outputRoot, { recursive: true });
 
 interface AuditResult {
@@ -63,14 +68,17 @@ for (const componentId of selectedIds) {
     fixture,
   });
 
-  if (skipped && !cli.force) {
+  if (skipped) {
     console.log(`SKIP ${componentId}: ${skipped.error ?? 'ledger current'}`);
     results.push({
       componentId,
       status: skipped.status === 'passed' ? 'passed' : 'skipped',
       durationMs: skipped.durationMs,
       error: skipped.error,
     });
+    if (skipped.status === 'skipped') {
+      ledger = upsertSecurityComponentLedgerEntry(ledger, skipped);
+    }
     continue;
   }
 
@@ -126,10 +134,15 @@ for (const componentId of selectedIds) {
 }
 
 writeSecurityComponentLedger(ledger, getDefaultLedgerPath());
-writeFileSync(join(outputRoot, 'security-component-live-audit.json'), JSON.stringify({ results }, null, 2));
+writeFileSync(
+  join(outputRoot, 'security-component-live-audit.json'),
+  JSON.stringify({ results }, null, 2),
+);
 
 const failures = results.filter((result) => result.status === 'failed');
 if (failures.length > 0) {
   process.exitCode = 1;
-  console.error(`Security component live audit failures: ${failures.map((item) => item.componentId).join(', ')}`);
+  console.error(
+    `Security component live audit failures: ${failures.map((item) => item.componentId).join(', ')}`,
+  );
 }