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
-
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.
-
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 thevscode
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.
Tooling
Helpful tools for extension development:
Getting started
-
Configure your Development Environment. When prompted for an AWS role, choose
dev
, and when prompted for a Development Environment, pick any option orNone
. You will need to have Node v21 installed beforehand. -
Open the editor in the base folder
/universe/integrates/retrieves
and from a terminal in the same folder run: -
To view the changes reflected as you edit the code:
- For
extension
: Launch the Extension Development Host by pressingF5
; 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.
- For
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:
or
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:
or
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:
Or, if you wish to run them interactively with the Cypress GUI: