Connectivity ============ There are a few instances where Sensei will try to communicate with other services to work properly, or some services will try to communicate with Sensei. This document describes each of these scenarios and also explains when these occur. .. contents:: Overview -------- ======================= ============== ======= ============ ============== event authentication startup periodically by user action ======================= ============== ======= ============ ============== :ref:`create_auth_link` x :ref:`license_check` x x :ref:`cb_locations` x x :ref:`dl_cookbooks` x x x x :ref:`update_check` x x :ref:`usage_metrics` x :ref:`code_metrics` x :ref:`local_api` x :ref:`docs_fetching` x :ref:`public_cbs` x ======================= ============== ======= ============ ============== - authentication: during the authentication process (this may include signing out) - startup: happens every time the IDE starts (some may occur after a small delay) - periodically: happens periodically while the IDE is running (but only when Sensei is in use) - by user action: only happens when the user does specific actions, see each event for details Details ------- .. _create_auth_link: Create auth link ~~~~~~~~~~~~~~~~ The following elements are required for the optional authentication process. 1. Sensei will send a request to ``${API}/getapptoken`` and receive a random identifier. 2. Next, the browser will open to ``${PLATFORM}/#/sensei/auth/${random-identifier}``. This will prompt the user to login onto our platform. 3. While the above process is happening, Sensei will periodically check if the user has already authenticated themself by calling the endpoint ``${API}/getusertoken?apptoken=${random-identifier}``. .. seealso:: See :doc:`/intro/installation` for more information. .. _license_check: License check ~~~~~~~~~~~~~ Sensei will try to fetch and renew its license by calling an endpoint and passing the Sensei user token and a machine identifier. This happens on boot and at the end of the optional authentication process or when signing out if previously authenticated. The endpoint is ``${API}/license?token=${usertoken}&identifier=${machine-identifier}``. In case of a non-authenticated user (anonymous), the token part is omitted. .. _cb_locations: Cookbook locations ~~~~~~~~~~~~~~~~~~ The location of the cookbooks that need to be loaded can be configured remotely. To fetch the latest configuration, Sensei will call the endpoint ``${API}/location.txt?token=${usertoken}``. This will occur at startup, when signing in or out, and every 24 hours the IDE has been running. .. seealso:: See :doc:`/topics/distribution` for more information. .. _dl_cookbooks: Download cookbooks ~~~~~~~~~~~~~~~~~~ Configured cookbooks that have a remote location (such as a HTTP(S) or remote git URL) will be loaded by Sensei. Sensei will connect to the given location and download the contents to the disk. This action will be run at startup, when an user manipulates a cookbook or the cookbook configuration and every 2 hours otherwise. .. _update_check: Update check ~~~~~~~~~~~~ Sensei will check if there is a new version available and will prompt to update if there is. Sensei executes the IDE's logic to perform the update check. This will connect to the JetBrains marketplace where Sensei can be downloaded from. This action will run every 90 minutes (or every 30 minutes in the case of :doc:`alpha builds`). .. _usage_metrics: Product usage metrics ~~~~~~~~~~~~~~~~~~~~~ Some events about the usage of Sensei are collected and may be pushed to the `Sensei Hub `__. These are only sent when both: - The flag :menuselection:`Sensei Insights --> disable data collection` has been switched off inside the company preferences section inside the SCW platform. This condition does not apply for non-authenticated (anonymous) Sensei users that do not use an account. - the :menuselection:`data collection` checkbox in the plugin is checked. This checkbox is toggled off by default and is presented when the quick start guide is shown after installing the plugin. This can be toggled at any point in the menu by going to :guilabel:`Preferences | Tools | Sensei by Secure Code Warrior ®` These events are sent to the endpoint: ``https://sensei.securecodewarrior.com/api/metrics/usage`` This sending action will run every 10 minutes after a 2 minute initial delay. Data present in all event types +++++++++++++++++++++++++++++++ - event type - timestamp - installation id - ide version - sensei version - (optional additional properties, specific to the event type) Event types +++++++++++ Quickstart opened Triggered when the quick start window is opened. Additional properties: - from (``menu`` or ``cookbook_manager`` or ``first_start``) Cookbook manager expand Triggered when the cookbook manager is expanded Cookbook manager collapse Triggered when the cookbook manager is collapsed Cookbook manager inspect code Triggered when the :guilabel:`Inspect code with cookbook` button is pressed Cookbook manager add cookbook Triggered when the ``+`` button is pressed in the cookbook manager cookbook list Cookbook manager remove cookbook Triggered when the ``-`` button is pressed in the cookbook manager cookbook list Cookbook manager reload cookbooks Triggered when the refresh button is pressed in the cookbook manager cookbook list Cookbook manager open settings Triggered when the settings button is pressed in the cookbook manager cookbook list Cookbook manager open help Triggered when the help button is pressed in the cookbook manager cookbook list Recipe editor create recipe Triggered when a recipe is created Additional properties: - hashed recipe id (SHA-256) Recipe editor delete recipe Triggered when a recipe is deleted Additional properties: - hashed recipe id (SHA-256) Recipe editor clone recipe Triggered when a recipe is cloned Additional properties: - hashed recipe id (SHA-256) Recipe editor import recipes Triggered when recipes are imported from the import button in the recipe list Additional properties: - hashed recipe ids (SHA-256) Recipe editor export recipe Triggered when a recipe is exported from the export button in the recipe list Additional properties: - hashed recipe id (SHA-256) Recipe editor switch tab Triggered when the tab is changed in the recipe editor Additional properties: - from (``general`` or ``recipe`` or ``quickfix`` or ``documentation``) - to (``general`` or ``recipe`` or ``quickfix`` or ``documentation``) - hashed recipe id (SHA-256) Recipe editor switch view Triggered when the yaml view is changed Additional properties: - tab (the currently opened tab, ``recipe`` or ``quickfix``) - from (``codeonly`` or ``uionly`` or ``codeandui``) - to (``codeonly`` or ``uionly`` or ``codeandui``) Recipe editor test recipe Triggered when the recipe is tested using the :guilabel:`Test inspection` link in the recipe editor. Additional properties: - hashed recipe id (SHA-256) Recipe editor close Triggered when the recipe editor is closed without saving Additional properties: - number of recipes in cookbook - open timestamp - close timestamp Recipe editor save Triggered when the recipe editor is closed by saving Additional properties: - number of recipes in cookbook - number of recipes created - number of recipes deleted - number of recipes cloned - number of recipes viewed - current tab (``general`` or ``recipe`` or ``quickfix`` or ``documentation``) - open timestamp - close timestamp .. _code_metrics: Coding usage metrics ~~~~~~~~~~~~~~~~~~~~ Some Sensei events during coding are collected and may be pushed to the `Sensei Hub `__ and the Secure Code Warrior platform. These are only sent when both: - The flag :menuselection:`Sensei Insights --> disable data collection` has been switched off inside the company preferences section inside the SCW platform. This condition does not apply for non-authenticated (anonymous) Sensei users that do not use an account. - the :menuselection:`data collection` checkbox in the plugin is checked. This checkbox is toggled on by default and is presented when the quick start guide is shown after installing the plugin. This can be toggled at any point in the menu by going to :guilabel:`Preferences | Tools | Sensei by Secure Code Warrior ®` These events are sent to the endpoint: ``https://sensei.securecodewarrior.com/api/metrics/code`` and ``https://portal-api(.eu).securecodewarrior.com/public/sensei-plugin/v2/track`` This sending action will run every 10 minutes after a 2 minute initial delay. Data present in all event types +++++++++++++++++++++++++++++++ - event type - timestamp - installation id - ide version - sensei version - hashed recipe id (SHA-256) - recipe level (``error`` or ``warn`` or ``info`` or ``marked_info`` or ``compliant``) - user id if logged in - (optional additional properties, specific to the event type) Event types +++++++++++ Inspection shown Triggered when a Sensei marking is shown. Additional properties: - legacy (``true`` or ``false``, depending on if the triggered code is existing code or new) Inspection removed Triggered when a Sensei marking is now gone. Additional properties: - legacy (``true`` or ``false``, depending on if the triggered code is existing code or new) Quick Fix applied Triggered when a quick fix is applied Additional properties: - quickfixId (index of the chosen quick fix, if multiple quick fix options were presented) Description shown Triggered when the user expands the description of the recipe while hovering on a Sensei marking. Training opened Triggered when the ``Take the training provided by Secure Code Warrior`` quick fix option is chosen. These quick fixes are automatically suggested on Sensei markings if the category or CWE id is set in the recipe's settings. .. _local_api: Local plugin API ~~~~~~~~~~~~~~~~ Sensei adds an endpoint to IntelliJ's builtin local HTTP server. The endpoint only allows requests coming from the ``securecodewarrior.com`` domain and sub-domains. This API receives a request from the Sensei Hub to improve the experience while using the Hub by only showing what is available for the current Sensei version installed and determine what capabilities are available. This API is also used to launch the "add cookbook" dialog when choosing to install a cookbook by using the Sensei Hub. Current data send from plugin to hub on request: Info API - IntelliJ version - Sensei version AddCookbook API Launches "add cookbook" dialog, only sends an optional error message as reply .. _docs_fetching: Fetch target docs ~~~~~~~~~~~~~~~~~ Sensei will do a request to the `Sensei Hub `__ to fetch updated docs to show in the :ref:`documentation box when selecting a search target `. This request will take place the first time the recipe editor is being opened (for each session), and when the recipe editor is being opened if it's been longer than 24 hours since the last time. Current data send from plugin to hub on request: - ide version - sensei version - user id if logged in - installation id .. _public_cbs: Fetch public cookbooks ~~~~~~~~~~~~~~~~~~~~~~ Sensei will do a request to the `Sensei Hub `__ to fetch a list of public cookbooks that can be added in the Cookbook manager. These are shown in the :menuselection:`Discover Cookbooks` sub-menu in the :guilabel:`Add cookbook` button menu in the Cookbook Manager. This request will take place the first time the Cookbook Manager is being opened (expanded) and every 12 hours subsequently.