actions-warden 0.2.0 → 0.4.0

package/docs/DEVELOPMENT.md

@@ -0,0 +1,373 @@
+# Developer guide
+
+This guide is for contributors changing actions-warden itself. For public CLI
+usage, start with the [CLI reference](./CLI.md).
+
+## Prerequisites
+
+- Node.js 20 or newer;
+- npm with the lockfile committed by the repository;
+- optional: `prek` or Python `pre-commit` for local hooks.
+
+Install exactly the locked dependency graph:
+
+```sh
+npm ci
+```
+
+The repository's `.npmrc` pins dependencies exactly and disables package
+lifecycle scripts during installation.
+
+Install hooks with either runner:
+
+```sh
+prek install --hook-type pre-commit --hook-type pre-push
+```
+
+or:
+
+```sh
+pre-commit install --hook-type pre-commit
+pre-commit install --hook-type pre-push
+```
+
+## Validation commands
+
+| command | purpose |
+|---|---|
+| `npm test` | Run the complete Vitest suite once |
+| `npm run test:watch` | Run Vitest in watch mode |
+| `npm run lint` | Lint source, scripts, and tests |
+| `npm run check:yaml` | Parse repository YAML files |
+| `npm run check:docs` | Validate local documentation links |
+| `npm run check:package` | Inspect the exact npm tarball manifest, required files, executable mode, and size bounds |
+| `npm run verify-deps` | Require exact runtime and development versions |
+| `npm run verify-version-sync` | Keep package, lockfile, bundled runtime, plugin, and public invocations aligned |
+| `npm run build:action` | Rebuild the committed Action bundle |
+| `npm run check:action-bundle` | Compare a clean rebuild with working and staged bundles |
+| `npm run audit` | Run the configured npm vulnerability threshold |
+| `npm run release:prepare -- X.Y.Z` | Update all local stable-version sources without committing or publishing |
+| `npm run release:check` | Gate a staged release candidate against npm state and every release validation |
+
+Before opening a pull request, run:
+
+```sh
+npm run verify-version-sync
+npm run verify-deps
+npm run check:yaml
+npm run check:docs
+npm run check:package
+npm run lint
+npm test
+npm run audit
+```
+
+If code reachable from `src/action.js` changed, also run:
+
+```sh
+npm run build:action
+npm run check:action-bundle
+```
+
+## Repository map
+
+```text
+src/
+  cli.js                    CLI parsing, exit codes, and output routing
+  action.js                 GitHub Action input/output adapter
+  index.js                  public JavaScript exports
+  version.js                runtime version embedded in the Action bundle
+  commands/                 audit, pin, verify, upgrade, report, org-scan
+  lib/
+    parser.js               YAML-to-normalized-workflow model
+    targets.js, paths.js    repository target discovery
+    path-equality.js        real-path destination/control comparisons
+    config.js, baseline.js  policy and accepted-finding controls
+    resolver.js, cache.js   GitHub API, caching, ref and ownership checks
+    github-org.js           read-only organization/tree/blob access
+    agent-mode.js           explicit bounded AI-agent CLI defaults
+    org-checkpoint.js       validated atomic organization resume state
+    org-progress.js         human rendering of structured scan progress
+    identity.js             stable IDs and semantic fingerprints
+    patcher.js, writer.js   source-range rewrites and guarded atomic writes
+    formatter.js, redact.js structured output and credential redaction
+    annotations.js          GitHub workflow annotations
+    concurrency.js          bounded async work
+  rules/                    one module per audit rule
+
+test/                       Vitest suites and hostile/edge-case fixtures
+scripts/                    repository validation and release helpers
+docs/                       user, integration, AI, and developer guides
+examples/                   copyable GitHub workflow examples
+skills/actions-warden/      Claude Code skill
+dist/                       generated, committed GitHub Action bundle
+action.yml                  public Action inputs, outputs, and runtime
+```
+
+## Data flow
+
+A local audit follows this path:
+
+```text
+targets → source read → YAML parser → normalized workflow model
+        → ignore directives → rules → stable identities
+        → severity/baseline filtering → renderer
+```
+
+Pin and upgrade add:
+
+```text
+normalized action refs → GitHub resolution and ownership verification
+                       → source-range patch plan → reparse
+                       → guarded atomic writer only when dryRun=false
+```
+
+An organization scan follows:
+
+```text
+repository listing → default-branch Git tree → bounded YAML blob reads
+                   → in-memory auditSources → repository aggregation
+
+optional checkpoint → identity validation → fresh tree SHA comparison
+                    → reuse unchanged error-free result or rescan
+```
+
+Remote repositories are never cloned, checked out, imported, or executed.
+
+## Safety invariants
+
+Changes must preserve these boundaries:
+
+- `pin` and `upgrade` default to dry-run at the command and API layers.
+- CLI and Action mutation require an explicit write option.
+- CLI integers and 16-hex change IDs use strict whole-value parsing. Commander
+  usage failures and application-level invocation failures both exit `2`.
+- A resolver failure must not fall back to a guessed tag or SHA.
+- Commits must be verified as belonging to the referenced repository.
+- Workflow rewrites operate on parsed scalar ranges and reparse before write.
+- Writes and configured paths remain inside the real repository root.
+- Symlink escapes and explicit targets that match nothing fail.
+- CLI report, baseline, and checkpoint destinations are preflighted before
+  network or workflow mutation, cannot replace selected/default-discovery
+  workflows or reserved policy paths, and are checked against active controls
+  again before output is written.
+- Credentials are redacted in JSON, TOON, text, SARIF, annotations, and
+  top-level errors.
+- Finding and change IDs exclude absolute checkout paths.
+- Parser errors remain findings and cannot be baselined away.
+- Organization coverage failures remain visible and make status fail.
+- Organization source reads remain count- and size-bounded and bypass disk
+  cache.
+- Organization resume never trusts a stale result without fresh discovery and
+  a matching repository identity, default branch, and tree SHA. Failed results
+  are never reused.
+- Organization result compatibility is controlled by
+  `ORGANIZATION_ANALYSIS_GENERATION`, not by the package version. Producer
+  versions remain checkpoint metadata and compatible checkpoints migrate
+  through the guarded atomic writer.
+- Checkpoints use guarded atomic writes, remain inside the working directory,
+  omit tokens and raw YAML, and cannot replace active policy or baseline files.
+- Progress stays outside deterministic report serialization; CLI progress is
+  stderr-only and Action progress cannot form workflow commands.
+- Agent mode is an explicit opt-in, never a TTY, parent-process, CI, or
+  vendor-environment heuristic. Explicit CLI output and progress options win.
+  Its automatic artifact key uses the validated checkpoint compatibility
+  identity, and its stdout receipt never includes findings or repository result
+  arrays.
+- Attacker-controlled values cannot forge TOON lines or GitHub annotations.
+
+Tests should demonstrate the fail-closed behavior for any change touching these
+boundaries.
+
+## Adding or changing a rule
+
+A rule module exports:
+
+```js
+export const id = 'example-rule';
+export const severity = 'high';
+export const description = 'Short sentence describing the risk.';
+
+export function check(workflow, context = {}) {
+  return [{
+    id,
+    severity,
+    line: 1,
+    fields: {
+      type: id,
+      sev: severity,
+      evidence: 'structured-value',
+    },
+    explain: 'one concise remediation',
+  }];
+}
+```
+
+Then:
+
+1. register the module in `src/rules/index.js`;
+2. add focused tests for safe and unsafe cases;
+3. test trigger, expression, quoting, and malformed-input boundaries relevant
+   to the rule;
+4. when behavior depends on a moving GitHub or first-party action contract,
+   verify it against a primary source, record the date/version boundary in code,
+   and test the last unsafe plus first safe version;
+5. test at least one legitimate pattern that must remain clean so remediation
+   guidance does not become a false-positive generator;
+6. update the rule table and accuracy boundaries in `docs/CONFIGURATION.md`,
+   plus the Claude skill;
+7. run `actions-warden rules --format=json` and ensure the ID is not redacted;
+8. rebuild the Action bundle.
+
+Keep `fields` structured and concise. They become JSON evidence, TOON fields,
+SARIF messages, and Action annotations. Never place raw secret values in them.
+Suggestions must name a safe end state, preserve legitimate use cases, and
+avoid claiming that one mitigation closes risks outside the rule's evidence.
+
+## Adding or changing a command
+
+A command normally needs changes in:
+
+1. `src/commands/<name>.js` for the API result and renderer;
+2. `src/cli.js` for public CLI flags and exit semantics;
+3. `src/index.js` and `package.json` exports;
+4. `src/action.js` and `action.yml` if the Action exposes it;
+5. command, CLI, Action, annotation, and output-format tests;
+6. `docs/CLI.md`, `docs/OUTPUTS.md`, API docs, and relevant examples;
+7. the Claude skill and version-sync checker when its command surface changes;
+8. the committed Action bundle.
+
+Return operational problems as structured `errors` when useful work can
+continue. Throw when top-level input or discovery makes the requested scope
+undefined or unsafe.
+
+Every non-JSON renderer must expose enough information to explain a `FAIL`
+status. Every JSON renderer must include `schemaVersion`, command data, and
+top-level `status`.
+
+## Parser and patcher changes
+
+The parser retains both a normalized model for rules and source locations for
+precise rewrites. When changing it:
+
+- cover workflow files and composite `action.yml` metadata;
+- preserve and recursively inspect steps inside `parallel` groups, while
+  retaining background/control-step declarations for structure checks;
+- include quoted, unquoted, inline, multiline, and malformed YAML cases;
+- avoid evaluating expressions;
+- preserve source offsets for patchable `uses` values;
+- test Windows and POSIX path normalization where relevant.
+
+The patcher should make the smallest source-range replacement. Do not reserialize
+the entire YAML document: that would destroy comments, formatting, anchors, and
+reviewable diffs.
+
+Property tests in `test/patcher-properties.test.js` exercise rewrite stability.
+
+## GitHub API changes
+
+All runtime requests belong in the resolver or organization GitHub layer and
+must remain pinned to `https://api.github.com`.
+
+For new endpoints:
+
+- validate status and response shape;
+- paginate boundedly;
+- validate identities, SHAs, sizes, encodings, and UTF-8 as applicable;
+- set timeouts and bounded retries through the shared fetch layer;
+- preserve authentication-isolated cache keys;
+- decide explicitly whether private content may be cached;
+- accumulate scoped errors when continued reporting is safe;
+- add tests with mocked responses for truncation and malformed data.
+
+Never execute content to determine what it contains.
+
+When changing organization resume behavior, cover interrupted writes,
+checkpoint schema and identity mismatches, hostile fields, changed tree SHAs,
+previous repository errors, output equivalence, and concurrent completions.
+Persist each completed result before emitting its completion event so an
+observer failure or process interruption loses at most in-flight work.
+
+`ORGANIZATION_ANALYSIS_GENERATION` in `src/lib/org-checkpoint.js` is the manual
+semantic compatibility switch. Increment it whenever organization workflow
+selection, parsing, finding identity, rule evaluation, suppression, summaries,
+or other persisted repository-result semantics can change. Keep it unchanged
+for documentation, release metadata, progress rendering, authentication,
+concurrency, or internal refactors that preserve those results. The rule
+catalog hash independently invalidates catalog changes. A generation change
+must add tests proving the old checkpoint fails closed and agent mode selects a
+new artifact key; a compatible format migration must prove the old checkpoint
+is validated, rewritten atomically, and still subject to fresh tree checks.
+
+## Output compatibility
+
+JSON is the public machine interface. Raw command results and serialized JSON
+are deliberately different: renderers add repository-relative paths,
+redaction, and `schemaVersion`.
+
+When changing output:
+
+- retain top-level `status`;
+- treat new fields as additive where possible;
+- update `docs/OUTPUTS.md`;
+- test all four formats;
+- prevent embedded control characters from forging records;
+- ensure error details are visible in every format;
+- verify stable IDs remain stable unless their semantic input changed.
+
+## GitHub Action bundle
+
+Never edit `dist/index.js` or `dist/package.json` by hand. They are generated:
+
+```sh
+npm run build:action
+```
+
+Commit source and its rebuilt bundle together when the Action runtime changes.
+`npm run check:action-bundle` performs a clean build in a temporary directory
+and compares both working-tree and staged bundle files.
+
+A docs-only, test-only, or CLI-only change that is unreachable from
+`src/action.js` does not require a bundle rebuild.
+
+## Tests and fixtures
+
+Tests use Vitest and should be deterministic and network-independent. Mock
+GitHub responses rather than relying on live repositories. Use temporary
+directories for writes and assert both file content and failure behavior.
+
+Useful focused runs:
+
+```sh
+npx vitest --run test/audit.test.js
+npx vitest --run test/org-scan.test.js
+npx vitest --run -t "stable id"
+```
+
+Keep hostile input in fixtures or inline strings when it clarifies the threat
+being tested. Tests should not contain real credentials.
+
+## Documentation maintenance
+
+README is the landing page, not the full manual. Put durable detail in the
+focused guide that owns it, then link from README.
+
+When CLI, Action, config, output, or API behavior changes:
+
+1. update the owning reference document;
+2. update examples and AI guidance that depend on it;
+3. run `npm run check:docs`;
+4. run live `--help` and at least one documented example against
+   `node src/cli.js`.
+
+Keep examples copyable, use exact package versions for `npx`, and use full
+commit placeholders for the Action itself.
+
+## Releases
+
+The authoritative [release runbook](../RELEASING.md) defines maintainer and
+agent authorization, SemVer selection, live-state preflight, preparation,
+trusted publication, monitoring, verification, and partial-failure recovery.
+Do not bump versions as part of an unrelated contribution. `release:prepare`
+is local-only; `release:check` is intended for a reviewed, staged candidate and
+will fail a stale or already-published version.

