5.5.4. Configuration

To access the settings, open File > Preferences > Settings and navigate to Extensions > Axivion. Alternatively, open the Extensions sidebar panel and use the context menu on the Axivion extension to open the Extension Settings.

|vscodeplugin| Settings.

Axivion Visual Studio Code Plugin Settings

5.5.4.1. Connection to Axivion Dashboard Server

The Axivion Visual Studio Code Plugin accesses analysis results through the Axivion Dashboard Server. Therefore, the first step after installation is to configure access to the Axivion Dashboard Server.

Click Axivion Dashboards > Edit in settings.json and specify a workspace-unique, recognizable name as the Dashboard ID, the URL of the Axivion Dashboard Server, and the username you wish to use to log in to the Axivion Dashboard Server. The ID will be used in the Issues View to select the Axivion Dashboard Server to connect to. You can configure multiple Axivion Dashboard Servers.

Note

The settings.json mentioned throughout this section is the Visual Studio Code settings file, not a configuration file of the Axivion Suite.

Example for the Axivion Visual Studio Code Plugin Axivion Dashboard Server settings.
{
    "axivion.dashboards": [
        {
            "id": "user friendly Dashboard name",
            "url": "http://localhost:9090/axivion/"
        }
    ]
}

Please remember to save the settings.json file for the new configuration to take effect.

By default, anonymous authentication is used to connect to the Axivion Dashboard Server. The Axivion Dashboard Server must be configured to support anonymous authentication. You can specify a username per Axivion Dashboard Server in the Visual Studio Code settings.json.

Example for the Axivion Visual Studio Code Plugin Axivion Dashboard Server settings with a username.
{
    "axivion.dashboards": [
        {
            "id": "user friendly Dashboard name",
            "url": "http://localhost:9090/axivion/",
            "username": "my-username"
        }
    ]
}

Instead of hard-coding the username, you can retrieve it from an environment variable using the ${env:VARIABLE} syntax (see VSCode Variable Substitution). This is useful when the workspace settings.json is committed to source control and shared among developers working on the project. The environment variable holding the name of the current user is USER on GNU/Linux and macOS and USERNAME on Windows; the plugin treats these as interchangeable and falls back to the other if the specified variable is not set, so a single spelling works on all platforms.

Example for the Axivion Visual Studio Code Plugin Axivion Dashboard Server settings with the username taken from the environment.
{
    "axivion.dashboards": [
        {
            "id": "user friendly Dashboard name",
            "url": "http://localhost:9090/axivion/",
            "username": "${env:USER}"
        }
    ]
}

After the Axivion Dashboard Server is configured, open the Issues View pane (Ax Status Bar Icon > Axivion: Show Issues View) and select the Axivion Dashboard Server in the left-most combobox. On first use, this combobox shows the entry Offline (see Offline Local Build). If the dashboard configuration is correct and a username is configured, you should be prompted for the Axivion Dashboard Server password or an ApiToken.

If the Axivion Dashboard Server (version 7.13 or newer) offers OpenID Connect identity providers, the plugin first asks whether to enter a password or ApiToken, or to create an ApiToken with one of these providers. Creating an ApiToken opens the browser, where you log in with the provider and copy the ApiToken provided by the Axivion Dashboard Server. Paste it into the subsequent prompt.

The password/ApiToken is stored using the Visual Studio Code secret storage. Since Visual Studio Code 1.80, this storage no longer resides in the system keyring or the Windows Credential Manager. Instead, Visual Studio Code encrypts the secrets and stores them in its own database in the user data directory: %APPDATA%\Code\User\globalStorage\state.vscdb on Windows, ~/.config/Code/User/globalStorage/state.vscdb on Linux, and ~/Library/Application Support/Code/User/globalStorage/state.vscdb on macOS. Only the encryption key is protected by the operating system. On Windows, it uses the Data Protection API of the user account, so no further steps are required. On macOS, the key is kept in the Keychain as Code Safe Storage. On Linux, the key is kept in the keyring (GNOME Keyring via libsecret, or KWallet), so you may be asked for a password to unlock your keyring. If no keyring is available, Visual Studio Code shows a warning; see the Visual Studio Code documentation on the --password-store argument for available options.

After entering the correct password, you should be able to select an analysis project using the second combobox in the window and view the list of issues within that project. See Section Issue View for more details on the Issues View window.

If the connection to the Axivion Dashboard Server fails, an error message will be displayed in place of the issue list.

The password is transmitted to the Axivion Dashboard Server in clear text. Use HTTPS to prevent the password from being visible during transmission over the network.

