microsoft / axe-sarif-converter

An axe-core reporter that outputs axe scan results in SARIF format (http://sarifweb.azurewebsites.net/)

axe-sarif-converter

Convert axe-core accessibility scan results to the SARIF format. Provides both a TypeScript API and a CLI tool.

Use this with the Sarif Viewer Build Tab Azure DevOps Extension to visualize accessibility scan results in the build results of an Azure Pipelines build.

Usage

Before using axe-sarif-converter, you will need to run an axe accessibility scan to produce some axe results to convert. Typically, you would do this by using an axe integration library for your favorite browser automation tool (@axe-core/puppeteer, @axe-core/webdriverjs, cypress-axe).

axe-sarif-converter exports a single function, named convertAxeToSarif. Use it like this:

import * as Axe from 'axe-core';
import * as AxePuppeteer from '@axe-core/puppeteer';
import * as fs from 'fs';
import * as Puppeteer from 'puppeteer';
import * as util from 'util';

import { convertAxeToSarif, SarifLog } from 'axe-sarif-converter';

test('my accessibility test', async () => {
    // This example uses @axe-core/puppeteer, but you can use any axe-based
    // library that outputs axe scan results in the default axe output format
    const testPage: Puppeteer.Page = /* ... set up your test page ... */;
    const axeResults: Axe.AxeResults = await new AxePuppeteer(testPage).analyze();

    // Perform the conversion
    const sarifResults: SarifLog = convertAxeToSarif(axeResults);

    // Output a SARIF file, perhaps for use with a Sarif Viewer tool
    await util.promisify(fs.writeFile)(
        './test-results/my-accessibility-test.sarif',
        JSON.stringify(sarifResults),
        { encoding: 'utf8' });
}

You can also use axe-sarif-converter as a command line tool:

# @axe-core/cli is used here for example purposes only; you could also run axe-core
# using your library of choice and JSON.stringify the results.
npx @axe-core/cli https://accessibilityinsights.io --save ./sample-axe-results.json

npx axe-sarif-converter --input-files ./sample-axe-results.json --output-file ./sample-axe-results.sarif

See npx axe-sarif-converter --help for full command line option details.

Samples

The microsoft/axe-pipelines-samples project contains full sample code that walks you through integrating this library into your project, from writing a test to seeing results in Azure Pipelines.

Version numbers

The version number of this library is independent from the version numbers of the axe-core inputs and SARIF outputs it supports.

• axe-sarif-converter version 2.x supports input from version ^3.2.0 || ^4.0.0 of axe-core (tested with 3.2.2, 3.3.2, 3.4.1, 3.4.2, 3.5.1, 3.5.2, 3.5.3, 3.5.4, 3.5.5, 4.0.1, 4.0.2, 4.1.1, 4.2.0, 4.3.2, 4.4.1, and 4.6.3) and outputs SARIF v2.1
• axe-sarif-converter version 1.x supports input from version >= 3.2.0 < 3.3.0 of axe-core (tested with 3.2.2) and outputs SARIF v2.0

Note that the SARIF format does not use semantic versioning, and there are breaking changes between the v2.0 and v2.1 SARIF formats. If you need compatibility with a SARIF viewer that only supports v2.0, you should use version 1.x of this library.

Contributing

All contributions are welcome! To get started, please read through our CONTRIBUTING guidelines for this project.

Contributor License Agreement

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For more details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

axe-sarif-converter's Issues

This package requires yarn >1.15.1, seems really aggressive

I'm not sure what features are required from recent releases of yarn, but this makes it so that all your consumers will have to have a yarn version above 1.15. This likely isn't the most friction free way to consume this library. Perhaps you don't need this requirement?

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

Cannot push to the Git repository.

semantic-release cannot push the version tag to the branch master on the remote Git repository with URL https://9bc9d3d4fce3c998aae26054a59274e46a9d79b6%[email protected]/Microsoft/axe-sarif-converter.git.

This can be caused by:

• a misconfiguration of the repositoryUrl option
• the repository being unavailable
• or missing push permission for the user configured via the Git credentials on your CI environment

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

npm audit fails due to devDependency chain from semantic-release > ... > tar

npm (which we now consume as a devDependency via semantic-release) has been affected by high-sev vulnerability in v2 of the tar package for a week. Its fix appears to be held up by nodejs/node-gyp#1718.

Once there is a compatible update in the dependencies, this issue tracks bumping the semantic-release dependency version in our project appropriately.

Package is not yet published

Are there plans to publish this as a package? https://www.npmjs.com/search?q=axe-sarif-converter

We'd like to be able to depend on this rather than using our own copy.

Generated SARIF is incompatible with codeql schema

The generated sarif file produces output like:

locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/flaskapp/__init__.py",
                  "index": 0
                },
                "region": {
                  "snippet": {
                    "text": "<html>"
                  }
                }
              },
              "logicalLocations": [
                {
                  "fullyQualifiedName": "html",
                  "kind": "element"
                }
              ]
            }
          ]
        },

However, the Github CodeQL SARIF upload requires additional fields in the region to determine a line number. See schema:
https://github.com/oasis-tcs/sarif-spec/blob/main/Documents/CommitteeSpecifications/2.1.0/sarif-schema-2.1.0.json#L1709

Here is my sophisticated post-processing step for adding a line number:

sed -i 's/"snippet"/"startLine":1,"startColumn":1,"endColumn":1,"snippet"/g' src/tests/axe_results.sarif

That works, and results in scan results that look like this:

Obviously that is not very accurate, but it at least makes CodeQL happy.
Perhaps I should also open a pull request on https://github.com/github/codeql-action/issues?q=is%3Aissue+is%3Aopen+location for making those location fields optional. I'm not sure what the right approach is here, just opening this issue for discussion and posterity.

Axe version is hardcoded as 3.2.2 instead of inferred from input/environment

getAxeToolProperties currently hardcodes axe version 3.2.2, but it would be more correct for it to infer the axe version from the input file (for v2 input) or from environment data (for raw input).