actions-warden 0.4.0 → 0.6.0

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 (76) hide show
  1. package/AGENTS.md +46 -8
  2. package/CONTRIBUTING.md +6 -2
  3. package/README.md +171 -61
  4. package/RELEASING.md +3 -2
  5. package/SECURITY.md +15 -5
  6. package/docs/AI-AGENTS.md +109 -29
  7. package/docs/CLI.md +284 -60
  8. package/docs/CONFIGURATION.md +34 -11
  9. package/docs/DEVELOPMENT.md +97 -24
  10. package/docs/GITHUB-ACTION.md +157 -27
  11. package/docs/JAVASCRIPT-API.md +172 -8
  12. package/docs/OUTPUTS.md +399 -36
  13. package/docs/README.md +1 -1
  14. package/examples/README.md +21 -0
  15. package/examples/baseline-adoption/README.md +79 -0
  16. package/examples/baseline-adoption/github-actions.yml +56 -0
  17. package/examples/baseline-adoption/policy.yml +7 -0
  18. package/examples/ci-violation-reporting/README.md +82 -0
  19. package/examples/ci-violation-reporting/github-actions.yml +55 -0
  20. package/examples/ci-violation-reporting/policy.yml +7 -0
  21. package/examples/ci-violation-reporting/violating-workflow.yml +17 -0
  22. package/examples/csv-reporting/README.md +50 -0
  23. package/examples/csv-reporting/github-actions.yml +59 -0
  24. package/examples/html-organization-report/README.md +35 -0
  25. package/examples/html-organization-report/github-actions.yml +61 -0
  26. package/examples/notifications/README.md +67 -0
  27. package/examples/notifications/github-actions.yml +163 -0
  28. package/examples/org-scan.yml +24 -5
  29. package/examples/sarif-code-scanning/README.md +42 -0
  30. package/examples/sarif-code-scanning/github-actions.yml +66 -0
  31. package/examples/upgrade-pr.yml +1 -1
  32. package/llms.txt +14 -5
  33. package/package.json +8 -4
  34. package/skills/actions-warden/SKILL.md +78 -35
  35. package/src/action.js +351 -174
  36. package/src/cli.js +191 -177
  37. package/src/commands/audit.js +17 -30
  38. package/src/commands/org-scan.js +451 -280
  39. package/src/commands/pin.js +9 -5
  40. package/src/commands/report.js +7 -2
  41. package/src/commands/upgrade.js +9 -5
  42. package/src/commands/verify.js +24 -4
  43. package/src/index.js +5 -1
  44. package/src/lib/action-summary.js +656 -0
  45. package/src/lib/annotations.js +4 -6
  46. package/src/lib/baseline.js +11 -1
  47. package/src/lib/config.js +10 -5
  48. package/src/lib/destination.js +98 -0
  49. package/src/lib/execution.js +5 -1
  50. package/src/lib/formats/csv.js +125 -0
  51. package/src/lib/formats/html.js +394 -0
  52. package/src/lib/formats/json.js +17 -0
  53. package/src/lib/formats/sarif.js +229 -0
  54. package/src/lib/formats/text.js +30 -0
  55. package/src/lib/formats/toon.js +50 -0
  56. package/src/lib/formatter.js +25 -192
  57. package/src/lib/github-org.js +208 -102
  58. package/src/lib/org-artifacts.js +211 -0
  59. package/src/lib/org-checkpoint.js +137 -96
  60. package/src/lib/org-progress.js +182 -4
  61. package/src/lib/org-report-comparison.js +505 -0
  62. package/src/lib/org-report-directory.js +251 -0
  63. package/src/lib/org-report.js +223 -0
  64. package/src/lib/org-run.js +305 -0
  65. package/src/lib/org-schema.js +89 -0
  66. package/src/lib/org-source-links.js +39 -0
  67. package/src/lib/parser.js +5 -0
  68. package/src/lib/paths.js +18 -1
  69. package/src/lib/redact.js +58 -7
  70. package/src/lib/resolver.js +66 -9
  71. package/src/lib/types.js +137 -0
  72. package/src/rules/pull-request-target-checkout.js +5 -0
  73. package/src/rules/unpinned-action.js +2 -3
  74. package/src/rules/workflow-structure.js +2 -4
  75. package/src/version.js +1 -1
  76. package/src/lib/agent-mode.js +0 -174
