KasperskyOS SDK Extension for Visual Studio Code

The KasperskyOS SDK Extension for Visual Studio Code (hereinafter also referred to as the KasperskyOS SDK Extension) integrates KasperskyOS Community Edition with the source code editor known as Visual Studio Code.

Installing and removing the extension

Installing dependencies

Extension dependencies are automatically installed from the Visual Studio Code Extension Marketplace. If your computer has access to the Visual Studio Code Extension Marketplace, you can skip the steps for setting dependencies below and instead proceed to the "Installing the extension" section.

Otherwise, you will need to manually set the dependencies for the extension. To set the dependencies of the KasperskyOS SDK Extension for Visual Studio Code:

1. On another computer that can access the Visual Studio Code Extension Marketplace, open the address https://marketplace.visualstudio.com/vscode in a browser.
2. Find and download the relevant extensions:
   • cpptools is required for working with the debugger.
   • clangd is required for static analysis of source code.
   • devcontainers is required for Docker support.
3. Copy the received VSIX files to the computer where you need to install the KasperskyOS SDK Extension.
4. Open the Visual Studio Code development environment.
5. Press F1.
6. Run the Extensions: Install from VSIX... command in the command line that opens in the upper part of the window.
7. Install the extensions that you downloaded at step 2.

Installing the extension

To install KasperskyOS SDK Extension, do the following:

1. Open the Visual Studio Code development environment.
2. Press F1.
3. Run the Extensions: Install from VSIX... command in the command line that opens in the upper part of the window.
4. Select the kos-extension-<version>.vsix extension file located in the directory /opt/KasperskyOS-Community-Edition-<version>/dev_tools/ide_integration/vscode/.

   During installation of the KasperskyOS SDK Extension, its dependencies are automatically set.

Removing the extension

To remove the extension, press the key combination CTRL+SHIFT+X, find the extension in the list, and select the Uninstall command from the context menu of the extension.

Extension functions

The extension automatically detects a KasperskyOS project in the open workspace and starts. The detection parameter is the presence of the .vscode/kos_project.json file or einit directory in the workspace. If the extension has not automatically activated in the directory but you are certain that it is a KasperskyOS project, run the command KOS: Activate extension in this directory. This command activates the extension and creates an empty .vscode/kos_project.json file in the project directory. To cancel manual activation, delete this file.

After startup, the extension adds the following buttons to the lower panel of the Visual Studio Code editor:

• – select the build target.
• – start the project in QEMU.
• – start the selected target with debugging.
• – build all targets.
• – build the selected target.
• – clear the build directory.
• – switch the build type.
• – enable/disable the project build with tests.
• – select the target platform for the build.
• – select the device or QEMU emulator.
• – display the SDK version.

Functions that provide buttons can also be called from the command line of the code editor, which can be opened by pressing F1. All commands have the KOS: prefix.

Working with a basic KasperskyOS image

The extension lets you avoid having to completely build a KasperskyOS-based solution after making changes to application code. Instead, you can use the following scenario:

1. Running a basic KasperskyOS-based solution image, included in the SDK, in the QEMU emulator. The basic image contains all the system programs required to run and debug programs packaged in KPA packages.
2. Build an application and package it into a KPA package. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Install a program from a KPA package into the solution image that was run at step 1 and start it under KasperskyOS.
4. Make changes to the application code.
5. Repeat steps 2–5.
6. With the extension, you can also debug a program that is running in a basic KasperskyOS image. For more details, refer to Debugging programs that are part of a KPA package.

Create a basic solution security policy description

The extension lets you automatically create basic solution security policy descriptions for a project.

To create a basic security policy description:

1. Make sure that the KasperskyOS SDK Extension is installed and active.
2. Press F1.
3. Run the command KOS: Generate policy file for current project.
4. Select the type of basic policy description that you want to create:
   • Grant all permissions: create a basic solution security policy description that allows all interactions between different processes of any class and between these processes and the KasperskyOS kernel, and that also allows any process to initialize the startup of processes.
   • Grant necessary permissions: create a basic solution security policy description that allows all interactions between different processes of any class and between these processes and the KasperskyOS kernel, and that also determines the necessary permissions for initializing the startup of processes based on the init.yaml.in file within the project.
5. Enter the file name for saving the created security policy description.

Running tests

After the extension is activated, the Testing tab () appears on the side panel of Visual Studio Code. When you select the Testing tab, the code editor window displays a tree of tests created using the Google Test library and found in files in the test/ directory.