If you are accessing the Axivion Dashboard Server over HTTPS and the server is using a self-signed certificate, you might receive the following error message:

Error while connecting to dashboard 'axivion.example.com':

request to https://axivion.example.com:9443/axivion/ failed, reason: unable to get local issuer certificate

Visual Studio Code (and therefore the Axivion Visual Studio Code Plugin) uses the system certificate store. Installing the root certificate of the Dashboard certificate should fix this error. https://code.visualstudio.com/docs/setup/network#_ssl-certificates

Caution

The error message

request to https://axivion.example.com:9443/axivion/ failed, reason: unable to verify the first certificate

indicates that the Axivion Dashboard Server only provides the server certificate during the TLS handshake. Consequently, Visual Studio Code fails to build and verify the certificate chain.

Visual Studio Code uses the system certificate store to retrieve the root certificate (trust anchor), but it does not read intermediate certificates from that store. Therefore, for the Axivion Visual Studio Code Plugin to work, it is crucial that the Axivion Dashboard Server delivers the entire certificate chain.

Caution

The error message

request to https://axivion.example.com:9443/axivion/ failed, reason: certificate has expired

in combination with a Let’s Encrypt certificate (New Default Chain) indicates an incompatibility between Visual Studio Code and the Let’s Encrypt workaround for old Android devices.

