CycloneDX.MSBuild 1.2.0

CycloneDX.MSBuild

MSBuild targets for automatic CycloneDX SBOM (Software Bill of Materials) generation during build and pack operations. Seamlessly integrates the CycloneDX .NET tool into your build pipeline.

🎯 Overview

CycloneDX.MSBuild is a NuGet package inspired by Microsoft.Sbom.Targets that automatically generates CycloneDX SBOMs for your .NET projects. Simply add the package reference, and SBOMs are generated automatically during dotnet build or dotnet pack.

Why CycloneDX.MSBuild?

• ✅ Zero Configuration: Works out of the box with sensible defaults
• ✅ Security by Design: Runs in build context, no elevated permissions required
• ✅ Multi-Target Support: Handles projects with multiple target frameworks
• ✅ Flexible: Highly configurable via MSBuild properties
• ✅ Standards Compliant: Generates CycloneDX 1.2-1.6 compatible SBOMs
• ✅ Development Dependency: Doesn't pollute your dependency tree

🚀 Quick Start

Installation

Add the package to your project:

dotnet add package CycloneDX.MSBuild

Or add it manually to your .csproj:

<ItemGroup>
  <PackageReference Include="CycloneDX.MSBuild" Version="1.0.0" PrivateAssets="all" />
</ItemGroup>

Build Your Project

dotnet build

That's it! Your SBOM will be generated at bin/Debug/net8.0/sbom.json (or your output directory).

📋 Features

Automatic SBOM Generation

SBOMs are generated automatically:

• During Build: After successful compilation
• During Pack: Included in NuGet packages under /sbom/
• During Publish: Copied to the publish directory
• Multi-Targeting: Generates once per project, not per framework

Supported Output Formats

• JSON (default) - CycloneDX JSON format
• XML - CycloneDX XML format

CycloneDX Specification Versions

The tool automatically uses the latest CycloneDX specification version supported by the installed tool version (typically 1.6).

⚙️ Configuration

All configuration is done via MSBuild properties. Set them in your .csproj, Directory.Build.props, or command line.

Core Settings

Enable/Disable SBOM Generation

<PropertyGroup>
  
  <GenerateCycloneDxSbom>false</GenerateCycloneDxSbom>
</PropertyGroup>

Error Handling

<PropertyGroup>
  
  <CycloneDxContinueOnError>false</CycloneDxContinueOnError>
</PropertyGroup>

Output Configuration

Output Format

<PropertyGroup>
  
  <CycloneDxOutputFormat>xml</CycloneDxOutputFormat>
</PropertyGroup>

Output Location

<PropertyGroup>
  
  <CycloneDxOutputDirectory>$(MSBuildProjectDirectory)/sbom/</CycloneDxOutputDirectory>

  
  <CycloneDxOutputFilename>software-bom</CycloneDxOutputFilename>
</PropertyGroup>

Advanced Options

Exclude Dependencies

<PropertyGroup>
  
  <CycloneDxExcludeDev>true</CycloneDxExcludeDev>

  
  <CycloneDxExcludeTestProjects>true</CycloneDxExcludeTestProjects>
</PropertyGroup>

Serial Number Control

<PropertyGroup>
  
  <CycloneDxDisableSerialNumber>true</CycloneDxDisableSerialNumber>
</PropertyGroup>

Automatic Metadata Generation

New in v1.1.0: CycloneDX.MSBuild now automatically extracts assembly and package metadata from your project properties and includes it in the generated SBOM. This eliminates the need for manual metadata templates in most cases.

Automatically Extracted Metadata:

• Version: From Version, VersionPrefix, AssemblyVersion, or GitVersion properties (GitVersion_FullSemVer, GitVersion_SemVer)
• Component Name: From AssemblyName or project name
• Authors/Supplier: From Authors or Company properties
• Description: From Description or PackageDescription properties
• Copyright: From Copyright property
• License: From PackageLicenseExpression property
• Package URL (purl): Automatically generated as pkg:nuget/{name}@{version}

