A GitHub Action using Phylum to automatically analyze Pull Requests for changes to package manager lockfiles.

Phylum provides a complete risk analyis of "open-source packages" (read: untrusted software from random Internet strangers). Phylum evolved forward from legacy SCA tools to defend from supply-chain malware, malicious open-source authors, and engineering risk, in addtion to software vulnerabilities and license risks. To learn more, please see our website

Once configured for a repository, this action will provide analysis of project dependencies from a lockfile during a Pull Request (PR) and output the results as a comment on the PR. The CI job will return an error (i.e., fail the build) if any of the newly added/modified dependencies from the PR fail to meet the project risk thresholds for any of the five Phylum risk domains:

• Vulnerability (aka vul)
• Malicious Code (aka mal)
• Engineering (aka eng)
• License (aka lic)
• Author (aka aut)

See Phylum Risk Domains documentation for more detail.

NOTE: It is not enough to have the total project threshold set. Individual risk domain threshold values must be set, either in the UI or with phylum-ci options, in order to enable analysis results for CI. Otherwise, the risk domain is considered disabled and the threshold value used will be zero (0).

There will be no note if no dependencies were added or modified for a given MR. If one or more dependencies are still processing (no results available), then the note will make that clear and the CI job will only fail if dependencies that have completed analysis results do not meet the specified project risk thresholds.

The GitHub Actions environment is primarily supported through the use of a Docker image. The pre-requisites for using this image are:

• Ability to run a Docker container action
  • GitHub-hosted runners must use an Ubuntu runner
  • Self-hosted runners must use a Linux operating system and have Docker installed
• Access to the phylumio/phylum-ci Docker image
• A GitHub token with API access
  • Can be the default GITHUB_TOKEN provided automatically at the start of each workflow run
    • Needs at least write access for pull-requests scope - see documentation
  • Can be a personal access token (PAT) - see documentation
    • Needs the repo scope or minimally the public_repo scope if private repositories are not used
• A Phylum token with API access
  • Contact Phylum or create an account and register to gain access
    • See also phylum auth register command documentation
  • Consider using a bot or group account for this token
• Access to the Phylum API endpoints
  • That usually means a connection to the internet, optionally via a proxy
  • Support for on-premises installs are not available at this time
• A .phylum_project file exists at the root of the repository
  • See phylum project and phylum project create command documentation

If not explicitly specified, an attempt will be made to automatically detect the lockfile. Some lockfile types (e.g., Python/pip requirements.txt) are ambiguous in that they can be named differently and may or may not contain strict dependencies. In these cases, it is best to specify an explicit lockfile path by using the phylum-ci --lockfile option. The list of currently supported lockfiles can be found in the Phylum Knowledge Base.

Phylum analysis of dependencies can be added to existing CI workflows or on it's own with this minimal configuration:

name: Phylum_analyze
on: pull_request
jobs:
  analyze_deps:
    name: Analyze dependencies with Phylum
    permissions:
      contents: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Analyze lockfile
        uses: phylum-dev/phylum-analyze-pr-action@v2
        with:
          phylum_token: ${{ secrets.PHYLUM_TOKEN }}

This configuration contains a single job, with two steps, that will only run on pull request events. It does not override any of the phylum-ci arguments, which are all either optional or default to secure values. Let's take a deeper dive into each part of the configuration:

The workflow and job names can be named differently or included in existing workflows/jobs.

name: Phylum_analyze                        # Name the workflow what you like
on: pull_request
jobs:
  analyze_deps:                             # Name the job what you like
    name: Analyze dependencies with Phylum  # This name is optional (defaults to job name)

The Phylum Analyze PR action expects to be run in the context of a pull_request webhook event. This includes both pull_request and pull_request_target events.

# NOTE: These are examples. Only one definition for `on` is expected.

# Specify the `pull_request` event trigger on one line
on: pull_request

# Alternative to specify `pull_request` trigger (e.g., when other triggers are present)
on:
  pull_request:

# Specify specific branches for the `pull_request` trigger to target
on:
  pull_request:
    branches:
      - main
      - develop

When using the default GITHUB_TOKEN provided automatically at the start of each workflow run, it is good practice to ensure the actions used in the workflow are given the least privileges needed to perform their intended function. The Phylum Analyze PR actions needs at least write access for the pull-requests scope. The actions/checkout action needs at least read access for the contents scope. See the GitHub documentation for more info.

    permissions:                # Ensure least privilege of actions
      contents: read            # For actions/checkout
      pull-requests: write      # For phylum-dev/phylum-analyze-pr-action

When using a personal access token (PAT) instead, the token should be created with the repo scope or minimally the with public_repo scope if private repositories will not be used with the PAT. See the GitHub documentation for more info.

    permissions:                # Ensure least privilege of actions
      contents: read            # For actions/checkout
      # The phylum-dev/phylum-analyze-pr-action does not
      # need the `pull-requests` scope here if using a PAT

The Phylum Analyze PR action is a Docker container action. This requires that GitHub-hosted runners use an Ubuntu runner. Self-hosted runners must use a Linux operating system and have Docker installed.

    runs-on: ubuntu-latest

