https://github.com/ossf/disclosure-check
disclosure-check
https://github.com/ossf/disclosure-check
Last synced: 9 months ago
JSON representation
disclosure-check
- Host: GitHub
- URL: https://github.com/ossf/disclosure-check
- Owner: ossf
- License: apache-2.0
- Created: 2023-05-31T16:12:01.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-24T18:55:48.000Z (about 2 years ago)
- Last Synced: 2024-11-06T15:14:23.421Z (over 1 year ago)
- Language: Python
- Size: 251 KB
- Stars: 3
- Watchers: 15
- Forks: 0
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://github.com/ossf/disclosure-check/actions/workflows/scorecards.yml)
# Disclosure Check
Disclosure Check is a tool for identifying vulnerability disclosure mechanisms for open source projects.
> **Warning**
> This project is still in development and may not work correctly for many different projects. If you encounter a bug,
> please open an issue and we'll try our best to address it. Pull requests welcome!
## Why the tool is needed
Most open source projects use a public issuer tracker for inbound requests, bug reports, etc. Since this is inappropriate
for reporting new vulnerabilities, many projects have other mechanisms for users to submit sensitive reports.
Unfortunately, there is no widely-used, machine-readable way to discover this for a given project. Instead, a human might
need to look for a SECURITY.md file (and read through it), review a README.md, check to see if a private vulnerability
reporting mechanism is available through the source repository, check to see if an e-mail address is associated with the
published package, etc.
This is time consuming for one project, and far more so when done at scale.
The purpose of Disclosure Check is to automate what a human would do when trying to discover the best way to report
a vulnerability to a project. It's use is orthogonal to the goal of more standardized reporting mechanisms; if and when
the later becomes a reality, this tool will no longer be useful.
## Installation
### Requirements
Disclosure Check is available through PyPI and Docker Hub. If you install through PyPI, you'll also need to install
[OSS Gadget](https://github.com/Microsoft/OSSGadget), which is needed to download the package contents for analysis.
Ensure that oss-download is in your path.
You'll also need a GitHub token to allow Disclosure Check to use the GitHub API for things like code search. The
token does not require any special permissions, and the tool will run without it, albeit with degraded functionality.
### PyPI
#### Installing OSS Gadget
Refer to the [OSS Gadget](https://github.com/Microsoft/OSSGadget) page for up to date installation instructions.
You can then install Disclosure Check from PyPI:
```
pip install disclosurecheck
```
You should always install packages like this in a virtual environment since installation will include other dependencies.
### Docker
You can pull the latest Docker image from the GitHub Container Registry:
```
docker pull ghcr.io/scovetta/disclosurecheck:latest
```
## Usage
To run Disclosure Check:
```
disclosurecheck --help
usage: OpenSSF Vulnerability Disclosure Mechanism Detector [-h] [--verbose] [--json] package_url
positional arguments:
package_url Package URL for the project/package you want to analyze.
options:
-h, --help show this help message and exit
--verbose Show extra logging.
--json Output as JSON.
```
Or if you're using the Docker image:
```
docker run -e GITHUB_TOKEN= --rm -t ghcr.io/scovetta/disclosurecheck:latest pkg:npm/left-pad
```
## How it Works
Disclosure Check works by looking for contact information (email, URLs, etc.) in the following places:
- [x] Project metadata (using [libraries.io](https://libraries.io))
- [x] Package contents (certain files like SECURITY.md, README.md, etc.)
- [x] GitHub repository (via code search in certain files like SECURITY.md, including org-level ".github" repositories)
- [x] GitHub Private Vulnerability Reporting
- [x] Coverage by [Tidelift]([https://tidelift.com](https://tidelift.com/docs/security))
- [x] The [Internet Bug Bounty](https://www.hackerone.com/internet-bug-bounty)
- [x] [Security Insights](https://github.com/ossf/security-insights-spec)
- [x] Generic reporting mechanisms like [Snyk](https://snyk.io/vulnerability-disclosure/), [CERT](https://www.kb.cert.org/vuls/report/), and [Github Security Lab](https://securitylab.github.com/).
- [x] Project-specific overrides for cases where we know the right reporting mechanism, but the information isn't visible to anything the tool could find.
The tool attempts to score these based on the priority (with 0 being the highest priority and 100 being the lowest).