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/lib/config.js CHANGED
@@ -2,9 +2,9 @@ import { readFile, realpath } from 'node:fs/promises';
2
2
  import { isAbsolute, relative, resolve, sep } from 'node:path';
3
3
  import picomatch from 'picomatch';
4
4
  import { parseDocument } from 'yaml';
5
+ import { SEVERITIES, isRecord } from './org-schema.js';
5
6
 
6
7
  const CONFIG_NAMES = ['.actions-warden.yml', '.actions-warden.yaml'];
7
- const SEVERITIES = new Set(['low', 'medium', 'high', 'critical']);
8
8
  const TOP_LEVEL_KEYS = new Set([
9
9
  'version',
10
10
  'baseline',
@@ -13,6 +13,10 @@ const TOP_LEVEL_KEYS = new Set([
13
13
  'runner-policy',
14
14
  ]);
15
15
 
16
+ /**
17
+ * Normalized built-in policy used when no repository configuration is found.
18
+ * Callers should treat the nested values as read-only defaults.
19
+ */
16
20
  export const DEFAULT_CONFIG = Object.freeze({
17
21
  path: null,
18
22
  baseline: null,
@@ -83,6 +87,7 @@ export async function loadConfig({
83
87
  };
84
88
  }
85
89
 
90
+ /** Remove files matched by repository-relative policy ignore globs. */
86
91
  export function filterIgnoredPaths(files, config, cwd) {
87
92
  if (config.ignorePaths.length === 0) return files;
88
93
  const matchers = config.ignorePaths.map(pattern => picomatch(pattern, { dot: true }));
@@ -92,6 +97,10 @@ export function filterIgnoredPaths(files, config, cwd) {
92
97
  });
93
98
  }
94
99
 
100
+ /**
101
+ * Resolve an existing repository path after rejecting lexical and real-path
102
+ * escapes, including escapes through symbolic links.
103
+ */
95
104
  export async function resolveRepositoryFile(path, cwd = process.cwd()) {
96
105
  const requestedRoot = resolve(cwd);
97
106
  const requested = resolve(requestedRoot, path);
@@ -176,10 +185,6 @@ function optionalString(value, label) {
176
185
  return value;
177
186
  }
178
187
 
179
- function isRecord(value) {
180
- return value !== null && typeof value === 'object' && !Array.isArray(value);
181
- }
182
-
183
188
  function isOutside(path) {
184
189
  return path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path);
185
190
  }
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Shared destination and control-file collision validation.
3
+ */
4
+
5
+ import { relative, resolve, sep } from 'node:path';
6
+ import { sameFilePath } from './path-equality.js';
7
+ import { writeFileGuarded } from './writer.js';
8
+
9
+ export const DEFAULT_CONFIG_PATHS = ['.actions-warden.yml', '.actions-warden.yaml'];
10
+
11
+ /**
12
+ * Check if a path corresponds to a default workflow or composite-action path.
13
+ *
14
+ * @param {string} path
15
+ * @param {string} cwd
16
+ * @returns {boolean}
17
+ */
18
+ export function isDefaultWorkflowPath(path, cwd) {
19
+ const localPath = relative(resolve(cwd), path).split(sep).join('/');
20
+ return /^\.github\/workflows\/[^/]+\.ya?ml$/i.test(localPath)
21
+ || /(^|\/)action\.ya?ml$/i.test(localPath);
22
+ }
23
+
24
+ /**
25
+ * Ensure destination paths cannot replace reserved config paths or default workflow paths.
26
+ *
27
+ * @param {Array<{label?: string, option?: string, path: string}>} destinations
28
+ * @param {string} cwd
29
+ */
30
+ export async function assertDestinationsUseSafeNames(destinations, cwd) {
31
+ await assertDestinationsDoNotReplaceControls(
32
+ destinations,
33
+ DEFAULT_CONFIG_PATHS.map(path => ({ label: 'reserved config path', path: resolve(cwd, path) })),
34
+ );
35
+ for (const destination of destinations) {
36
+ if (isDefaultWorkflowPath(destination.path, cwd)) {
37
+ const name = destination.option || destination.label || 'destination';
38
+ throw new Error(`${name} cannot use a default workflow discovery path`);
39
+ }
40
+ }
41
+ }
42
+
43
+ /**
44
+ * Ensure destination paths do not collide with control files.
45
+ *
46
+ * @param {Array<{label?: string, option?: string, path: string}>} destinations
47
+ * @param {Array<{label: string, path: string|null|undefined}>} controls
48
+ */
49
+ export async function assertDestinationsDoNotReplaceControls(destinations, controls) {
50
+ for (const destination of destinations) {
51
+ if (!destination.path) continue;
52
+ for (const control of controls) {
53
+ if (control.path && await sameFilePath(destination.path, resolve(control.path))) {
54
+ const name = destination.option || destination.label || 'destination';
55
+ throw new Error(`${name} cannot replace the ${control.label}`);
56
+ }
57
+ }
58
+ }
59
+ }
60
+
61
+ /**
62
+ * Ensure multiple write destinations are distinct from each other.
63
+ *
64
+ * @param {Array<{label?: string, option?: string, path: string}>} destinations
65
+ */
66
+ export async function assertDestinationsAreDistinct(destinations) {
67
+ for (let left = 0; left < destinations.length; left += 1) {
68
+ for (let right = left + 1; right < destinations.length; right += 1) {
69
+ if (await sameFilePath(destinations[left].path, destinations[right].path)) {
70
+ const leftName = destinations[left].option || destinations[left].label || 'destination';
71
+ const rightName = destinations[right].option || destinations[right].label || 'destination';
72
+ throw new Error(`${leftName} and ${rightName} must use different paths`);
73
+ }
74
+ }
75
+ }
76
+ }
77
+
78
+ /**
79
+ * Validate that a write destination can be created safely.
80
+ *
81
+ * @param {{option?: string, label?: string, path: string, cwd: string}} options
82
+ * @returns {Promise<{option?: string, label?: string, path: string}>}
83
+ */
84
+ export async function validateWriteDestination({ option, label, path, cwd }) {
85
+ const name = option || label || 'destination';
86
+ if (typeof path !== 'string' || path.length === 0 || path.includes('\0')) {
87
+ throw new Error(`${name} must be a non-empty path`);
88
+ }
89
+ try {
90
+ await writeFileGuarded({ path, content: '', dryRun: true, cwd });
91
+ return { option, label, path: resolve(cwd, path) };
92
+ } catch (error) {
93
+ if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
94
+ throw new Error(`parent directory for ${name} must exist`);
95
+ }
96
+ throw error;
97
+ }
98
+ }
@@ -4,7 +4,7 @@
4
4
  * code execution while covering common build/test/package entry points.
5
5
  */
6
6
 
7
- const WORKSPACE_COMMAND = /(?:^|[;&|])\s*(?:sudo\s+)?(?:(?:\.{0,2}[\\/]|[A-Za-z]:[\\/]|[A-Za-z0-9_.-]+[\\/])[^\s;&|]+|source\s+[^\s;&|]+|make(?:\s|$)|npm\s+(?:ci|install|test|run|exec)\b|npx\b|pnpm\s+(?:install|test|run|exec)\b|yarn\s+(?:install|test|run|exec)\b|bun\s+(?:install|test|run|x)\b|(?:bash|sh|zsh|python3?|ruby|node|perl|php)\s+[^\s;&|]+|(?:pwsh|powershell)(?:\.exe)?\s+(?:-File\s+)?[^\s;&|]+|cmd(?:\.exe)?\s+\/c\s+[^\s;&|]+|java\s+-jar\s+[^\s;&|]+|cargo\s+(?:build|test|run)\b|go\s+(?:build|test|run)\b|mvn\b|gradle\b|\.\/gradlew\b|dotnet\s+(?:build|test|run|publish)\b|bundle\s+exec\b|rake\b|pytest\b)/im;
7
+ const WORKSPACE_COMMAND = /(?:^|[;&|])\s*(?:sudo\s+)?(?:(?:\.{0,2}[\\/]|[A-Za-z]:[\\/]|[A-Za-z0-9_.-]+[\\/])[^\s;&|]+|source\s+[^\s;&|]+|make(?:\s|$)|npm\s+(?:ci|install|test|run|exec)\b|npx\b|pnpm\s+(?:install|test|run|exec)\b|yarn\s+(?:install|test|run|exec)\b|bun\s+(?:install|test|run|x)\b|deno\s+(?:run|test|task)\b|(?:pip3?|uv\s+pip|poetry)\s+(?:install|run)\b|uv\s+run\b|tox\b|nox\b|composer\s+(?:install|run|exec)\b|swift\s+(?:build|test)\b|sbt\b|cmake\s+--build\b|(?:bash|sh|zsh|python3?|ruby|node|perl|php)\s+[^\s;&|]+|(?:pwsh|powershell)(?:\.exe)?\s+(?:-File\s+)?[^\s;&|]+|cmd(?:\.exe)?\s+\/c\s+[^\s;&|]+|java\s+-jar\s+[^\s;&|]+|cargo\s+(?:build|test|run|check|clippy)\b|go\s+(?:build|test|run)\b|mvn\b|gradle\b|\.\/gradlew\b|dotnet\s+(?:build|test|run|publish)\b|bundle\s+exec\b|rake\b|pytest\b|docker(?:\s+compose)?\s+(?:build|run)\b)/im;
8
8
  const WORKSPACE_ACTION = /(?:^|[-_/])(build|builder|compile|exec|package|publish|runner|test|deploy)(?:[-_/]|$)/i;
9
9
 
10
10
  /**
@@ -40,6 +40,10 @@ export function executesWorkspace(step, { sourcePaths = ['.'] } = {}) {
40
40
  ));
41
41
  }
42
42
 
43
+ /**
44
+ * Normalize a configured source path, conservatively treating dynamic
45
+ * expressions and empty values as the workspace root.
46
+ */
43
47
  export function normalizeSourcePath(value) {
44
48
  if (typeof value !== 'string' || !value.trim()) return '.';
45
49
  const expanded = normalizeTrustedRoots(value);
@@ -0,0 +1,125 @@
1
+ // @ts-check
2
+ /**
3
+ * Deterministic RFC 4180-compatible CSV with an explicit status row.
4
+ */
5
+
6
+ import { redact, redactDeep } from '../redact.js';
7
+
8
+ const CSV_PREFERRED_COLUMNS = Object.freeze([
9
+ 'status',
10
+ 'organization',
11
+ 'repo',
12
+ 'repository',
13
+ 'file',
14
+ 'path',
15
+ 'line',
16
+ 'id',
17
+ 'type',
18
+ 'ruleId',
19
+ 'sev',
20
+ 'severity',
21
+ 'action',
22
+ 'image',
23
+ 'from',
24
+ 'to',
25
+ 'sha',
26
+ 'version',
27
+ 'level',
28
+ 'change',
29
+ 'msg',
30
+ 'explain',
31
+ 'url',
32
+ 'permalink',
33
+ ]);
34
+
35
+ /**
36
+ * Render records as deterministic RFC 4180-compatible CSV. The first column
37
+ * identifies the record type and a final STATUS record preserves semantic
38
+ * status. Control characters are escaped to keep one physical line per record,
39
+ * and formula-like cells are prefixed with an apostrophe for spreadsheet safety.
40
+ *
41
+ * @param {Array<{label: string, fields: Record<string, unknown>}>} records
42
+ * @param {{status?: 'OK'|'FAIL'}} [options]
43
+ * @returns {string}
44
+ */
45
+ export function renderCsv(records, options = {}) {
46
+ const normalized = normalizeCsvRecords(records);
47
+ if (options.status) {
48
+ normalized.push({
49
+ label: 'STATUS',
50
+ fields: new Map([['status', redact(String(options.status))]]),
51
+ });
52
+ }
53
+
54
+ const discovered = new Set(normalized.flatMap(record => [...record.fields.keys()]));
55
+ discovered.delete('record_type');
56
+ const preferred = CSV_PREFERRED_COLUMNS.filter(column => discovered.delete(column));
57
+ const columns = ['record_type', ...preferred, ...[...discovered].sort()];
58
+ const rows = [columns.map(csvCell).join(',')];
59
+ for (const record of normalized) {
60
+ rows.push(columns.map(column => csvCell(
61
+ column === 'record_type' ? record.label : record.fields.get(column),
62
+ )).join(','));
63
+ }
64
+ return `${rows.join('\r\n')}\r\n`;
65
+ }
66
+
67
+ /**
68
+ * @param {unknown} records
69
+ * @returns {Array<{label: string, fields: Map<string, unknown>}>}
70
+ */
71
+ function normalizeCsvRecords(records) {
72
+ if (!Array.isArray(records)) return [];
73
+ return records.map(record => {
74
+ const source = record?.fields;
75
+ const entries = source && typeof source === 'object' && !Array.isArray(source)
76
+ ? Object.entries(source)
77
+ : [];
78
+ return {
79
+ label: redact(String(record?.label ?? 'RECORD')),
80
+ fields: new Map(entries.map(([key, value]) => [
81
+ redact(String(key)),
82
+ redactDeep(value),
83
+ ])),
84
+ };
85
+ });
86
+ }
87
+
88
+ /** @param {unknown} value */
89
+ function csvCell(value) {
90
+ if (value === null || value === undefined) return '';
91
+ const formulaSensitive = typeof value === 'string';
92
+ let serialized;
93
+ if (typeof value === 'string') {
94
+ serialized = redact(value);
95
+ } else if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
96
+ serialized = String(value);
97
+ } else {
98
+ serialized = JSON.stringify(redactDeep(value));
99
+ if (serialized === undefined) serialized = String(value);
100
+ }
101
+ serialized = escapeCsvControls(redact(serialized));
102
+ if (formulaSensitive && /^\s*[=+\-@]/u.test(serialized)) serialized = `'${serialized}`;
103
+ return /[",\r\n]/.test(serialized)
104
+ ? `"${serialized.replaceAll('"', '""')}"`
105
+ : serialized;
106
+ }
107
+
108
+ /** @param {string} value */
109
+ function escapeCsvControls(value) {
110
+ let escaped = '';
111
+ for (const character of value) {
112
+ if (character === '\r') escaped += '\\r';
113
+ else if (character === '\n') escaped += '\\n';
114
+ else if (character === '\t') escaped += '\\t';
115
+ else {
116
+ const code = character.charCodeAt(0);
117
+ if (code <= 31 || code === 127) {
118
+ escaped += `\\u${code.toString(16).padStart(4, '0')}`;
119
+ } else {
120
+ escaped += character;
121
+ }
122
+ }
123
+ }
124
+ return escaped;
125
+ }