feat: add argument --ghe-hostname for GHE Servers (#371)

Co-authored-by: 최하늘 <[email protected]>

Author: woodruffw

Diff for: docs/snippets/help.txt

@@ -14,6 +14,8 @@ Options:
           Perform only offline operations [env: ZIZMOR_OFFLINE=]
       --gh-token <GH_TOKEN>
           The GitHub API token to use [env: GH_TOKEN=]
+      --gh-hostname <GH_HOSTNAME>
+          The GitHub Server Hostname. Defaults to github.com [env: GH_HOST=] [default: github.com]
       --no-online-audits
           Perform only offline audits [env: ZIZMOR_NO_ONLINE_AUDITS=]
   -v, --verbose...

Diff for: docs/usage.md

@@ -434,6 +434,22 @@ as GitHub's example of [running ESLint] as a security workflow.
 
 [Advanced Security]: https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security
 
+### Use with GitHub Enterprise
+
+`zizmor` supports GitHub instances other than `github.com`.
+
+To use it with your [GitHub Enterprise] instance (either cloud or self-hosted),
+pass your instance's domain with `--gh-hostname` or `GH_HOST`:
+
+```bash
+zizmor --gh-hostname custom.example.com ...
+
+# or, with GH_HOST
+GH_HOST=custom.ghe.com zizmor ...
+```
+
+[GitHub Enterprise]: https://github.com/enterprise
+
 ### Use with `pre-commit`
 
 `zizmor` can be used with the [`pre-commit`](https://pre-commit.com/) framework.

Diff for: src/audit/github_env.rs

@@ -378,6 +378,7 @@ impl Audit for GitHubEnv {
 mod tests {
     use crate::audit::github_env::{GitHubEnv, GITHUB_ENV_WRITE_CMD};
     use crate::audit::Audit;
+    use crate::github_api::GitHubHost;
     use crate::state::AuditState;
 
     #[test]
@@ -435,6 +436,7 @@ mod tests {
                 no_online_audits: false,
                 cache_dir: "/tmp/zizmor".into(),
                 gh_token: None,
+                gh_hostname: GitHubHost::Standard("github.com".into()),
             };
 
             let sut = GitHubEnv::new(audit_state).expect("failed to create audit");
@@ -519,6 +521,7 @@ mod tests {
                 no_online_audits: false,
                 cache_dir: "/tmp/zizmor".into(),
                 gh_token: None,
+                gh_hostname: GitHubHost::Standard("github.com".into()),
             };
 
             let sut = GitHubEnv::new(audit_state).expect("failed to create audit");

Diff for: src/github_api.rs

@@ -27,13 +27,46 @@ use crate::{
     utils::PipeSelf,
 };
 
+/// Represents different types of GitHub hosts.
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) enum GitHubHost {
+    Enterprise(String),
+    Standard(String),
+}
+
+impl GitHubHost {
+    pub(crate) fn from_clap(hostname: &str) -> Result<Self, String> {
+        let normalized = hostname.to_lowercase();
+
+        // NOTE: ideally we'd do a full domain validity check here.
+        // For now, this just checks the most likely kind of user
+        // confusion (supplying a URL instead of a bare domain name).
+        if normalized.starts_with("https://") || normalized.starts_with("http://") {
+            return Err("must be a domain name, not a URL".into());
+        }
+
+        if normalized.eq_ignore_ascii_case("github.com") || normalized.ends_with(".ghe.com") {
+            Ok(Self::Standard(hostname.into()))
+        } else {
+            Ok(Self::Enterprise(hostname.into()))
+        }
+    }
+
+    fn to_api_url(&self) -> String {
+        match self {
+            Self::Enterprise(ref host) => format!("https://{host}/api/v3"),
+            Self::Standard(ref host) => format!("https://api.{host}"),
+        }
+    }
+}
+
 pub(crate) struct Client {
-    api_base: &'static str,
+    api_base: String,
     http: ClientWithMiddleware,
 }
 
 impl Client {
-    pub(crate) fn new(token: &str, cache_dir: &Path) -> Self {
+    pub(crate) fn new(hostname: &GitHubHost, token: &str, cache_dir: &Path) -> Self {
         let mut headers = HeaderMap::new();
         headers.insert(USER_AGENT, "zizmor".parse().unwrap());
         headers.insert(
@@ -71,7 +104,7 @@ impl Client {
         .build();
 
         Self {
-            api_base: "https://api.github.com",
+            api_base: hostname.to_api_url(),
             http,
         }
     }
@@ -463,3 +496,22 @@ pub(crate) struct File {
     name: String,
     path: String,
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::github_api::GitHubHost;
+
+    #[test]
+    fn test_github_host() {
+        for (host, expected) in [
+            ("github.com", "https://api.github.com"),
+            ("something.ghe.com", "https://api.something.ghe.com"),
+            (
+                "selfhosted.example.com",
+                "https://selfhosted.example.com/api/v3",
+            ),
+        ] {
+            assert_eq!(GitHubHost::from_clap(host).unwrap().to_api_url(), expected);
+        }
+    }
+}

Diff for: src/main.rs

@@ -9,6 +9,7 @@ use clap::{Parser, ValueEnum};
 use clap_verbosity_flag::InfoLevel;
 use config::Config;
 use finding::{Confidence, Persona, Severity};
+use github_api::GitHubHost;
 use indicatif::ProgressStyle;
 use models::{Action, Uses};
 use owo_colors::OwoColorize;
@@ -48,13 +49,18 @@ struct App {
     ///
     /// This disables all online audit rules, and prevents zizmor from
     /// auditing remote repositories.
-    #[arg(short, long, env = "ZIZMOR_OFFLINE", group = "_offline")]
+    #[arg(short, long, env = "ZIZMOR_OFFLINE",
+        conflicts_with_all = ["gh_token", "gh_hostname"])]
     offline: bool,
 
     /// The GitHub API token to use.
-    #[arg(long, env, group = "_offline")]
+    #[arg(long, env)]
     gh_token: Option<String>,
 
+    /// The GitHub Server Hostname. Defaults to github.com
+    #[arg(long, env = "GH_HOST", default_value = "github.com", value_parser = GitHubHost::from_clap)]
+    gh_hostname: GitHubHost,
+
     /// Perform only offline audits.
     ///
     /// This is a weaker version of `--offline`: instead of completely

Diff for: src/state.rs

@@ -4,13 +4,17 @@ use std::path::PathBuf;
 
 use etcetera::{choose_app_strategy, AppStrategy, AppStrategyArgs};
 
-use crate::{github_api::Client, App};
+use crate::{
+    github_api::{Client, GitHubHost},
+    App,
+};
 
 #[derive(Clone)]
 pub(crate) struct AuditState {
     pub(crate) no_online_audits: bool,
     pub(crate) cache_dir: PathBuf,
     pub(crate) gh_token: Option<String>,
+    pub(crate) gh_hostname: GitHubHost,
 }
 
 impl AuditState {
@@ -33,14 +37,16 @@ impl AuditState {
             no_online_audits: app.no_online_audits,
             cache_dir,
             gh_token: app.gh_token.clone(),
+            gh_hostname: app.gh_hostname.clone(),
         }
     }
 
     /// Return a cache-configured GitHub API client, if
     /// a GitHub API token is present.
+    /// If gh_hostname is also present, set it as api_base for client.
     pub(crate) fn github_client(&self) -> Option<Client> {
         self.gh_token
             .as_ref()
-            .map(|token| Client::new(token, &self.cache_dir))
+            .map(|token| Client::new(&self.gh_hostname, token, &self.cache_dir))
     }
 }