DemaConsulting.SarifMark 1.4.0

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, including multi-run 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 - Builds and runs on Windows, Linux, and macOS with .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

Update

To update to the latest version:

# Global installation
dotnet tool update --global DemaConsulting.SarifMark

# Local installation
dotnet tool update DemaConsulting.SarifMark

Compatibility

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
  --exclude <glob>           Exclude findings whose location matches glob (repeatable)
  --report <file>            Export analysis results to markdown file
  --depth <depth>            Markdown header depth for report (1-6, 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"

Exclude generated code from a report:

sarifmark --sarif analysis.sarif --report report.md --exclude "**/bin/**" --exclude "**/obj/**"

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

Building

pwsh ./build.ps1

User Guide

The SarifMark User Guide is available on the SarifMark releases page.

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.

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

Support

• 🐛 Report Bugs: GitHub Issues
• 💡 Request Features: GitHub Issues
• ❓ Ask Questions: GitHub Discussions
• 📖 User Guide: SarifMark releases page
• 🤝 Contributing: Contributing Guide

Project Development Practices

• 🔍 Linting Enforcement - markdownlint, cspell, and yamllint enforced on every CI run
• 📋 Continuous Compliance - Compliance evidence generated automatically on every CI run, following the Continuous Compliance methodology
• ☁️ SonarCloud Integration - Quality gate and security analysis on every build
• 🔗 Requirements Traceability - Requirements linked to passing tests with auto-generated trace matrix

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. File Count - Number of files analyzed in this run
4. Issues Summary - Count of issues found in the analysis
5. Issues List - Detailed list of issues in compiler-style format with file, line, level, rule ID, and message

Example report structure:

# MockTool Analysis

**Tool:** MockTool 1.0.0
**Files:** 2

## Issues

Found 2 issues

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

Self Validation

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:

Running self-validation produces a report containing the following information:

# DEMA Consulting SarifMark

| Information         | Value                                              |
| :------------------ | :------------------------------------------------- |
| SarifMark Version   | <version>                                          |
| Machine Name        | <machine-name>                                     |
| OS Version          | <os-version>                                       |
| DotNet Runtime      | <dotnet-runtime-version>                           |
| Time Stamp          | <timestamp> UTC                                    |

✓ SarifMark_SarifReading - Passed
✓ SarifMark_MarkdownReportGeneration - Passed
✓ SarifMark_Enforcement - Passed

Total Tests: 3
Passed: 3
Failed: 0

Each test in the report proves:

• SarifMark_SarifReading - SARIF file reading and parsing works correctly.
• SarifMark_MarkdownReportGeneration - Markdown report generation from SARIF data works correctly.
• SarifMark_Enforcement - Enforcement mode returns a non-zero exit code when issues are found.

On validation failure the tool will exit with a non-zero exit code.

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
• Microsoft.Extensions.FileSystemGlobbing - Glob pattern matching used by --exclude