SonarMark

Code Quality Reporting Tool for SonarQube/SonarCloud

Overview

SonarMark is a .NET command-line tool that generates comprehensive markdown reports from SonarQube/SonarCloud analysis results. It fetches quality gate status, issues, and security hot-spots directly from the SonarQube/SonarCloud API, making it easy to integrate code quality reporting into your CI/CD pipelines and documentation workflows.

Features

• 📊 Quality Gate Reports - Retrieve and report quality gate status with detailed conditions
• 🐛 Issue Analysis - Fetch and categorize issues by type and severity
• 🔒 Security Hot-Spots - Identify and report security vulnerabilities requiring review
• 📝 Markdown Output - Generate human-readable markdown reports for easy sharing
• 🚀 CI/CD Integration - Enforce quality gates and fail builds on quality issues
• 🌐 Multi-Platform - Support for .NET 8, 9, and 10 across Windows, Linux, and macOS
• ✅ Self-Validation - Built-in tests to verify functionality without requiring a live server
• 🔗 API Integration - Direct integration with SonarQube and SonarCloud REST APIs
• 🔍 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
• 🗂️ Requirements Traceability - Requirements linked to passing tests with auto-generated trace matrix

Installation

Prerequisites

• .NET SDK 8.0, 9.0, or 10.0

Global Installation

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

dotnet tool install --global DemaConsulting.SonarMark

Verify the installation:

sonarmark --version

Local Installation

Install SonarMark 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.SonarMark

Run the tool:

dotnet sonarmark --version

Usage

Basic Usage

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

sonarmark --help

This will display:

Usage: sonarmark [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 quality gate fails
  --log <file>               Write output to log file
  --server <url>             SonarQube/SonarCloud server URL
  --project-key <key>        SonarQube/SonarCloud project key
  --branch <name>            Branch name to query (default: main branch)
  --token <token>            Personal access token for SonarQube/SonarCloud
  --report <file>            Export quality results to markdown file
  --report-depth <depth>     Markdown header depth for report (default: 1)

Quick Start Examples

Generate a report for the main branch:

sonarmark --server https://sonarcloud.io \
  --project-key my-org_my-project \
  --token $SONAR_TOKEN \
  --report quality-report.md

Generate a report for a specific branch:

sonarmark --server https://sonarcloud.io \
  --project-key my-org_my-project \
  --branch feature/new-feature \
  --token $SONAR_TOKEN \
  --report quality-report.md

Enforce quality gate in CI/CD:

sonarmark --server https://sonarcloud.io \
  --project-key my-org_my-project \
  --token $SONAR_TOKEN \
  --enforce

Run self-validation:

sonarmark --validate

Run self-validation with test results output:

sonarmark --validate --results validation-results.trx

Self Validation

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

# DEMA Consulting SonarMark

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

✓ SonarMark_QualityGateRetrieval - Passed
✓ SonarMark_IssuesRetrieval - Passed
✓ SonarMark_HotSpotsRetrieval - Passed
✓ SonarMark_MarkdownReportGeneration - Passed

Total Tests: 4
Passed: 4
Failed: 0

Each test in the report proves:

• SonarMark_QualityGateRetrieval - Verifies fetching and processing quality gate status from SonarQube/SonarCloud.
• SonarMark_IssuesRetrieval - Verifies fetching and processing code issues with severity classification.
• SonarMark_HotSpotsRetrieval - Verifies fetching and processing security hot-spots and vulnerabilities.
• SonarMark_MarkdownReportGeneration - Verifies generating markdown reports with quality metrics and findings.

See the User Guide for more details on the self-validation tests.

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

Report Format

The generated markdown report includes:

1. Project Header - Project name and dashboard link
2. Quality Gate Status - Overall pass/fail status (OK, ERROR, WARN, or NONE)
3. Conditions - Detailed quality gate conditions with metrics, comparators, thresholds, and actual values
4. Issues - Count and list of issues in compiler-style format with file, line, severity, type, rule, and message
5. Security Hot-Spots - Count and list of security vulnerabilities requiring review in compiler-style format

Example report structure:

# Example Project Sonar Analysis

**Dashboard:** <https://sonarcloud.io/dashboard?id=my_project>

**Quality Gate Status:** ERROR

## Conditions

| Metric | Status | Comparator | Threshold | Actual |
|:-------------------------------|:-----:|:--:|--------:|-------:|
| Coverage on New Code | ERROR | LT | 80 | 65.5 |
| New Bugs | ERROR | GT | 0 | 3 |

## Issues

Found 2 issues

src/Program.cs(42): MAJOR CODE_SMELL [csharpsquid:S1234] Remove this unused variable
src/Helper.cs(15): MINOR CODE_SMELL [csharpsquid:S5678] Refactor this method

## Security Hot-Spots

Found 1 security hot-spot

src/Database.cs(88): HIGH [sql-injection] Make sure using this SQL query is safe

Contributing

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

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

SonarMark is built with the following open-source projects:

• .NET - Cross-platform framework for building applications
• SonarQube - Continuous code quality inspection
• SonarCloud - Cloud-based code quality and security service
• DemaConsulting.TestResults - Test results parsing library