package/src/cli.js CHANGED
@@ -14,7 +14,7 @@
14
14
  */
15
15
 
16
16
  import { stat } from 'node:fs/promises';
17
- import { relative, resolve, sep } from 'node:path';
17
+ import { resolve } from 'node:path';
18
18
  import { createRequire } from 'node:module';
19
19
  import { Command, CommanderError, InvalidArgumentError, Option } from 'commander';
20
20
 
@@ -28,21 +28,32 @@ import { listRules } from './rules/index.js';
28
28
  import { format as fmt } from './lib/formatter.js';
29
29
  import { writeFileGuarded } from './lib/writer.js';
30
30
  import { serializeBaseline } from './lib/baseline.js';
31
- import { formatOrganizationProgress } from './lib/org-progress.js';
31
+ import {
32
+ createOrganizationProgressReporter,
33
+ isScanFailureReported,
34
+ } from './lib/org-progress.js';
35
+ import { redact } from './lib/redact.js';
32
36
  import { resolveTargets } from './lib/targets.js';
33
- import { sameFilePath } from './lib/path-equality.js';
34
37
  import {
35
- AGENT_MODE_ENVIRONMENT_VARIABLE,
36
- createOrganizationAgentArtifacts,
37
- renderOrganizationAgentReceipt,
38
- resolveAgentMode,
39
- } from './lib/agent-mode.js';
38
+ EXECUTION_CONTEXT_ENVIRONMENT_VARIABLE,
39
+ renderOrganizationScanReceipt,
40
+ resolveExecutionContext,
41
+ } from './lib/org-artifacts.js';
42
+ import { runOrganizationScan } from './lib/org-run.js';
43
+ import { SEVERITY_LEVELS, VISIBILITY_FILTERS } from './lib/org-schema.js';
44
+ import { writeOrganizationReportDirectory } from './lib/org-report-directory.js';
45
+ import {
46
+ assertDestinationsAreDistinct,
47
+ assertDestinationsDoNotReplaceControls,
48
+ assertDestinationsUseSafeNames,
49
+ validateWriteDestination,
50
+ } from './lib/destination.js';
40
51
 
41
52
  const program = new Command();
42
53
  const require = createRequire(import.meta.url);
43
54
  const { version } = require('../package.json');
44
55
  const FIX_ID_RE = /^[0-9a-f]{16}$/i;
45
- const DEFAULT_CONFIG_PATHS = ['.actions-warden.yml', '.actions-warden.yaml'];
56
+ let structuredProgressContext = null;
46
57
  program
47
58
  .name('actions-warden')
48
59
  .description('Audit GitHub Actions across repositories and organizations; pin, verify, and upgrade dependencies.')
@@ -52,16 +63,16 @@ program
52
63
  throw error;
53
64
  });
54
65
 
