Skip to content

Commit 2aafca3

Browse files
aegilopsaegilops
committed
Add and update documentation
1 parent 125965c commit 2aafca3

File tree

7 files changed

+237
-47
lines changed

7 files changed

+237
-47
lines changed

‎CODEOWNERS‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# For more information, see [docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#codeowners-syntax)
2+
3+
## This repository is maintained by
4+
5+
* @aegilops

‎CODE_OF_CONDUCT.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of experience,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at [email protected]. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at [http://contributor-covenant.org/version/1/4][version]
72+
73+
[homepage]: http://contributor-covenant.org
74+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Contributing
2+
3+
Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
4+
5+
Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE).
6+
7+
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
8+
9+
## Submitting a pull request
10+
11+
1. Fork and clone the repository
12+
1. Configure and install the dependencies: `pip3 install -r requirements.txt`
13+
1. Create a new branch: `git checkout -b my-branch-name`
14+
1. Push to your fork and submit a pull request
15+
1. Pat your self on the back and wait for your pull request to be reviewed! :tada:
16+
17+
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
18+
19+
- Follow the [style guide](https://black.readthedocs.io/en/stable/) - it'll automatically run via the [super-linter](https://github.com/github/super-linter).
20+
- Write tests.
21+
- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
22+
- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
23+
24+
## Resources
25+
26+
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
27+
- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
28+
- [GitHub Help](https://help.github.com)

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright GitHub, Inc.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 65 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@ Enumerate Dependency Graph SBOMs from all repositories in a GitHub Enterprise (a
44

55
Search collected SBOMs by PURL, cache them for offline analysis, sync malware security advisories, and match SBOM packages against those advisories. Supports human-readable and JSON output with file output for JSON.
66

7-
## Features
7+
> [!NOTE]
8+
> This is an _unofficial_ tool created by Field Security Specialists, and is not officially supported by GitHub.
9+
10+
## 🚀 Features
811

912
- Enumerate orgs in an Enterprise and repos in each org
1013
- Fetch SBOM per repo with concurrency + optional delay and retry/throttle handling
@@ -13,21 +16,17 @@ Search collected SBOMs by PURL, cache them for offline analysis, sync malware se
1316
- SBOMs are written incrementally to allow for stopping and resuming
1417
- Sync malware security advisories from the GitHub Advisory Database
1518
- Version-aware matching of SBOM packages vs. malware advisories
19+
- Optional suppression of "unbounded" malware advisories that claim all versions are affected (e.g. vulnerable range '*', '>=0')
1620
- Optional SARIF 2.1.0 output per repository for malware matches with optional Code Scanning upload
1721
- YAML ignore file support to suppress specific advisory IDs or PURLs globally or scoped to an org / repo
18-
- Optional suppression of "unbounded" malware advisories that claim all versions are affected (e.g. vulnerable range '*', '>=0')
1922
- Works with GitHub.com, GitHub Enterprise Server, GitHub Enterprise Managed Users and GitHub Enterprise Cloud with Data Residency (custom base URL)
2023
- Reason tracing: every search match shows which query matched; every malware match shows which advisory triggered it
2124
- Interactive REPL for ad‑hoc PURL queries (history, graceful Ctrl+C handling)
2225
- Optional progress bar while fetching SBOMs
23-
- Option to suppress secondary rate limit warnings, and full quiet mode to suppress informative messages
2426
- Intelligent skip logic: if the repository was pushed to, but the default branch head commit date isn't newer than the prior SBOM retrieval, the existing cached SBOM is reused
27+
- Option to suppress secondary rate limit warnings, and full quiet mode to suppress informative messages
2528
- Adaptive backoff: each secondary rate limit hit increases the SBOM fetch delay by 10% to reduce future throttling
2629

27-
## Auth Requirements
28-
29-
Token needs scopes: `repo`, `read:org`, and `security_events` (for dependency graph SBOM API). For public-only scanning you may omit `repo`.
30-
3130
## Usage
3231

3332
### Quick Start
@@ -53,35 +52,15 @@ Using GitHub Enterprise Server:
5352
npm run start -- --sync-sboms --enterprise ent --base-url https://github.internal/api/v3 --sbom-cache sboms --token $GHES_TOKEN
5453
```
5554

56-
### Argument Reference
55+
### 🔑 Authentication
5756

58-
| Arg | Purpose |
59-
|------|---------|
60-
| `--sbom-cache <dir>` | Directory holding per-repo SBOM JSON files (required for offline mode; used as write target when syncing) |
61-
| `--sync-sboms` | Perform API calls to (re)collect SBOMs; without it the CLI runs offline loading cached SBOMs. Requires a GitHub token |
62-
| `--enterprise <slug>` / `--org <login>` | Scope selection (mutually exclusive when syncing) |
63-
| `--purl <purl>` | Add a PURL/range/wildcard query (repeatable) |
64-
| `--purl-file <file>` | File with one query per line |
65-
| `--json` | Emit search JSON to stdout (unless overridden by `--output-file`) |
66-
| `--cli` | Also emit human-readable output when producing JSON (requires `--output-file`) |
67-
| `--output-file <file>` | Write search JSON payload to file; required when using both `--json` and `--cli` |
68-
| `--interactive` | Enter interactive search prompt after initial processing |
69-
| `--sync-malware` | Fetch & cache malware advisories (MALWARE classification). Requires a GitHub token |
70-
| `--match-malware` | Match current SBOM set against cached advisories |
71-
| `--malware-cache <dir>` | Advisory cache directory (required with malware operations) |
72-
| `--malware-cutoff <ISO-date>` | Ignore advisories whose publishedAt AND updatedAt are both before this date/time (e.g. `2025-09-29` or full timestamp) |
73-
| `--ignore-file <path>` | YAML ignore file (advisories / purls / scoped blocks) to filter malware matches before output |
74-
| `--ignore-unbounded-malware` | Ignore matches whose advisory vulnerable version range covers all versions (e.g. `*`, `>=0`, `0.0.0`) |
75-
| `--sarif-dir <dir>` | Write SARIF 2.1.0 files per repository (with malware matches) |
76-
| `--upload-sarif` | Upload generated SARIF to Code Scanning (requires --match-malware & --sarif-dir and a GitHub token) |
77-
| `--concurrency <n>` | Parallel SBOM fetches (default 5) |
78-
| `--sbom-delay <ms>` | Delay between SBOM fetch (dependency-graph/sbom) requests (default 5000) |
79-
| `--light-delay <ms>` | Delay between lightweight metadata calls (listing repos, commit head checks) (default 500) |
80-
| `--base-url <url>` | GitHub Enterprise Server REST base URL (ends with /api/v3) |
81-
| `--progress` | Show a dynamic progress bar during SBOM collection |
82-
| `--suppress-secondary-rate-limit-logs` | Hide secondary rate limit warning lines (automatically applied with `--progress`) |
83-
| `--quiet` | Suppress all non-error and non-result output (progress bar, JSON and human readable output still show) |
84-
| `--ca-bundle <path>` | Path to a PEM file containing one or more additional CA certificates (self‑signed / internal PKI) |
57+
A GitHub token with appropriate scope is required when performing network operations such as `--sync-sboms`, `--sync-malware` and `--upload-sarif`.
58+
59+
A fine-grained PAT needs scope `Read-only` on `Contents`. To upload SARIF you need `Read and write` on `Code scanning alerts`. If necessary you can use a Classic PAT, or a token from a GitHub App with `repo`, `read:org`, and `security_events` (write) scopes. You may find generating a token with the [`gh` CLI](https://cli.github.com/) is convenient.
60+
61+
It can be provided in the `GITHUB_TOKEN` environment variable, or with the `--token` argument.
62+
63+
Offline operations (pure searches, matches using pre-cached data) need no token.
8564

8665
### Supplying PURL Queries from a File
8766

@@ -311,16 +290,46 @@ npm run start -- --sbom-cache sboms --interactive
311290

312291
Then type one PURL query per line. Entering a blank line or using Ctrl+C on a blank line exits. Ctrl+C on a non-blank line clears the line.
313292

293+
## Argument Reference
294+
295+
| Arg | Purpose |
296+
|------|---------|
297+
| `--sbom-cache <dir>` | Directory holding per-repo SBOM JSON files (required for offline mode; used as write target when syncing) |
298+
| `--sync-sboms` | Perform API calls to (re)collect SBOMs; without it the CLI runs offline loading cached SBOMs. Requires a GitHub token |
299+
| `--enterprise <slug>` / `--org <login>` | Scope selection (mutually exclusive when syncing) |
300+
| `--purl <purl>` | Add a PURL/range/wildcard query (repeatable) |
301+
| `--purl-file <file>` | File with one query per line |
302+
| `--json` | Emit search JSON to stdout (unless overridden by `--output-file`) |
303+
| `--cli` | Also emit human-readable output when producing JSON (requires `--output-file`) |
304+
| `--output-file <file>` | Write search JSON payload to file; required when using both `--json` and `--cli` |
305+
| `--interactive` | Enter interactive search prompt after initial processing |
306+
| `--sync-malware` | Fetch & cache malware advisories (MALWARE classification). Requires a GitHub token |
307+
| `--match-malware` | Match current SBOM set against cached advisories |
308+
| `--malware-cache <dir>` | Advisory cache directory (required with malware operations) |
309+
| `--malware-cutoff <ISO-date>` | Ignore advisories whose publishedAt AND updatedAt are both before this date/time (e.g. `2025-09-29` or full timestamp) |
310+
| `--ignore-file <path>` | YAML ignore file (advisories / purls / scoped blocks) to filter malware matches before output |
311+
| `--ignore-unbounded-malware` | Ignore matches whose advisory vulnerable version range covers all versions (e.g. `*`, `>=0`, `0.0.0`) |
312+
| `--sarif-dir <dir>` | Write SARIF 2.1.0 files per repository (with malware matches) |
313+
| `--upload-sarif` | Upload generated SARIF to Code Scanning (requires --match-malware & --sarif-dir and a GitHub token) |
314+
| `--concurrency <n>` | Parallel SBOM fetches (default 5) |
315+
| `--sbom-delay <ms>` | Delay between SBOM fetch (dependency-graph/sbom) requests (default 5000) |
316+
| `--light-delay <ms>` | Delay between lightweight metadata calls (listing repos, commit head checks) (default 500) |
317+
| `--base-url <url>` | GitHub Enterprise Server REST base URL (ends with /api/v3) |
318+
| `--progress` | Show a dynamic progress bar during SBOM collection |
319+
| `--suppress-secondary-rate-limit-logs` | Hide secondary rate limit warning lines (automatically applied with `--progress`) |
320+
| `--quiet` | Suppress all non-error and non-result output (progress bar, JSON and human readable output still show) |
321+
| `--ca-bundle <path>` | Path to a PEM file containing one or more additional CA certificates (self‑signed / internal PKI) |
322+
314323
## Build & test
315324

316-
## Build
325+
## 🏗️ Build
317326

318327
```bash
319328
npm install
320329
npm run build
321330
```
322331

323-
## Test
332+
## 🧪 Test
324333

325334
The repo ships with a minimal test fixture to validate end-to-end malware matching without making network calls.
326335

@@ -350,24 +359,33 @@ Alternatively, you can exercise the CLI purely offline using the fixtures (no to
350359
npm run start -- --sbom-cache fixtures/sboms --malware-cache fixtures/malware-cache --match-malware
351360
```
352361

353-
## Authentication and Rate Limiting
362+
## 🚦 Rate Limiting
354363

355-
### Rate Limiting & Retries
356-
357-
Standard & secondary rate limits automatically retried (up to 2 times).
364+
Standard & secondary rate limits trigger an automatic retry (up to 2 times).
358365

359366
You can tune concurrency and increase the delay to reduce the chance of hitting rate limits.
360367

361368
Each time a secondary rate limit is hit, the delay between fetching SBOMs is increased by 10%, to provide a way to adaptively respond to that rate limit.
362369

363-
### Authentication
370+
## 🤝 Contributing
364371

365-
A GitHub token with appropriate scope is required when performing network operations such as `--sync-sboms`, `--sync-malware` and `--upload-sarif`.
372+
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.
366373

367-
It can be provided in the `GITHUB_TOKEN` environment variable, or with the `--token` argument.
374+
## 📄 License
368375

369-
Offline operations (pure searches, matches using pre-cached data) need no token.
376+
MIT License - see [LICENSE](LICENSE) file for details
377+
378+
## 🆘 Support
379+
380+
> [!NOTE]
381+
> This is an _unofficial_ tool created by Field Security Specialists, and is not officially supported by GitHub.
382+
383+
See [SUPPORT.md](SUPPORT.md) for support options.
384+
385+
## 📜 Code of Conduct
386+
387+
See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for our Code of Conduct.
370388

371-
## License
389+
## 🛡️ Privacy
372390

373-
MIT License
391+
See [PRIVACY.md](PRIVACY.md) for the privacy notice.

‎SECURITY.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Security
2+
3+
Thanks for helping make GitHub safe for everyone.
4+
5+
GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub).
6+
7+
Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation.
8+
9+
## Reporting Security Issues
10+
11+
If you believe you have found a security vulnerability in any GitHub-owned repository, please report it to us through coordinated disclosure.
12+
13+
**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
14+
15+
Instead, please send an email to opensource-security[@]github.com.
16+
17+
Please include as much of the information listed below as you can to help us better understand and resolve the issue:
18+
19+
* The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
20+
* Full paths of source file(s) related to the manifestation of the issue
21+
* The location of the affected source code (tag/branch/commit or direct URL)
22+
* Any special configuration required to reproduce the issue
23+
* Step-by-step instructions to reproduce the issue
24+
* Proof-of-concept or exploit code (if possible)
25+
* Impact of the issue, including how an attacker might exploit the issue
26+
27+
This information will help us triage your report more quickly.
28+
29+
## Policy
30+
31+
See [GitHub's Safe Harbor Policy](https://docs.github.com/en/github/site-policy/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)

‎SUPPORT.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Support
2+
3+
## How to file issues and get help
4+
5+
This project uses GitHub issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue.
6+
7+
For help or questions about using this project, please search the existing discussions and issues, then open a new discussion. Thanks!
8+
9+
This project is actively developed and is maintained by GitHub staff **AND THE COMMUNITY** on a best-effort basis. We will do our best to respond to support and community questions in a timely manner.
10+
11+
## GitHub Support Policy
12+
13+
Support for this project is limited to the resources listed above.

0 commit comments

Comments
 (0)