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.
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.
{
"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.
{
"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.
{
"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.
https://letsencrypt.org/2020/12/21/extending-android-compatibility.html
https://community.letsencrypt.org/t/production-chain-changes/150739
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:
The error message you are seeing and the content of the
Axivionoutput pane channel.The output of the OpenSSL command described in testing the Dashboard certificate configuration.
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.
{
"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.
{
"axivion.pathMappings": [
{
"analysisProject": "some-project",
"localPath": "C:\\Users\\User\\Project\\src"
}
]
}
{
"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.
{
"axivion.pathMappings": [
{
"analysisProject": "some-project",
"localPath": "C:\\Users\\User\\Project\\src",
"analysisPath": "path/relative/to/the/project/directory"
}
]
}
{
"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.
{
"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.
{
"axivion.axivionSuiteDirectory": "C:\\Program Files (x86)\\Bauhaus"
}
{
"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.
{
"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"
},
}
}
{
"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}).
{
"axivion.localBuild": {
"my-project": {
"command": "\"C:\\Users\\User\\Project With Spaces\\axivion\\start_analysis.bat\""
},
"my-other-project": {
"command": "\"${workspaceFolder}\\axivion\\start_analysis.bat\""
}
}
}
{
"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.
{
"axivion.axivionSuiteDirectory": "C:\\Program Files (x86)\\Bauhaus"
}
{
"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.
{
"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",
}
]
}
{
"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}).
:: 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"
# 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.
:: 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
# 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.
{
"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"
}
}
}
{
"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
{
"axivion.singleFileAnalysis": [
{
"bauhausConfig": "${workspaceFolder}\\axivion",
"command": "${workspaceFolder}\\axivion\\analysis.bat ${file}"
}
]
}
{
"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:
{
"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.