4.7. Setup Guide for External Analysis Tools

This guide describes how to run third-party analysis tools and import their findings into the Axivion Dashboard Server, so that the findings appear next to the results of the Axivion Suite. The imported findings are handled like style violations: they can be filtered, suppressed, and tracked over time.

4.7.1. Importers for known tools

The following rules run a specific tool, parse its report, and import the findings. They are located in the ImportThirdPartyAnalysisResults group. The group is not activated as a whole; activate the rules for the tools you use.

Rule

Tool

Notes

ImportClippy

Clippy (Rust)

config_file is the Cargo.toml of the crate.

ImportDetekt

detekt (Kotlin)

Runs gradlew detekt and reads the Checkstyle XML report of the Gradle plugin.

ImportESLint

ESLint (JavaScript, TypeScript)

Prefers the eslint executable in node_modules/.bin relative to the directory where the tool runs.

ImportKnip

knip (JavaScript, TypeScript)

Requires knip 6.35 or later.

ImportPMD

PMD (Java)

config_file is the ruleset; source_directories and exclude_paths select the sources.

ImportPylint

pylint (Python)

ImportPyright

pyright (Python)

Pass the files or directories to check in additional_args.

ImportQMLLint

qmllint (QML)

qml_files selects the files to check.

ImportRuff

Ruff (Python)

ImportSpotBugs

SpotBugs (Java)

Pass the class files in additional_args; set source_directories to map findings to sources.

ImportTypos

typos

config_file is required.

4.7.1.1. Setup

  1. Install the tool on the machine that runs the analysis, or note the path to its executable.

  2. Activate the rule for the tool in the ImportThirdPartyAnalysisResults group.

  3. Optionally set cwd to the directory in which the tool runs. If unset, the current working directory is used. Relative paths in the other options, and the file paths in the tool’s report, are interpreted relative to it.

  4. Set executable if the tool is not on PATH.

  5. Set config_file if the rule offers it. The rule then passes the file to the tool and disables the tool’s own configuration lookup, so that the results do not depend on configuration files in the analyzed sources.

  6. Pass tool-specific arguments, such as the files to check, in additional_args.

All these rules have the following options in common:

cwd

The directory in which the tool runs. If unset, the current working directory is used.

executable

The path to the tool’s executable. If unset, the tool is looked up on PATH.

config_file

The tool’s configuration file, relative to cwd.

additional_args

Additional arguments for the tool, passed on unquoted and unfiltered.

environment

Additional environment variables for the tool.

check_returncode

Whether a non-zero exit status from the tool causes the rule to fail. Most linters exit with a non-zero status when they report findings, so the rules for such tools set this to false. A run that imports no findings while the tool exits non-zero always fails.

provider

The name under which the findings are shown in the Axivion Dashboard Server.

encoding and encoding_error_handler

The encoding of the tool’s output and how to handle undecodable characters.

If you need to run a tool several times, for example for several projects, copy the rule in the configuration and give each copy its own options.

4.7.2. Importing reports of other tools

For tools without a dedicated rule, use one of the following rules.

ImportSarifReport

Runs a tool that emits a SARIF 2.1.0 report and imports the report. The report is read from the tool’s standard output or from the file named by report_location. Unless provider is set, the provider is the name of the tool used in each SARIF run.

ImportCheckstyleReport

Runs a tool that emits a Checkstyle-format XML report and imports the report. report_location and provider work as they do for ImportSarifReport. The provider defaults to checkstyle.

Both rules take the executable and its arguments from executable and additional_args. Pass the flags that instruct the tool to write the report in that format, for example ["--format", "checkstyle"].

ImportExternalAnalysisOutput

Runs a command and matches its output line by line against regular expressions. The expressions are configured as formats in the ExternalAnalysisFormats group. Use this rule for tools that only print text.

  1. Add a rule to ExternalAnalysisFormats and set its provider. Its regular expression must define the named groups for the parts of a finding, for example filename, line, message, and errno.

  2. Set command and options of ImportExternalAnalysisOutput. Set execute_as_shell_command if the command requires a shell.

  3. Set capture_stdout_provider and capture_stderr_provider to the provider of the format that matches the respective output.

  4. Use strip_path_prefix and prepend_path_prefix to turn the reported paths into paths relative to the project directory.

Miscellaneous-ImportCSV

Imports findings from a CSV file that another process has already written. Set filename to the file and map its columns with the column_* options. strip_prefix and prepend_prefix canonicalize the file paths. This rule does not run a tool.

C#-ImportCompilerAndAnalyzerDiagnostics

Imports the warnings and errors of the C# compiler and Roslyn analyzers. See Source Code Analysis Setup Guide for C#/.NET.

4.7.3. Running the import

The importers run as part of the analysis, for example when you run axivion_ci. They require no build step. If a tool is missing or fails without producing findings, the rule fails instead of reporting that the tool found nothing.

Imported findings are suppressed and justified like other findings. See Exclude, Suppress and Justify Analysis Results for details.

4.7.4. References