Retrieves | VSCode Plugin for Vulnerability Management | Fluid Attacks Help

Introduction

Retrieves is the product responsible for the VSCode plugin. It communicates with the Integrates API to fetch live vulnerability data and mark it in users’ editors.

Internals

  1. Retrieves is written in Typescript with React used for the Webview section. Webpack bundles the code deployed to the marketplace.

    2. When telemetry is enabled, debugging information is reported/logged to Bugsnag, where developers can use it to improve exception handling and enhance the program’s logic to prevent crashes. It communicates with the Fluid Attacks Platform through the API to retrieve Vulnerability information and autofix data upon request.

  2. The application is divided into two sections:

    1. Extension (entrypoint: src/extension.ts): This is the main part of the application, which also consumes the Integrates API and interfaces with the vscode library to mark vulnerabilities and populate the sidebar. Webpack bundles this section.
    2. Webview (entrypoint: src/webview/App.tsx): This uses React and hosts the webviews (Finding description, Suggested autofix, ToE Lines, etc…). These webviews and the extension communicate through message handlers. For more information, refer to this the webview API page. Webpack also bundles this section.

Product structure

▶ 📁 __mocks__/
Holds VSCode API mocks needed for unit tests
...
▶ 📁 src
▶ 📁 api/
GraphQL operation handlers
...
▶ 📁 commands/
Extension commands, can be found in the Command Palette
...
▶ 📁 diagnostics/
Code to underline locations
...
▶ 📁 mocks/
Mock Service Worker handlers needed for unit tests
...
▶ 📁 panels/
ToE Lines table code
...
▶ 📁 providers/
Organizes and passes the info needed for the sidebar
...
▶ 📁 test/
Functional test stub
...
▶ 📁 treeItems/
Sidebar items, including buttons and actions that may call commands
...
▶ 📁 utils/
General utils and validations
...
▶ 📁 webview
 App.tsx        Webview entrypoint        
  extension.ts        Extension entrypoint, registers commands and runs validations
  queries.ts        GraphQL operations can be found here 
▶ 📁 webpack/
Webpack config
...


Tooling

Helpful tools for extension development:
  1. tsl problem matcher
  2. Jest Runner
  3. ESLint
  4. Prettier


Getting started

  1. Configure your Development Environment. When prompted for an AWS role, choose dev, and when prompted for a Development Environment, pick any option or None. You will need to have Node v21 installed beforehand.
  2. Open the editor in the base folder /universe/retrieves and from a terminal in the same folder run:

    3. npm install

  3. To view the changes reflected as you edit the code:

    1. For extension: Launch the Extension Development Host by pressing F5; this will bundle the code and launch Webpack in watch mode. Despite Webpack’s hot reloading, some changes may require a manual reload of the Extension Host to be reflected.
    2. For webview: Follow the steps above, and the new changes to the code will be immediately reflected thanks to Webpack dev server’s hot reloading.


Versioning

To publish your changes to the VSCode marketplace, you must increment the version number in the package.json file located in the Retrieves base folder. Otherwise, the change will be merged to trunk, but the publication/deployment process will be skipped.

For more info, check the semver documentation.

Linting

Retrieves uses ESLint and Prettier to enforce compliance with a defined coding style.

To view linting issues globally, you can run:

npm run lint

or

retrieves lint

Testing

Unit tests

Retrieves uses Jest as a test runner and MSW to mock API responses for unit tests.

To execute the test cases on your computer, you can run:

npm run test

or

retrieves test

To execute test cases individually, you can install the Jest Runner extension and run or debug the tests from the UI.

Idea
Tip
Have an idea to simplify our architecture or noticed docs that could use some love? Don't hesitate to open an issue or submit improvements.