OSS Gadget

Note: OSS Gadget is currently in public preview and is not ready for production use.

OSS Gadget is a collection of tools that can help analyze open source projects. These are intended to make it simple to perform low-level tasks, like locating the source code of a given package, downloading it, performing basic analyses on it, or estimating its health. The tools included in OSS Gadget will grow over time.

Included Tools

A list of tools included is below. Click on the name of a tool to go to the wiki for usage information.

• oss-characteristic: Identify a package's notable characteristics and features. Uses Application Inspector.
• oss-defog: Searches a package for obfuscated strings (Base-64).
• oss-detect-backdoor: Identifies potential backdoors and malicious code within a package. Currently has a high false-positive rate.
• oss-detect-cryptography: Identifies cryptographic implementations within a package.
• oss-diff: Compares two packages using a standard diff/patch view.
• oss-download: Downloads a package and extracts it locally.
• oss-find-domain-squats: Identifies potential typo-squatting for a given domain name.
• oss-find-source: Attempts to locate the source code (on GitHub, currently) of a given package.
• oss-find-squats: Identifies potential typo-squatting for a given package.
• oss-health: Calculates health metrics for a given package.
• oss-metadata: Retrieves metadata from deps.dev or libraries.io for a given package.
• oss-risk-calculator: Calculates a metric for risk of using a package.
• oss-reproducible: Evaluates a package for semantic equivalency with the detected source code to produce an estimate of how well the two comport.

All OSS Gadget tools accept one or more Package URLs as a way to uniquely identify a package. Package URLs look like pkg:npm/express or pkg:gem/azure@0.7.10. If you leave the version number off, it implicitly means, "attempt to find the latest version". Using an asterisk (pkg:npm/express@*) means "perform the action on all available versions".

Package Sources

OSS Gadget supports packages provided by these sources:

• Cargo - pkg:cargo/...
• Cocoapods - pkg:cocoapods/...
• Composer - pkg:composer/...
• CPAN - pkg:cpan/...
• CRAN - pkg:cran/...
• GitHub - pkg:github/...
• Go - pkg:golang/...
• Hackage - pkg:hackage/...
• Maven - pkg:maven/...
• NPM - pkg:npm/...
• NuGet - pkg:nuget/...
• RubyGems - pkg:gem/...
• PyPI - pkg:pypi/...
• Ubuntu - pkg:ubuntu/...
• Visual Studio Marketplace - pkg:vsm/...
• Generic - pkg:url/...?url=URL

We will continue expanding this list to cover additional package management systems and would be happy to accept contributions from the community.

Basic Usage

All OSS Gadget tools are command line programs. When installed globally, they can be accessed from your path. For example, to download the NPM left-pad module, type:

$ oss-download pkg:npm/left-pad

This will download left-pad into a newly-created directory named npm-left-pad@1.3.0. (Because, at the time of this writing, 1.3.0 was the latest version of left-pad).

Each of the programs self-documents information on command line options (--help).

Building from Source

OSS Gadget builds with standard dotnet build commands and includes tests via dotnet test.

See Building from Source in the wiki for information on building from source.

Docker Image

See Docker Image in the wiki for information on how to use the included Dockerfile.

Advanced Usage

See Advanced Usage in the wiki for advanced usage information like changing API endpoints.

Reporting Security Vulnerabilities

To report a security vulnerability, please see SECURITY.md.

Contributing to OSS Gadget

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.