git is used within the phylum-ci package to do things like determine if there was a lockfile change and, when specified, report on new dependencies only. Therefore, a clone of the repository is required to ensure that the local working copy is always pristine and history is available to pull the requested information.

    steps:
      - name: Checkout the repo
        uses: actions/checkout@v3
        with:
          # Specifying a depth of 0 ensures all history for all branches.
          # This input may not be required when `--all-deps` option is used.
          fetch-depth: 0

The action inputs are used to ensure the phylum-ci tool is able to perform it's job.

A Phylum token with API access is required to perform analysis on project dependencies. Contact Phylum or create an account and register to gain access. See also phylum auth register command documentation and consider using a bot or group account for this token.

A GitHub token with API access is required to use the API (e.g., to post comments). This can be the default GITHUB_TOKEN provided automatically at the start of each workflow run but it will need at least write access for the pull-requests scope (see documentation). Alternatively, it can be a personal access token (PAT) with the repo scope or minimally the public_repo scope, if private repositories are not used.

The values for the phylum_token and github_token action inputs can come from repository, environment, or organizational encrypted secrets. Since they are sensitive, care should be taken to protect them appropriately.

The cmd arguments to the Docker image are the way to exert control over the execution of the Phylum analysis. The phylum-ci script entry point is expected to be called. It has a number of arguments that are all optional and defaulted to secure values. To view the arguments, their description, and default values, run the script with --help output as specified in the Usage section of the phylum-dev/phylum-ci repository's README or view the source code directly.

    steps:
      - name: Analyze lockfile
        uses: phylum-dev/phylum-analyze-pr-action@v2
        with:
          # Contact Phylum (https://phylum.io/contact-us/) or create an account and register to gain access.
          # See also `phylum auth register` (https://docs.phylum.io/docs/phylum_auth_register) command docs.
          # Consider using a bot or group account for this token.
          phylum_token: ${{ secrets.PHYLUM_TOKEN }}

          # NOTE: These are examples. Only one `github_token` entry line is expected.
          #
          # Use the default `GITHUB_TOKEN` provided automatically at the start of each workflow run.
          # This entry does not have to be specified since it is the default.
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # Use a personal access token (PAT)
          github_token: ${{ secrets.GITHUB_PAT }}

          # NOTE: These are examples. Only one `cmd` entry line is expected.
          #
          # Use the defaults for all the arguments.
          # The default behavior is to only analyze newly added dependencies against
          # the risk domain threshold levels set at the Phylum project level.
          # This entry does not have to be specified since it is the default.
          cmd: phylum-ci
          # Consider all dependencies in analysis results instead of just the newly added ones.
          # The default is to only analyze newly added dependencies, which can be useful for
          # existing code bases that may not meet established project risk thresholds yet,
          # but don't want to make things worse. Specifying `--all-deps` can be useful for
          # casting the widest net for strict adherence to Quality Assurance (QA) standards.
          cmd: phylum-ci --all-deps
          # Some lockfile types (e.g., Python/pip `requirements.txt`) are ambiguous in that
          # they can be named differently and may or may not contain strict dependencies.
          # In these cases, it is best to specify an explicit lockfile path.
          cmd: phylum-ci --lockfile requirements-prod.txt
          # Thresholds for the five risk domains may be set at the Phylum project level.
          # They can be set differently for CI environments to "fail the build."
          # NOTE: The shortened form is used here for brevity, but the long form might be more
          #       descriptive for future readers. For instance `--vul-threshold` instead of `-u`.
          cmd: phylum-ci -u 60 -m 60 -e 70 -c 90 -o 80
          # Install a specific version of the Phylum CLI.
          cmd: phylum-ci --phylum-release 3.5.0 --force-install
          # Mix and match for your specific use case.
          cmd: phylum-ci -u 60 -m 60 -e 70 -c 90 -o 80 --lockfile requirements-prod.txt --all-deps

The above examples will fail the workflow when issues are found. If the desire is to ensure the workflow continues, even if Phylum finds issues with dependencies, then continue-on-error can be used at the step level and/or the job level.

This feature pairs nicely with the --all-deps and --force-analysis flags offered by the phylum-ci image. This can be useful for existing code bases that may not meet established project risk thresholds yet, but still want to know the full and current state of their dependency health.

name: Example workflow using Phylum with continue on error
on: pull_request
jobs:
  analyze_deps:
    name: Analyze dependencies in a pull request with Phylum
    permissions:
      contents: read
      pull-requests: write
    runs-on: ubuntu-latest
    continue-on-error: true     # This is the job level
    steps:
      - name: Checkout the repo with full history
        uses: actions/checkout@v3
        with:
          fetch-depth: 0        # Not really needed for `--all-deps`
      - name: Analyze lockfile
        continue-on-error: true # This is the step level
        uses: phylum-dev/phylum-analyze-pr-action@v2
        with:
          phylum_token: ${{ secrets.PHYLUM_TOKEN }}
          cmd: phylum-ci --all-deps

Phylum OSS Supply Chain Risk Analysis - FAILED

Phylum OSS Supply Chain Risk Analysis - SUCCESS

MIT - with complete text available in the LICENSE file.

Suggestions and help are welcome. Feel free to open an issue or otherwise contribute. More information is available on the contributing documentation page.

Everyone participating in the phylum-analyze-pr-action project, and in particular in the issue tracker and pull requests, is expected to treat other people with respect and more generally to follow the guidelines articulated in the Code of Conduct.

Found a security issue in this repository? See the security policy for details on coordinated disclosure.