feat: remote auditing (#230)

Author: woodruffw

Diff for: Cargo.lock

@@ -16,6 +16,7 @@ rust-version = "1.80.1"
 annotate-snippets = "0.11.4"
 anstream = "0.6.18"
 anyhow = "1.0.93"
+camino = { version = "1.1.9", features = ["serde1"] }
 clap = { version = "4.5.21", features = ["derive", "env"] }
 clap-verbosity-flag = "3.0.0"
 env_logger = "0.11.5"

Diff for: Cargo.toml

@@ -19,4 +19,4 @@ $(VENV): site-requirements.txt
 
 .PHONY: snippets
 snippets:
-	cargo run -- --help > docs/snippets/help.txt
+	cargo run -- -h > docs/snippets/help.txt

Diff for: Makefile

@@ -1,37 +1,73 @@
 # Quickstart
 
-First, run `zizmor --help` to make sure your installation succeeded.
+First, run `zizmor -h` to make sure your installation succeeded.
 
 You should see something like this:
 
 ```console
 --8<-- "help.txt"
 ```
 
+!!! tip
+
+    Run `zizmor --help` for a longer and more detailed version of `zizmor -h`.
+
 ## Running `zizmor`
 
-You can run `zizmor` on any file(s) you have locally:
+Here are some different ways you can run `zizmor` locally:
 
-```bash
-# audit a specific workflow
-zizmor my-workflow.yml
-# discovers .github/workflows/*.yml automatically
-zizmor path/to/repo
-```
+=== "On one or more files"
 
-By default, `zizmor` will emit Rust-style diagnostics, e.g.:
+    You can run `zizmor` on one or more workflows as explicit inputs:
 
-```console
-error[pull-request-target]: use of fundamentally insecure workflow trigger
-  --> /home/william/devel/gha-hazmat/.github/workflows/pull-request-target.yml:20:1
-   |
-20 | / on:
-21 | |   # NOT OK: pull_request_target should almost never be used
-22 | |   pull_request_target:
-   | |______________________^ triggers include pull_request_target, which is almost always used insecurely
-   |
-
-1 findings (0 unknown, 0 informational, 0 low, 0 medium, 1 high)
-```
+    ```bash
+    zizmor ci.yml tests.yml lint.yml
+    ```
+
+    These can be in any directory as well:
+
+    ```
+    zizmor ./subdir/ci.yml ../sibling/tests.yml
+    ```
+
+=== "On one or more directories"
+
+    If you have multiple workflows in a single directory, `zizmor` will
+    discover them:
+
+    ```bash
+    # somewhere/ contains ci.yml and tests.yml
+    zizmor somewhere/
+    ```
+
+    Moreover, if the specified directory contains a `.github/workflows`
+    subdirectory, `zizmor` will discover workflows there:
+
+    ```bash
+    # my-local-repo/ contains .github/workflows/{ci,tests}.yml
+    zizmor my-local-repo/
+    ```
+
+=== "On one or more remote repositories"
+
+    !!! tip
+
+        Private repositories can also be audited remotely, as long
+        as your GitHub API token has sufficient permissions.
+
+    `zizmor` can also fetch workflows directly from GitHub, if given a
+    GitHub API token via `GH_TOKEN` or `--gh-token`:
+
+    ```bash
+    # audit all workflows in woodruffw/zizmor
+    # assumes you have `gh` installed
+    zizmor --gh-token=$(gh auth token) woodruffw/zizmor
+    ```
+
+    Multiple repositories will also work:
+
+    ```bash
+    zizmor --gh-token=$(gh auth token) woodruffw/zizmor woodruffw/gha-hazmat
+    ```
 
 See [Usage](./usage.md) for more examples, including examples of configuration.

Diff for: docs/quickstart.md

@@ -3,69 +3,38 @@ Static analysis for GitHub Actions
 Usage: zizmor [OPTIONS] <INPUTS>...
 
 Arguments:
-  <INPUTS>...
-          The workflow filenames or directories to audit
+  <INPUTS>...  The inputs to audit
 
 Options:
   -p, --pedantic
-          Emit 'pedantic' findings.
-          
-          This is an alias for --persona=pedantic.
-
+          Emit 'pedantic' findings
       --persona <PERSONA>
-          The persona to use while auditing
-          
-          [default: regular]
-
-          Possible values:
-          - auditor:  The "auditor" persona (false positives OK)
-          - pedantic: The "pedantic" persona (code smells OK)
-          - regular:  The "regular" persona (minimal false positives)
-
+          The persona to use while auditing [default: regular] [possible values: auditor, pedantic, regular]
   -o, --offline
-          Only perform audits that don't require network access
-
+          Perform only offline operations [env: ZIZMOR_OFFLINE=]
+      --gh-token <GH_TOKEN>
+          The GitHub API token to use [env: GH_TOKEN=]
+      --no-online-audits
+          Perform only offline audits [env: ZIZMOR_NO_ONLINE_AUDITS=]
   -v, --verbose...
           Increase logging verbosity
-
   -q, --quiet...
           Decrease logging verbosity
-
   -n, --no-progress
           Disable the progress bar. This is useful primarily when running with a high verbosity level, as the two will fight for stderr
-
-      --gh-token <GH_TOKEN>
-          The GitHub API token to use
-          
-          [env: GH_TOKEN=]
-
       --format <FORMAT>
-          The output format to emit. By default, plain text will be emitted
-          
-          [default: plain]
-          [possible values: plain, json, sarif]
-
+          The output format to emit. By default, plain text will be emitted [default: plain] [possible values: plain, json, sarif]
   -c, --config <CONFIG>
           The configuration file to load. By default, any config will be discovered relative to $CWD
-
       --no-config
           Disable all configuration loading
-
       --no-exit-codes
           Disable all error codes besides success and tool failure
-
       --min-severity <MIN_SEVERITY>
-          Filter all results below this severity
-          
-          [possible values: unknown, informational, low, medium, high]
-
+          Filter all results below this severity [possible values: unknown, informational, low, medium, high]
       --min-confidence <MIN_CONFIDENCE>
-          Filter all results below this confidence
-          
-          [possible values: unknown, low, medium, high]
-
+          Filter all results below this confidence [possible values: unknown, low, medium, high]
   -h, --help
-          Print help (see a summary with '-h')
-
+          Print help (see more with '--help')
   -V, --version
           Print version

Diff for: docs/snippets/help.txt

@@ -15,10 +15,15 @@ Both of these can be made explicit through their respective command-line flags:
 
 ```bash
 # force offline, even if a GH_TOKEN is present
+# this disables all online actions, including repository fetches
 zizmor --offline workflow.yml
 
-# passing a token explicitly will forcefully enable online mode
+# passing a token explicitly will enable online mode
 zizmor --gh-token ghp-... workflow.yml
+
+# online for the purpose of fetching the input (example/example),
+# but all audits themselves are offline
+zizmor --no-online-audits --gh-token ghp-... example/example
 ```
 
 ## Output formats
@@ -317,7 +322,7 @@ jobs:
 1. Optional: Remove the `env:` block to only run `zizmor`'s offline audits.
 
 For more inspiration, see `zizmor`'s own [repository workflow scan], as well
-as  GitHub's example of [running ESLint] as a security workflow.
+as GitHub's example of [running ESLint] as a security workflow.
 
 [SARIF]: https://sarifweb.azurewebsites.net/
 
@@ -336,7 +341,7 @@ To do so, add the following to your `.pre-commit-config.yaml` `repos` section:
 
 ```yaml
 -   repo: https://github.com/woodruffw/zizmor
-    rev: v0.3.0 # (1)!
+    rev: v0.7.0 # (1)!
     hooks:
     - id: zizmor
 ```

Diff for: docs/usage.md

@@ -172,7 +172,7 @@ mod tests {
             ("something | tee \"${$OTHER_ENV}\" # not $GITHUB_ENV", false),
         ] {
             let audit_state = AuditState {
-                offline: false,
+                no_online_audits: false,
                 gh_token: None,
                 caches: Caches::new(),
             };

Diff for: src/audit/github_env.rs

@@ -116,7 +116,7 @@ impl ImpostorCommit {
 
 impl WorkflowAudit for ImpostorCommit {
     fn new(state: AuditState) -> Result<Self> {
-        if state.offline {
+        if state.no_online_audits {
             return Err(anyhow!("offline audits only requested"));
         }
 

Diff for: src/audit/impostor_commit.rs

@@ -125,7 +125,7 @@ impl WorkflowAudit for KnownVulnerableActions {
     where
         Self: Sized,
     {
-        if state.offline {
+        if state.no_online_audits {
             return Err(anyhow!("offline audits only requested"));
         }
 

Diff for: src/audit/known_vulnerable_actions.rs

@@ -61,7 +61,7 @@ impl WorkflowAudit for RefConfusion {
     where
         Self: Sized,
     {
-        if state.offline {
+        if state.no_online_audits {
             return Err(anyhow!("offline audits only requested"));
         }
 

Diff for: src/audit/ref_confusion.rs

@@ -123,7 +123,10 @@ impl Config {
         // multiple files, as the first location is the one a user will
         // typically ignore, suppressing the rest in the process.
         for loc in &finding.locations {
-            for rule in ignores.iter().filter(|i| i.filename == loc.symbolic.name) {
+            for rule in ignores
+                .iter()
+                .filter(|i| i.filename == loc.symbolic.key.filename())
+            {
                 match rule {
                     // Rule has a line and (maybe) a column.
                     WorkflowRule {

Diff for: src/config.rs

@@ -9,7 +9,10 @@ use regex::Regex;
 use serde::Serialize;
 use terminal_link::Link;
 
-use crate::models::{Job, Step, Workflow};
+use crate::{
+    models::{Job, Step, Workflow},
+    registry::WorkflowKey,
+};
 
 pub(crate) mod locate;
 
@@ -120,8 +123,8 @@ impl<'w> Route<'w> {
 /// Represents a symbolic workflow location.
 #[derive(Serialize, Clone, Debug)]
 pub(crate) struct SymbolicLocation<'w> {
-    /// The name of the workflow, as it appears in the workflow registry.
-    pub(crate) name: &'w str,
+    /// The unique ID of the workflow, as it appears in the workflow registry.
+    pub(crate) key: &'w WorkflowKey,
 
     /// An annotation for this location.
     pub(crate) annotation: String,
@@ -139,7 +142,7 @@ pub(crate) struct SymbolicLocation<'w> {
 impl<'w> SymbolicLocation<'w> {
     pub(crate) fn with_keys(&self, keys: &[RouteComponent<'w>]) -> SymbolicLocation<'w> {
         SymbolicLocation {
-            name: self.name,
+            key: self.key,
             annotation: self.annotation.clone(),
             link: None,
             route: self.route.with_keys(keys),