Edit

Audit reports for privacy and compliance

The 📦 Microsoft.Extensions.AuditReports NuGet package provides functionality to generate audit reports about the code being compiled. These reports are particularly useful for privacy audits, compliance reviews, and understanding what telemetry data your application collects and transmits.

Why use audit reports

Audit reports help organizations maintain compliance and transparency:

  • Privacy compliance: Identify all places where privacy-sensitive data is accessed or logged.
  • Telemetry tracking: Understand what metrics and telemetry your application generates.
  • Code review: Review data classification usage across your codebase.
  • Compliance audits: Provide documentation for compliance and security audits.
  • Data governance: Ensure data handling practices align with organizational policies.

Get started

The Microsoft.Extensions.AuditReports package is a build-time tool that generates reports during compilation. Install it as a development dependency:

dotnet add package Microsoft.Extensions.AuditReports

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Report types

The package can generate three types of reports:

Report type Description
Metrics Generates a report on source-generated metric definitions used in your code, so you can understand what metrics your application emits.
Compliance Generates a report on the usage of privacy-sensitive data, including source-generated logging methods that handle personal or sensitive information.
Metadata Generates a comprehensive report that combines both metrics and compliance information.

Configure report generation

Configure report generation by setting MSBuild properties in your project file:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    
    <!-- Enable audit report generation -->
    <GenerateComplianceReport>true</GenerateComplianceReport>
    
    <!-- Specify report output path (optional) -->
    <ComplianceReportOutputPath>$(OutputPath)compliance-report.json</ComplianceReportOutputPath>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.AuditReports" Version="10.0.0" />
  </ItemGroup>

</Project>

Generate a compliance report

To generate a compliance report, set the GenerateComplianceReport property to true:

<PropertyGroup>
  <GenerateComplianceReport>true</GenerateComplianceReport>
</PropertyGroup>

This report identifies code that handles privacy-sensitive data, particularly in logging operations.

Generate a metrics report

To generate a metrics report, set the GenerateMetricsReport property to true:

<PropertyGroup>
  <GenerateMetricsReport>true</GenerateMetricsReport>
  <MetricsReportOutputPath>$(OutputPath)metrics-report.json</MetricsReportOutputPath>
</PropertyGroup>

This report documents all metrics generated by your application.

Generate a metadata report

For a comprehensive report that includes both compliance and metrics information:

<PropertyGroup>
  <GenerateMetadataReport>true</GenerateMetadataReport>
  <MetadataReportOutputPath>$(OutputPath)metadata-report.json</MetadataReportOutputPath>
</PropertyGroup>

Example: Compliance report output

When you build a project with compliance reporting enabled, you get a JSON file that identifies privacy-sensitive data usage:

{
  "version": "1.0",
  "reportType": "compliance",
  "generatedAt": "2025-10-20T12:00:00Z",
  "entries": [
    {
      "filePath": "Services/UserService.cs",
      "lineNumber": 42,
      "memberName": "LogUserActivity",
      "dataClassification": "PersonalData",
      "message": "Logs user email address"
    },
    {
      "filePath": "Controllers/AccountController.cs",
      "lineNumber": 88,
      "memberName": "LogLoginAttempt",
      "dataClassification": "AuthenticationData",
      "message": "Logs authentication attempt with username"
    }
  ]
}

Use with data classification

The audit reports work in conjunction with the data classification attributes from Microsoft.Extensions.Compliance.Abstractions:

using Microsoft.Extensions.Compliance.Classification;
using Microsoft.Extensions.Logging;

public class UserService
{
    private readonly ILogger<UserService> _logger;

    public UserService(ILogger<UserService> logger)
    {
        _logger = logger;
    }

    [LoggerMessage(Level = LogLevel.Information, Message = "User {Email} logged in")]
    public partial void LogUserLogin(
        [PrivateData] string email);
}

When you build this code with compliance reporting enabled, the report will identify that email is classified as PrivateData.

Configure report output location

Specify custom paths for your audit reports:

<PropertyGroup>
  <!-- Generate all report types -->
  <GenerateComplianceReport>true</GenerateComplianceReport>
  <GenerateMetricsReport>true</GenerateMetricsReport>
  
  <!-- Custom output locations -->
  <ComplianceReportOutputPath>$(OutputPath)audit\compliance.json</ComplianceReportOutputPath>
  <MetricsReportOutputPath>$(OutputPath)audit\metrics.json</MetricsReportOutputPath>
</PropertyGroup>

Integrate with CI/CD pipelines

Audit reports can be integrated into your CI/CD pipeline for automated compliance checks:

# Example GitHub Actions workflow
name: Compliance Check

on:
  pull_request:
    branches: [ main ]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: '10.0.x'
    
    - name: Build with compliance report
      run: dotnet build -p:GenerateComplianceReport=true
    
    - name: Upload compliance report
      uses: actions/upload-artifact@v3
      with:
        name: compliance-report
        path: '**/compliance-report.json'
    
    - name: Analyze compliance report
      run: |
        # Add script to analyze the compliance report
        # and fail the build if violations are found
        ./scripts/check-compliance.sh

Example: Metrics report output

A metrics report documents the metrics your application produces:

{
  "version": "1.0",
  "reportType": "metrics",
  "generatedAt": "2025-10-20T12:00:00Z",
  "metrics": [
    {
      "name": "http_request_duration",
      "description": "HTTP request duration in milliseconds",
      "unit": "milliseconds",
      "type": "histogram",
      "tags": ["endpoint", "method", "status_code"]
    },
    {
      "name": "active_connections",
      "description": "Number of active connections",
      "unit": "connections",
      "type": "gauge",
      "tags": ["connection_type"]
    }
  ]
}

Practical example: Privacy audit workflow

Here's a complete example showing how to set up privacy auditing:

Project file configuration:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    
    <!-- Enable compliance reporting -->
    <GenerateComplianceReport>true</GenerateComplianceReport>
    <ComplianceReportOutputPath>$(OutputPath)audit\compliance.json</ComplianceReportOutputPath>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.AuditReports" Version="10.0.0" />
    <PackageReference Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.0.0" />
    <PackageReference Include="Microsoft.Extensions.Telemetry.Abstractions" Version="10.0.0" />
  </ItemGroup>

</Project>

Code with data classification:

using Microsoft.Extensions.Compliance.Classification;
using Microsoft.Extensions.Logging;

public partial class OrderService(ILogger<OrderService> logger)
{

    [LoggerMessage(Level = LogLevel.Information, Message = "Order created for customer {CustomerId}")]
    public partial void LogOrderCreated(
        [PublicData] string customerId);

    [LoggerMessage(Level = LogLevel.Information, Message = "Payment processed for {CardNumber}")]
    public partial void LogPaymentProcessed(
        [PrivateData] string cardNumber);
}

When you build this project, the compliance report will identify the privacy-sensitive logging of cardNumber.

Best practices

When using audit reports, consider the following best practices:

  • Integrate early: Add audit reporting to your projects early in development to catch privacy issues sooner.
  • Automate reviews: Integrate audit report generation into your CI/CD pipeline for continuous compliance monitoring.
  • Review regularly: Regularly review audit reports during code reviews and before releases.
  • Classify data: Use data classification attributes consistently to ensure accurate audit reports.
  • Store reports: Archive audit reports for compliance documentation and historical tracking.
  • Version control: Track changes to audit reports over time to understand how your data handling evolves.
  • Security scanning: Use audit reports as input for security and privacy scanning tools.

See also

  • Last updated on