package/docs/GITHUB-ACTION.md

@@ -0,0 +1,285 @@
+# GitHub Action guide
+
+The bundled JavaScript Action runs the same commands as the CLI on GitHub's
+managed Node 24 runtime. Consumer workflows do not run `npm install`.
+
+## Repository audit
+
+Pin every third-party Action, including actions-warden itself, to a reviewed
+full commit SHA:
+
+```yaml
+name: actions-warden
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # actions-warden-ref: v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Audit workflows
+        uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
+        with:
+          command: audit
+          severity: high
+          explain: 'true'
+```
+
+Findings are written to the log, job summary, and native annotations. Audit
+findings fail the step by default.
+
+## Inputs
+
+GitHub passes Action inputs as strings. Boolean values should be quoted in YAML
+for clarity.
+
+| input | default | applies to | behavior |
+|---|---|---|---|
+| `command` | `audit` | all | `audit`, `pin`, `upgrade`, `verify`, `report`, `org-scan`, or `rules` |
+| `workflow` | discovery | repository commands | One path/glob per line or a JSON string array |
+| `severity` | all levels | `audit`, `report`, `org-scan` | Minimum `low`, `medium`, `high`, or `critical` |
+| `format` | `toon` | all | `toon`, `json`, `text`, or `sarif` |
+| `mode` | `minor` | `upgrade`, `report` | `major`, `minor`, or `patch` |
+| `min-age` | `7` | `upgrade`, `report` | Non-negative cooldown in days |
+| `write` | `false` | `pin`, `upgrade` | Apply changes in the checked-out workspace |
+| `fix` | none | `pin`, `upgrade` | Limit work to one exact planned ID |
+| `explain` | `false` | `audit`, `report`, `org-scan` | Include remediation hints |
+| `offline` | `false` | `report` | Skip pin and upgrade network work |
+| `fail-on-findings` | `true` | `audit`, `report`, `org-scan` | Allow findings to be advisory when `false` |
+| `annotations` | `true` | all | Emit native workflow-command annotations |
+| `config` | auto | `audit`, `report`, `org-scan` | Policy path inside the working directory |
+| `ignore-config` | `false` | `audit`, `report`, `org-scan` | Ignore repository policy |
+| `baseline` | policy/default | `audit`, `report`, `org-scan` | Accepted-finding baseline |
+| `organization` | none | `org-scan` | Required organization login |
+| `repository` | all eligible | `org-scan` | One repository glob per line or a JSON string array |
+| `visibility` | `all` | `org-scan` | `all`, `public`, `private`, or `internal` |
+| `include-archived` | `false` | `org-scan` | Include archived repositories |
+| `include-disabled` | `false` | `org-scan` | Include disabled repositories |
+| `include-forks` | `false` | `org-scan` | Include forked repositories |
+| `max-repos` | none | `org-scan` | Positive repository limit |
+| `concurrency` | `4` | `org-scan` | Concurrent repository scans from 1 through 16 |
+| `checkpoint-path` | none | `org-scan` | Create or replace an atomic resumable checkpoint |
+| `resume-from` | none | `org-scan` | Resume from and update an existing checkpoint |
+| `progress` | `true` | `org-scan` | Show discovery, repository, retry, and completion updates in the step log |
+| `output-path` | none | all | Save the selected format inside the working directory |
+| `token` | none | network commands | GitHub API token; normally `${{ github.token }}` or a secret |
+| `working-directory` | `$GITHUB_WORKSPACE` | all | Scan and path-safety root |
+
+`node-version` is a deprecated compatibility input. It is accepted but ignored
+because the Action runtime is declared by the bundle.
+
+Multivalue inputs can be line-separated:
+
+```yaml
+with:
+  workflow: |
+    .github/workflows/release.yml
+    .github/actions
+```
+
+or JSON:
+
+```yaml
+with:
+  repository: '["service-*", "platform-*"]'
+```
+
+## Outputs and failure policy
+
+| output | description |
+|---|---|
+| `status` | Semantic `OK` or `FAIL` |
+| `findings` | Finding count for `audit`, `report`, and `org-scan` |
+| `report-path` | Absolute saved path when `output-path` is supplied |
+| `annotations` | Number of annotations emitted |
+| `annotations-skipped` | Number omitted by the per-level cap |
+
+Give the step an `id` to read outputs:
+
+```yaml
+- name: Audit workflows
+  id: warden
+  uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
+  with:
+    command: audit
+    fail-on-findings: 'false'
+
+- name: Show result
+  run: echo "status=${{ steps.warden.outputs.status }} findings=${{ steps.warden.outputs.findings }}"
+```
+
+`fail-on-findings: 'false'` changes step failure only for security findings in
+`audit`, `report`, and `org-scan`. It does not hide findings or change the
+`status` output.
+
+Operational failures always fail the step, including:
+
+- invalid or unparseable workflow YAML;
+- organization repository or blob read failures;
+- ref resolution and ownership-verification failures;
+- unsafe paths or writes;
+- errors in the pin or upgrade phases of `report`.
+
+`pin`, `upgrade`, and `verify` errors always fail. Warnings from `verify` do
+not fail.
+
+## Native annotations
+
+Annotations are independent of `format`:
+
+| result | annotation level |
+|---|---|
+| critical or high finding | error |
+| medium finding | warning |
+| low finding | notice |
+| verification warning | warning |
+| resolver, verification, scan, or write error | error |
+
+Local findings attach to the repository-relative file and source line.
+Organization findings belong to other repositories, so they omit a local file
+attachment while retaining repository, remote path, source URL, rule, and
+stable ID in the message and saved report.
+
+The Action emits at most 10 annotations per level per step, with more severe
+records first. All omitted records remain in normal output and saved reports.
+Set `annotations: 'false'` to disable annotations without changing status or
+failure behavior.
+
+Workflow-command data is escaped and credential-like values are redacted before
+emission.
+
+## Save a report artifact
+
+`output-path` writes the selected format in addition to stdout:
+
+```yaml
+- name: Generate report
+  id: warden
+  uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
+  with:
+    command: report
+    format: json
+    output-path: reports/actions-warden.json
+    fail-on-findings: 'false'
+    token: ${{ github.token }}
+
+- name: Upload report
+  if: always()
+  uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
+  with:
+    name: actions-warden-report
+    path: ${{ steps.warden.outputs.report-path }}
+    if-no-files-found: error
+```
+
+The output path must remain inside `working-directory`, its parent directory
+must already exist, and an existing destination must be a regular file rather
+than a directory or symlink.
+
+## Organization report
+
+The default repository `GITHUB_TOKEN` generally sees only the repository where
+the workflow runs. Use a GitHub App installation token or a fine-grained token
+whose repository access covers the intended organization scope.
+
+```yaml
+name: organization Actions report
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '23 7 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # actions-warden-ref: v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Scan organization
+        id: warden
+        uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
+        with:
+          command: org-scan
+          organization: ${{ github.repository_owner }}
+          token: ${{ secrets.ACTIONS_WARDEN_ORG_TOKEN }}
+          severity: high
+          explain: 'true'
+          format: json
+          output-path: actions-warden-org-report.json
+          checkpoint-path: .actions-warden-org-checkpoint.json
+          fail-on-findings: 'false'
+
+      - name: Upload organization report
+        if: always()
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
+        with:
+          name: actions-warden-org-report
+          path: |
+            actions-warden-org-report.json
+            .actions-warden-org-checkpoint.json
+          if-no-files-found: error
+```
+
+Keep the token in Actions secrets, avoid printing it, and grant only metadata
+and contents read access for selected repositories. The complete copyable file
+is [examples/org-scan.yml](../examples/org-scan.yml).
+
+The Action writes live progress to the step log separately from the selected
+report format. Set `progress: 'false'` to disable it.
+
+CLI `--agent-mode` is not an Action input. The Action already has explicit
+`output-path`, checkpoint, progress, summary, and output channels; configure
+those inputs directly when an agent generates a workflow.
+
+`checkpoint-path` starts a new checkpoint. To resume, restore that file into
+the working directory before the actions-warden step, remove
+`checkpoint-path`, and set `resume-from` to the restored path. The Action does
+not itself retain files between ephemeral runners; use a protected artifact or
+other caller-managed storage. Scope, policy, baseline, analysis generation, and
+rule identity must match; a compatible package-version change is allowed and
+atomically refreshes checkpoint metadata on the first successful resume. Fresh
+repository discovery and tree checks still occur, and changed or previously
+failed repositories are rescanned. Checkpoints hold redacted report evidence
+about repositories and findings, so protect them like the organization report.
+`checkpoint-path` and `resume-from` are mutually exclusive and cannot equal
+`output-path`.
+
+## Mutation workflows
+
+With `write: 'true'`, `pin` and `upgrade` modify only the runner's checked-out
+working tree. The Action does not commit, push, or open a pull request.
+
+A safe automation flow is:
+
+1. run the command without `write` and retain the report;
+2. require review or select one `fix` ID;
+3. run with `write: 'true'`;
+4. run `verify` and repository tests;
+5. create a pull request using a separately reviewed workflow.
+
+See [examples/upgrade-pr.yml](../examples/upgrade-pr.yml) for an opt-in,
+cooldown-aware upgrade pull request workflow. It uses explicit contents and
+pull-request write permissions only in the mutation job.
+
+## Bundle integrity
+
+The repository commits `dist/index.js` because GitHub Actions executes the
+bundle directly. Releases verify that a clean rebuild matches the committed
+bundle. Consumers should pin the Action to a full commit SHA, then use
+actions-warden's metadata comment to retain the reviewed release name.