README.md 3.12 KB
Newer Older
Dennis Appelt's avatar
Dennis Appelt committed
1
# Package Hunter CLI
Dennis Appelt's avatar
Dennis Appelt committed
2

Dennis Appelt's avatar
Dennis Appelt committed
3
4
Behavorial monitoring for identifying malicious dependencies.

Josiah Ritchie's avatar
Josiah Ritchie committed
5
This is the Package Hunter CLI client. It is useful for running Package Hunter jobs in CI pipelines and from your local computer. Requires a running [Package Hunter server](https://gitlab.com/gitlab-org/security-products/package-hunter).
Dennis Appelt's avatar
Dennis Appelt committed
6
7
8
9
10

# Getting Started

## GitLab CI

11
12
13
14
15
16
Instructions to add a Package Hunter job to your CI pipeline:
- Set up a Package Hunter server as described in the docs [docs](https://gitlab.com/gitlab-org/security-products/package-hunter/-/blob/master/README.md#installation).
- Set the CI variables `PACKAGE_HUNTER_USER` and `PACKAGE_HUNTER_PASS` in your GitLab [project settings](https://docs.gitlab.com/ee/ci/variables/) according to your server configuration.
- Include the Package Hunter template in your CI config file `.gitlab-ci.yml`:
```yaml
include: "https://gitlab.com/gitlab-org/security-products/package-hunter-cli/-/raw/main/ci/template/Package-Hunter.gitlab-ci.yml"
Dennis Appelt's avatar
Dennis Appelt committed
17
18
19

.package_hunter-base:
  variables:
20
    PACKAGE_HUNTER_HOST: "https://package-hunter-server.example"
Dennis Appelt's avatar
Dennis Appelt committed
21
22
23
```

## Locally
Dennis Appelt's avatar
Dennis Appelt committed
24
25
26
27
28
29
30

### Docker (recommended)

Requirements:
- Docker

```sh
Dennis Appelt's avatar
Dennis Appelt committed
31
docker run --rm registry.gitlab.com/gitlab-org/security-products/package-hunter-cli analyze --help
Dennis Appelt's avatar
Dennis Appelt committed
32
33
34
```

### From Source
Dennis Appelt's avatar
Dennis Appelt committed
35
36
37
38
39

Requirements:
- Node.js v12.16 or newer

```sh
Dennis Appelt's avatar
Dennis Appelt committed
40
git clone https://gitlab.com/gitlab-org/security-products/package-hunter-cli.git
Dennis Appelt's avatar
Dennis Appelt committed
41
42
cd package-hunter-cli
npm install
Dennis Appelt's avatar
Dennis Appelt committed
43
DEBUG=pkgs* node cli.js analyze --help
Dennis Appelt's avatar
Dennis Appelt committed
44
45
46
47
```

## Usage

Dennis Appelt's avatar
Dennis Appelt committed
48
To analyze a project, create an archive with the project sources and pass it to the CLI client:
Dennis Appelt's avatar
Dennis Appelt committed
49
50

```sh
Dennis Appelt's avatar
Dennis Appelt committed
51
52
tar czvf gitlab.tgz ~/git/gitlab

Dennis Appelt's avatar
Dennis Appelt committed
53
54
55
56
57
# using Docker
docker run --rm \
  -v "${PWD}:/usr/src/app" \
  --env "DEBUG=pkgs*" \
  --env "HTR_user=someuser" --env "HTR_pass=somepass" \
Dennis Appelt's avatar
Dennis Appelt committed
58
  registry.gitlab.com/gitlab-org/security-products/package-hunter-cli analyze gitlab.tgz
Dennis Appelt's avatar
Dennis Appelt committed
59

Dennis Appelt's avatar
Dennis Appelt committed
60
61
# using Source
DEBUG=pkgs* "HTR_user=someuser" "HTR_pass=somepass" node cli.js analyze gitlab.tgz
Dennis Appelt's avatar
Dennis Appelt committed
62
```
Dennis Appelt's avatar
Dennis Appelt committed
63
64
65
66

The archive will be send to the Package Hunter server and any suspicious behavior will be reported back. To get an overview of the rules that were violated, you can use jq like so `... analyze gitlab.tgz | jq .result[].rule`.

The Package Hunter server requires authentication. User and password have to be provided to the client via the env var `HTR_user` and `HTR_pass` ([credentials](https://start.1password.com/open/i?a=LKATQYUATRBRDHRRABEBH4RJ5Y&v=6gq44ckmq23vqk5poqunurdgay&i=rvy4v2kvdjcpnoiihlm3vlda34&h=gitlab.1password.com) are in 1Password)
Dennis Appelt's avatar
Dennis Appelt committed
67
68
69

## Publishing

70
This project uses semantic versioning. Commits are automatically tagged [based on the commit message](https://gitlab.com/gitlab-org/security-products/package-hunter/-/blob/2f113a6976b9e8c941a30908095eba2e3bf8b6b4/CONTRIBUTING.md#git-commit-guidelines).
Dennis Appelt's avatar
Dennis Appelt committed
71

Dennis Appelt's avatar
Dennis Appelt committed
72
A CI job will build the docker image and publish it to the container registry. Execute the release with:
Dennis Appelt's avatar
Dennis Appelt committed
73
74

```sh
75
# to run release 1.2.3
Dennis Appelt's avatar
Dennis Appelt committed
76
docker run registry.gitlab.com/gitlab-org/security-products/package-hunter-cli:1.2.3
Dennis Appelt's avatar
Dennis Appelt committed
77
78
79

# or to run the latest release

Dennis Appelt's avatar
Dennis Appelt committed
80
docker run registry.gitlab.com/gitlab-org/security-products/package-hunter-cli:latest
Dennis Appelt's avatar
Dennis Appelt committed
81
```
82
83
84
85

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).