# Prerequisites

- Github token with repo:read permissions (fine-grained tokens are supposed to work but did not in my experience)
- Python 3.12+ with UV installed

# Helper Script

- There is a helper script, largely copied from jtorp/github_repos but using the PyGithub library, that will download all repositories for an organization. Usage example:

```python
nohup python clone.py --token ghp_1234566789 --org MYORGNAME  --path . --concurrent 50 &
```

# Scanner script

The scanner script expects a CSV containing malicious packages in the form of `@author/package_name,version` or `package_name,version` where version is the semantic package version number, e.g. `@moosamus/malicious-package,1.2.3` or `malicious-lib,1.0.0`. The header row column names should be `Package` and `Version`, respectively.

## Matching Logic

The scanner follows these rules:

- **Scoped malicious packages** (e.g., `@jimmy/eslint-prettier`): Only match **exactly** that scoped package
  - If the CSV contains `@jimmy/eslint-prettier`, it will match `@jimmy/eslint-prettier` in dependencies
  - It will **NOT** match the official unscoped `eslint-prettier` package

- **Unscoped malicious packages** (e.g., `malicious-lib`): Match **all occurrences** (both scoped and unscoped)
  - If the CSV contains `malicious-lib`, it will match:
    - `malicious-lib` (unscoped package)
    - `@any-author/malicious-lib` (scoped packages from any author)
  - The findings CSV will include the full package name with scope/author if one exists

## Usage

Use the `--malicious-csv` argument to provide the file name containing this malicious package list. There are a few other configurable options if needed.

```bash
python scan_malicious_packages.py --malicious-csv malicious-packages.csv --repos-path /path/to/repos --output findings.csv
```