Example Project Configuration:

<PropertyGroup>
  <Version>1.2.3</Version>
  <Authors>Your Name</Authors>
  <Company>Your Company Inc.</Company>
  <Description>A brief description of your application</Description>
  <Copyright>Copyright (c) 2024 Your Company Inc.</Copyright>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

Generated SBOM Component Metadata:

{
  "component": {
    "type": "application",
    "bom-ref": "pkg:nuget/YourProject@1.2.3",
    "name": "YourProject",
    "version": "1.2.3",
    "description": "A brief description of your application",
    "supplier": {
      "name": "Your Name"
    },
    "copyright": "Copyright (c) 2024 Your Company Inc.",
    "licenses": [
      {
        "license": {
          "id": "MIT"
        }
      }
    ],
    "purl": "pkg:nuget/YourProject@1.2.3"
  }
}

Disable Automatic Metadata Generation:

If you prefer to use a manual metadata template or disable metadata generation entirely:

<PropertyGroup>
  
  <CycloneDxGenerateMetadata>false</CycloneDxGenerateMetadata>
</PropertyGroup>

GitVersion Integration:

If you're using GitVersion for semantic versioning, CycloneDX.MSBuild automatically detects and uses the GitVersion-generated version:

Import Metadata Template (Advanced)

Note: With automatic metadata generation enabled by default (see above), manual metadata templates are typically only needed for advanced scenarios or custom metadata structures.

<PropertyGroup>
  
  <CycloneDxImportMetadataPath>$(MSBuildProjectDirectory)/sbom-metadata.xml</CycloneDxImportMetadataPath>
</PropertyGroup>

When you specify a custom metadata template path, automatic metadata generation is skipped, and your template is used instead. This is useful for:

• Adding custom component information beyond standard properties
• Including additional metadata fields not extracted automatically
• Providing complex metadata structures

Example sbom-metadata.xml:

Note: CycloneDX.MSBuild supports metadata templates using CycloneDX schema versions 1.2 through 1.6. You may use any supported version, but 1.6 is recommended for new projects.

<?xml version="1.0" encoding="utf-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.6">
  <metadata>
    <component type="application" bom-ref="pkg:nuget/YourProject@1.0.0">
      <name>YourProject</name>
      <version>1.0.0</version>
      <description>
        <![CDATA[Your project description]]>
      </description>
      <licenses>
        <license>
          <name>Apache License 2.0</name>
          <id>Apache-2.0</id>
        </license>
      </licenses>
      <purl>pkg:nuget/YourProject@1.0.0</purl>
    </component>
  </metadata>
</bom>

GitHub License Resolution

<PropertyGroup>
  
  <CycloneDxEnableGitHubLicenses>true</CycloneDxEnableGitHubLicenses>

  
  <CycloneDxGitHubUsername>your-username</CycloneDxGitHubUsername>
  <CycloneDxGitHubToken>ghp_yourtoken</CycloneDxGitHubToken>
</PropertyGroup>

Tool Version

<PropertyGroup>
  
  <CycloneDxToolVersion>5.5.0</CycloneDxToolVersion>
</PropertyGroup>

📦 NuGet Package Integration

When you run dotnet pack, the generated SBOM is automatically included in the NuGet package under the /sbom/ directory.

dotnet pack

Consumers of your NuGet package can inspect the SBOM:

# Extract and view
unzip -q MyPackage.1.0.0.nupkg -d extracted
cat extracted/sbom/sbom.json

🚀 Publish Integration

When you run dotnet publish, the generated SBOM is automatically copied to the publish directory alongside your application.

dotnet publish -c Release

The SBOM will be available in your publish directory:

# View the SBOM in publish directory
cat bin/Release/net8.0/publish/sbom.json

This makes it easy to include the SBOM when deploying your application, ensuring supply chain transparency in production environments.

🏗️ Architecture

MSBuild Integration

CycloneDX.MSBuild uses MSBuild's extensibility hooks:

1. .props file - Defines configurable properties with defaults
2. .targets file - Implements build targets for SBOM generation
3. buildMultiTargeting/ - Special handling for multi-target projects

Target Execution Order

Build → ValidateCycloneDxConfiguration → EnsureCycloneDxToolInstalled → GenerateCycloneDxSbom

Security by Design

• Sandboxed Execution: Runs in build context without elevated privileges
• Input Validation: All properties are validated before use
• Fail-Safe Defaults: Continues build on errors by default
• No Code Execution: Only executes vetted CycloneDX tool
• Dependency Pinning: Explicit tool version control

Clean Code Principles

• Separation of Concerns: Configuration (.props) separated from logic (.targets)
• Single Responsibility: Each target has one clear purpose
• DRY: Reusable property groups
• Consistent Naming: CycloneDx* prefix for all properties
• Comprehensive Documentation: XML comments for all properties

🧪 Testing

The repository includes integration tests for various scenarios:

tests/
├── SimpleProject/          # Basic single-target project
├── MultiTargetProject/     # Multi-targeting (.NET 6, 8, Standard 2.0)
└── DisabledProject/        # Project with SBOM generation disabled

🔄 Versioning

This project uses automated semantic versioning with:

• MinVer: Automatic version calculation from Git tags
• semantic-release: Automated releases, changelogs, and NuGet publishing

All commits must follow Conventional Commits format.

📖 For detailed information, see VERSIONING.md

🚀 CI/CD Pipeline

This project includes a comprehensive CI/CD pipeline with automated testing and publishing:

Continuous Integration (CI)

Runs on all pull requests and feature branches:

• ✅ Multi-platform testing (Ubuntu, Windows, macOS)
• ✅ Multi-version .NET testing (.NET 6.0 and 8.0)
• ✅ Code quality checks (formatting, package validation)
• ✅ Dependency security scanning (vulnerable and deprecated packages)
• ✅ Build artifact generation

Continuous Deployment (CD)

Runs on pushes to main, master, beta, or alpha branches:

1. Build & Test - Full test suite execution
2. Package Validation - NuGet package quality checks
3. Semantic Release - Automatic version determination from commits
4. NuGet Publishing - Automatic publishing to NuGet.org
5. GitHub Release - Automated release notes and changelog

Setting up Automated Publishing

To enable automated NuGet publishing:

1. Get a NuGet API key from NuGet.org
2. Add it as a GitHub secret named NUGET_API_KEY
3. The release workflow will automatically publish on version bumps

📖 For detailed CI/CD documentation, see .github/workflows/README.md

🔧 Development

Project Structure

CycloneDX.MSBuild/
├── src/
│   └── CycloneDX.MSBuild/
│       ├── build/
│       │   ├── CycloneDX.MSBuild.props      # Configuration properties
│       │   └── CycloneDX.MSBuild.targets    # Build integration
│       ├── buildMultiTargeting/             # Multi-target support
│       └── CycloneDX.MSBuild.csproj         # Package definition
├── tests/
│   └── Integration.Tests/
└── README.md

Building Locally

# Build the package
dotnet build src/CycloneDX.MSBuild/CycloneDX.MSBuild.csproj

# Pack the package
dotnet pack src/CycloneDX.MSBuild/CycloneDX.MSBuild.csproj

# Test with local projects
dotnet build tests/Integration.Tests/SimpleProject/SimpleProject.csproj

📚 Comparison with Microsoft.Sbom.Targets

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Guidelines

• Follow existing code style and architecture
• Maintain security by design principles
• Add tests for new features
• Update documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• CycloneDX .NET Tool - The underlying SBOM generation tool
• CycloneDX Specification - CycloneDX standard
• Microsoft.Sbom.Targets - Microsoft's SPDX SBOM tool
• OWASP Dependency-Track - SBOM analysis platform

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• CycloneDX Community: https://cyclonedx.org/

Made with ❤️ for Software Supply Chain Security