# Sonatype for VS Code

Sonatype for VS Code extension allows you to surface and remediate issues in your workspace dependencies, a true Shift Left in application security for development teams.

The Sonatype for VS Code extension is available on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=SonatypeIntegrations.iq-vscode-plugin).

## Supported Languages and Ecosystems

- Java (Maven and Gradle)
- JavaScript (npm, pnpm, and Yarn)
- Go (Go modules)
- Python (Poetry, pip)
- Rust (Cargo)
- PHP (Composer)
- C (Conan (1.x only))
- CycloneDX (SBOM standard)

## Changelog

### Version 1.8.3 (July 07, 2026)
- Improved component detection for maven projects

### Version 1.8.2 (March 03, 2026)
- Fixed an issue where the VS code `http.noProxy` setting was ignored for excluded hosts
- Fixed a timeout issue when performing policy evaluation against IQ Server for environments with many applications

### Version 1.8.1 (November 10, 2025)
- Fixed issue where users assigned to the ‘Component Evaluator’ role in IQ Server fail to trigger scan

### Version 1.8.0 (June 13, 2025)
- Added support for analyzing CycloneDx JSON files
- Improved error reporting when local tooling is not available

### Version 1.6.0 (April 17, 2025)
- Added Yarn 4 support

### Version 1.4.1 (April 4, 2025)
- Optimized fetching by requesting only the required application during scans

### Version 1.4.0 (November 18, 2024)
- Added support for limiting the number of component versions shown in Version History
- Added support for scanning subfolders

### Version 1.2.0 (October 22, 2024)
- Added support for Golden Versions, the non-breaking upgrade resolving policy violations for the component and its dependencies

### Version 1.0.9 (September 23, 2024)
- Added support to configure an alternate path for the pip virtual environment folder in the .sonatype-config file
- Improved recommendations for Python components

### Version 1.0.8 (August 28, 2024)
- Fixed issue where empty dependencies were being displayed
- Fixed issue where a trailing slash in the IQ Server URL was breaking links in the Component Details view
- Improved Gradle documentation

### Version 1.0.7 (June 17, 2024)
- Added support for scanning pnpm projects

### Version 1.0.6 (May 29, 2024)
- Added support for proxy usage within VSCode
- Added support for WSL and Devcontainers
- Fixed Pip analysis was considering all global components instead of just the ones in each project

### Version 1.0.5 (May 1, 2024)
- Updated documentation and minor improvements

### Version 1.0.4 (April 30, 2024)
- Added configuration to accept non-strict SSL connections

### Version 1.0.3 (April 26, 2024)
- Added support to configure an alternate path for the user settings.xml file for maven projects in .sonatype-config

### Version 1.0.2 (April 22, 2024)
- Minor bug fixes

### Version 1.0.1 (April 15, 2024)
- Improved component detection for Go (Go modules) projects
- Minor improvement in component detection for Python (Poetry) projects

### Version 1.0.0 (April 9, 2024)
- Initial release

## Installing Sonatype for VS Code

