Updated docs

Author: aegilops

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 Updated audit script to take JSON input to filter by Actions and commits.
 
+Added unit tests for the audit script.
+
+Added supporting documentation.
+
 ## 2025-05-20
 
 Added script to allow decoding secrets from workflows affected by a particular set of compromises in March 2025.

README.md

@@ -1,15 +1,15 @@
 # Audit GitHub Actions used in workflow runs for an organization, Enterprise or repository
 
-Discover which exact versions (down to the commit) of GitHub Actions were used in workflow runs.
+Discover which versions of GitHub Actions were used in workflow runs, down to the exact commit.
 
-Check the audit log for a GitHub Enterprise/organization (or just list the runs, for a repository) for workflow runs created between the start date and end date.
+Checks the audit log for a GitHub Enterprise/organization (or just lists the runs, for a repository) for workflow runs created between the start date and end date.
 
 Lists the Actions and specific versions and commits used in them.
 
-Optionally, filter by particular Actions, possibly including one or more commit SHAs of interest.
+Optionally, filters by particular Actions, possibly including one or more commit SHAs of interest.
 
 > [!NOTE]
-> This is unofficial software, not supported by GitHub
+> This is an _unofficial_ tool created by Field Security Specialists, and is not officially supported by GitHub.
 
 ## Usage
 
@@ -23,14 +23,18 @@ For Enterprise Server or Data Residency users, please set `GITHUB_BASE_URL` in y
 node audit_workflow_runs.js <org or enterprise name> <ent|org|repo> <start date> <end date> [<output-file>] [<input-filters-file>]
 ```
 
-Results are printed to the console in CSV, and also appended to a file in the current directory, named `workflow_audit_results.sljson` by default. This can be set with the optional `output-file` parameter.
+Results are printed to the console in CSV, for convenience, and also appended to a single-line JSON file in the current directory. This is named `workflow_audit_results.sljson` by default, and can be set with the optional `output-file` parameter.
 
 By default all Actions are listed, but you can filter by particular Actions using a JSON formatted input file.
 
 For example:
 
 ```bash
-node audit_workflow_runs.js github org 2025-03-13 2025-03-15 github_actions_audit.json
+node audit_workflow_runs.js github org 2025-03-13 2025-03-15 github_actions_audit.sljson
+```
+
+```bash
+node audit_workflow_runs.js github org 2025-03-13 2025-03-15 github_actions_audit.sljson actions_to_find.json
 ```
 
 #### JSON input file format
@@ -43,12 +47,20 @@ You can express some wildcards - use `*` after the first `/` in the Action to in
 
 An Action name given without a path will match any Action in that repository, whether or not it has a path. You can also explictly use `*` in the path to match any path.
 
+```json
+{
+    "actions/setup-node": ["*"],
+    "actions/checkout": ["*"],
+    "actions/setup-python": ["0000000000000000000000000000000000000000"],
+} 
+```
+
 ### find_compromised_secrets.js
 
 > [!NOTE]
 > This is relevant only to secrets leaked because of the `tj-actions/changed-files` and `reviewdog` compromises in March 2025.
 
-This script takes the structured single-line JSON output of `audit_workflow_runs.js` (not the convenience CSV output) and searches for secrets that were leaked in those workflow runs.
+This script takes the structured single-line JSON output of `audit_workflow_runs.js` (not the convenience CSV output) and searches for secrets in the format that was leaked in those workflow runs (doubly base64 encoded, with predictable content).
 
 ```text
 node find_compromised_secrets.js < <path sljson file>
@@ -77,8 +89,6 @@ See [CODEOWNERS](CODEOWNERS) for the list of maintainers.
 
 See the [SUPPORT](SUPPORT.md) file.
 
-## Background and acknowledgements
-
-The `changes` Action relies on the [`dorny/paths-filter`](https://github.com/dorny/paths-filter/) Action.
+## Background
 
 See the [CHANGELOG](CHANGELOG.md), [CONTRIBUTING](CONTRIBUTING.md), [SECURITY](SECURITY.md), [SUPPORT](SUPPORT.md), [CODE OF CONDUCT](CODE_OF_CONDUCT.md) and [PRIVACY](PRIVACY.md) files for more information.