Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
177 lines (137 loc) · 6.41 KB

CONTRIBUTING.md

File metadata and controls

177 lines (137 loc) · 6.41 KB

How to contribute

We'd love to accept your patches and contributions to this project.

Before you begin

Review our community guidelines

This project follows OpenSSF's Contributor Code of Conduct.

Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Setup

Required steps:

  1. Create a GitHub account.
  2. Install git for source control.
  3. Clone the repository, e.g:
git clone git@github.com:ossf/malicious-packages.git
cd malicious-packages

Contributing changes will require forking the repository and pushing your changes to the fork.

Optional:

  • Install Go for code development.
  • Install make for running development commands.

Contributing OSV Reports

We accept new reports of malicious packages that are within scope, and updates to any existing report in the database.

Note: This process is still evolving. We welcome suggestions on how the process can be improved.

The ideal report

Please familiarize yourself with the OSV Schema.

An ideal malicious report being added has the following properties:

  • affected must have a single entry, for a single package. affected[0].ranges or affacted[0].versions is populated for the specific malicious versions.
  • details provides useful information about the malicious package, such as:
    • why is it considered malicious?
    • what does it do? (info stealer, remote shell, crypto miner, dropper, etc)
    • how is the payload triggered? (on install, on import, function call, etc)
    • what campaign does it belong to?
  • credits or references has at least one entry indicating where the report came from.
  • database_specific.iocs contains any meaningful indicators of compromise. See the schema additions for more details on adding IoCs.
  • id and summary are not present.

Via Pull Request

New Individual Report

  1. If needed, create the directory under ./osv/malicious/ for the report to live in.
    • Directories are formatted [ecosystem]/[package_name], with no escaping of slashes. (e.g. ./malicious/go/github.com/ossf/package-analysis/ or ./malicious/npm/@example/package/).
    • If you're unsure, once the PR is created this will be checked by a GitHub action.
  2. Create the JSON file with the name MAL-0000-[name].json. Where [name] can be replaced with any arbitrary text.
  3. Populate the JSON file conforming to the OSV Schema format and the notes below.
  4. Commit and push the change to a fork.
  5. Ensure validation actions run successfully.
  6. Create a PR.

Bulk Import

  1. Create an issue if this is the first bulk import. The issue should include the following:

    • A proposed unique "source id" if you do not already have one.
    • Some details on the reports (i.e. quantity, ecosystems), etc.

  2. Use the ingest command to copy the reports from a local folder to the appropriate locations, and to ensure the origin data is correctly populated.

    • Ensure your OSV reports are in a local directory.
    • From the repo run (requires Go):
    go run ./cmd/ingest \
   -config config/config.yaml \
   -dir /path/to/osv \
   -source [source id]
    • Fix any problems reported. You will need to revert the repo before running ingest again.

  3. Commit and push the changes to a form and submit a Pull Request.

    • Reference the issue from step #1 in the PR, and any future bulk import PR, even once the issue is closed.
    • Please fix any validation errors, although the ingest command should avoid these.

Via Automated Ingestion

Requirements

  • OSV Reports are available in cloud storage.
    • Currently only AWS S3 and Google Cloud Storage are supported.
    • It must be possible to grant access to the data.
  • New reports are frequently added. If not, consider a bulk import PR.
  • Reports have a low false positive rate.
  • OSV reports:
  • A valid email contact for communication.

Process

  1. Create an issue, which should include the following:
    • A proposed unique "source id" if you do not already have one.
    • Some information about the organization/group producticing the reports.
    • Some details on the reports (i.e. quantity, ecosystems), etc and the frequency of updates.
  2. Access to the storage will need to be granted to a service/worker account (TBC).
  3. The source is added to config.yaml.
  4. The ingest command will be executed regularly to ingest new OSV reports (TBC).

OSV Schema Notes

  • id - assigned automatically, do not set.
  • summary - overridden with a standard summary.
  • details - aggregated together during merge, with one entry per source (longest). Only a single user contributed detail is allowed before the source based details.
  • affected - must have one entry, and only one.
  • affected[0].package.ecosystem and affected[0].package.name - required.
  • affected[0].ranges - appended, no effort is made to consolidate SEMVER ranges.
  • database_specific and affected[0].database_specific objects:
    • scalar values are stripped
    • during merge, duplicate keys with object values will be merged
    • during merge, duplicate keys with array values will be appended together
  • affected[0].ecosystem_specific and *.severity data is dropped.
  • credits are merged, with entries deduplicated based on the credit name and type.
  • Other fields are merged by append lists together and removing duplicates.

Contributing Code

Code contributions are welcome!

For larger features or changes, please create an issue first.

When creating a Pull Request, please ensure:

  • there are unit tests, and they are passing (run: make test)
  • all lint errors have been fixed