Sonatype for VS Code can be installed from within VS Code using the Extensions Manager or via the [Microsoft Marketplace](https://marketplace.visualstudio.com/items?itemName=SonatypeIntegrations.iq-vscode-plugin). The extension can be run in local VS Code, VS Code hosted in GitHub Codespaces, and supports Visual Studio Code Dev Containers as well as WSL2.

### Verifying Local Build-Tool Availability

For the extension to analyze your project, your project’s build tool must be available within the VS Code environment. You can verify that the necessary command-line tool is installed and accessible by opening a new terminal in VS Code (**Terminal** > **New Terminal**) and running the appropriate version command:

- **Maven**: `mvn -v`
- **Go**: `go version`
- **Gradle**: `gradle -v`
- **npm**: `npm -v`
- **pnpm**: `pnpm -v`
- **Yarn**: `yarn -v`
- **Pip**: `pip -V`

## Configuring Sonatype for VS Code

At a minimum, the extension requires the IQ Server URL and the credentials to be set.

You can set up the URL and username by opening the extension settings in VS Code: _Settings > Extensions > Sonatype for VS Code_

The password can be entered in two ways:

- Open the command palette by pressing `Command + Shift + P` on Mac or `Control + Shift + P` on Windows, and then enter the `Sonatype: Set IQ Server Password` command after the `>` prefix. If you want to clear the stored password, you can use the `Sonatype: Clear IQ Server Password` command.

- You can also use the SONATYPE_IQ_PASSWORD environmental variable. This method requires the "Use Environment Variable for Password" checkbox to be selected in the extension settings. You might need to restart VS Code for the changes to be recognized.

In the extension settings, enter the Default Application ID before running the component analysis. This is required to use the appropriately scoped policy set for your application.

You can configure additional settings such as:

- Including or excluding development dependencies from the overall analysis.
- Parallelization - higher values mean the component analysis will be faster, but it requires more resources from VS Code; lower values mean the component analysis will be slower, but it will have less impact on VS Code's performance.
- Starting the Analysis on VS Code Startup for the opened workspace.
- Restricting the number of versions shown in the Version History view that are older than the version in use. Default is 10, but you can change it based on your preferences.

### Overriding the Configuration At Project Level

You can override the properties by including a Sonatype configuration file in the project's root folder with one of the following filenames:

- `.sonatype-config`
- `.sonatype-config.yml`
- `.sonatype-config.yaml`

In this file, you can choose at per project (workspace folder) level which Lifecycle application is used for analysis; whether to include or exclude development dependencies; and you can also enforce the ecosystem for the current project (you may want to do this to exclude analysis of a certain ecosystem in a given folder or to specify only certain ecosystems to be analyzed).

Syntax with examples is as follows:

```
iq-for-vscode:
  applicationId: application-id-in-lifecycle
  includeDev: false
  type: ['maven', 'npm']
```

Possible values for the `type` field above are: 'maven', 'gradle', 'npm', 'yarn', 'go', 'pip', 'poetry', 'cargo', 'composer', and 'conan'.

For Maven, the `settings.xml` to be used can also be overridden. The path to the `settings.xml` can be specified as follows:

```
iq-for-vscode:
  maven:
    settingsXmlPath: '/.m2/alternative-settings.xml'
```

For pnpm, the default list depth for transitive dependencies is set to 4. This setting can be overridden as follows:

```
iq-for-vscode:
  pnpm:
    listDepth: 8
```

### Additional Properties

`lookupfolders`

By default, Sonatype for VS Code only scans the root folder of the workspace. With the `lookupfolders` property, you can set up custom folders to be analyzed as well.

Subfolders provided in the `lookupfolders` property must be relative to the root folder and can be input as follows:

```
iq-for-vscode:
  lookupFolders: ['subfolder', 'another/sub/folder']
```

Subfolders can have their own `.sonatype-config` files. A `.sonatype-config` file in a subfolder overrides the root folder's configuration.

## Using Sonatype for VS Code

### Running the Analysis

Component analysis provides detailed information on the components of the projects opened in the workspace of the VS Code.

If “Start Component Analysis On Load” is selected in the extension settings, analysis will run once the workspace has loaded in VS Code.

If it’s not selected, you can start the analysis by clicking the **Run Component Analysis** button in the Sonatype panel.

### Language and Ecosystem Identification

#### Java

##### Maven

`pom.xml` must exist in the project's root folder and an installation of `mvn` must be present.

##### Gradle

One of `settings.gradle`, `build.gradle` or `build.gradle.kts` must exist in the project's root folder and an installation of `gradle` must be present.

The extension relies on the following configurations to build the dependency tree:

- `runtimeClasspath` - if the "Include Development Dependencies" flag is disabled in settings, or
- `testRuntimeClasspath` - if "Include Development Dependencies" is enabled.

Developers can also define custom configurations derived from the standard ones. However, the extension does not currently handle these custom configurations. Refer to the [Java plugin documentation](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_plugin_and_dependency_management) for more details on Java dependency management with Gradle.

#### Javascript

##### npm

`package.json` and `package-lock.json` must exist in the project's root folder and an installation of `npm` must be present.

##### pnpm

`package.json` and `pnpm-lock.yaml` must exist in the project's root folder and an installation of `pnpm` must be present.

##### Yarn

`package.json` and `yarn.lock` must exist in the project's root folder and an installation of `yarn` must be present.

#### Go

`go.mod` and `go.sum` must exist in the project's root folder and an installation of `go` must be present.

#### Python

##### Poetry

- `pyproject.toml` and `poetry.lock` must exist in the project's root folder.

##### pip

- `requirements.txt` must exist in the project's root folder and an installation of `pip`, `pip2` or `pip3` must be present.
- Components must be installed in the virtual environment prior to scanning as only the installed components will be discovered.
- If a virtual environment exists in the `venv`, `.venv`, or your project's root directory, it will be automatically detected and used. Alternatively, you can override the default virtual environment location by specifying a custom path in the `sonatype-config` file as follows:

```
pip:
    venvPath: /customVenv
```

#### Rust

##### Cargo

- `cargo.toml` and `cargo.lock` must exist in the project's root folder.

#### PHP

##### Composer

- `composer.lock` must exist in the project's root folder.

#### C

##### Conan

- `conan.lock` must exist in the project's root folder.

#### CycloneDX

- Workspace scans don’t automatically detect CycloneDX SBOMs. To analyze one, right-click any file whose name ends with `-bom.json` and choose Sonatype SBOM Analysis to inspect its components.

### Inspecting the Results

Once the analysis is complete, dependencies for each project opened in the workspace will appear in the Component Tree tab under the Sonatype panel.

You can select a component to see its details in a new tab. The Component Versions view will list all versions of this component together with their highest policy violation scores, and the recommended version for the given project. A version of a dependency with no policy violations and no breaking changes for the same component and its dependencies will be presented as a Golden Version, which means that the migration can be done with minimal effort. Alternate versions might also be available so you can migrate to them in case there is no Golden Version available.

### Component Filters

Both the Component Tree view and the Version History view can be filtered by Threat Levels using the filter icon on the menu bar of each view.

### Re-Running the Analysis

After required actions are taken, you can run the analysis again by clicking on the ⟳ icon on the menu bar of Component Tree view.

### Known Limitations

The extension has support for resolving transitive dependencies and including/excluding development dependencies, with the following exceptions:
- A dependency tree cannot be built for Pip; all dependencies are shown in a flat list.
- Dependency scope information is not supported for Pip and Go

### Troubleshooting using the Output Console

The Sonatype for VS Code extension writes detailed operational logs to its own output channel. This is useful for observing the analysis process or diagnosing issues. To filter the view to show only logs generated by this extension:

1. Open the Output panel (**View** > **Output**).
2. From the dropdown menu on the right of the panel, next to _Filter_, select **SonatypeIntegrations.iq-vscode-plugin**.

3. To increase logging for troubleshooting, select the gear icon in the Output panel and set the log level to Trace for the **SonatypeIntegrations.iq-vscode-plugin** output channel. You can also use the Filter field to search the logs for relevant entries such as error, mvn, or npm.