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, 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 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=<YOUR 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:

• Project metadata (using libraries.io)
• Package contents (certain files like SECURITY.md, README.md, etc.)
• GitHub repository (via code search in certain files like SECURITY.md, including org-level ".github" repositories)
• GitHub Private Vulnerability Reporting
• Coverage by Tidelift
• The Internet Bug Bounty
• Security Insights
• Generic reporting mechanisms like Snyk, CERT, and Github Security Lab.
• 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).