Switching to the Alternative Chain should fix the problem. For certbot, the option preferred-chain = ISRG Root X1 (on the command line or in the file cli.ini, see https://community.letsencrypt.org/t/what-is-the-chain-to-pass-to-preferred-chain-argument-to-keep-using-dst-root-x3-root-certificate/137889 ) can be used.

The New Default Chain and the Alternative Chain differ only in the intermediate certificates the server (Axivion Dashboard Server) provides during the TLS handshake. The New Default Chain contains one more certificate than the Alternative Chain:

Subject: C = US, O = Internet Security Research Group, CN = ISRG Root X1
Issuer: O = Digital Signature Trust Co., CN = DST Root CA X3
Serial number: 4001772137d4e942b8ee76aa3c640ab7
Thumbprint MD5: C1E1 FF07 F9F6 8849 8274 D1A1 8053 EABF
Thumbprint SHA-1: 933C 6DDE E95C 9C41 A40F 9F50 493D 82BE 03AD 87BF
Thumbprint SHA-256: 6D99 FB26 5EB1 C5B3 7447 65FC BC64 8F3C D8E1 BFFA FDC4 C2F9 9B9D 47CF 7FF1 C24F

As a workaround, remove this certificate from the certificate chain delivered by the server (Axivion Dashboard Server or a reverse proxy in front of the dashboard).

Note

If you encounter certificate or TLS connection problems and require support from Axivion, please provide the following information in your support request email:

5.5.4.2. Path Mapping

Issues found by the Axivion Suite analysis reference files on the build machine where the analysis was performed. In contrast, the Visual Studio Code editor operates on local files on the developer’s machine.

The path mapping in the Axivion Visual Studio Code Plugin defines the mapping between local paths and analysis projects. This allows the plugin to jump to the corresponding local file when double-clicking an issue in the Issues View window. Conversely, when opening a local file in the Visual Studio Code editor, the path mapping is used to determine the corresponding analysis project and file, and all the issues found in the latest analysis of that file are shown in the breakpoint margin.

The path mapping configuration is stored in the Visual Studio Code settings.json. This can be the user settings.json file or a workspace settings.json that is committed to source control and shared by all developers working on the project.

Alternatively, the path mapping configuration can be stored in the “Global configuration” (%USERPROFILE%\.bauhaus\launcher.config on Windows, $HOME/.bauhaus/launcher.config on GNU/Linux and macOS).

Configuration of the Path Mapping

The Axivion Visual Studio Code Plugin can attempt to infer the path mapping automatically based on a local path. This is triggered by double-clicking an issue in the Issues View. If no matching path mapping is defined for the current project, the Axivion Visual Studio Code Plugin searches for files inside the current workspace that match the file path. The search is limited to five seconds and returns all files matched within this period.

If candidates are found, the user can choose one of the suggested files or select “Search manually”. If the user selects “Search manually”, cancels the automatic search, or if the Axivion Visual Studio Code Plugin does not find any local path candidates, a file explorer window opens, prompting the user to locate the file containing the issue. If successful, a path mapping entry is generated in either the workspace/user settings.json or the “Global configuration” (launcher.config).

The default storage location for generated path mappings is specified by the defaultSettingsSource property (options: workspace | user | global). This property also determines the settings.json file where the Axivion Visual Studio Code Plugin adds a generated Local Build configuration or Axivion Dashboard Server entry. For these, global selects the workspace settings.json.

Example for the default storage place of generated path mappings.
{
    "axivion.defaultSettingsSource": "workspace"
}

To configure the path mapping manually, open the settings for the Axivion extension and select Axivion Path Mappings > Edit in settings.json. This opens a list of path mapping configurations. Specify a project name from the projects available in your configured Axivion Dashboard Server and assign a local path to it so that the Axivion Visual Studio Code Plugin can open the correct file. The local path denotes a directory that corresponds to the project directory of the analysis (option /Project/directory). It is stored as an absolute path in your file system.

Example for the Axivion Visual Studio Code Plugin path mapping settings on Windows.
{
    "axivion.pathMappings": [
        {
            "analysisProject": "some-project",
            "localPath": "C:\\Users\\User\\Project\\src"
        }
    ]
}
Example for the Axivion Visual Studio Code Plugin path mapping settings on GNU/Linux and macOS.
{
    "axivion.pathMappings": [
        {
            "analysisProject": "some-project",
            "localPath": "/home/user/Project/src"
        }
    ]
}

Please remember to save the settings.json file for the new configuration to take effect.

Optionally, you can specify an analysis path prefix for which the mapping should be applied. Every issue path retrieved from the Axivion Dashboard Server that matches this analysis path is redirected to your local path. This is useful if only some parts of the analyzed source code are available locally.

The analysis path is a relative path describing a directory within the analysis project (relative to the project directory, /Project/directory). If left empty, the mapping entry refers to the project directory.

Example for the Axivion Visual Studio Code Plugin path mapping settings with analysis path on Windows.
{
    "axivion.pathMappings": [
        {
            "analysisProject": "some-project",
            "localPath": "C:\\Users\\User\\Project\\src",
            "analysisPath": "path/relative/to/the/project/directory"
        }
    ]
}
Example for the Axivion Visual Studio Code Plugin path mapping settings with analysis path on GNU/Linux and macOS.
{
    "axivion.pathMappings": [
        {
            "analysisProject": "some-project",
            "localPath": "/home/user/Project/src",
            "analysisPath": "path/relative/to/the/project/directory"
        }
    ]
}

The Axivion Visual Studio Code Plugin supports a wildcard project name: *. This attempts to match the path mapping for every project. This special path mapping can be useful when working with remote workspaces.

Special project name path mapping.
{
    "axivion.pathMappings": [
        {
            "analysisProject": "*",
            "localPath": "${workspaceFolder}"
        }
    ]
}

A more detailed example of a configuration can be found in the documentation of the Axivion Visual Studio Plugin in Section Example Configuration.

5.5.4.3. Local Build Settings

For Local Build to work, the Axivion Visual Studio Code Plugin requires access to your locally installed Axivion Suite. You can either configure it as follows or ensure the Axivion Suite directory is included in your PATH environment variable.

Example for the Axivion Visual Studio Code Plugin Axivion Suite setting on Windows.
{
    "axivion.axivionSuiteDirectory": "C:\\Program Files (x86)\\Bauhaus"
}
Example for the Axivion Visual Studio Code Plugin Axivion Suite setting on GNU/Linux and macOS.
{
    "axivion.axivionSuiteDirectory": "/opt/bauhaus-suite"
}

To configure Local Build, specify the command that triggers the analysis. Please refer to Starting Local Build from within the IDE Plugins.

If you have multiple versions of Axivion Suite installed, you can choose which one to use for each project by overriding the global axivionSuiteDirectory setting.

Example for the Axivion Visual Studio Code Plugin Local Build project settings on Windows.
{
    "axivion.localBuild": {
        "some-project": {
            "command": "analysis.bat"
        },
        "second-project": {
            "command": "C:\\Users\\User\\Project\\axivion\\start_analysis.bat",
            "axivionSuiteDirectory": "C:\\Tools\\Bauhaus-7.11"
        },
        "*": {
            "command": "my-works-with-all-projects.bat"
        },
    }
}
Example for the Axivion Visual Studio Code Plugin Local Build project settings on GNU/Linux and macOS.
{
    "axivion.localBuild": {
        "some-project": {
            "command": "analysis.sh"
        },
        "second-project": {
            "command": "/home/user/Project/axivion/start_analysis.sh",
            "axivionSuiteDirectory": "/opt/bauhaus-suite-7.11"
        },
        "*": {
            "command": "my-works-with-all-projects.sh"
        },
    }
}

The entry * is used for any project that does not have its own entry.

When starting a Local Build for a project without a Local Build configuration, the Axivion Visual Studio Code Plugin offers to create one using the command ${workspaceFolder}/axivion/start_analysis.bat (start_analysis.sh on GNU/Linux and macOS). The configuration is added to the settings.json selected by defaultSettingsSource.

Caution

Ensure that any special characters in the command value are correctly escaped (this also applies to variables such as ${workspaceFolder}).

Example escaping in the Axivion Visual Studio Code Plugin Local Build project settings on Windows.
{
    "axivion.localBuild": {
        "my-project": {
            "command": "\"C:\\Users\\User\\Project With Spaces\\axivion\\start_analysis.bat\""
        },
        "my-other-project": {
            "command": "\"${workspaceFolder}\\axivion\\start_analysis.bat\""
        }
    }
}
Example escaping in the Axivion Visual Studio Code Plugin Local Build project settings on GNU/Linux and macOS.
{
    "axivion.localBuild": {
        "my-project": {
            "command": "\"/home/user/Project With Spaces/axivion/start_analysis.sh\""
        },
        "my-other-project": {
            "command": "\"${workspaceFolder}/axivion/start_analysis.sh\""
        }
    }
}

5.5.4.4. Single-File Analysis Settings

For Single-File Analysis to work, the Axivion Visual Studio Code Plugin needs access to your locally installed Axivion Suite. You can either configure it as follows or ensure the Axivion Suite directory is included in your PATH environment variable.

Example for the Axivion Visual Studio Code Plugin Axivion Suite setting on Windows.
{
    "axivion.axivionSuiteDirectory": "C:\\Program Files (x86)\\Bauhaus"
}
Example for the Axivion Visual Studio Code Plugin Axivion Suite setting on GNU/Linux and macOS.
{
    "axivion.axivionSuiteDirectory": "/opt/bauhaus-suite"
}

The Single-File Analysis command should point to an executable. It is responsible for creating an IR for the analyzed file and calling the analyzer tool axivion_analysis. The bauhausConfig property points to the configuration directory of the analyzer tool. It corresponds to the BAUHAUS_CONFIG variable. When starting Single-File Analysis, you will be prompted to select one of the existing Single-File Analysis configurations if multiple are available.

Example for the Axivion Visual Studio Code Plugin Single-File Analysis settings on Windows.
{
    "axivion.singleFileAnalysis": [
        {
            "command": "${workspaceFolder}\\axivion\\single_file_analysis_variant_1.bat ${file}",
            "bauhausConfig": "${workspaceFolder}\\axivion",
        },
        {
            "command": "${workspaceFolder}\\axivion\\single_file_analysis_variant_2.bat ${file}",
            "bauhausConfig": "${workspaceFolder}\\axivion",
        }
    ]
}
Example for the Axivion Visual Studio Code Plugin Single-File Analysis settings on GNU/Linux and macOS.
{
    "axivion.singleFileAnalysis": [
        {
            "command": "${workspaceFolder}/axivion/single_file_analysis_variant_1.sh ${file}",
            "bauhausConfig": "${workspaceFolder}/axivion",
        },
        {
            "command": "${workspaceFolder}/axivion/single_file_analysis_variant_2.sh ${file}",
            "bauhausConfig": "${workspaceFolder}/axivion",
        }
    ]
}

See VSCode Variable Substitution for supported variable substitutions in the command property.

Caution

Ensure that any special characters in the command value are correctly escaped (this also applies to variables such as ${workspaceFolder}).

Example single_file_analysis.bat on Windows
:: 1. Execute the Axivion compiler on source file "%1" to produce a Unit IR file.
cafeCC -B. -c -o "%1.o.ir" "%1"

:: 2. Execute the actual payload analysis on the Unit IR file from step 1.
axivion_analysis --output - --quiet --ir "%1.o.ir"
Example single_file_analysis.sh on GNU/Linux and macOS
# 1. Execute the Axivion compiler on source file "$1" to produce a Unit IR file.
cafeCC -B. -c -o "$1.o.ir" "$1"

# 2. Execute the actual payload analysis on the Unit IR file from step 1.
axivion_analysis --output - --quiet --ir "$1.o.ir"

Note

The example above is for illustrative purposes only and is not a working solution. You must adjust the compiler invocation call to suit your specific project.

When using any of the build integrations CompileCommandsIntegration, IARIntegration, KeilIntegration, RenesasIntegration or any of their command-line counterparts (build_compile_commands, build_ewp, build_uvprojx, build_rcpe), you can directly invoke a single-file analysis using the corresponding command-line tools as follows. The script contains only the line for the build integration you use.

Example single_file_analysis.bat on Windows
:: CompileCommandsIntegration (or CMakeIntegration)
build_compile_commands --single_file "%1" build_axivion/compile_commands.json

:: IARIntegration
build_ewp --single_file "%1" MyProject.ewp

:: KeilIntegration
build_uvprojx --single_file "%1" MyProject.uvprojx

:: RenesasIntegration
build_rcpe --single_file "%1" MyProject.rcpe
Example single_file_analysis.sh on GNU/Linux and macOS
# CompileCommandsIntegration (or CMakeIntegration)
build_compile_commands --single_file "$1" build_axivion/compile_commands.json

# IARIntegration
build_ewp --single_file "$1" MyProject.ewp

# KeilIntegration
build_uvprojx --single_file "$1" MyProject.uvprojx

# RenesasIntegration
build_rcpe --single_file "$1" MyProject.rcpe

5.5.4.5. VSCode Variable Substitution

VSCode does not provide built-in support for variable substitution in configuration files (settings.json) as it does for tasks.json and launch.json. See https://code.visualstudio.com/docs/editor/variables-reference. We have included support for the ${workspaceFolder} variable in the properties listed below.

Example for the Axivion Visual Studio Code Plugin settings with workspace folder substitution on Windows.
{
    "axivion.pathMappings": [
        {
            "analysisProject": "some-project",
            "localPath": "${workspaceFolder}\\src"
        }
    ],
    "axivion.axivionSuiteDirectory": "${workspaceFolder}\\third-party\\tools\\Bauhaus",
    "axivion.localBuild": {
        "some-project": {
            "command": "${workspaceFolder}\\axivion\\analysis.bat",
            "axivionSuiteDirectory": "${workspaceFolder}\\third-party\\tools\\Bauhaus-7.11"
        }
    }
}
Example for the Axivion Visual Studio Code Plugin settings with workspace folder substitution on GNU/Linux and macOS.
{
    "axivion.pathMappings": [
        {
            "analysisProject": "some-project",
            "localPath": "${workspaceFolder}/src"
        }
    ],
    "axivion.axivionSuiteDirectory": "${workspaceFolder}/third-party/tools/bauhaus-suite",
    "axivion.localBuild": {
        "some-project": {
            "command": "${workspaceFolder}/axivion/analysis.sh",
            "axivionSuiteDirectory": "${workspaceFolder}/third-party/tools/bauhaus-suite-7.11"
        }
    }
}

In a code workspace with multiple workspace folders, ${workspaceFolder:<workspace_name>} is also supported, where <workspace_name> is the name of the workspace folder as shown in the VSCode explorer view.

Substitution of the ${workspaceRoot} variable is also supported, but its use is strongly discouraged as it has been deprecated. See https://code.visualstudio.com/docs/editor/variables-reference#_why-isnt-workspaceroot-documented.

For the axivion.singleFileAnalysis.command property, we support the following variables, which are also commonly used in tasks.json:

${file} - the currently opened file
${fileWorkspaceFolder} - the currently opened file's workspace folder
${relativeFile} - the currently opened file relative to workspaceFolder
${relativeFileDirname} - the currently opened file's dirname relative to workspaceFolder
${fileBasename} - the currently opened file's basename
${fileBasenameNoExtension} - the currently opened file's basename with no file extension
${fileDirname} - the currently opened file's dirname
${fileExtname} - the currently opened file's extension
Example for the single file analysis command with variable substitution on Windows.
{
    "axivion.singleFileAnalysis": [
        {
            "bauhausConfig": "${workspaceFolder}\\axivion",
            "command": "${workspaceFolder}\\axivion\\analysis.bat ${file}"
        }
    ]
}
Example for the single file analysis command with variable substitution on GNU/Linux and macOS.
{
    "axivion.singleFileAnalysis": [
        {
            "bauhausConfig": "${workspaceFolder}/axivion",
            "command": "${workspaceFolder}/axivion/analysis.sh ${file}"
        }
    ]
}

Environment variable substitution is supported using the ${env:VARIABLE} syntax, where VARIABLE is the name of the environment variable known to VSCode at startup:

Example for the Axivion Visual Studio Code Plugin settings with environment variable substitution.
{
   "axivion.dashboards": [
     {
       "id": "...",
       "username": "${env:USER}",
       "url": "..."
     },
   ],
   "axivion.axivionSuiteDirectory": "${env:TOOLS_PATH}/bauhaus-suite",
}

The variables USER (set on GNU/Linux and macOS) and USERNAME (set on Windows) are interchangeable; if one is not set, the other is used. Therefore, the example above also works on Windows.