To run the tests, tap the button. All detected tests are run by default. However, you can select specific tests on the tabs containing the source code of the tests, or you can select specific groups of tests by selecting them from the tree of all tests. You can only run tests that are added to CMakeLists.txt files for building programs using the kl_kos_add_small_test() or generate_kos_test() CMake commands from the TestGenerator CMake library included in the SDK.

The test results and log files are located in the directory <build_directory>/bin/tests/output.

Starting solution security policy tests

The extension lets you run solution security policy tests for a project if they were created based on the solution security policy description.

To build and run solution security policy tests:

1. Make sure that the solution security policy description contains the solution security policy tests.
2. Make sure that the CMake commands for building solution security policy tests have been added to one of the CMakeLists.txt files of the project.
3. Make sure that the KasperskyOS SDK Extension is installed and active.
4. Build all targets by clicking the button in the lower panel.
5. Click the build target selection button and select the target named kos-qemu-image-PalTest<N>-sim (N refers to the PSL file index within the list of PSL files containing solution security policy tests).
6. Click the button to build the selected target.

Starting a basic KasperskyOS-based solution image

The basic KasperskyOS-based solution image is included in the SDK and contains all the system programs required to run and debug programs packaged in KPA packages.

To start a basic KasperskyOS-based solution image from Visual Studio Code:

1. Make sure that the KasperskyOS SDK Extension is installed and active.
2. Click the device selection button on the lower panel or press F1 and run the command KOS: Select Device.
3. Select Create new emulator.
4. Select kos_base-dev.
5. In the opened field, enter the additional QEMU flags and press Enter, or immediately press Enter to use the default flags.
6. In the opened field, enter the name of the new emulator and press Enter, or immediately press Enter to use the automatically generated name.
7. Wait until the previous command completes.
8. In the notification about the new emulator being created, click the Start button.
9. Wait for the emulator to finish loading.

Building programs in Visual Studio Code

To build a program in Visual Studio Code:

1. Open the program project directory in Visual Studio Code.
2. Make sure that the project was correctly identified based on the appearance of additional extension buttons in the lower panel. If the buttons do not appear, manually activate the solution by running the command KOS: Activate extension in this directory.
3. Select the build architecture by clicking the button for selecting the target platform for the build .
4. Build all targets by clicking the button in the lower panel.

Starting programs in a basic solution image

If a program that you want to start uses file systems (via the VFS component), the following is required before starting the program:

1. Use the menu to open the extension settings window: File → Preferences → Settings, then select Extensions → KasperskyOS.
2. Set the client:kl.VfsSdCardFs value for the VFS_FILESYSTEM_BACKEND environment variable in the Application Environment Variables parameter.

To start a program in a basic solution image:

1. Open the program project directory in Visual Studio Code.
2. Make sure that the project was correctly identified based on the appearance of additional extension buttons in the lower panel. If the buttons do not appear, manually activate the solution by running the command KOS: Activate extension in this directory.
3. Make sure that the basic solution image is started according to the instructions provided in the Starting a basic KasperskyOS-based solution image section.
4. Click the button for selecting the device or QEMU emulator in the lower panel.
5. Select the previously started basic solution image.
6. Build the program according to the instructions provided in the Building a program in Visual Studio Code section.
7. Make sure that the program has been packed into a KPA package.

   You must use the CMake commands of the kpa library to pack a program into a KPA package.

8. Click the target selection button . In the drop-down list, select the built program KPA package that is signed as [application] in the list.
9. Click the start button . The program will be installed to the selected basic image and will automatically start.

Debugging a program that is part of a KPA package

Unlike debugging programs in a KasperskyOS-based solution, debugging a program in a KPA package means you don’t have to rebuild the entire KasperskyOS-based solution after updating the application code.

The scenario for debugging a program that is part of a KPA package looks as follows:

1. Install the KasperskyOS SDK Extension.
2. Build an application and package it into a KPA package. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Run a basic KasperskyOS image from KasperskyOS Community Edition with a GDB server built into the kernel.
4. Connect the debugger to the GDB server of the kernel. The debugger can be connected at program startup or while the program is running. Details:
   • Connecting a debugger at program startup.
   • Connecting a debugger while a program is running.
5. Debugging a program using the Visual Studio Code graphical user interface. For more details, refer to the Visual Studio Code documentation: https://code.visualstudio.com/docs/editor/debugging .

Connecting a debugger when starting a program in a basic image

To connect a debugger to the GDB server of the kernel while starting a program in QEMU using the Visual Studio Code extension:

1. Set a breakpoint in the program source code before the fragment to be debugged.
2. Build the program. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Run a basic KasperskyOS image from KasperskyOS Community Edition.
4. Wait for the basic image to finish loading and install the program by running the command KOS: Install package.
5. On the side bar of Visual Studio Code, click Run and debug > create a launch.json file and then select KasperskyOS Debugger.

   This will create a debug configuration file named launch.json.

6. In the launch.json file, in the field of the configuration named (kos/gdb) Launch & debug application, specify the path to the binary file of your program resulting from the build, and the program name. In the eiid field, you need to specify the kl.Kds value.
7. Start debugging by clicking the (kos/gdb) Launch & debug application button on the lower pane.
8. In the drop-down list, select the configuration named (kos/gdb) Launch & debug application.
9. The debug console will show a message stating that the program is ready for debugging. Click Continue, and program execution will be stopped at the breakpoint that you selected at step 1.

Connecting a debugger while a program is running from a basic image

To connect a debugger to the GDB server of the kernel while the program is running in QEMU using the Visual Studio Code extension:

1. Add an infinite loop to the main function of the program. This enables the debugger to connect to the running program.
2. Set a breakpoint in the program source code before the fragment to be debugged.
3. Build the program. You must use the CMake commands of the kpa library to pack a program into a KPA package.
4. Run a basic KasperskyOS image from KasperskyOS Community Edition.
5. On the side bar of Visual Studio Code, click Run and debug > create a launch.json file and then select KasperskyOS Debugger.

   This will create a debug configuration file named launch.json.

6. In the launch.json file, in the field of the configuration named (kos/gdb) Attach to process, specify the path to the binary file of your program resulting from the build.
7. Start the program in the basic image.
8. Start debugging by clicking the (kos/gdb) Attach to process button on the lower pane.
9. In the drop-down list, select the configuration named (kos/gdb) Attach to process and select the name of the program to debug.
10. The debug console will show a message stating that the program is ready for debugging. Click Continue, and program execution will be stopped at the breakpoint that you selected at step 2.

Extension settings

The extension settings are located in the Visual Studio Code storage, which can be called through the menu as follows: File → Preferences → Settings, then Extensions → KasperskyOS.

Extension settings

Application Arguments

List of command-line arguments for applications started with the extension.

Application Environment Variables

List of environment variables for applications started with the extension.

Auto_update

Enable/disable automatic updates of the extension when the SDK Path parameter is modified.

Build Threads Num

Select the quantity of processor threads used during the build. All available threads are used by default.

Cmake Build Flags

Additional CMake flags for the build.

Cmake Config Flags

Additional configuration flags for running CMake.

Auto Open Log Tab

Enable/disable automatic opening of the tab containing the command execution log.

Force Clean

The Clean button deletes the build directory.

Gdbinit File

Path to the gdbinit file containing the GDB commands that are executed when the debugger is started.

Run No Graphic

Enable/disable enforced startup of the emulator without a graphical user interface.

SDK Path

Path to the installed KasperskyOS Community Edition.

If the extension does not detect the correct SDK in the SDK Path at startup, you will be prompted to select an SDK from the list of detected SDKs. To avoid having to do this for each workspace, it is recommended to set the SDK Path for the User settings.

Set Build Dir

Project build directory. The ./build directory is used by default.

Shell Export Variables

Additional variables that are set before starting CMake.

Suppress Extensions Recommendations

Enable/disable the reminder that you need to set the dependencies of the KasperskyOS SDK Extension.

Test Failures Num

Number of failed tests displayed in the log.

Test Failures Only

Enable/disable display of only failed tests in the log.

Test Files Pattern

Mask for searching for files containing the source code of project tests.

Test No Skipped

Enable/disable display of skipped tests in the log.

Test Skip Details

Enable/disable display of skipped and failed tests in the log.

Test Threads Num

Select the quantity of processor threads used when running tests. All available threads are used by default. However, single tests will use one thread each.

Test Timeout

Time limit for running each test (in seconds). When this value is set to 0, the limits from the test configurations are applied.

Test Verbose

Enable/disable display of debug information about tests in the log.

Trace: Server

Select the level of logging detail for the Visual Studio Code LSP client when working with the LSP server built into the SDK for the IDL/CDL/EDL languages. You can view the LSP client log by selecting the nk-lsp channel in the Visual Studio Code output window.

User SDKs

Additional paths to SDKs for displaying the SDK selection menu