-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Andrew Lilley Brinker <[email protected]>
- Loading branch information
1 parent
824628d
commit 68924d8
Showing
3 changed files
with
43 additions
and
158 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,183 +1,68 @@ | ||
# Hipcheck | ||
# Hipcheck ✓ | ||
|
||
__Hipcheck__ scores risks for software projects; yours and your dependencies. | ||
It analyzes repositories to assess risks, review development practices, | ||
and identify possible supply chain attacks, making it possible to assess | ||
and manage open source software supply chain security at scale. | ||
[![License: Apache-2.0](https://img.shields.io/github/license/mitre/hipcheck)](https://github.com/mitre/hipcheck/blob/main/LICENSE) | ||
[![GitHub Release](https://img.shields.io/github/v/release/mitre/hipcheck)](https://github.com/mitre/hipcheck/releases/latest) | ||
|
||
--- | ||
__Go from hundreds of dependencies you can't review, to just a few you can!__ | ||
|
||
Managing the security risk of third-party software at scale is difficult. Normal | ||
projects can easily have hundreds of dependencies; far too many to review by hand. | ||
Hipcheck is designed to help you filter that list of dependencies down to just | ||
a few that appear concerning, and to give you the information you need to make | ||
a security decision quickly. | ||
|
||
* [Capabilities](#capabilities) | ||
* [Goals](#goals) | ||
* [Analyses](#analyses) | ||
* [Usage](#usage) | ||
* [Installation](#installation) | ||
* [Configuration](#configuration) | ||
* [Examples](#examples) | ||
* [Learn More](#learn-more) | ||
Hipcheck is a command line interface (CLI) tool for analyzing open source | ||
software packages and source repositories to understand their software supply | ||
chain risk. It analyzes a project's _software development practices_ and | ||
detects _active supply chain attacks_ to give you both a long-term and immediate | ||
picture of the risk from using a package. | ||
|
||
## Capabilities | ||
## Very Quick Explanation | ||
|
||
Hipcheck can analyze repositories and pull requests. For repositories, | ||
it answers questions like: | ||
- You'd like to use an open source software package, but you want to assess it. | ||
- Run `hc check -t npm express`. | ||
- If Hipcheck says "investigate," use Hipcheck's output to guide you. | ||
|
||
* Does this project practice code review? | ||
* When was this project last updated? | ||
* Are there concerning contributors to this project? | ||
* Are there potential malicious contributions to review? | ||
* Are there potential typosquatting attacks present? | ||
* Where are the highest risk parts of the codebase? | ||
## Values | ||
|
||
For pull requests, it answers questions like: | ||
Hipcheck's product values are to be: | ||
|
||
* What parts of the code are in the greatest need of review? | ||
* Is this pull request especially concerning? | ||
* Is this contributor new to this part of the code? | ||
* __Configurable:__ Hipcheck should be adaptable to the policies of its users. | ||
* __Fast:__ Hipcheck should provide answers quickly. | ||
* __Actionable:__ Hipcheck should empower users to make informed security decisions. | ||
|
||
With analyses like these (and more), Hipcheck provides automation-assisted | ||
risk management for software projects. | ||
|
||
## Goals | ||
|
||
Hipcheck's core goals are to be: | ||
|
||
* __Effective__: A risk tool is only helpful if it identifies risks. Hipcheck's | ||
analyses look at project practices, potential supply chain attacks, who is | ||
contributing, and how projects change over time to produce high quality, | ||
actionable conclusions and to guide manual review. | ||
* __Fast__: Software development moves quickly, and Hipcheck runs quickly too. | ||
Whether it's running in CI looking for high-risk PRs, reporting on | ||
high risk parts of a codebase, or running against your dependencies, | ||
you won't wait long for a risk report. | ||
* __Configurable__: Different projects have different threat models and risk | ||
tolerances, and Hipcheck handles them gracefully. Analyses, weights, and | ||
risk thresholds are all configurable. | ||
Read more about Hipcheck's product and project values in [RFD #2][rfd_2]. | ||
|
||
## Installation | ||
|
||
### As a Container | ||
|
||
You can build Hipcheck locally with `docker`, using the | ||
Hipcheck `Containerfile`. | ||
|
||
```sh | ||
$ # Run the following from the root of the Hipcheck repository. | ||
$ docker build -t hipcheck:3.2.1 -f ./Containerfile | ||
``` | ||
|
||
### Local Install | ||
|
||
First, install the Rust compiler. We recommend following the official | ||
[installation instructions][install_rust]. Make sure to add | ||
`${CARGO_HOME}/bin` to your `PATH`. | ||
|
||
You will also need Node installed. We recommend following the official | ||
[installation_instructions][install_node]. | ||
|
||
You may install Hipcheck either using an [automated script](#script-based-installation) | ||
or [manually](#build-from-source). | ||
|
||
#### Script-based Installation | ||
|
||
You can install the latest release of Hipcheck by downloading and running the | ||
`install.sh` script from the repository root. | ||
|
||
```sh | ||
$ curl https://raw.githubusercontent.com/mitre/hipcheck/main/install.sh | bash | ||
``` | ||
|
||
This will ask you to export pre-defined values for the `HC_CONFIG` and `HC_DATA` | ||
environment variables on which Hipcheck relies. | ||
|
||
#### Build from Source | ||
|
||
Get the Hipcheck repository. Then navigate into the root directory of | ||
the repository and run `cargo install --path hipcheck`. | ||
|
||
```sh | ||
$ git clone https://github.com/mitre/hipcheck | ||
$ cd hipcheck | ||
$ cargo install --path hipcheck | ||
``` | ||
__If installing locally:__ run the install script from the [latest release][latest_release], | ||
then run __`hc setup`__. | ||
|
||
## Usage | ||
__If running as a container:__ use a [Hipcheck image from | ||
Docker Hub][docker]. | ||
|
||
### Container Image | ||
|
||
You can run Hipcheck in a container like so: | ||
|
||
```sh | ||
$ docker run --env "HC_GITHUB_TOKEN=<GITHUB_TOKEN>" hipcheck:3.2.1 [<HIPCHECK_ARGS>]... | ||
``` | ||
|
||
### Direct Usage | ||
|
||
To run Hipcheck, make sure you export `HC_GITHUB_TOKEN` with a valid token for | ||
connecting to the GitHub API. | ||
|
||
If you installed from `install.sh` and set the appropriate environment | ||
variables as directed, you can run Hipcheck with the `hc` binary without any | ||
further configuration. | ||
|
||
```sh | ||
$ hc check repo https://github.com/expressjs/express | ||
``` | ||
|
||
If you installed from source, you will need to configure values for `--config`, | ||
`--data` and `--home`. From the CLI section of the Hipcheck book: | ||
|
||
* -c, --config `<FILE>` | ||
* Specifies the path to the configuration file. | ||
* This value can instead be set persistently with the `HC_CONFIG` environment variable. | ||
* **Hipcheck will not run `hc check` if it cannot find the configuration file.** | ||
* The config file is called Hipcheck.toml. | ||
* On a default Hipcheck installation, this file should be in `hipcheck/config/`. | ||
* If no filepath is specified, Hipcheck defaults to looking in the current active directory. | ||
|
||
* -d, --data `<FOLDER>` | ||
* Specifies the path to the folder containing essential Hipcheck data files. | ||
* This value can instead be set persistently with the `HC_DATA` environment variable. | ||
* **Certain Hipcheck analyses will generate an error if they cannot find necessary files in this folder.** | ||
* The custom Hipcheck `module-deps.js` file needs to be in this folder. | ||
* A default Hipcheck installation currently does not create this folder and the files in it. | ||
* If no filepath is specified, Hipcheck defaults to looking in the default platform data directory. | ||
|
||
* -H, --home `<FOLDER>` | ||
* Specifies the path to the hipcheck home/root where repos are cached. | ||
* If no filepath is specified, Hipcheck will look in the `HC_HOME` system environment variable first and then the system cache directory second. | ||
* `hc --print-home` shows the directory Hipcheck is currently using as its home. | ||
* If a Git repo cloning is interrupted or Hipcheck is using too much disk space, clear appropriate subdirectories in the home directory. | ||
|
||
### Run Configuring | ||
|
||
Hipcheck requires a set of configuration files, which you can find default | ||
versions of in this repository, under the `config/` directory. The path to | ||
this configuration file must be specified if it is not in the current | ||
active directory. | ||
|
||
## Learn More | ||
|
||
Hipcheck is documented in the Hipcheck book, found under the `/docs/book` directory | ||
in this repository. Follow the instructions in the README there to build and | ||
view the contents of the book. | ||
For alternative installation options, check out the [installation documentation][install_docs]. | ||
|
||
## License | ||
|
||
Hipcheck's software is licensed under the Apache 2.0 license (SPDX license | ||
identifier `Apache-2.0`), the full text of which may be found in the `LICENSE.md` | ||
file included with this repository. | ||
Hipcheck's software is licensed under the Apache 2.0 license, which can be found in | ||
the [`LICENSE`](LICENSE) file in this repository. | ||
|
||
## Public Release | ||
|
||
Approved for Public Release; Distribution Unlimited. Public Release Case Number 22-2145. | ||
|
||
Portions of this software were produced for the U. S. Government under Contract No. | ||
FA8702-19-C-0001 and W56KGU-18-D-0004, and is subject to the Rights in Noncommercial | ||
Computer Software and Noncommercial Computer Software Documentation Clause DFARS | ||
252.227-7014 (FEB 2014). | ||
> [!NOTE] | ||
> Approved for Public Release; Distribution Unlimited. Public Release Case Number 22-2145. | ||
> | ||
> Portions of this software were produced for the U.S. Government under Contract No. | ||
> FA8702-19-C-0001 and W56KGU-18-D-0004, and is subject to the [Rights in Noncommercial | ||
> Computer Software and Noncommercial Computer Software Documentation Clause DFARS | ||
> 252.227-7014 (FEB 2014)][dfars]. | ||
[react]: https://github.com/facebook/react | ||
[install_rust]: https://www.rust-lang.org/tools/install | ||
[install_node]: https://nodejs.org/en/learn/getting-started/how-to-install-nodejs | ||
|
||
[rfd_2]: https://github.com/mitre/hipcheck/blob/main/docs/rfds/0002-hipchecks-values.md | ||
[latest_release]: https://github.com/mitre/hipcheck/releases/latest | ||
[docker]: https://hub.docker.com/r/mitre/hipcheck | ||
[install_docs]: # | ||
[dfars]: https://www.acquisition.gov/dfars/252.227-7014-rights-other-commercial-computer-software-and-other-commercial-computer-software-documentation. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.