<div align="center"> <img src="./PackageGuard.png" style="width:300px" alt="PackageGuard"/> </div> <h1 align="center">Get a grip on your open-source packages</h4> <div align="center">

GitHub Repo stars

<a href="#about">About</a> • <a href="#download">Download</a> • <a href="#how-do-i-configure-it">How To Configure</a> • <a href="#how-do-i-use-it">How To Use</a> • <a href="#roadmap">Roadmap</a> • <a href="#building">Building</a> • <a href="#contributing">Contributing</a> • <a href="#versioning">Versioning</a> • <a href="#credits">Credits</a> •

</div>

About

What's this?

PackageGuard is a fully open-source tool to scan the NuGet, NPM, PNPM and Yarn dependencies of your codebase against a deny- or allowlist so to control the open-source licenses that you want to allow or certain versions of certain packages you want to enforce or avoid.

What's so special about that?

I've noticed that the commercial solutions for this are usually very expensive and have functionality that smaller companies may not need. Hopefully this little tools fills the gap between tools like GitHub's Dependabot and expensive commercial products like Blackduck, SNYK and others.

Who created this?

My name is Dennis Doomen and I'm a Microsoft MVP and Principal Consultant at Aviva Solutions with 28 years of experience under my belt. As a software architect and/or lead developer, I specialize in designing full-stack enterprise solutions based on .NET as well as providing coaching on all aspects of designing, building, deploying and maintaining software systems. I'm the author of several open-source projects such as Fluent Assertions, Reflectify, Liquid Projections, and I've been maintaining coding guidelines for C# since 2001.

Contact me through Email, Bluesky, Twitter/X or Mastadon

Download

The tool is available in two forms:

As a .NET Global Tool (recommended)

Install as a NuGet Tool package:

dotnet tool install PackageGuard --global

Then use packageguard --help to see a list of options.

As a portable deployment

Download the latest PackageGuard-{version}.zip from the releases page, extract it, and run it using dotnet PackageGuard.dll. This requires .NET 9.0 or later to be installed but works on Windows, Linux, and macOS.

USAGE:
    PackageGuard [path] [OPTIONS]            # When installed as a global tool
    dotnet PackageGuard.dll [path] [OPTIONS] # When using the portable deployment

ARGUMENTS:
    [path]    The path to a directory containing a .sln/.slnx file and/or a package.json, a specific .sln/.slnx file, a
              specific .csproj file, or a specific package.json. Defaults to the current working directory

OPTIONS:
                                 DEFAULT
    -h, --help                              Prints help information
    -c, --config-path                       The path to the configuration file. Defaults to hierarchical discovery of
                                            packageguard.config.json or .packageguard/config.json files starting from
                                            the solution directory
    -i, --restore-interactive    True       Allow enabling or disabling an interactive mode of "dotnet restore".
                                            Defaults to true
        --ignore-violations                 Don't fail the analysis if any violations are found. Defaults to false
    -f, --force-restore                     Force restoring the NuGet dependencies, even if the lockfile is up-to-date
    -s, --skip-restore                      Prevent the restore operation from running, even if the lock file is missing
                                            or out-of-date
    -a, --github-api-key                    GitHub API key to use for fetching package licenses. If not specified, you
                                             may run into GitHub's rate limiting issues
    --use-caching                       Maintains a cache of the package information to speed up future analysis
    --cache-file-path        False      Overrides the file path where analysis data is cached. Defaults to the
                                             "<workingdirectory>/.packageguard/cache.bin"
        --refresh-risk-cache                Force `--report-risk` to rebuild cached risk-related package data
        --risk-cache-max-age-hours 24       Maximum age in hours for cached risk-related package data before
                                             `--report-risk` refreshes it
        --nuget                  True       Explicitly enable or disable scanning for .csproj, .sln or .slnx files
        --npm                               Explicitly specify the package manager to use (npm, yarn, pnpm). If not
                                             specified, it will detect it automatically
        --npm-exe-path                      The path to the npm, yarn or pnpm executable. If not specified, the system
                                             PATH is used

How do I configure it?

PackageGuard supports hierarchical configuration files that are automatically discovered based on your .NET solution and project structure. This allows you to define repository-wide policies at the solution level and add project-specific rules as needed. Since PackageGuard will scan a single package.json per run, it will use the configuration that is associated with that directy.

Hierarchical Configuration Discovery

PackageGuard will automatically look for configuration files in the following order:

Solution level: packageguard.config.json in the same folder as your .sln, .slnx or package.json file
Solution level: config.json in a .packageguard subdirectory of your solution or package.json folder
Project level: packageguard.config.json in individual project directories
Project level: config.json in a .packageguard subdirectory of project directories

Settings from multiple configuration files are merged together, with project-level settings taking precedence over solution-level settings for boolean values, while arrays (packages, licenses, feeds) are combined.

Manual Configuration Path

You can still specify a custom configuration file path using the --configpath CLI parameter to override the hierarchical discovery:

packageguard --configpath path/to/my-config.json

About the package cache

When --use-caching is enabled, PackageGuard stores package metadata in .packageguard/cache.bin. For --report-risk, that cache now also keeps the expensive risk-related package data that comes from external services and package inspection.

By default, cached risk-related package data is reused for up to 24 hours. After that, a --report-risk run will refresh the package entry from upstream sources before rebuilding the report.

If you want to force a fully fresh risk report while still using the cache file for subsequent runs, use:

packageguard . --report-risk --use-caching --refresh-risk-cache

You can also tune the time-to-live for cached risk-related package data:

packageguard . --report-risk --use-caching --risk-cache-max-age-hours 6

Configuration Format

Each configuration file should follow this JSON format:

{
    "settings": {
        "allow": {
          "prerelease": false,
          "licenses": [
              "Apache-2.0", // Uses SPDX naming
              "MIT",
          ],
          "packages": [
              "MyPackage/[7.0.0,8.0.0)"
          ],
          "feeds": [
            "*dev.azure.com*"
          ]
        },
        "deny": {
          "licenses": [],
          "packages": [
            "ProhibitedPackage"
          ]

Packageguard

Install / Use

README