55
- function createFormatOption() {
66
+ function createFormatOption(defaultValue = 'toon') {
56
67
  return new Option('--format <fmt>', 'output format')
57
- .choices(['toon', 'json', 'text', 'sarif'])
58
- .default('toon');
68
+ .choices(['toon', 'json', 'text', 'csv', 'sarif', 'html'])
69
+ .default(defaultValue);
59
70
  }
60
71
 
61
- function createOutputOption() {
72
+ function createOutputOption(defaultValue = 'stdout') {
62
73
  return new Option('--output <dest>', 'output destination')
63
74
  .choices(['stdout', 'file'])
64
- .default('stdout');
75
+ .default(defaultValue);
65
76
  }
66
77
 
67
78
  function createOutputPathOption() {
@@ -109,7 +120,7 @@ async function emit(payload, opts) {
109
120
 
110
121
  addCommonOptions(program.command('audit'), { includeToken: false })
111
122
  .description('Scan workflows for security findings')
112
- .addOption(new Option('--severity <level>', 'minimum severity').choices(['low', 'medium', 'high', 'critical']))
123
+ .addOption(new Option('--severity <level>', 'minimum severity').choices(SEVERITY_LEVELS))
113
124
  .option('--explain', 'include plain-English remediation hint for each finding')
114
125
  .addOption(new Option('--config <path>', 'repository policy file (default: .actions-warden.yml)')
115
126
  .argParser(value => parseNonEmpty(value, '--config'))
@@ -156,6 +167,8 @@ addCommonOptions(program.command('audit'), { includeToken: false })
156
167
  },
157
168
  }], {
158
169
  status: 'OK',
170
+ title: 'Finding baseline created',
171
+ metadata: { path: createBaseline },
159
172
  json: {
160
173
  schemaVersion: '1.0',
161
174
  path: createBaseline,
@@ -221,7 +234,7 @@ addCommonOptions(program.command('upgrade'))
221
234
  addCommonOptions(program.command('report'))
222
235
  .description('Combined audit + pin (dry) + upgrade (dry) report')
223
236
  .addOption(new Option('--mode <m>', 'upgrade scope').choices(['major', 'minor', 'patch']).default('minor'))
224
- .addOption(new Option('--severity <level>', 'minimum audit severity').choices(['low', 'medium', 'high', 'critical']))
237
+ .addOption(new Option('--severity <level>', 'minimum audit severity').choices(SEVERITY_LEVELS))
225
238
  .option('--explain', 'include remediation hints in audit findings')
226
239
  .addOption(new Option('--min-age <days>', 'cooldown for upgrades (days)')
227
240
  .argParser(value => parseInteger(value, '--min-age', { min: 0 }))
@@ -275,7 +288,7 @@ program.command('org-scan <organization>')
275
288
  .description('Scan workflow security across a GitHub organization')
276
289
  .addOption(new Option('-r, --repository <pattern...>', 'repository name or glob (repeatable)')
277
290
  .argParser((value, previous) => collectNonEmpty(value, previous, '--repository')))
278
- .addOption(new Option('--visibility <visibility>', 'repository visibility').choices(['all', 'public', 'private', 'internal']).default('all'))
291
+ .addOption(new Option('--visibility <visibility>', 'repository visibility').choices(VISIBILITY_FILTERS).default('all'))
279
292
  .option('--include-archived', 'include archived repositories')
280
293
  .option('--include-disabled', 'include disabled repositories')
281
294
  .option('--include-forks', 'include forked repositories')
@@ -284,7 +297,7 @@ program.command('org-scan <organization>')
284
297
  .addOption(new Option('--concurrency <count>', 'concurrent repository scans (1-16)')
285
298
  .argParser(value => parseInteger(value, '--concurrency', { min: 1, max: 16 }))
286
299
  .default(4))
287
- .addOption(new Option('--severity <level>', 'minimum severity').choices(['low', 'medium', 'high', 'critical']))
300
+ .addOption(new Option('--severity <level>', 'minimum severity').choices(SEVERITY_LEVELS))
288
301
  .option('--explain', 'include plain-English remediation hint for each finding')
289
302
  .addOption(new Option('--config <path>', 'organization-wide policy file (default: .actions-warden.yml)')
290
303
  .argParser(value => parseNonEmpty(value, '--config'))
@@ -292,131 +305,67 @@ program.command('org-scan <organization>')
292
305
  .addOption(new Option('--ignore-config', 'do not load organization-wide policy').conflicts('config'))
293
306
  .addOption(new Option('--baseline <path>', 'suppress findings recorded in an organization baseline')
294
307
  .argParser(value => parseNonEmpty(value, '--baseline')))
295
- .addOption(new Option('--checkpoint <path>', 'create or replace a resumable scan checkpoint')
308
+ .addOption(new Option('--checkpoint <path>', 'create or automatically resume a scan checkpoint')
296
309
  .argParser(value => parseNonEmpty(value, '--checkpoint'))
297
310
  .conflicts('resume'))
298
311
  .addOption(new Option('--resume <path>', 'resume from and update an existing checkpoint')
299
312
  .argParser(value => parseNonEmpty(value, '--resume'))
300
313
  .conflicts('checkpoint'))
301
- .addOption(new Option('--progress <mode>', 'live progress on stderr').choices(['auto', 'always', 'never']).default('auto'))
314
+ .addOption(new Option('--fresh', 'start fresh and replace the selected checkpoint')
315
+ .conflicts('resume'))
316
+ .addOption(new Option('--no-auto-checkpoint', 'disable the automatic scope-specific checkpoint'))
317
+ .addOption(new Option('--previous-report <path>', 'compare with a prior organization JSON report')
318
+ .argParser(value => parseNonEmpty(value, '--previous-report')))
319
+ .addOption(new Option('--progress <mode>', 'stderr progress: auto, plain, json, or none')
320
+ .choices(['auto', 'plain', 'json', 'none'])
321
+ .default('auto'))
322
+ .addOption(new Option('--report-dir <dir>', 'write compact JSON plus per-repository artifacts')
323
+ .argParser(value => parseNonEmpty(value, '--report-dir'))
324
+ .conflicts('outputPath'))
302
325
  .option('--agent-mode', 'use bounded AI-agent output and automatic artifacts')
303
326
  .option('--no-agent-mode', 'disable agent mode from the environment')
304
327
  .addOption(createCwdOption())
305
328
  .addOption(createTokenOption())
306
- .addOption(createFormatOption())
307
- .addOption(createOutputOption())
329
+ .addOption(createFormatOption('json'))
330
+ .addOption(createOutputOption('file'))
308
331
  .addOption(createOutputPathOption())
309
332
  .action(async (organization, opts, command) => {
310
333
  await validateWorkingDirectory(opts.cwd);
311
334
  assertMutuallyExclusiveFlags('--agent-mode', '--no-agent-mode');
312
- const concurrency = opts.concurrency;
313
- const maxRepositories = opts.maxRepos;
314
- const agentMode = resolveAgentMode({
335
+ const executionContext = resolveExecutionContext({
315
336
  optionValue: opts.agentMode,
316
337
  optionSource: command.getOptionValueSource('agentMode'),
317
- environmentValue: process.env[AGENT_MODE_ENVIRONMENT_VARIABLE],
318
- });
319
- const effective = { ...opts };
320
- if (agentMode) {
321
- if (command.getOptionValueSource('format') === 'default') effective.format = 'json';
322
- if (command.getOptionValueSource('output') === 'default') effective.output = 'file';
323
- if (command.getOptionValueSource('progress') === 'default') effective.progress = 'never';
324
- }
325
- const agentArtifacts = agentMode
326
- ? await createOrganizationAgentArtifacts({
327
- organization,
328
- cwd: effective.cwd,
329
- repositories: effective.repository,
330
- visibility: effective.visibility,
331
- includeArchived: Boolean(effective.includeArchived),
332
- includeDisabled: Boolean(effective.includeDisabled),
333
- includeForks: Boolean(effective.includeForks),
334
- maxRepositories,
335
- severity: effective.severity,
336
- explain: Boolean(effective.explain),
337
- configPath: effective.ignoreConfig ? false : effective.config,
338
- baseline: effective.baseline,
339
- reportFormat: effective.format,
340
- })
341
- : null;
342
- if (agentMode && effective.output === 'file' && !effective.outputPath) {
343
- effective.outputPath = agentArtifacts.reportPath;
344
- }
345
- const outputDestination = await validateOutputDestination(effective);
346
- await assertDestinationsUseSafeNames(
347
- outputDestination ? [outputDestination] : [],
348
- effective.cwd,
349
- );
350
- let checkpointPath = effective.resume ?? effective.checkpoint;
351
- let resume = Boolean(effective.resume);
352
- if (agentMode && !checkpointPath) {
353
- checkpointPath = agentArtifacts.checkpointPath;
354
- resume = agentArtifacts.resume;
355
- }
356
- const checkpointDestination = checkpointPath
357
- ? await validateWriteDestination({
358
- option: resume ? '--resume' : '--checkpoint',
359
- path: checkpointPath,
360
- cwd: effective.cwd,
361
- })
362
- : null;
363
- await assertDestinationsUseSafeNames(
364
- checkpointDestination ? [checkpointDestination] : [],
365
- effective.cwd,
366
- );
367
- if (
368
- checkpointDestination
369
- && outputDestination
370
- && await sameFilePath(checkpointDestination.path, outputDestination.path)
371
- ) {
372
- throw new Error('checkpoint and report output paths must be different');
373
- }
374
- const result = await scanOrganization({
375
- organization,
376
- cwd: effective.cwd,
377
- token: effective.token,
378
- repositories: effective.repository,
379
- visibility: effective.visibility,
380
- includeArchived: Boolean(effective.includeArchived),
381
- includeDisabled: Boolean(effective.includeDisabled),
382
- includeForks: Boolean(effective.includeForks),
383
- maxRepositories,
384
- concurrency,
385
- severity: effective.severity,
386
- explain: Boolean(effective.explain),
387
- configPath: effective.ignoreConfig ? false : effective.config,
388
- baseline: effective.baseline,
389
- checkpointPath,
390
- resume,
391
- onProgress: progressEnabled(effective.progress)
392
- ? event => {
393
- const message = formatOrganizationProgress(event);
394
- if (message) process.stderr.write(message);
395
- }
396
- : undefined,
397
- });
398
- await assertDestinationsDoNotReplaceControls(
399
- outputDestination ? [outputDestination] : [],
400
- [
401
- { label: 'active config', path: result.configPath },
402
- { label: 'active baseline', path: result.baseline.path },
403
- ],
404
- );
405
- const payload = renderOrganizationScan(result, {
406
- format: effective.format,
407
- cwd: effective.cwd,
338
+ environmentValue: process.env[EXECUTION_CONTEXT_ENVIRONMENT_VARIABLE],
408
339
  });
409
- await emit(payload, effective);
410
- if (agentMode && effective.output === 'file') {
411
- process.stdout.write(renderOrganizationAgentReceipt({
412
- result,
413
- reportPath: effective.outputPath,
414
- reportFormat: effective.format,
415
- checkpointPath,
416
- resumed: resume,
417
- }));
340
+ const effective = resolveOrganizationScanOptions(opts, command);
341
+ let progressReporter;
342
+ const startedAt = new Date();
343
+ try {
344
+ const run = await runOrganizationScan({
345
+ ...organizationRunOptions(organization, effective),
346
+ scanOrganization,
347
+ openProgress: () => {
348
+ progressReporter = openOrganizationProgress({
349
+ organization,
350
+ effective,
351
+ command,
352
+ executionContext,
353
+ });
354
+ return progressReporter;
355
+ },
356
+ });
357
+ await writeOrganizationOutput({
358
+ run,
359
+ effective,
360
+ agentMode: executionContext === 'agent',
361
+ startedAt,
362
+ });
363
+ process.exitCode = run.result.status === 'OK' ? 0 : 1;
364
+ progressReporter?.close();
365
+ } catch (error) {
366
+ if (!structuredProgressContext) progressReporter?.close();
367
+ throw error;
418
368
  }
419
- process.exitCode = result.status === 'OK' ? 0 : 1;
420
369
  });
421
370
 
422
371
  program.command('rules')
@@ -426,6 +375,7 @@ program.command('rules')
426
375
  const rules = listRules();
427
376
  const payload = fmt(opts.format, rules.map(r => ({ label: 'RULE', fields: r })), {
428
377
  status: 'OK',
378
+ title: 'Audit rule catalog',
429
379
  json: { schemaVersion: '1.0', rules, status: 'OK' },
430
380
  });
431
381
  process.stdout.write(payload);
@@ -436,10 +386,30 @@ program.parseAsync(process.argv).catch((err) => {
436
386
  process.exitCode = err.exitCode;
437
387
  return;
438
388
  }
439
- process.stderr.write(`error: ${err.message}\n`);
389
+ if (isScanFailureReported(err)) {
390
+ // The scan adapter already emitted the terminal structured failure.
391
+ } else if (structuredProgressContext) {
392
+ structuredProgressContext.reporter.emit({
393
+ type: 'command-failed',
394
+ organization: structuredProgressContext.organization,
395
+ error: String(err?.message ?? err),
396
+ });
397
+ } else {
398
+ process.stderr.write(`error: ${cliErrorText(err)}\n`);
399
+ }
400
+ structuredProgressContext?.reporter.close();
440
401
  process.exitCode = 2;
441
402
  });
442
403
 
404
+ function cliErrorText(error) {
405
+ return [...redact(String(error?.message ?? error))]
406
+ .map(char => {
407
+ const code = char.charCodeAt(0);
408
+ return code < 32 || code === 127 ? ' ' : char;
409
+ })
410
+ .join('');
411
+ }
412
+
443
413
  function parseNonEmpty(value, option) {
444
414
  if (value.length === 0) {
445
415
  throw new InvalidArgumentError(`${option} must be non-empty`);
@@ -475,10 +445,6 @@ function parseFixId(value) {
475
445
  return value.toLowerCase();
476
446
  }
477
447
 
478
- function progressEnabled(mode) {
479
- return mode === 'always' || (mode === 'auto' && Boolean(process.stderr.isTTY));
480
- }
481
-
482
448
  async function preflightRepositoryCommand(opts, { additionalDestinations = [] } = {}) {
483
449
  await validateWorkingDirectory(opts.cwd);
484
450
  const outputDestination = await validateOutputDestination(opts);
@@ -501,18 +467,6 @@ async function preflightRepositoryCommand(opts, { additionalDestinations = [] }
501
467
  return destinations;
502
468
  }
503
469
 
504
- async function assertDestinationsUseSafeNames(destinations, cwd) {
505
- await assertDestinationsDoNotReplaceControls(
506
- destinations,
507
- DEFAULT_CONFIG_PATHS.map(path => ({ label: 'reserved config path', path: resolve(cwd, path) })),
508
- );
509
- for (const destination of destinations) {
510
- if (isDefaultWorkflowPath(destination.path, cwd)) {
511
- throw new Error(`${destination.option} cannot use a default workflow discovery path`);
512
- }
513
- }
514
- }
515
-
516
470
  async function validateWorkingDirectory(cwd) {
517
471
  if (typeof cwd !== 'string' || cwd.length === 0 || cwd.includes('\0')) {
518
472
  throw new Error('--cwd must be an existing directory');
@@ -529,10 +483,14 @@ async function validateWorkingDirectory(cwd) {
529
483
  if (!metadata.isDirectory()) throw new Error('--cwd must be an existing directory');
530
484
  }
531
485
 
532
- async function validateOutputDestination(opts) {
486
+ function assertOutputPathUsesFile(opts) {
533
487
  if (opts.outputPath && opts.output !== 'file') {
534
488
  throw new Error('--output-path cannot be used with --output=stdout');
535
489
  }
490
+ }
491
+
492
+ async function validateOutputDestination(opts) {
493
+ assertOutputPathUsesFile(opts);
536
494
  if (opts.output !== 'file') return null;
537
495
  if (!opts.outputPath) throw new Error('--output-path is required when --output=file');
538
496
  return validateWriteDestination({
@@ -542,41 +500,102 @@ async function validateOutputDestination(opts) {
542
500
  });
543
501
  }
544
502
 
545
- async function validateWriteDestination({ option, path, cwd }) {
546
- if (typeof path !== 'string' || path.length === 0 || path.includes('\0')) {
547
- throw new Error(`${option} must be a non-empty path`);
548
- }
549
- try {
550
- await writeFileGuarded({ path, content: '', dryRun: true, cwd });
551
- } catch (error) {
552
- if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
553
- throw new Error(`parent directory for ${option} must exist`);
503
+ function resolveOrganizationScanOptions(opts, command) {
504
+ const effective = { ...opts };
505
+ if (effective.reportDir) {
506
+ if (command.getOptionValueSource('format') === 'cli' && effective.format !== 'json') {
507
+ throw new Error('--report-dir supports only --format=json');
554
508
  }
555
- throw error;
509
+ if (command.getOptionValueSource('output') === 'cli' && effective.output !== 'file') {
510
+ throw new Error('--report-dir cannot be used with --output=stdout');
511
+ }
512
+ effective.format = 'json';
513
+ effective.output = 'file';
556
514
  }
557
- return { option, path: resolve(cwd, path) };
515
+ if (effective.previousReport && effective.format === 'sarif') {
516
+ throw new Error('--previous-report cannot be used with --format=sarif');
517
+ }
518
+ assertOutputPathUsesFile(effective);
519
+ return effective;
558
520
  }
559
521
 
560
- async function assertDestinationsAreDistinct(destinations) {
561
- for (let left = 0; left < destinations.length; left += 1) {
562
- for (let right = left + 1; right < destinations.length; right += 1) {
563
- if (await sameFilePath(destinations[left].path, destinations[right].path)) {
564
- throw new Error(
565
- `${destinations[left].option} and ${destinations[right].option} must use different paths`,
566
- );
567
- }
568
- }
569
- }
522
+ function organizationRunOptions(organization, effective) {
523
+ return {
524
+ scan: {
525
+ organization,
526
+ cwd: effective.cwd,
527
+ token: effective.token,
528
+ repositories: effective.repository,
529
+ visibility: effective.visibility,
530
+ includeArchived: Boolean(effective.includeArchived),
531
+ includeDisabled: Boolean(effective.includeDisabled),
532
+ includeForks: Boolean(effective.includeForks),
533
+ maxRepositories: effective.maxRepos,
534
+ concurrency: effective.concurrency,
535
+ severity: effective.severity,
536
+ explain: Boolean(effective.explain),
537
+ configPath: effective.ignoreConfig ? false : effective.config,
538
+ baseline: effective.baseline,
539
+ },
540
+ format: effective.format,
541
+ output: effective.output,
542
+ outputPath: effective.outputPath,
543
+ reportDirectory: effective.reportDir,
544
+ checkpointPath: effective.checkpoint,
545
+ resumePath: effective.resume,
546
+ fresh: Boolean(effective.fresh),
547
+ autoCheckpoint: effective.autoCheckpoint !== false,
548
+ previousReportPath: effective.previousReport,
549
+ labels: { output: '--output-path', checkpoint: '--checkpoint', resume: '--resume' },
550
+ };
570
551
  }
571
552
 
572
- async function assertDestinationsDoNotReplaceControls(destinations, controls) {
573
- for (const destination of destinations) {
574
- for (const control of controls) {
575
- if (control.path && await sameFilePath(destination.path, resolve(control.path))) {
576
- throw new Error(`${destination.option} cannot replace the ${control.label}`);
577
- }
578
- }
553
+ function openOrganizationProgress({ organization, effective, command, executionContext }) {
554
+ const reporter = createOrganizationProgressReporter({
555
+ mode: effective.progress,
556
+ context: command.getOptionValueSource('progress') === 'cli' ? 'auto' : executionContext,
557
+ stream: process.stderr,
558
+ });
559
+ if (reporter.mode === 'json') structuredProgressContext = { organization, reporter };
560
+ return reporter;
561
+ }
562
+
563
+ async function writeOrganizationOutput({ run, effective, agentMode, startedAt }) {
564
+ const { result } = run;
565
+ let reportPath = run.reportPath;
566
+ let reportDirectoryPath;
567
+ let manifestPath;
568
+ if (run.reportDirectory) {
569
+ const directoryResult = await writeOrganizationReportDirectory({
570
+ result,
571
+ path: effective.reportDir,
572
+ cwd: effective.cwd,
573
+ });
574
+ reportPath = directoryResult.reportPath;
575
+ reportDirectoryPath = directoryResult.directory;
576
+ manifestPath = directoryResult.manifestPath;
577
+ } else {
578
+ const payload = renderOrganizationScan(result, {
579
+ format: effective.format,
580
+ cwd: effective.cwd,
581
+ });
582
+ await emit(payload, { ...effective, outputPath: run.reportPath });
579
583
  }
584
+ if (effective.output !== 'file') return;
585
+ process.stdout.write(renderOrganizationScanReceipt({
586
+ result,
587
+ startedAt,
588
+ finishedAt: new Date(),
589
+ reportPath,
590
+ reportFormat: effective.format,
591
+ checkpointPath: run.checkpointPath,
592
+ resumed: run.resumed,
593
+ repositoriesReused: run.repositoriesReused,
594
+ reportLayout: run.reportDirectory ? 'directory' : 'single',
595
+ reportDirectory: reportDirectoryPath,
596
+ manifestPath,
597
+ kind: agentMode ? 'actions-warden-agent-receipt' : 'actions-warden-org-scan-receipt',
598
+ }));
580
599
  }
581
600
 
582
601
  function assertMutuallyExclusiveFlags(left, right) {
@@ -586,8 +605,3 @@ function assertMutuallyExclusiveFlags(left, right) {
586
605
  }
587
606
  }
588
607
 
589
- function isDefaultWorkflowPath(path, cwd) {
590
- const localPath = relative(resolve(cwd), path).split(sep).join('/');
591
- return /^\.github\/workflows\/[^/]+\.ya?ml$/i.test(localPath)
592
- || /(^|\/)action\.ya?ml$/i.test(localPath);
593
- }
@@ -16,20 +16,11 @@ import { format, summarize, SEVERITY_ORDER } from '../lib/formatter.js';
16
16
  import { parseIgnoreDirectives, isIgnored } from '../lib/ignore.js';
17
17
  import { canonicalPath, occurrenceId, pinOccurrenceId } from '../lib/identity.js';
18
18
  import { resolveTargets } from '../lib/targets.js';
19
- import { assignBaselineFingerprints, loadBaseline } from '../lib/baseline.js';
19
+ import { assignBaselineFingerprints, emptyBaseline, loadBaseline } from '../lib/baseline.js';
20
20
  import { DEFAULT_CONFIG, filterIgnoredPaths, loadConfig } from '../lib/config.js';
21
21
  import { RULES } from '../rules/index.js';
22
22
 
23
- /**
24
- * @typedef {object} Finding
25
- * @property {string} id - unique id (sha1 short)
26
- * @property {string} ruleId
27
- * @property {string} severity
28
- * @property {string} file
29
- * @property {number} line
30
- * @property {Record<string, unknown>} fields
31
- * @property {string} explain
32
- */
23
+ /** @typedef {import('../lib/types.js').Finding} Finding */
33
24
 
34
25
  /**
35
26
  * @param {object} opts
@@ -227,20 +218,12 @@ async function resolveBaselineData({ baseline, cwd }) {
227
218
  : emptyBaseline();
228
219
  }
229
220
 
230
- function emptyBaseline() {
231
- return { path: null, ids: new Set(), fingerprints: new Set() };
232
- }
233
-
234
221
  function stripExplain(f) {
235
222
  const copy = { ...f };
236
223
  delete copy.explain;
237
224
  return copy;
238
225
  }
239
226
 
240
- /**
241
- * @param {string[]|undefined} workflows
242
- * @param {string} cwd
243
- */
244
227
  /**
245
228
  * @param {Finding[]} findings
246
229
  * @param {string|undefined} min
@@ -255,15 +238,12 @@ function filterBySeverity(findings, min) {
255
238
  ));
256
239
  }
257
240
 
258
- function relPath(p, cwd) {
259
- return canonicalPath(p, cwd);
260
- }
261
-
262
241
  /**
263
242
  * Render an audit result to the chosen format.
264
243
  *
265
244
  * @param {Awaited<ReturnType<typeof audit>>} result
266
- * @param {{format: 'toon'|'json'|'text', explain?: boolean, cwd?: string}} opts
245
+ * @param {{format: 'toon'|'json'|'text'|'csv'|'sarif'|'html', explain?: boolean,
246
+ * cwd?: string}} opts
267
247
  */
268
248
  export function renderAudit(result, opts) {
269
249
  const cwd = opts.cwd ?? process.cwd();
@@ -272,14 +252,14 @@ export function renderAudit(result, opts) {
272
252
  status: result.status,
273
253
  json: {
274
254
  schemaVersion: '1.0',
275
- files: result.files.map(f => relPath(f, cwd)),
276
- findings: result.findings.map(f => ({ ...f, file: relPath(f.file, cwd) })),
255
+ files: result.files.map(f => canonicalPath(f, cwd)),
256
+ findings: result.findings.map(f => ({ ...f, file: canonicalPath(f.file, cwd) })),
277
257
  summary: result.summary,
278
258
  baseline: {
279
259
  ...result.baseline,
280
- path: result.baseline.path ? relPath(result.baseline.path, cwd) : null,
260
+ path: result.baseline.path ? canonicalPath(result.baseline.path, cwd) : null,
281
261
  },
282
- configPath: result.configPath ? relPath(result.configPath, cwd) : null,
262
+ configPath: result.configPath ? canonicalPath(result.configPath, cwd) : null,
283
263
  status: result.status,
284
264
  },
285
265
  });
@@ -299,7 +279,7 @@ export function renderAudit(result, opts) {
299
279
  }
300
280
  }
301
281
  for (const f of result.files) {
302
- records.push({ label: 'SCAN', fields: { file: relPath(f, opts.cwd ?? process.cwd()) } });
282
+ records.push({ label: 'SCAN', fields: { file: canonicalPath(f, opts.cwd ?? process.cwd()) } });
303
283
  }
304
284
  for (const finding of result.findings) {
305
285
  const fields = { id: finding.id, ...finding.fields, line: finding.line };
@@ -310,5 +290,12 @@ export function renderAudit(result, opts) {
310
290
  records.push({ label: 'FINDING', fields });
311
291
  }
312
292
  records.push({ label: 'SUMMARY', fields: result.summary });
313
- return format(opts.format, records, { status: result.status });
293
+ return format(opts.format, records, {
294
+ status: result.status,
295
+ title: 'Workflow security audit',
296
+ metadata: {
297
+ config: result.configPath ? canonicalPath(result.configPath, cwd) : 'built-in defaults',
298
+ baseline: result.baseline.path ? canonicalPath(result.baseline.path, cwd) : 'none',
299
+ },
300
+ });
314
301
  }