remit-actions 1__tar.gz

remit_actions-1/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## Version 1 — 2026-11-04
+
+First public release.
+
+- **Ten rules** for privilege changes between a pull request's base and head:
+  token scope increases (WF001), jobs relying on or leaving the repository's
+  default token permissions (WF002), review-sensitive triggers such as
+  `pull_request_target` (WF003), new secret references and forwarding (WF004),
+  self-hosted, custom or group runners (WF005), environment changes (WF007),
+  runner/environment re-pairing in matrices (WF008), new third-party code in a
+  privileged job (WF009), pull request content brought into a
+  `pull_request_target`, `workflow_run` or `issue_comment` job (WF010), and
+  mutable pull request references checked out after a label, comment or
+  environment approval (WF011, time-of-check to time-of-use).
+- **Compares from the merge-base.** When the base comes from the pull request
+  event, the Action compares from where the PR branched off, as GitHub's Files
+  changed view does, so a stale branch doesn't show base-branch changes reversed.
+- **Indirect references are followed:** WF010 and WF011 trace pull request
+  references through environment variables, `$GITHUB_ENV`, step outputs,
+  `needs` job outputs and action inputs, and treat runtime lookups such as
+  `gh pr view` as pull request content. Besides checkouts, WF010 recognizes
+  clones of the head repository, `gh pr diff | git apply`, archive downloads of
+  the head commit, and artifact downloads with `gh run download` or
+  `github-script`.
+- **Comment commands count as approval only when checked:** an `issue_comment`
+  job is treated as gated (WF011) only when it, or a job it needs, checks who
+  commented. A check of the comment's text alone is WF010, since anyone can
+  type it.
+- **`remit audit`** reports WF010 and WF011 in a repository's current state,
+  for a directory or any Git commit, as JSON, Markdown or SARIF, with an
+  optional `--fail-on-findings` exit code for scheduled checks.
+- **Local code is followed:** steps inside local composite actions and local
+  reusable workflows (`./path` and `$/path`) count, and a change to them is
+  caught even when no workflow file changed. A local file that can't be read or
+  parsed makes the analysis `incomplete` for every job that uses it.
+- **Reports** as pull request annotations on the line that introduced each
+  finding (an incomplete analysis first, then the most serious rules, with a
+  job's WF001 scopes combined so GitHub's 10-annotation limit doesn't hide them), a Markdown job summary with a review question per rule, JSON, and
+  SARIF for GitHub code scanning.
+- **GitHub Action** with `advisory` and `require-complete` modes. Findings never
+  fail the step; incomplete or failed analysis is reported explicitly.
+- **Safe on untrusted pull requests:** the head is read as Git data and never
+  executed, the analysis makes no network calls, and the Action ships a
+  hash-verified PyYAML bundle. Git reads ignore caller redirection and
+  replacement refs, and YAML anchors are bounded before parsing.
+- **CLI** `remit` (`pip install remit-actions`), for directories or local Git commits.
+- **Validation:** the test suite on Python 3.11–3.14, an end-to-end Action run
+  with networking disabled, a hosted contract of 18 cases in both modes, a
+  replay of 74 historical public PRs, and a reproducible comparison with zizmor.

remit_actions-1/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing
+
+## Development
+
+Python 3.11+ and Git are required.
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e .
+python scripts/validate.py
+python scripts/offline_smoke.py
+pip install ruff==0.16.9 && ruff check
+```
+
+To run one test file: `python -m unittest discover -s tests -p 'test_contexts.py'`.
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the code is organised.
+
+## Tests
+
+| Command | What it covers |
+|---|---|
+| `python scripts/validate.py` | The full unit and integration suite: rules, parser limits, source readers, CLI, the Action controller, and the template's fetch step against local Git repositories. Writes `validation-results.json` (git-ignored) with versions and source hashes. |
+| `python scripts/offline_smoke.py` | Runs the real Action controller against local Git fixtures in both modes. In CI, `--network-namespace` runs it with networking disabled. |
+| `scripts/replay_benchmark.py` | Replays [74 historical public PRs](benchmarks/README.md) and checks the expected WF001/WF003/WF004 findings. |
+| `scripts/compare_zizmor.py` | Needs `zizmor` and a replay cache. Measures how many findings zizmor's new-findings view also surfaces. |
+| *Action outcome contract* workflow | Manually dispatched. Runs the published, pinned Action against the fixtures in `tests/hosted_cases.json` in both modes. |
+
+CI runs `ruff check`, plus `validate.py` and the network-isolated smoke test on
+Python 3.11–3.14. The repository also runs its own Action on every PR
+([`privilege-review.yml`](.github/workflows/privilege-review.yml)), loaded from
+the PR's base commit.
+
+## Changing behaviour
+
+- Add a regression test that fails without the change, plus a nearby case that
+  should stay quiet. Cover `incomplete`/`error` outcomes too.
+- Findings already established must survive uncertainty elsewhere in the file.
+- Analysis must stay local: no executing workflow content, no network access, no
+  querying live repository settings.
+- Keep rule IDs stable. Bump `schemaVersion` only for incompatible changes to the
+  JSON report.
+- Update [docs/RULES.md](docs/RULES.md) and the `Unreleased` section of the
+  [changelog](CHANGELOG.md).
+- If report output changes, regenerate `examples/sample-report.md` and
+  `examples/sample-report.json` (a test checks them).
+- For rule changes, run the replay and look at any new findings. Don't change an
+  expected result just to make the replay pass.
+- Changes to the Action controller, template or bundled dependency need the
+  offline smoke test, and the hosted contract before release.
+
+## Releases
+
+1. Update the version in `pyproject.toml` and `src/remit/__init__.py`,
+   and move `Unreleased` entries in the changelog under the new version.
+2. Run CI, the offline smoke test, the replay and the hosted contract on the
+   release candidate.
+3. Merge to `main`, then run [`publish.yml`](.github/workflows/publish.yml)
+   from the Actions tab (Run workflow, branch `main`). It refuses other
+   branches, builds with hash-pinned tools, tests the wheel and uploads to PyPI
+   through trusted publishing. Record the CI and contract runs in the
+   changelog entry.
+4. Update the pinned SHA in `README.md`, `examples/github-action-template.yml`
+   and the contract workflow.
+
+PyPI trusted publishing needs a one-time setup on pypi.org: add a pending
+publisher for project `remit-actions`, owner `adi271213`, repository
+`remit`, workflow `publish.yml`, environment `pypi`.
+
+Tags are never moved or deleted after publication.
+
+## Feedback
+
+If you've tried the check on a repository, the *Trial feedback* issue template
+is the quickest way to say what was useful, what was noise and what it missed.
+
+## Pull requests
+
+Describe the problem, the new behaviour and the checks you ran. Include a small
+public or synthetic example for bugs. Don't include credentials or private logs.
+Report vulnerabilities privately; see [SECURITY.md](SECURITY.md).
+
+`main` is protected: changes go through a pull request with passing CI on all
+four Python versions.

remit_actions-1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

remit_actions-1/MANIFEST.in

@@ -0,0 +1,9 @@
+include action.yml requirements.txt CHANGELOG.md CONTRIBUTING.md SECURITY.md SETUP.md
+recursive-include scripts *.py *.sh
+recursive-include tests *.py *.json
+graft examples
+graft docs
+graft benchmarks
+graft vendor
+prune .benchmark-cache
+global-exclude __pycache__ *.py[cod] .DS_Store

remit_actions-1/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: remit-actions
+Version: 1
+Summary: See what a pull request changes about what your GitHub Actions workflows are allowed to do.
+License-Expression: MIT
+Project-URL: Source, https://github.com/adi271213/remit
+Project-URL: Issues, https://github.com/adi271213/remit/issues
+Project-URL: Documentation, https://github.com/adi271213/remit/blob/main/SETUP.md
+Keywords: github-actions,security,ci,workflows,permissions,supply-chain,code-review
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML==6.0.3
+Dynamic: license-file
+
+<div align="center">
+
+# Remit
+
+**Know when a pull request widens your workflows' authority.**
+
+[![CI](https://github.com/adi271213/remit/actions/workflows/ci.yml/badge.svg)](https://github.com/adi271213/remit/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/remit-actions)](https://pypi.org/project/remit-actions/)
+[![Python](https://img.shields.io/pypi/pyversions/remit-actions)](https://pypi.org/project/remit-actions/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/adi271213/remit/blob/main/LICENSE)
+
+</div>
+
+The changes that matter in a workflow PR are often a single line: `contents: read`
+becomes `write`, a `pull_request_target` trigger appears, a release job starts
+running a new third-party action with your secrets. Remit compares the base and
+head of every pull request and puts each of those changes on the line that
+introduced it, so reviewers can't miss them.
+
+- **Only what changed.** Unchanged configuration stays quiet, so ordinary PRs get no noise.
+- **Flags common pwn-request patterns.** Privileged workflows that start checking out, fetching or downloading pull request content, including the time-of-check to time-of-use trap after a label or comment approval.
+- **Right on the diff.** Findings appear as annotations in the PR's *Files changed* tab.
+- **Safe on untrusted PRs.** The PR is read as data and never executed; the analysis makes no network calls.
+- **Nothing to install.** A pinned Action with a hash-verified bundled parser; no secrets, `contents: read` only.
+
+## What it catches
+
+A PR edits a release workflow:
+
+```diff
+ name: Release
+-on: push
++on: [push, pull_request_target]
+ permissions: {}
+ jobs:
+   publish:
+     runs-on: ubuntu-latest
+     permissions:
+-      contents: read
++      contents: write
++      id-token: write
+     steps:
+       - uses: actions/checkout@v4
+       - run: make dist
++      - uses: someone/release-action@v1
++        with:
++          token: ${{ secrets.RELEASE_TOKEN }}
+```
+
+Remit annotates five lines of that diff:
+
+| Line | Rule | Finding |
+|---|---|---|
+| 2 | WF003 | Review-sensitive trigger `pull_request_target` introduced. |
+| 8 | WF001 | Job publish is newly configured to use `contents: write`. |
+| 9 | WF001 | Job publish is newly configured to request an OIDC identity token. |
+| 13 | WF009 | Job publish now runs third-party code from `someone/release-action@v1`, which can use `contents: write`; `id-token: write`; secrets: `RELEASE_TOKEN`. |
+| 15 | WF004 | Job publish adds a reference or forwarding path to `RELEASE_TOKEN`. |
+
+The job summary groups the same findings by workflow and job, with a question
+for the reviewer on each ([sample](https://github.com/adi271213/remit/blob/main/examples/sample-report.md)).
+JSON and SARIF reports carry the same data for tooling and GitHub code scanning.
+
+## Quick start
+
+1. Copy [`examples/github-action-template.yml`](https://github.com/adi271213/remit/blob/main/examples/github-action-template.yml)
+   (45 lines) to `.github/workflows/remit.yml`.
+2. Merge it.
+3. Open a pull request that touches a workflow and look at *Files changed*.
+
+The template checks out the base commit, fetches the PR head without checking it
+out, and runs the Action pinned to a full commit SHA:
+
+```yaml
+- uses: adi271213/remit@3db5c481c527a7f60bf92c0499083fe15f7829be # version 1
+  with:
+    mode: advisory
+```
+
+Use the whole template rather than this step alone: the step needs both commits
+in the local clone. The [setup guide](https://github.com/adi271213/remit/blob/main/SETUP.md)
+covers inputs, outputs, code scanning and troubleshooting.
+
+## Rules
+
+| Rule | Reports |
+|---|---|
+| WF001 | A job's token scope increases (`none` → `read` → `write`), including new `id-token: write` (OIDC) |
+| WF002 | A job starts relying on the repository's default token permissions, or replaces them with permissions that may exceed the default |
+| WF003 | A newly added `pull_request_target`, `workflow_run`, `issue_comment`, `issues`, `discussion` or `discussion_comment` trigger |
+| WF004 | A job newly references a secret, or forwards all secrets (`secrets: inherit`, `toJSON(secrets)`) |
+| WF005 | A job's runner changes to a self-hosted, custom-label, runner-group or unresolvable selection |
+| WF007 | A job's deployment environment is added, removed or changed |
+| WF008 | A matrix job pairs a runner with a different environment while the overall runner and environment sets stay the same |
+| WF009 | Third-party code (an action or reusable workflow) newly runs in a job with write scopes, OIDC, secrets or an environment |
+| WF010 | A `pull_request_target`, `workflow_run` or `issue_comment` job newly checks out, fetches or downloads pull request content: the "pwn request" |
+| WF011 | An approval-gated privileged job checks out a pull request reference that can change after approval: time-of-check to time-of-use |
+
+Rules follow steps into local composite actions and local reusable workflows
+(`./` and `$/` references), so a change inside `.github/actions/` is caught even
+when no workflow file changed.
+
+[docs/RULES.md](https://github.com/adi271213/remit/blob/main/docs/RULES.md) describes the exact behaviour of each rule.
+
+## Remit and zizmor
+
+[zizmor](https://github.com/zizmorcore/zizmor) audits what your workflows *are*
+for risky patterns. Remit reports what a pull request *changed*, including
+increases that never become a zizmor alert because the end state isn't "bad"
+by a state rule: a job gaining `id-token: write`, a new secret reference, a
+changed environment, or a new action receiving write access.
+
+On [74 historical public PRs](https://github.com/adi271213/remit/blob/main/benchmarks/README.md),
+Remit reported 72 findings. For 46 of them (64%), zizmor 1.32 (pedantic,
+offline) reported no new finding of a related audit in the same workflow and
+job, including all 8 new secret references. The PRs were selected and labelled
+by this project and the matching is approximate, so read this as an indication,
+not a benchmark. Run zizmor for what is dangerous, and Remit for what got wider.
+
+## Results
+
+Every run reports an **analysis** status and a **review** status:
+
+| Analysis | Meaning | CLI exit | `require-complete` (default) | `advisory` |
+|---|---|---|---|---|
+| `complete` | All changed workflows were compared | 0 | pass | pass |
+| `incomplete` | Some context is unknown, e.g. a dynamic expression | 2 | fail | pass with warning |
+| `error` | Some input couldn't be parsed or read | 2 | fail | pass with warning |
+
+Review is `suggested` when there are findings, `none` when analysis is complete
+with no findings, and (in the Action) `unknown` when analysis is incomplete and
+nothing was found. Known findings are reported alongside incomplete or failed parts.
+
+**Findings never fail the step.** Remit is a review aid, not a merge gate: a
+clean report doesn't mean a PR is safe, and a PR can edit the workflow that runs
+the check.
+
+<details>
+<summary><b>Inherited token permissions</b></summary>
+
+A job without a `permissions` block gets the repository or organization default,
+which Remit can't see. When a PR adds such a job, or removes a job's
+`permissions` block, WF002 asks the author to declare permissions explicitly.
+When a job that used the default starts declaring permissions, only levels above
+GitHub's narrowest possible default (`contents: read`, `packages: read`) are
+reported, so ordinary hardening PRs stay quiet. To compare against your real
+default instead, pass it in:
+
+```yaml
+  with:
+    default-permissions: '{"contents": "read"}'
+```
+
+</details>
+
+<details>
+<summary><b>Limitations</b></summary>
+
+- Workflows are read from `.github/workflows/`, and local composite actions and
+  reusable workflows are followed. Actions and reusable workflows from other
+  repositories, and the contents of scripts, are not analysed.
+- Repository and organization settings are not visible: default token
+  permissions, runner inventory, environment protection rules and secrets.
+- WF003 looks at trigger names only. Filter changes on existing triggers
+  (branches, types, paths) are not analysed.
+- Expressions are not evaluated. Only direct `${{ matrix.<field> }}` references
+  into a static matrix of up to 256 rows are resolved; anything else is reported
+  as unresolved.
+- YAML merge keys (`<<`) and recursive aliases are rejected as errors.
+- A renamed file is matched only if its content is identical; an edited rename
+  is treated as a new file and can produce findings for unchanged settings.
+- Input limits: 200 workflow files and 4 MiB per commit; per file, 256 KiB and
+  60,000 YAML tokens (a very dense file can reach the token limit first).
+- WF010 and WF011 follow pull request references through environment variables,
+  `$GITHUB_ENV`, step and job outputs, and action inputs within the repository.
+  Values computed in other ways (a script that builds a ref from pieces, files
+  passed between jobs) are not traced.
+
+</details>
+
+## Command line
+
+The package is `remit-actions` on PyPI; the command it installs is `remit`.
+
+```sh
+pip install remit-actions
+remit scan --repo . --base main --head my-branch --format markdown
+remit scan --dirs path/to/before path/to/after --format sarif --output remit.sarif
+```
+
+Output is JSON by default; `--format markdown` and `--format sarif` are also
+available. `--summary FILE` appends the Markdown summary and `--sarif FILE`
+also writes SARIF. The exit code is 0 for complete analysis and 2 otherwise.
+
+## Audit an existing repository
+
+Pull request checks only see what a PR changes. `remit audit` reports what is
+already there: every place a `pull_request_target`, `workflow_run` or
+`issue_comment` job brings in pull request content (WF010), and every mutable
+checkout after a label, comment or environment approval (WF011), including
+through local actions and reusable workflows.
+
+```sh
+remit audit --repo .                          # the current commit
+remit audit --repo . --ref v2.3.0             # any commit or tag
+remit audit --dir path/to/checkout --format markdown
+remit audit --repo . --format sarif --output remit-audit.sarif
+```
+
+Like `scan`, it reads committed Git objects (or a directory) as data and runs
+nothing. The exit code is 0 for a complete audit, 2 when something couldn't be
+analysed, and with `--fail-on-findings`, 1 when the audit found something. The
+[setup guide](https://github.com/adi271213/remit/blob/main/SETUP.md#scheduled-audit)
+has a weekly scheduled audit workflow.
+
+## Status
+
+Rule IDs, Action inputs and outputs, and the JSON report format stay compatible
+within a version; an incompatible change gets a new version number. Each release
+runs the test suite on Python 3.11–3.14, runs the Action end to end with networking
+disabled, and replays 74 historical public PRs. The replay's expected results
+were labelled by the project, so treat it as a regression suite rather than an
+accuracy measurement. Feedback from real repositories is the most useful thing
+you can send: open a [trial feedback issue](https://github.com/adi271213/remit/issues/new?template=trial_feedback.md).
+
+[Setup](https://github.com/adi271213/remit/blob/main/SETUP.md) ·
+[Rules](https://github.com/adi271213/remit/blob/main/docs/RULES.md) ·
+[Architecture](https://github.com/adi271213/remit/blob/main/docs/ARCHITECTURE.md) ·
+[Contributing](https://github.com/adi271213/remit/blob/main/CONTRIBUTING.md) ·
+[Security](https://github.com/adi271213/remit/blob/main/SECURITY.md) ·
+[Changelog](https://github.com/adi271213/remit/blob/main/CHANGELOG.md) ·
+[MIT license](https://github.com/adi271213/remit/blob/main/LICENSE)

remit_actions-1/README.md

@@ -0,0 +1,232 @@
+<div align="center">
+
+# Remit
+
+**Know when a pull request widens your workflows' authority.**
+
+[![CI](https://github.com/adi271213/remit/actions/workflows/ci.yml/badge.svg)](https://github.com/adi271213/remit/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/remit-actions)](https://pypi.org/project/remit-actions/)
+[![Python](https://img.shields.io/pypi/pyversions/remit-actions)](https://pypi.org/project/remit-actions/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/adi271213/remit/blob/main/LICENSE)
+
+</div>
+
+The changes that matter in a workflow PR are often a single line: `contents: read`
+becomes `write`, a `pull_request_target` trigger appears, a release job starts
+running a new third-party action with your secrets. Remit compares the base and
+head of every pull request and puts each of those changes on the line that
+introduced it, so reviewers can't miss them.
+
+- **Only what changed.** Unchanged configuration stays quiet, so ordinary PRs get no noise.
+- **Flags common pwn-request patterns.** Privileged workflows that start checking out, fetching or downloading pull request content, including the time-of-check to time-of-use trap after a label or comment approval.
+- **Right on the diff.** Findings appear as annotations in the PR's *Files changed* tab.
+- **Safe on untrusted PRs.** The PR is read as data and never executed; the analysis makes no network calls.
+- **Nothing to install.** A pinned Action with a hash-verified bundled parser; no secrets, `contents: read` only.
+
+## What it catches
+
+A PR edits a release workflow:
+
+```diff
+ name: Release
+-on: push
++on: [push, pull_request_target]
+ permissions: {}
+ jobs:
+   publish:
+     runs-on: ubuntu-latest
+     permissions:
+-      contents: read
++      contents: write
++      id-token: write
+     steps:
+       - uses: actions/checkout@v4
+       - run: make dist
++      - uses: someone/release-action@v1
++        with:
++          token: ${{ secrets.RELEASE_TOKEN }}
+```
+
+Remit annotates five lines of that diff:
+
+| Line | Rule | Finding |
+|---|---|---|
+| 2 | WF003 | Review-sensitive trigger `pull_request_target` introduced. |
+| 8 | WF001 | Job publish is newly configured to use `contents: write`. |
+| 9 | WF001 | Job publish is newly configured to request an OIDC identity token. |
+| 13 | WF009 | Job publish now runs third-party code from `someone/release-action@v1`, which can use `contents: write`; `id-token: write`; secrets: `RELEASE_TOKEN`. |
+| 15 | WF004 | Job publish adds a reference or forwarding path to `RELEASE_TOKEN`. |
+
+The job summary groups the same findings by workflow and job, with a question
+for the reviewer on each ([sample](https://github.com/adi271213/remit/blob/main/examples/sample-report.md)).
+JSON and SARIF reports carry the same data for tooling and GitHub code scanning.
+
+## Quick start
+
+1. Copy [`examples/github-action-template.yml`](https://github.com/adi271213/remit/blob/main/examples/github-action-template.yml)
+   (45 lines) to `.github/workflows/remit.yml`.
+2. Merge it.
+3. Open a pull request that touches a workflow and look at *Files changed*.
+
+The template checks out the base commit, fetches the PR head without checking it
+out, and runs the Action pinned to a full commit SHA:
+
+```yaml
+- uses: adi271213/remit@3db5c481c527a7f60bf92c0499083fe15f7829be # version 1
+  with:
+    mode: advisory
+```
+
+Use the whole template rather than this step alone: the step needs both commits
+in the local clone. The [setup guide](https://github.com/adi271213/remit/blob/main/SETUP.md)
+covers inputs, outputs, code scanning and troubleshooting.
+
+## Rules
+
+| Rule | Reports |
+|---|---|
+| WF001 | A job's token scope increases (`none` → `read` → `write`), including new `id-token: write` (OIDC) |
+| WF002 | A job starts relying on the repository's default token permissions, or replaces them with permissions that may exceed the default |
+| WF003 | A newly added `pull_request_target`, `workflow_run`, `issue_comment`, `issues`, `discussion` or `discussion_comment` trigger |
+| WF004 | A job newly references a secret, or forwards all secrets (`secrets: inherit`, `toJSON(secrets)`) |
+| WF005 | A job's runner changes to a self-hosted, custom-label, runner-group or unresolvable selection |
+| WF007 | A job's deployment environment is added, removed or changed |
+| WF008 | A matrix job pairs a runner with a different environment while the overall runner and environment sets stay the same |
+| WF009 | Third-party code (an action or reusable workflow) newly runs in a job with write scopes, OIDC, secrets or an environment |
+| WF010 | A `pull_request_target`, `workflow_run` or `issue_comment` job newly checks out, fetches or downloads pull request content: the "pwn request" |
+| WF011 | An approval-gated privileged job checks out a pull request reference that can change after approval: time-of-check to time-of-use |
+
+Rules follow steps into local composite actions and local reusable workflows
+(`./` and `$/` references), so a change inside `.github/actions/` is caught even
+when no workflow file changed.
+
+[docs/RULES.md](https://github.com/adi271213/remit/blob/main/docs/RULES.md) describes the exact behaviour of each rule.
+
+## Remit and zizmor
+
+[zizmor](https://github.com/zizmorcore/zizmor) audits what your workflows *are*
+for risky patterns. Remit reports what a pull request *changed*, including
+increases that never become a zizmor alert because the end state isn't "bad"
+by a state rule: a job gaining `id-token: write`, a new secret reference, a
+changed environment, or a new action receiving write access.
+
+On [74 historical public PRs](https://github.com/adi271213/remit/blob/main/benchmarks/README.md),
+Remit reported 72 findings. For 46 of them (64%), zizmor 1.32 (pedantic,
+offline) reported no new finding of a related audit in the same workflow and
+job, including all 8 new secret references. The PRs were selected and labelled
+by this project and the matching is approximate, so read this as an indication,
+not a benchmark. Run zizmor for what is dangerous, and Remit for what got wider.
+
+## Results
+
+Every run reports an **analysis** status and a **review** status:
+
+| Analysis | Meaning | CLI exit | `require-complete` (default) | `advisory` |
+|---|---|---|---|---|
+| `complete` | All changed workflows were compared | 0 | pass | pass |
+| `incomplete` | Some context is unknown, e.g. a dynamic expression | 2 | fail | pass with warning |
+| `error` | Some input couldn't be parsed or read | 2 | fail | pass with warning |
+
+Review is `suggested` when there are findings, `none` when analysis is complete
+with no findings, and (in the Action) `unknown` when analysis is incomplete and
+nothing was found. Known findings are reported alongside incomplete or failed parts.
+
+**Findings never fail the step.** Remit is a review aid, not a merge gate: a
+clean report doesn't mean a PR is safe, and a PR can edit the workflow that runs
+the check.
+
+<details>
+<summary><b>Inherited token permissions</b></summary>
+
+A job without a `permissions` block gets the repository or organization default,
+which Remit can't see. When a PR adds such a job, or removes a job's
+`permissions` block, WF002 asks the author to declare permissions explicitly.
+When a job that used the default starts declaring permissions, only levels above
+GitHub's narrowest possible default (`contents: read`, `packages: read`) are
+reported, so ordinary hardening PRs stay quiet. To compare against your real
+default instead, pass it in:
+
+```yaml
+  with:
+    default-permissions: '{"contents": "read"}'
+```
+
+</details>
+
+<details>
+<summary><b>Limitations</b></summary>
+
+- Workflows are read from `.github/workflows/`, and local composite actions and
+  reusable workflows are followed. Actions and reusable workflows from other
+  repositories, and the contents of scripts, are not analysed.
+- Repository and organization settings are not visible: default token
+  permissions, runner inventory, environment protection rules and secrets.
+- WF003 looks at trigger names only. Filter changes on existing triggers
+  (branches, types, paths) are not analysed.
+- Expressions are not evaluated. Only direct `${{ matrix.<field> }}` references
+  into a static matrix of up to 256 rows are resolved; anything else is reported
+  as unresolved.
+- YAML merge keys (`<<`) and recursive aliases are rejected as errors.
+- A renamed file is matched only if its content is identical; an edited rename
+  is treated as a new file and can produce findings for unchanged settings.
+- Input limits: 200 workflow files and 4 MiB per commit; per file, 256 KiB and
+  60,000 YAML tokens (a very dense file can reach the token limit first).
+- WF010 and WF011 follow pull request references through environment variables,
+  `$GITHUB_ENV`, step and job outputs, and action inputs within the repository.
+  Values computed in other ways (a script that builds a ref from pieces, files
+  passed between jobs) are not traced.
+
+</details>
+
+## Command line
+
+The package is `remit-actions` on PyPI; the command it installs is `remit`.
+
+```sh
+pip install remit-actions
+remit scan --repo . --base main --head my-branch --format markdown
+remit scan --dirs path/to/before path/to/after --format sarif --output remit.sarif
+```
+
+Output is JSON by default; `--format markdown` and `--format sarif` are also
+available. `--summary FILE` appends the Markdown summary and `--sarif FILE`
+also writes SARIF. The exit code is 0 for complete analysis and 2 otherwise.
+
+## Audit an existing repository
+
+Pull request checks only see what a PR changes. `remit audit` reports what is
+already there: every place a `pull_request_target`, `workflow_run` or
+`issue_comment` job brings in pull request content (WF010), and every mutable
+checkout after a label, comment or environment approval (WF011), including
+through local actions and reusable workflows.
+
+```sh
+remit audit --repo .                          # the current commit
+remit audit --repo . --ref v2.3.0             # any commit or tag
+remit audit --dir path/to/checkout --format markdown
+remit audit --repo . --format sarif --output remit-audit.sarif
+```
+
+Like `scan`, it reads committed Git objects (or a directory) as data and runs
+nothing. The exit code is 0 for a complete audit, 2 when something couldn't be
+analysed, and with `--fail-on-findings`, 1 when the audit found something. The
+[setup guide](https://github.com/adi271213/remit/blob/main/SETUP.md#scheduled-audit)
+has a weekly scheduled audit workflow.
+
+## Status
+
+Rule IDs, Action inputs and outputs, and the JSON report format stay compatible
+within a version; an incompatible change gets a new version number. Each release
+runs the test suite on Python 3.11–3.14, runs the Action end to end with networking
+disabled, and replays 74 historical public PRs. The replay's expected results
+were labelled by the project, so treat it as a regression suite rather than an
+accuracy measurement. Feedback from real repositories is the most useful thing
+you can send: open a [trial feedback issue](https://github.com/adi271213/remit/issues/new?template=trial_feedback.md).
+
+[Setup](https://github.com/adi271213/remit/blob/main/SETUP.md) ·
+[Rules](https://github.com/adi271213/remit/blob/main/docs/RULES.md) ·
+[Architecture](https://github.com/adi271213/remit/blob/main/docs/ARCHITECTURE.md) ·
+[Contributing](https://github.com/adi271213/remit/blob/main/CONTRIBUTING.md) ·
+[Security](https://github.com/adi271213/remit/blob/main/SECURITY.md) ·
+[Changelog](https://github.com/adi271213/remit/blob/main/CHANGELOG.md) ·
+[MIT license](https://github.com/adi271213/remit/blob/main/LICENSE)