Skip to content
Fluid Attacks Development Portal

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.

    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:

    • 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.
    • 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 link. Webpack also bundles this section.

Product structure

  • Directory__mocks__/ Holds VSCode API mocks needed for unit tests
    • …
  • Directorysrc
    • Directoryapi/ GraphQL operation handlers
      • …
    • Directorycommands/ Extension commands, can be found in the Command Palette
      • …
    • Directorydiagnostics/ Code to underline locations
      • …
    • Directorymocks/ Mock Service Worker handlers needed for unit tests
      • …
    • Directorypanels/ ToE Lines table code
      • …
    • Directoryproviders/ Organizes and passes the info needed for the sidebar
      • …
    • Directorytest/ Functional test stub
      • …
    • DirectorytreeItems/ Sidebar items, including buttons and actions that may call commands
      • …
    • Directoryutils/ General utils and validations
      • …
    • Directorywebview React components to show fix guides, git urls, finding descriptions and ToE lines
      • App.tsx Webview entrypoint
    • extension.ts Extension entrypoint, registers commands and runs validations
    • queries.ts GraphQL operations can be found here
  • Directorytest/ e2e tests
    • …
  • Directorywebpack/ Webpack config
    • …

Tooling

Helpful tools for extension development:

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/integrates/retrieves and from a terminal in the same folder run:

    Terminal window
    npm install

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

    • 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.
    • 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.

Retrieves follows the MAJOR.MINOR.PATCH scheme for versioning:

  • MAJOR: Breaking changes.
  • MINOR: Backward compatible changes.
  • PATCH: Bugfixes.

For more info, see 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:

Terminal window
  npm run lint

or

Terminal window
  m . /integrates/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:

Terminal window
  npm run test

or

Terminal window
  m . /integrates/retrieves/test

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

E2E tests

Retrieves supports end-to-end testing trough a web technology for serving VSCode locally called code-server. This way, cypress can be used as the testing framework. When executed, these tests run a standalone server of VSCode accessible in the browser at: http://localhost:9090. Retrieves e2e tests run with a user access token with access to VBD roots under Makimachi > Asgard: bwapp and WebGoat .

Execute headless e2e tests with:

Terminal window
  m .  /integrates/retrieves/test/e2e run

Or, if you wish to run them interactively with the Cypress GUI:

Terminal window
  m .  /integrates/retrieves/test/e2e open