PackageGuard

Documentation

Visit the official documentation website for the full guide to installing, configuring and running PackageGuard.

• Installation - install the global tool or the portable deployment
• Getting started with init - scaffold a configuration from the licenses you actually use
• Configuration - define your allow- and deny-lists
• Usage - run a scan and read the results
• Explaining a package - see why a specific package is present and how it was evaluated
• Risk Metrics - score packages on legal, security and operational risk
• Software Bill of Materials - emit the dependency graph as CycloneDX or SPDX
• Caching and Rate Limits - make repeated scans fast and avoid GitHub throttling
• Roadmap - what's planned next

About

What's this?

PackageGuard is a fully open-source CLI tool that keeps your open-source supply chain honest. It scans the NuGet, npm, pnpm and Yarn dependencies of your codebase, enforces allow- and deny-lists for licenses, packages and versions, scores every package's legal/security/operational risk, and can emit a standards-compliant SBOM — all from a single, cacheable command that fits into any CI pipeline.

At a glance, PackageGuard can:

• Scan NuGet, npm, pnpm and Yarn dependencies across an entire solution or codebase in one run, direct and transitive alike
• Scaffold a starting configuration (packageguard init) from the licenses actually found in your repository, flagging copyleft licenses and suggesting a policy that fits whether your software is proprietary, SaaS, or open source
• Enforce allow- and deny-lists for open-source licenses, specific packages, and package versions, discovered hierarchically across solution-, project- and repository-level configuration files
• Resolve licenses from NuGet/npm metadata, GitHub repositories, and downloaded license text through a chain of fetchers, falling back gracefully when a source doesn't have an answer
• Explain a single package on demand (packageguard explain <package>, with fuzzy name matching) - its dependency path, how its version was resolved, the exact policy rule and configuration file that allowed or denied it, and its risk breakdown
• Score every package's risk across three dimensions - Legal, Security and Operational - via --report-risk, weighing signals such as license compatibility, known vulnerabilities (OSV), maintainer activity, package signing, release cadence, and dozens more
• Gate policies on that risk data, not just package identity: deny packages by overall or per-dimension risk score, OSV severity, unsigned/deprecated/repository-less status, or minimum package age per ecosystem, with documented, expiring exceptions for accepted-risk packages and a warn-only mode (--treat-deny-as-warning) for phasing in new rules
• Back every risk score with evidence, not just a number: each package card in the HTML report has a dedicated Evidence section with collapsible, collapsed-by-default panels naming the exact packages, versions, GHSA/OSV vulnerability ids and release dates behind its rationale, so you can see why a package scored the way it did without digging through logs
• Produce a colored console summary, a self-contained HTML report you can open in a browser, and a SARIF file for surfacing violations and risk findings directly in GitHub code scanning
• Generate a standards-compliant Software Bill of Materials (SBOM) in CycloneDX or SPDX JSON format via --sbom, complete with purls, declared-vs-concluded license evidence, and a direct/transitive dependency graph
• Enrich that SBOM with vulnerability data from OSV when --sbom is combined with --report-risk
• Cache package, license and risk data (--use-caching) - including GitHub responses and per-repository risk profiles - to keep repeated scans and CI runs fast, with configurable cache freshness (--risk-cache-max-age-hours, --refresh-risk-cache)
• Run as a .NET global tool or a portable, cross-platform (Windows/Linux/macOS) deployment - no CI-specific plugin required

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

Versioning

This library uses Semantic Versioning to give meaning to the version numbers. For the versions available, see the tags on this repository.

Credits

This library wouldn't have been possible without the following tools, packages and companies:

• Spectre.Console - a .NET library that makes it easier to create beautiful console applications.
• Fallout - .NET build automation, the hard-fork successor to Nuke by Matthias Koch
• CliWrap - Library for running command-line processes by Oleksii Holub
• Coverlet - Cross platform code coverage for .NET by Toni Solarin-Sodara
• GitVersion - From git log to SemVer in no time
• ReportGenerator - Converts coverage reports by Daniel Palme
• StyleCopyAnalyzer - StyleCop rules for .NET
• Roslynator - A set of code analysis tools for C# by Josef Pihrt
• Serilog - Flexible, structured events — log file convenience
• CSharpCodingGuidelines - Roslyn analyzers by Bart Koelman to go with the C# Coding Guidelines
• Meziantou - Another set of awesome Roslyn analyzers by Gérald Barré
• FluentAssertions - Extension methods to fluently assert the outcome of .NET tests
• Verify - Snapshot testing by Simon Cropp
• Pathy - Fluently building and using file and directory paths without binary dependencies
• MemoryPack - Zero encoding extreme performance binary serializer for C# and Unity by Yoshifumi Kawai