SarifMark

SARIF Report Generation Tool

Overview

SarifMark is a .NET command-line tool that generates comprehensive markdown reports from SARIF (Static Analysis Results Interchange Format) files. It processes SARIF files produced by various static analysis tools and converts them into human-readable markdown reports, making it easy to integrate code quality reporting into your CI/CD pipelines and documentation workflows.

Features

• 📄 SARIF Processing - Read and parse SARIF 2.1.0 format files
• 📝 Markdown Reports - Generate human-readable reports from SARIF data
• 🎯 Customizable Output - Configure report depth and custom headings
• 🚀 CI/CD Integration - Enforce quality gates and fail builds on issues
• 🌐 Multi-Platform - Support for .NET 8, 9, and 10
• ✅ Self-Validation - Built-in tests without requiring external tools
• 📊 Detailed Reporting - Extract tool information, results, and locations

Installation

Prerequisites

• .NET SDK 8.0, 9.0, or 10.0

Global Installation

Install SarifMark as a global .NET tool for system-wide use:

dotnet tool install --global DemaConsulting.SarifMark

Verify the installation:

sarifmark --version

Local Installation

Install SarifMark as a local tool in your project (recommended for team projects):

dotnet new tool-manifest  # if you don't have a tool manifest already
dotnet tool install DemaConsulting.SarifMark

Run the tool:

dotnet sarifmark --version

Usage

Basic Usage

Run the tool with the --help option to see available commands and options:

sarifmark --help

This will display:

Usage: sarifmark [options]

Options:
  -v, --version              Display version information
  -?, -h, --help             Display this help message
  --silent                   Suppress console output
  --validate                 Run self-validation
  --results <file>           Write validation results to file (.trx or .xml)
  --enforce                  Return non-zero exit code if issues found
  --log <file>               Write output to log file
  --sarif <file>             SARIF file to process
  --report <file>            Export analysis results to markdown file
  --report-depth <depth>     Markdown header depth for report (default: 1)
  --heading <text>           Custom heading for report (default: [ToolName] Analysis)

Quick Start Examples

Generate a report from a SARIF file:

sarifmark --sarif analysis.sarif --report report.md

Generate a report with custom heading:

sarifmark --sarif analysis.sarif --report report.md --heading "Code Quality Analysis"

Enforce quality gate in CI/CD:

sarifmark --sarif analysis.sarif --enforce

Run self-validation:

sarifmark --validate

Run self-validation with test results output:

sarifmark --validate --results validation-results.trx

Self-Validation Tests

SarifMark includes built-in self-validation tests that verify the tool's functionality without requiring external static analysis tools. These tests use mock SARIF data to validate core features and generate test result files in TRX or JUnit format.

The self-validation suite includes the following tests:

Test Name	Description
SarifMark_SarifReading	Verifies reading and parsing SARIF 2.1.0 format files
SarifMark_MarkdownReportGeneration	Verifies generating markdown reports from SARIF data
SarifMark_Enforcement	Verifies enforcement mode returns non-zero exit code when issues are found

These tests provide evidence of the tool's functionality and are particularly useful for:

• Verifying the installation is working correctly
• Running automated tests in CI/CD pipelines without requiring static analysis tools
• Generating test evidence for compliance and traceability requirements

For detailed usage instructions, command-line options, and examples, including tool update instructions, see the Usage Guide.

Report Format

The generated markdown report includes:

1. Report Header - Custom heading or tool name with "Analysis" suffix
2. Tool Information - Tool name and version extracted from SARIF file
3. Results Summary - Count of issues found in the analysis
4. Results List - Detailed list of results in compiler-style format with file, line, level, rule ID, and message

Example report structure:

# MockTool Analysis

**Tool:** MockTool 1.0.0

**Results:** 2

## Results

Found 2 results

src/Program.cs(42): warning TEST001: Test issue 1
src/Helper.cs(15): error TEST002: Test issue 2

Contributing

Contributions are welcome! We appreciate your interest in improving SarifMark.

Please see our Contributing Guide for development setup, coding standards, and submission guidelines. Also review our Code of Conduct for community guidelines.

For bug reports, feature requests, and questions, please use GitHub Issues.

License

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

Support

• 🐛 Report Bugs: GitHub Issues
• 💡 Request Features: GitHub Issues
• ❓ Ask Questions: GitHub Discussions
• 📖 Documentation: Usage Guide
• 🤝 Contributing: Contributing Guide

Security

For security concerns and vulnerability reporting, please see our Security Policy.

Acknowledgements

SarifMark is built with the following open-source projects:

• .NET - Cross-platform framework for building applications
• SARIF - Static Analysis Results Interchange Format specification
• DemaConsulting.TestResults - Test results parsing library