https://github.com/tonycknight/pkgchk-cli
A dotnet tool for package dependency checks.
https://github.com/tonycknight/pkgchk-cli
ci dotnet nuget sca
Last synced: 4 months ago
JSON representation
A dotnet tool for package dependency checks.
- Host: GitHub
- URL: https://github.com/tonycknight/pkgchk-cli
- Owner: tonycknight
- License: mit
- Created: 2023-12-21T13:16:05.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-25T22:06:35.000Z (5 months ago)
- Last Synced: 2026-01-26T14:11:34.771Z (5 months ago)
- Topics: ci, dotnet, nuget, sca
- Language: F#
- Homepage:
- Size: 215 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# pkgchk-cli
[](https://github.com/tonycknight/pkgchk-cli/actions/workflows/build.yml)
[](https://www.nuget.org/packages/pkgchk-cli/)
A dotnet tool for package dependency checks.
`dotnet list package` is a wonderful tool and with its `--vulnerable` option it is essential for verifying your project's dependencies. It's quick, easy and _free_. If you're not famlilar with it or why you should depend on it (pun intented), [read this blog post](https://devblogs.microsoft.com/nuget/how-to-scan-nuget-packages-for-security-vulnerabilities/).
Unfortunately, integrating it into your CI pipelines isn't as simple as you'd hope: the tool does not return a non-zero return code when vulnerabilities are found (what _every_ pipeline needs), and doesn't produce any reports for things like PR checks. We're left to dig into the build logs and parse the tool's console output to see what's up.
There are long-lived issues on the Dotnet & Nuget boards:
- [Dotnet issue 16852](https://github.com/dotnet/sdk/issues/16852)
- [Dotnet issue 25091](https://github.com/dotnet/sdk/issues/25091)
- [Nuget issue 11781](https://github.com/NuGet/Home/issues/11781)
So until those issues are resolved, `dotnet list package` needs some workarounds in CI pipelines.
This tool tries to do just that. It wraps `dotnet list package` and interprets the output for vulnerabilities. Anything found will return in a non-zero return code, and you get some nice markdown to make your PRs obvious. And because it's a `dotnet tool`, using it in a CI pipeline is as easy as using it on your dev machine.
## If you want to use this as a Github Action
A Github Action is available - see [pkgchk-action](https://github.com/tonycknight/pkgchk-action).
## What you need to install it
:warning: This tool only works with .Net SDK 7.0.200 or higher.
You'll need .Net SDK 7.0.200 installed. Any `global.json` files must use .Net SDK 7.0.200 or higher.
If your SDK is lower than 7.0.200, this tool will not work: you'll get some unexpected results. Sorry about that.
.Net 7.0.200 introduced JSON output, which `pkgchk-cli` leans on.
## Installing into your repository
If you want it in your pipelines, you'll need to install a version into your repository.
Create a tool manifest for your repository:
```dotnet new tool-manifest```
Add the tool to your repository's toolset:
```dotnet tool install pkgchk-cli```
## Installing onto your machine
If you want to use it _in every directory_ just add the tool to your global toolset:
```dotnet tool install pkgchk-cli -g```
## How to use it
To get help:
```pkgchk --help```
To check for top-level and transitive dependency vulnerabilities:
```pkgchk scan ```
If there's only one project or solution file in your directory, omit the `` argument.
To list dependencies:
```pkgchk list ```
If there's only one project or solution file in your directory, omit the `` argument.
To list packages with upgrades:
```pkgchk upgrades ```
If there's only one project or solution file in your directory, omit the `` argument.
### Scan vulnerabilities and deprecations
| | | | |
| - | - | - | - |
| `--vulnerable` | Scan for vulnerable packages | `true`/`false` | `true` by default |
| `--deprecated` | Scan for deprecated packages | `true`/`false` | `false` by default |
| `--transitive` | Scan for transitive packages, vulnerable, deprecated or otherwise | `true`/`false` | `true` by default |
| `--output` | The relative or absolute directory for reports. If ommitted, no reports are generated | `string` | None by default |
| `--severity` | Severity levels to search for, or deprecation reasons. Any number of severties can be given. | `string` | `High`, `Critical`, `Critical Bugs`, `Legacy` |
| `--included-package` | The name of a package to specifically search for. Multiple `--included-package` options can be given. | None by default |
| `--excluded-package` | The name of a package to exclude from searches. Multiple `--excluded-package` options can be given. | None by default |
| `--no-restore` | Don't automatically restore the project/solution. | n/a | Package restoration is automatic by default |
| `--trace` | Show working logs | n/a | |
To check only for top-level dependency vulnerabilities:
```pkgchk scan --transitive false```
To add deprecated packages in a scan:
```pkgchk scan --deprecated true```
Vulnerable packages are automatically searched for. To turn off vulnerable package searches::
```pkgchk scan --vulnerable false```
To produce a markdown file, simply give an output folder:
```pkgchk scan --output ./reports_directory```
Project restores (`dotnet restore`) occur automatically. To suppress restores and speed up scanning, just add `--no-restore`:
```pkgchk scan --no-restore```
By default only `High`, `Critical`, `Critical Bugs` and `Legacy` vulnerabilities and deprecations are detected. Specify the vulnerability severities (or deprecation reasons) with ``--severity`` switches, e.g. to just check for `Moderate` issues:
```pkgchk scan --severity Moderate```
### Listing dependencies
| | | | |
| - | - | - | - |
| `--included-package` | The name of a package to specifically search for. Multiple `--included-package` options can be given. | None by default |
| `--excluded-package` | The name of a package to exclude from searches. Multiple `--excluded-package` options can be given. | None by default |
| `--transitive` | Scan for transitive packages, vulnerable, deprecated or otherwise | `true`/`false` | `true` by default |
| `--no-restore` | Don't automatically restore the project/solution. | n/a | Package restoration is automatic by default |
| `--trace` | Show working logs | n/a | |
To list top-level dependencies with transitives:
```pkgchk list ```
To list top-level dependencies without transitives:
```pkgchk list --transitive false```
### Finding upgrades
| | | | |
| - | - | - | - |
| `--included-package` | The name of a package to specifically search for. Multiple `--included-package` parameter can be given. | None by default |
| `--excluded-package` | The name of a package to exclude from searches. Multiple `--excluded-package` parameter can be given. | None by default |
| `--output` | The relative or absolute directory for reports. If ommitted, no reports are generated | `string` | None by default |
| `--no-restore` | Don't automatically restore the project/solution. | n/a | Package restoration is automatic by default |
| `--trace` | Show working logs | n/a | |
### Configuration files
In some circumstances, you may need to apply a standard list of options, such as excluding specific packages across `scan`, `list`, `upgrade`.
Each command has a `--config` parameter available for the name of a file, for example:
```pkgchk upgrades --config pkgchkconfig.yml```
If you specify `--config`, all other configurable parameters (see below) will be ignored.
Acceptable formats are YAML:
| | | |
| - | - | - |
| `noBanner` | To hide the command line's banner. | |
| `noRestore` | Equivalent to the `--no-restore` parameter. | |
| `excludePackages` | An array of package names to exclude, e.g. `excludedPackages: [ Ignored.Package ]` |
| `includePackages` | An array of package names to include, e.g. `excludedPackages: [ Important.Package ]` |
| `breakOnUpgrades` | For the `upgrades` command, to return a non-zero return code if package upgrades are found. |
| `severities` | For the `scan` command, an array of severities, equivalent to the command's `--severity` parameters. |
| `scanVulnerabilities` | For the `scan` command, equivalent to the commandss `--vulnerable` parametrer. |
| `scanDeprecations` | For the `scan` command, equivalent to the command's `--deprecated` parameter. |
| `scanTransitives` | Equivalent to the `--transitive` parameter. |
## Integration within Github actions
If you want to directly use the tool in Github, simply restore the tool and run, with the same parameters as you'd use from the command line:
```
name: run SCA
run: |
dotnet tool restore
pkgchk scan
```
Alternatively, if you want better visibility and easier control within GitHub, [see pkgchk-action](https://github.com/marketplace/actions/pkgchk).
## Integration within other CI platforms
Most CI platforms fail on non-zero return codes from steps.
Simply ensure your repository has `pkgchk-cli` in its tools manifest, your CI includes `nuget.org` as a package source and run:
```
dotnet tool restore
pkgchk scan
```
## Licence
`pkgchk-cli` is licenced under MIT.
`pkgchk-cli` uses [Spectre.Console](https://spectreconsole.net/) - please check their licence.
`pkgchk-cli` uses [`dotnet list package`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-list-package) published by Microsoft.