phylum-dev/cli

Command line interface for the Phylum API

---

Introduction

The Phylum command line interface (CLI) allows users to submit their project package dependencies to Phylum's API for analysis. Currently pre-built binaries for Linux and macOS are available. On Windows, we recommend using the Linux binaries under WSL. See the alternate installation methods for more options.

Install phylum CLI

Install on Linux

Install on Linux with the following command:

curl https://sh.phylum.io/ | sh -

Install on macOS

On macOS, we recommend installing phylum with Homebrew:

brew install phylum

Note: When using Homebrew, official extensions must be installed separately.

Quickstart for Linux or macOS

1. Register for an account (if you don't already have one)

   phylum auth register

2. Authenticate with Phylum

   phylum auth login

3. Setup your Phylum project in your project directory

   phylum init

4. Submit your lockfiles and manifests to analyze dependencies

   phylum analyze

5. (Optional) View the analysis results in the Phylum UI

Extensions

Phylum CLI extensions allow you to extend the existing CLI functionality with new features. You can start exploring by taking a look at the official Phylum extensions:

https://github.com/phylum-dev/cli/tree/main/extensions

How-tos

How-to articles for the extension framework can be found here.

musl binaries

As of version 3.8.0, the provided Linux binaries of the Phylum CLI depend on glibc. We no longer provide binaries that are statically compiled with the musl libc.

This means the provided binaries won't be executable in environments such as Alpine Linux. If your use case requires a lightweight Docker base image, consider using Debian slim instead.

License

Copyright (C) 2022 Phylum, Inc.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/gpl.html or write to [email protected] or [email protected]

---

Discord

Join us on the Phylum Community Discord!

Questions/Issues

Please contact Phylum with any questions or issues using the CLI tool.

Email: [email protected]

cli's Issues

Update documentation for `--filter` option

Describe the issue
The --filter option has some CLI description and examples, but the full list of options isn't documented.

Describe why the issue is needed
Without a list of the acceptable arguments, the user is left guessing.

Describe the proposed solution
Document at least one of each of the acceptable filter arguments in the Phylum docs.

Estimated Subtasks
TBD

Additional Information

`set-thresholds` fails on WSL

Describe the bug
When running in Ubuntu on WSL, the set-thresholds command gets stuck on the action prompt.

To Reproduce
Steps to reproduce the behavior:

1. Install the Ubuntu version of WSL
2. Create a phylum project
3. Run phylum projects set-thresholds <proj-name>
4. Submit a value for the TOTAL PROJECT Threshold (that seems to work fine)
5. Observe the command prompt disappear

Expected behavior
Complete threshold setup as expected.

Screenshots

Desktop (please complete the following information):

• OS: Windows
• Version 10
• Ubuntu on Windows Subsystem for Linux (WSL)

`auth status` incorrectly claims a non-existent user is authenticated

Describe the bug
auth status sometimes will report that a user that has never been registered with phylum auth register is currently authenticated.

I'm setting as Medium Priority but Low might make sense.

To Reproduce
Steps to reproduce the behavior:

1. Manually edit $HOME/.phylum/settings.yaml to have credentials to a new, un-registered user.
2. Attempt to perform an action that requires authentication, such as analyze
3. Note the 401 Unauthorized error
4. Finally, execute phylum auth status
5. Note that phylum believes the user to be currently authenticated

Expected behavior
The auth status command should send a small message to the API to confirm that the current user authentication status is
accurate. I suspect this will be useful for situations in CI/CD automation.

Screenshots

❯ phylum analyze package-LES-lock.json
---------------- Update Available ----------------

A new version of the Phylum CLI is available. Run

        phylum update

to update to the latest version!

--------------------------------------------------


[2021-06-18T18:35:41Z ERROR phylum_cli::restson] server returned "401 Unauthorized" error
[2021-06-18T18:35:41Z ERROR phylum] Error attempting to authenticate: HttpError(401, "{\"msg\":\"Invalid login credentials provided\"}\n")
❗ Error: Error attempting to authenticate

root in Customer-provided package files/abbott/LES on ☁  (us-west-2) 
❯ phylum auth
---------------- Update Available ----------------

A new version of the Phylum CLI is available. Run

        phylum update

to update to the latest version!

--------------------------------------------------


auth
Manage authentication, registration, and API keys

USAGE:
    auth [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help        Prints this message or the help of the given subcommand(s)
    keys        Manage API keys
    login       Login to an existing account
    register    Register a new account
    status      Return the current authentication status


root in Customer-provided package files/abbott/LES on ☁  (us-west-2) 
❯ phylum auth status
---------------- Update Available ----------------

A new version of the Phylum CLI is available. Run

        phylum update

to update to the latest version!

--------------------------------------------------


✅ Currenty authenticated as [email protected]

`history` displays in reverse order

Describe the bug
phylum history says that it displays the "last 30 runs of x submitted," but it actually shows the first 30.

To Reproduce
Steps to reproduce the behavior:

1. Submit over 30 projects for analysis
2. Use the CLI tool to run phylum history
3. Observe that the first 30 are displayed and not the most recent

Expected behavior
Display the last 30 runs

`version` does not display release candidate versions

Describe the bug
The version command does not display release candidate versions.

To Reproduce
Steps to reproduce the behavior:

1. Install a pre-release version of the phylum CLI
2. Run phylum version
3. Observe that only the major.minor.patch semver is shown

Expected behavior
Display the actual version of the software, including any pre-release semvers

Screenshots

Add public-key signature verification to `update` process

Is your feature request related to a problem? Please describe.
phylum has an update function that can update the binary in place with an updated version from Phylum's github repo. This currently doesn't do digital signature verification.

Describe the solution you'd like
Two steps:

1. Add a github action to sign releases with a private key
2. Add a signature verification requirement to the update CLI command.

Describe alternatives you've considered
Minisign is an implementation of ED25519 that looks very usable for this feature as we're only updating the rust CLI binary.
This looks like a promising crate to use in the CLI tool to implement this.

`--filter=lic` does not properly exclude vulnerabilities in output

Describe the bug
When passing the argument --filter=lic, phylum still outputs issues of the vulnerability risk domain.

To Reproduce
Steps to reproduce the behavior:

1. Use a project with both license and vulnerability issues
2. Request only lic risk domain issues with: phylum analyze <file> --verbose --filter=lic
3. Observe vulnerabilities present at the end of the response

Expected behavior
When using the --filter=X option, only elements pertaining to the filter are displayed

Swap custom 'Renderable' implementation for a serde serializer

Renderable is used to provide human readable output when querying Projects/Packages by the cli.

It could instead be replaced with implementing a custom serializer to make use of the existing serde infrastructure.

See https://github.com/serde-rs/example-format/blob/master/src/ser.rs for an example

Improve `analyze` subcommand

Is your feature request related to a problem? Please describe.
N/A

Describe the solution you'd like
A reorganization of the analyze subcommand. Running ph analyze should return the high level help information for this command. This command is really a renaming (and slight re-work) of the submit command. It takes the following form:

ph analyze <pathToPackageFile.ext> --verbose --json --web

The first positional parameter is the path to the package-lock.json, yarn-lock.json, requirements.txt, etc. We currently have separate facilities for processing package files from each ecosystem. These facilities should be rolled into the ph binary to minimize friction to getting started.

The default view for this is a summary overview containing things like:

• Number of packages
• Number of packages that fall within certain score ranges (i.e. bar graph style display)
• Worst packages
• Highest score and lowest score

Really, just give the user a feel for their current posture and give them a path to where they should look first.

The flags for this command are all optional.

• --verbose - Returns a more verbose response. If --json is provided with this flag, give more verbose JSON output. If it is not provided, expand upon our summary and give full package details.
• --json - Returns a JSON formatted response
• --web - Open the users web browser to the web application for the specified project. (This is a low priority item).

Note: The analyze subcommand expects to be associated with a project. If we are not currently associated with a project, exit and alert the user to this fact. Provide a helpful message describing how they can create a new project, or how they can link to an existing project.

We should also fetch the configured threshold for the specified project and exit with a non-zero exit code if the threshold is broken.

• Rename submit to analyze
• Add native support for NPM package lock files
• Add native support for Yarn lock files
• Add native support for Gemfiles
• Add native support for Python requirements
• Improve help message for missing project
• Query threshold settings
• Add summary output (brief)
• Add summary output (detailed)
• Update default response for summary view (see @peterjmorgan's work for inspiration)

Describe alternatives you've considered
N/A

Additional context
N/A

Break out build script from install script

`analyze` subcommand: Allow user to specify yarn lock filenames not restricted to `yarn.lock`

Is your feature request related to a problem? Please describe.
phylum requires yarn.lock files to named exactly yarn.lock. Some customers use yarn.lock files that have other names, which would require them to rename the file prior to submitting.

Describe the solution you'd like
The user specifies the filename as an argument to phylum analyze and the cli tool infers the type of the file from the headers present.

Describe alternatives you've considered
An alternative could be to add an option or flag to the cli to specify the lock file type.

Additional context
Add any other context or screenshots about the feature request here.

Implement OIDC support for user login and refresh/api tokens

We need to port the CLI over to using KeyCloak as a oauth provider, and we need to implement a small part of OIDC to do so.

• Support user registration
• Support user login
• Support a method to obtain addition long lived refresh_tokens, say grabbing a token to use a secret for a CLI install
• Support going to account page so long lived tokens can be revoked
• TODO: Theme that page and others....

Incorrect scores and missing impacts on `history` subcommand

Describe the bug
When viewing the history output, the scores are all identical and we are missing the impacts.

To Reproduce
Steps to reproduce the behavior:

1. Run phylum history
2. Note the identical scores and missing impacts

Expected behavior
Scores should be pulled from the job along with the impacts.

Screenshots
N/A

Desktop (please complete the following information):
N/A

Additional context
N/A

Update Available message language

Describe the issue
The Update Available message does not take into consideration pre-release versions.

Describe the proposed solution
We could possibly change the language to side-step this. Proposed language:

You are not running the latest stable version of the Phylum CLI.
phylum update
The above command will update to the latest stable release.

I am not sure if we should also change the title to "Warning" or something like some other Linux CLI tools do?

Estimated Subtasks
TBD

Remove overlap in histogram ranges

Is your feature request related to a problem? Please describe.
The histogram ranges have overlap in the display (0-10, 10-20, etc) so it is unclear where a package with score 10 will be represented.

Describe the solution you'd like
Change display ranges to be unique (0-10, 11-20, 21-30, etc) and ensure the packages are populated correctly in the new ranges.

Describe alternatives you've considered
none

Additional context
It would also be good to flip the histogram where high scores are on top and low scores are on the bottom to match the UI.

Installer on MacOS used bashrc instead of zshrc

Describe the bug
The MacOS system was running zsh and had a .zshrc in the $HOME directory, but the installer still chose bashrc.

Expected behavior
Use zsh if .zshrc exists

Add examples

Add examples to README

`analyze` CLI sometimes fails to parse yarn.lock files

Describe the bug
The CLI tool sometimes fails to parse yarn.lock files yarn lock files with names of than "yarn.lock". It doesn't indicate the error in parsing, but the yarn.lock files are well-formed, even testing with reproducing a new file with yarn.

To Reproduce
Steps to reproduce the behavior:

1. Submit the dailypay partner-portal yarn.lock file (attached)

Expected behavior
The CLI tool can infer and parse yarn.lock files. When it fails to parse, there should be some indication why it failed (happy to discuss!)

dailypay-partner-portal.yarn.lock.txt

Reconsider of chrono crate due to https://rustsec.org/advisories/RUSTSEC-2020-0071.html

I don't we hit the vulnerable code paths, and if we do, we don't use set_env, though we can't make transitive guarantees about crates we consume.

I think we can probably use the time crate ( v > 0.3 ) for our needs. Maybe?

Update mechanism fails on tmpfs

Describe the bug
Attempts to use the update functionality on a machine using tmpfs fails with Cross-device link (os error 18)

To Reproduce
Steps to reproduce the behavior:

1. From a machine using tmpfs run phylum update

Expected behavior
Should download the latest release, verify the signatures, and put the new binary in the proper place.

Additional context
The update mechanism works properly for any system not leveraging tmpfs. We should account for this during the update process.

`analyze` subcommand should require a project association

Describe the bug
Without a .phylum_project file, you should not be able to submit packages for analysis. However, currently this is possible.

To Reproduce
Steps to reproduce the behavior:

1. Go into a folder with a package-lock.json
2. Ensure that an existing project association does not exist, and rm .phylum_project if it does
3. Submit the packages for analysis with phylum analyze package-lock.json

Expected behavior
The CLI should stop and inform you that you do not have an associated project. It should also instruct you to run phylum projects create <project-name> or phylum projects link <project-name> to associate the current working directory/repository with a Phylum project.

Screenshots
N/A

Desktop (please complete the following information):
N/A

Additional context
N/A

Add improve verbosity/filtering commands

Is your feature request related to a problem? Please describe.
We should provide the user with a mechanism to filter based on the problem domain (e.g. "Only show me issues related to author risk"). Additionally, we should improve the verbosity flags to allow varying levels of output.

Describe the solution you'd like

• Levels for verbosity, e.g. -v for more verbose but still trimmed down response, -vv for extra verbosity.
• Filtering sub commands, i.e. phylum analyze --filter=critical ...

Describe alternatives you've considered
N/A

Additional context
N/A

Consolidate `Type` and `Language` fields to Ecosystem

Describe the issue
It seems that it would be most accurate if we deprecate Type and Language for the project analysis in favor of something like Ecosystem.

Describe why the issue is needed
At the project level, the analysis may contain multiple languages.

Describe the proposed solution
Eliminate Language and change Type to Ecosystem.

Estimated Subtasks
TBD

Additional Information
This will likely require us to at least change the Python Type entry as it states Python and not PyPi.

Processing documentation is missing

Describe the issue
The CLI references documentation for processing, but the page does not exist.

Describe why the issue is needed
Users need documentation to better understand the processing state.

Describe the proposed solution
Populate the processing documentation.

Estimated Subtasks
TBD

`analyze` subcommand sometimes mis-reports number of dependencies on submission

Describe the bug
analyze subcommand sometimes mis-reports the number of dependencies on submission. The lock file has many more dependencies than is sometimes reported by phylum analyze.

In the following example, I'm submitting a yarn.lock file that has 1730 dependencies as shown:

❯ cat native-mobile.yarn.lock.txt | rg "^[[:alpha:]]+.*?:$" | wc -l
1730

phylum analyze output:

❯ phylum analyze native-mobile.yarn.lock.txt
---------------- Update Available ----------------

A new version of the Phylum CLI is available. Run

        phylum update

to update to the latest version!

--------------------------------------------------


✅ Job ID: 40916790-bab6-4d44-bcae-4142c244c752


          Project: native-mobile                                           Label: uncategorized
       Proj Score: 100                                                      Date: 2021-06-09 22:10:40 UTC
         Num Deps: 47                                                     Job ID: 40916790-bab6-4d44-bcae-4142c244c752
             Type: NPM                                                  Language: Javascript
          User ID: [email protected]                              View in Phylum UI: https://app.phylum.io/40916790-bab6-4d44-bcae-4142c244c752

     Score       Count
      0 - 10   [    0]                                                                                 Project Score: 0.6
     10 - 20   [    0]                                                                       Malicious Code Risk MAL:   0
     20 - 30   [    0]                                                                        Vulnerability Risk VLN:   0
     30 - 40   [    0]                                                                          Engineering Risk ENG:   0
     40 - 50   [    0]                                                                               Author Risk AUT:   0
     50 - 60   [    0]                                                                              License Risk LIC:   0
     60 - 70   [    0]
     70 - 80   [    0]
     80 - 90   [    0]
     90 - 100  [   47] ███████████████████████████████

This appears to be an issue with NPM package-lock files as well. The next example is using a package-lock.json:

❯ cat package-LES-lock.json | pcregrep "^    \".+?\": {" | grep -v 'node_modules' | wc -l
1275

❯ ph analyze package-LES-lock.json
---------------- Update Available ----------------

A new version of the Phylum CLI is available. Run

        phylum update

to update to the latest version!

--------------------------------------------------


✅ Job ID: 82715ae3-2ac7-41a7-8cfd-16b644ddd400


          Project: les                                                     Label: uncategorized
       Proj Score: 100                                                      Date: 2021-06-09 22:21:50 UTC
         Num Deps: 2                                                      Job ID: 82715ae3-2ac7-41a7-8cfd-16b644ddd400
             Type: NPM                                                  Language: Javascript
          User ID: [email protected]                              View in Phylum UI: https://app.phylum.io/82715ae3-2ac7-41a7-8cfd-16b644ddd400

     Score       Count
      0 - 10   [    0]                                                                                  Project Score: 0.6
     10 - 20   [    0]                                                                        Malicious Code Risk MAL:   0
     20 - 30   [    0]                                                                         Vulnerability Risk VLN:   0
     30 - 40   [    0]                                                                           Engineering Risk ENG:   0
     40 - 50   [    0]                                                                                Author Risk AUT:   0
     50 - 60   [    0]                                                                               License Risk LIC:   0
     60 - 70   [    0]
     70 - 80   [    0]
     80 - 90   [    0]
     90 - 100  [    2] ████████████████████████████████

To Reproduce
Steps to reproduce the behavior:

1. Create a project
2. Submit the relevant lockfile (contact @pete if you don't have them)
3. Note the differences in reported dependencies

Expected behavior
The CLI should report the correct number of deps.

I ran CLI under RUST_LOG=debug and noted this:

package-LES-lock.json

[2021-06-09T22:54:16Z INFO  phylum] Found project configurtion file at ./.phylum_project
[2021-06-09T22:54:16Z WARN  phylum] Attempting to obtain packages from unrecognized lockfile type: package-LES-lock.json
[2021-06-09T22:54:17Z DEBUG phylum] Submitting file as type package lock
[2021-06-09T22:54:17Z DEBUG phylum] Read 1275 packages from file `package-LES-lock.json`

native-mobile.yarn.lock.txt

[2021-06-09T22:56:51Z INFO  phylum] Found project configurtion file at ./.phylum_project
[2021-06-09T22:56:51Z WARN  phylum] Attempting to obtain packages from unrecognized lockfile type: native-mobile.yarn.lock.txt
[2021-06-09T22:56:51Z DEBUG phylum] Submitting file as type yarn lock
[2021-06-09T22:56:51Z DEBUG phylum] Read 178 packages from file `native-mobile.yarn.lock.txt`

Note: The value reported by CLI above (175 packages) is not correct. It should be 1730

Long project names can mess up formatting

Describe the bug
If a project is created with a long name it can mess up the formatting on a few of the CLI views.

To Reproduce
Steps to reproduce the behavior:

1. Create a project with a very long name
2. Run phylum projects list and observe formatting
   Note: this also impacts several other views

Expected behavior
CLI handles long project names. Perhaps truncating and adding ellipsis? Or limiting the accepted project name size and throwing an error if it is exceeded?

Screenshots
projects list view

history view

analyze view

Log scale for histogram output

Is your feature request related to a problem? Please describe.
No

Describe the solution you'd like
Apply a log scale to the histogram view.

Describe alternatives you've considered
N/A

Additional context
We want to ensure that the histogram output is meaningful. In some instances high numbers of packages in one bucket will overshadow all other buckets. We should account for this by applying a log scale to the output.

Add the ability to specify a Project GUID when using `analyze`

Is your feature request related to a problem? Please describe.
When using Phylum with automation there may be cases where having a .phylum_project file is difficult or the user might want to specify everything on a single command line.

Describe the solution you'd like
Add an option to specify an existing Project GUID to the phylum analyze command.

Describe alternatives you've considered
Currently, there is no way to submit a request for analysis without a .phylum_project file.

Add synchronous mode to CLI tool

Add a synchronous option so the CLI tool will wait for a return from the server.

Probably makes sense to have a max timeout period set as well.

`analyze` submission gives confusing results with number of dependencies compared to number of histogram entries

Describe the bug
Sometimes when using the analyze subcommand, the response shows confusing information when comparing the number of dependencies and the histogram.

To Reproduce
Steps to reproduce the behavior:

1. Submit root9b's packages using analyze
2. Note the number of dependencies in the header stats block
3. Note the number of packages listed in the histogram

Expected behavior
The number of dependencies is the same as the number of entries in the histogram

Crit field not populated in `history` view

Describe the bug
The Crit field is shown in the history view, but is not populated with any data.

To Reproduce
Steps to reproduce the behavior:

1. Have analyzed at least one project
2. Run phylum history
3. Observe the "Crit:" field

Expected behavior
Either remove this field or populate it with the correct data.

Screenshots

Update fails on macOS

Describe the bug
Running phylum update works as expected on Linux. However, doing so on macOS fetches the binary for Linux which breaks the installation.

To Reproduce
Steps to reproduce the behavior:

1. Install phylum on macOS
2. Run phylum update
3. Attempt to run phylum
4. Verify that it's an ELF executable

file `which phylum`

Expected behavior
We should download the platform specific executable.

Additional context
We recently added automated builds for macOS. Previously this worked because there was no executable to fetch for the macOS platform.

CLI `--json` option includes update notification stanza that breaks JSON format

Describe the bug
phylum has a --json option to return JSON formatted data. The update notification stanza breaks JSON format. In its current implementation a user will need to remove that header before the data can be interpreted as JSON with something like:
phylum analyze myfile.lock --json | taiil -n+9

To Reproduce
Steps to reproduce the behavior:

1. Submit with phylum analyze <lockfile> --json and pipe to an editor
2. Observe the header

Expected behavior
The --json option will often be used for automation. It is strongly desirable to ensure the response is well-formed JSON.

Suggestion
We could consider adding a key to the JSON output that notifies for the presence of an update to the CLI tool.

Screenshots

`analyze` Change project ID to project name in header stats block

Is your feature request related to a problem? Please describe.
Customer value improvement. I can't think of a specific use for the Project ID in this context. The project name, however, would be valuable for the user to see in this output.

Describe the solution you'd like
Change project ID to Project name and list the name instead of the GUID.

Setting thresholds for a new project fails

Describe the bug
Attempting to set project thresholds from the CLI for a new project fails. If user settings have previously been created (e.g. from the UI) this bug does not manifest.

To Reproduce
Steps to reproduce the behavior:

1. Create a new project
2. Run `phylum projects set-thresholds <proj_name>
3. Observe the error:

Risk thresholds allow you to specify what constitutes a failure.
You can set a threshold for the overall project score, or for individual
risk vectors:

    * Author
    * Malicious Code
    * Vulnerability
    * License
    * Engineering

If your project score falls below a given threshold, it will be
considered a failure and the action you specify will be taken.

Possible actions are:

    * Print a warning: print a message to standard error
    * Break the build: If we are in CI/CD break the build and return a non-zero exit code
    * Nothing, fail silently: Ignore the failure and continue

Specify the thresholds and actions for eric-foobar. A threshold of zero will disable the threshold.

✔ TOTAL PROJECT Threshold · 70

What should happen if a score falls below the total project threshold?

✔ TOTAL PROJECT Action · Break the CI/CD build

-----

thread 'main' panicked at 'no entry found for key', src/types.rs:375:30

Expected behavior
Setting thresholds for a new project should function correctly.

Use colorblindness safe colors in terminal

It might be worthwhile to consider using colorblind safe colors or techniques in terminal messages

Such as Bold or italic or whatever else ansi term supports.

Improve `auth` subcommand

Is your feature request related to a problem? Please describe.
N/A

Describe the solution you'd like
A reorganization of the auth subcommand. Running ph auth should return the high level help information for this command, along with the list of subcommands of auth and their descriptions.

This command should have several of its own subcommands:

• ph auth register - Should go into an interactive mode and ask the user for their email, password, confirm password and name. We currently request first and last name, this should be updated to simply name. After successful registration, we should create a new API key named cli that will be used for authentication moving forward.
• ph auth login - Log a user in with existing credentials. Also in interactive mode. After login, we should get or create the API key cli and use that for authentication moving forward.
• ph auth keys - Provide management facilities for API keys. This command should similarly have its own subcommands: create, list and remove.
• ph auth status - Return an indicator of current authentication status.

Describe alternatives you've considered
N/A

Additional context
N/A

Add `--no-check-certificate` as a config option

Is your feature request related to a problem? Please describe.
When a user is required to use the --no-check-certificate option, they must include it for all subcommands. This makes the workflow a bit clunky for that use case.

Describe the solution you'd like
Have the --no-check-certificate option as a configuration parameter option stored in the settings.yaml file. When set, this would run all commands with that option set. This will allow the user to omit that option from the command line. NOTE: We should clearly warn the user that they are running in this mode for each request. Maybe a red warning text after each request?

Describe alternatives you've considered
The current command option works, but is not as clean.

Additional context
This is impacting customers with SSL decryption and other MITM solutions.

Add `update` subcommand and update checking facilities

Is your feature request related to a problem? Please describe.
N/A

Describe the solution you'd like
We need a simple path to upgrading the binary. We should add a subcommand ph update that checks for an updated binary release on Github. If a new release exists, we should fetch it and replace the existing binary with this updated version.

Additionally, we should notify the user if an update is available with a banner during runtime.

• Add an update subcommand to update binary on disk
• Add facilities for checking for updates that can be added to other commands to notify user of an available update.

Describe alternatives you've considered
N/A

Additional context
N/A

Improve `package` subcommand

Is your feature request related to a problem? Please describe.
N/A

Describe the solution you'd like
A reorganization of the package subcommand. Running ph package should return the high level help information for this command. This subcommand should take two positional arguments, packageName and packageVersion. i.e.,

ph package react 16.3.1

This subcommand should operate as a read only interface. It is merely fetching what we know about this package from our API and displaying it to the user.

Like the analyze subcommand, we should return nicely formatted, human readable summaries by default. If the user provides us with a --json flag, we should return the JSON output instead.

Describe alternatives you've considered
N/A

Additional context
N/A

Improve `history` subcommand

Is your feature request related to a problem? Please describe.
N/A

Describe the solution you'd like
A reorganization of the history subcommand. Running ph history should return the high level help information for this command, along with the list of subcommands of history and their descriptions.

Really history is mostly a renaming of the current status command with some minor UX improvements.

This command should have several of its own subcommands:

• Setup command scaffolding for subcommands, arguments, etc.
• ph history - Should show the 30 most recent runs.
• ph history --job <job id> - Show the full results of a given job
• ph history project - Show a list of projects associated with the user
• Update the projects endpoint to support the next task.
• ph history project <project name> - Shows the project based history listing
• ph history project <project name> <job id> - Shows the full results of a job

Describe alternatives you've considered
N/A

Additional context
N/A

Normalize ranges for thresholds and scores

Describe the issue
We currently report scores in the 0-100 range. Thresholds are reported in the 0-1 range. We should normalize these to 0-100.

Describe why the issue is needed
Prevents the user from comparing domain thresholds with project scores. Confusing.

Describe the proposed solution
Normalize thresholds/scores to use the 0-100 range.

Estimated Subtasks
N/A

Additional Information
N/A

Rename CLI binary to something shorter

Is your feature request related to a problem? Please describe.
We've noticed that users consistently alias the phylum-cli binary to something much shorter.

Describe the solution you'd like
Shorten the name of the distributed binary to simply ph instead of the long form phylum-cli.

Describe alternatives you've considered
N/A

Additional context
N/A

Be more explicit with incomplete states

Describe the issue
In some instances, we may encounter a package we haven't seen before. The CLI will currently notify the user that some items are still processing. However, this is not clear enough. The "Status" for the job run still returns PASS or FAIL which further obfuscates the true state (i.e. INCOMPLETE).

Describe why the issue is needed
To avoid confusing the user, we need to be as explicit as possible in all cases.

Describe the proposed solution
Add an INCOMPLETE status. Link to documentation for why something is incomplete.

Estimated Subtasks

• Update status check for CLI response to add an INCOMPLETE state.
• Add a link to the documentation for the incomplete message.

Additional Information
N/A

Improve `projects` subcommand

Is your feature request related to a problem? Please describe.
N/A

Describe the solution you'd like
A reorganization of the projects subcommand. Running ph projects should return the high level help information for this command, along with the list of subcommands of projects and their descriptions.

This command should have several of its own subcommands:

• ph projects create <projectName> - Create a new project with the given name.
• ph projects list - List all known projects in a nice format, e.g.

ID          Name
1            Foo
2            Bar
3            Baz
...

• ph projects link <projectId> - Associate the current working directory (likely Git repository) with the specified project ID.
• ph projects set-thresholds - The UI supports setting thresholds for the overall project, and the specific domains. These thresholds have an associated action (e.g. Break Build or Warn). We should be able to set these values here from the CLI. This command should drop the user into an interactive mode to set these values.

Describe alternatives you've considered
N/A

Additional context
N/A

python manifest parser fails to recognize .egg dependencies in nonstandard locations

Describe the bug
python manifest parser fails to recognize .egg dependencies in nonstandard locations such as git+ssh://

Some very popular packages use this format when installing (such as matplotlib)

To Reproduce
Steps to reproduce the behavior:

1. git clone https://github.com/matplotlib/matplotlib
2. activate a virtualenv
3. install deps pip install -ve .
4. generate concrete requirements.txt pip freeze > phylum_requirements.txt
5. auth, create project and attempt to analyze phylum analyze phylum_requirements.txt

Expected behavior
python manifest parser correctly identifies non-standard locations, such as:
-e git+ssh://[email protected]/matplotlib/matplotlib.git@0666c59edb2ecaa92a66af8385a41cf5cba150e4#egg=matplotlib

`phylum` does not gracefully display error conditions when `analyze` submission is not correctly associated with a project

Is your feature request related to a problem? Please describe.
Yes. When a user submits an analyze request but has not created a project for the request, the rust error message is returned to stderr.

Describe the solution you'd like
This feature request centers on removing the stderr output and cleanly reporting the error in the design of the CLI tool

Update CLI to use new Request manager support in API

Ensure the CLI is kept in sync with the new Request Manager API

Clean up Error Handling and exit codes

Right now, handler functions tend to directly call various process.exit versions.

Instead, they should all return some form of Result, with the top level main function finally handling the Result and determing the exit code

• All handlers return result with appropriate info for error cases
• Main function examines results and calls appropriate print methods and process exit.

Add additional help text during installation

Describe the issue
When a user runs the installation script, they are not informed that they need to source their bashrc (or zshrc, etc.) to add the newly installed binary to their path.

Describe why the issue is needed
Confusing for the user.

Describe the proposed solution
We should print out a bit of instructional text, a la rustup, that informs the user that they need to either source the proper files, manually add the binary installation folder to their PATH or restart their terminal.

Estimated Subtasks
None

Additional Information
N/A