feat: extend GHA integration to support pull_request_target events

This change makes it possible to use the GitHub Action (GHA) integration
for PRs that originate from forks, by enabling workflows to run on the
`pull_request_target` event. This change is simple enough, but comes
with some heavy security considerations. In order for the GHA to run, a
workflow using it will need to checkout the PRs code. This requires very
careful attention so as not to allow so-called "pwn requests":

* securitylab.github.com/research/github-actions-preventing-pwn-requests
* blog.gitguardian.com/github-actions-security-cheat-sheet

To that end, the documentation updates that go with this change will be
explicit in their warnings about how to properly use the Phylum GHA in
the most secure way possible. This effectively means the workflow should
be limited to executing the bare minimum required for Phylum analysis.

Further, the Phylum analysis that does run will need to do so in a way
that does not allow for arbitrary code execution. Therefore, this PR is
intended to be held back until the Phylum CLI adds some additional
protections around lockfile generation.

Closes #331

src/phylum/ci/ci_github.py

@@ -70,6 +70,7 @@ def _check_prerequisites(self) -> None:
         These are the current pre-requisites for operating within a GitHub Actions Environment:
           * The environment must actually be within GitHub Actions
           * A GitHub token providing `issues` API access is available
+          * `pull_request` or `pull_request_target` is the triggering event
           * `pull_request` webhook event payload is available
         """
         super()._check_prerequisites()
@@ -85,19 +86,19 @@ def _check_prerequisites(self) -> None:
         self._github_token = github_token
 
         # Unfortunately, there's not always a simple default environment variable that contains the desired information.
-        # Instead, the full event webhook payload can be used to obtain the information. Reference:
-        # https://docs.github.com/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request
-        if os.getenv("GITHUB_EVENT_NAME") != "pull_request":
-            msg = "The workflow event must be `pull_request`"
+        # Instead, the full event webhook payload can be used to obtain the information. The webhook payload for both
+        # `pull_request` and `pull_request_target` events is the same - `pull_request`.
+        # Ref: https://docs.github.com/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request
+        if os.getenv("GITHUB_EVENT_NAME") not in {"pull_request", "pull_request_target"}:
+            msg = "The workflow event must be `pull_request` or `pull_request_target`"
             raise SystemExit(msg)
         github_event_path_envvar = os.getenv("GITHUB_EVENT_PATH")
         if github_event_path_envvar is None:
             msg = "Could not read the `GITHUB_EVENT_PATH` environment variable"
             raise SystemExit(msg)
         github_event_path = Path(github_event_path_envvar)
         with github_event_path.open(encoding="utf-8") as f:
-            pr_event = json.load(f)
-        self._pr_event = pr_event
+            self._pr_event = json.load(f)
 
     @property
     def github_token(self) -> str:
@@ -125,7 +126,11 @@ def comments_url(self) -> str:
     def phylum_label(self) -> str:
         """Get a custom label for use when submitting jobs for analysis."""
         pr_number = self.pr_event.get("pull_request", {}).get("number", "unknown-number")
-        pr_src_branch = os.getenv("GITHUB_HEAD_REF", "unknown-ref")
+        if os.getenv("GITHUB_EVENT_NAME") == "pull_request_target":
+            # Use the `OWNER:BRANCH` form when the PR comes from a forked repo
+            pr_src_branch = self.pr_event.get("pull_request", {}).get("head", {}).get("label", "unknown-ref")
+        else:
+            pr_src_branch = os.getenv("GITHUB_HEAD_REF", "unknown-ref")
         label = f"{self.ci_platform_name}_PR#{pr_number}_{pr_src_branch}"
         label = re.sub(r"\s+", "-", label)
         return label