Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cyclonedx/cyclonedx-dotnet
Creates CycloneDX Software Bill of Materials (SBOM) from .NET Projects
https://github.com/cyclonedx/cyclonedx-dotnet
bill-of-materials bom cyclonedx dotnet dotnet-core hacktoberfest mbom obom owasp package-url purl saasbom sbom sbom-generator software-bill-of-materials spdx vex
Last synced: about 17 hours ago
JSON representation
Creates CycloneDX Software Bill of Materials (SBOM) from .NET Projects
- Host: GitHub
- URL: https://github.com/cyclonedx/cyclonedx-dotnet
- Owner: CycloneDX
- License: apache-2.0
- Created: 2018-10-02T21:58:30.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-09-18T20:09:33.000Z (about 2 months ago)
- Last Synced: 2024-11-02T14:51:35.429Z (15 days ago)
- Topics: bill-of-materials, bom, cyclonedx, dotnet, dotnet-core, hacktoberfest, mbom, obom, owasp, package-url, purl, saasbom, sbom, sbom-generator, software-bill-of-materials, spdx, vex
- Language: C#
- Homepage: https://cyclonedx.org/
- Size: 2.62 MB
- Stars: 180
- Watchers: 14
- Forks: 87
- Open Issues: 73
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/CycloneDX/cyclonedx-dotnet/actions?workflow=.NET+Core+CI)
[](https://hub.docker.com/r/cyclonedx/cyclonedx-dotnet)
[][License]
[](https://www.nuget.org/packages/CycloneDX/)
[](https://cyclonedx.org/)
[](https://cyclonedx.org/slack/invite)
[](https://groups.io/g/CycloneDX)
[](https://twitter.com/CycloneDX_Spec)
# CycloneDX module for .NET
The CycloneDX module for .NET creates a valid CycloneDX bill-of-material document containing an aggregate of all project dependencies. CycloneDX is a lightweight BOM specification that is easily created, human readable, and simple to parse.
This module runs on
* .NET 6.0
* .NET 7.0
* .NET 8.0
This module no longer runs on
* .NET Core 2.1
* .NET Core 3.1
* .NET 5.0
* see https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core for more information
## Usage
CycloneDX for .NET is distributed via NuGet and Docker Hub.
#### Installing via NuGet
```bash
dotnet tool install --global CycloneDX
```
If you already have a previous version of **CycloneDX** installed, you can upgrade to the latest version using the following command:
```bash
dotnet tool update --global CycloneDX
```
#### Execution via DotNet
```bash
dotnet CycloneDX -o
```
#### Execution via Docker
```bash
docker run cyclonedx/cyclonedx-dotnet [OPTIONS]
```
#### Options
```text
Usage:
CycloneDX [options]
Arguments:
The path to a .sln, .csproj, .fsproj, .vbproj, or packages.config file or the path to a directory which will be recursively analyzed for packages.config files.
Options:
-tfm, --framework The target framework to use. If not defined, all will be aggregated.
-rt, --runtime The runtime to use. If not defined, all will be aggregated.
-o, --output The directory to write the BOM
-fn, --filename Optionally provide a filename for the BOM (default: bom.xml or bom.json)
-j, --json Produce a JSON BOM instead of XML
-ed, --exclude-dev Exclude development dependencies from the BOM (see https://github.com/NuGet/Home/wiki/DevelopmentDependency-support-for-PackageReference)
-t, --exclude-test-projects Exclude test projects from the BOM
-u, --url Alternative NuGet repository URL to https:///nuget//v3/index.json
-us, --baseUrlUsername Alternative NuGet repository username
-usp, --baseUrlUserPassword Alternative NuGet repository username password/apikey
-uspct, --isBaseUrlPasswordClearText Alternative NuGet repository password is cleartext
-rs, --recursive To be used with a single project file, it will recursively scan project references of the supplied project file
-ns, --no-serial-number Optionally omit the serial number from the resulting BOM
-gu, --github-username Optionally provide a GitHub username for license resolution. If set you also need to provide a GitHub personal access token
-gt, --github-token Optionally provide a GitHub personal access token for license resolution. If set you also need to provide a GitHub username
-gbt, --github-bearer-token Optionally provide a GitHub bearer token for license resolution. This is useful in GitHub actions
-egl, --enable-github-licenses Enables GitHub license resolution
-dpr, --disable-package-restore Optionally disable package restore
-dhc, --disable-hash-computation Optionally disable hash computation for packages
-dct, --dotnet-command-timeout dotnet command timeout in milliseconds (primarily used for long dotnet restore operations) [default: 300000]
-biop, --base-intermediate-output-path Optionally provide a folder for customized build environment. Required if folder 'obj' is relocated.
-imp, --import-metadata-path Optionally provide a metadata template which has project specific details.
-ipr, --include-project-references Include project references as components (can only be used with project files).
-sn, --set-name Override the autogenerated BOM metadata component name.
-sv, --set-version Override the default BOM metadata component version (defaults to 0.0.0).
-st, --set-type
--version Show version information
-?, -h, --help Show help and usage information
```
#### Examples
To run the **CycloneDX** tool you need to specify a solution or project file. In case you pass a solution, the tool will aggregate all the projects.
The following will create a BOM from a solution and all projects defined within:
```bash
dotnet CycloneDX YourSolution.sln -o /output/path
```
The following will recursively scan the directory structure for packages.config and create a BOM:
```bash
dotnet CycloneDX /path/to/project -o /output/path
```
The following will recursively scan the project references of the supplied project file, and create a BOM of all package references from all included projects:
```bash
dotnet CycloneDX /path/to/project/MyProject.csproj -o /output/path -rs
```
Project [metadata](https://cyclonedx.org/docs/1.2/#type_metadata) **template example**
```xml
CycloneDX
1.3.0
Apache License 2.0
Apache-2.0
pkg:nuget/[email protected]
```
_Update the data and import it within a build pipeline e.g. create the file using a script and add also dynamic data (version, timestamp, ...)_
#### GitHub License Resolution
SPDX license IDs can be resolved for packages that reference a supported license
file in a GitHub repository.
The GitHub license API has an unauthenticated call limit of 60 calls per hour.
To ensure consistent output if a rate limit is exceeded BOM generation will
fail. If you start hitting rate limits you will need to generate a personal
access token and provide this, and your username, when running CycloneDX.
To generate a token go to
[Personal access tokens](https://github.com/settings/tokens) under
`Settings / Developer setings`. From there select the option to
[Generate new token](https://github.com/settings/tokens/new). No special token
permissions are required.
Due to current limitations in the GitHub API licenses will only be resolved for
master branch license references.
## License
Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. See the [LICENSE] file for the full license.
[License]: https://github.com/CycloneDX/cyclonedx-dotnet/blob/master/LICENSE
## Contributing
Pull requests are welcome. But please read the
[CycloneDX contributing guidelines](https://github.com/CycloneDX/.github/blob/master/CONTRIBUTING.md) first.
To build and test the solution locally you should have .NET 6.0 or .NET 7.0
installed. Standard commands like `dotnet build` and `dotnet test` work.
Alternatively, you can use VS Code and the included devcontainer configuration
to work in a pre-configured docker image. (You will also need the "Remote - Containers"
extension and Docker)
It is generally expected that pull requests will include relevant tests.
Tests are automatically run on Windows, MacOS and Linux for every pull request.
And build warnings will break the build.
If you are having trouble debugging a test that is failing for a platform you
don't have access to please us know.
Thanks to [Gitpod](https://gitpod.io/) there is a really easy way of creating
a ready to go development environment with VS Code. You can open a Gitpod
hosted development environment in your browser.
[](https://gitpod.io/#https://github.com/CycloneDX/cyclonedx-dotnet)