Editing business process groovy scripts in admin-portal

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. Problem statement and solution

The development of the registry regulations business processes includes the development of Groovy scripts that reflect the logic of the business process steps. The admin portal allows the development of business processes for the registry regulations.

Developing Groovy scripts in specialized development tools, such as IDE (Desktop or Web versions), is much more efficient.

Extending the admin portal with the rich web editors for editing groovy scripts will improve the user experience to the level of using Desktop IDE tools, as well as reduce the time for continuous transfer of scripts to Desktop IDE for editing and back to BPMN.IO visual business process designer.

2. Glossary

  • LSP - Language Server Protocol

  • LS - Language Server

  • WS - WebSocket

  • WSS - WebSocket Secure

3. Actors

  • Registry regulations developer

4. Editor functionality

The following functionality is equally used for two functional scenarios: creating a new workflow step and editing or viewing an existing one.

  • Auto-completion as a drop-down list of the call variants.

  • Display the results of code analysis for errors using the language server.

  • Display Hoover tooltip with javadoc information.

  • Use different colors when viewing code.

  • Auto-completion for DDM JUEL functions:

    • initiator

    • completer

    • system_user

    • submission

    • sign_submission

    • get_variable

    • set_variable

    • set_transient_variable

    • process_caller

    • message_payload

5. Basic principles

  • Monaco editor as a Web tool for the development of groovy scripts.

  • Using third-party Language Servers (LS) to get hints, the list for auto-completion and results of errors of semantic analysis of Groovy scripts.

  • Using Language Server Protocol for communication between Language Server and Monaco editor.

  • Using lsp4j for LS management (orchestration).

  • Transport communication protocol between Monaco editor and LS - WebSocket over HTTP (HTTPS).

  • Logical communication protocol (payload structure in the transport protocol messages) between Monaco editor and LS.

6. High-level design

bp groovy script editor

6.1. Description and purpose of components

Name Programming language Description

Monaco editor

JavaScript

Visual browser-based code editor

Remote LS’s

Java, LSP4J

Instances of LS services that use the LSP protocol and perform the client code check returning the test results in Json-RPC (LSP) format.

LS Manager, Websocket Manager

Java, Spring

Spring boot web controller. Creates the required LS instances. Creates a WebSocket and uses the appropriate LS instance to analyze and validate code from the visual editor to the client.

6.2. LSP communication

  • WSS protocol is used as transport protocol.

  • The LSP protocol, version 3.17 is used as RPC interaction.

6.2.1. WebSocket communication

web sockets diagram

  • WSS is used as a transport protocol.

  • To configure Web-socket communication from the UI layer side, the monaco-languageclient is used.

  • spring-websocket is used to organize the websocket backend part.

6.2.2. Number of LS instances

web sockets concurrency diagram

  • Each window with monaco editor uses its own individual web-socket instance to connect to LS.

  • Each web-socket uses an individual LS instance.

  • All LS instances are in the same JVM instance. Technically, each LS instance is a new instance with the org.eclipse.lsp4j.services.LanguageServer interface.

bp-script-editing ls-communication-sequence

7. Component deployment

ls deployment

8. Scaling

In the current version of the service deployment, it is suggested to use only vertical scaling (RAM, CPU). Since the approach of placing all LSs within a single JVM is used, therefore, a significant increase in the use of computing resources is not expected during an increase in the number of the LS clients working at the same time.

Horizontal scaling is possible by adding Load Balancer for the LSP (WebSocket JSON-RPC) traffic. Out of scope.

9. Threat modeling

Area Name Description Limit Value

Kong

WSS traffic through Kong

Settings of the traffic through admin kong by using Upgrade headers. WebSocket kong manual

Authorization during the handshake process

Current authorization in admin kong. GET /groovy shall be accessible only for authorized users through admin realm

Maximum request size

Limit for payload in LSP (JSON-RPC). Use Request Size Limiting

65kb (30kb after SC)

Socket timeout

Idle time for the socket through which it automatically closes. Required configuration on both BE and FE side. Kong config property proxy_read_timeout

60s (should be by default)

Socket open Rate limit

Limit on the number of requests to create web-socket /groovy. Use existing plugin in Kong Rate limit plugin

10 per minute per user

Java application

CORS configuration

Configure CORS for the /groovy method for web-socket opening

Chart configuration

RAM limit

Set the RAM limit by configuring resources.requests.memory in the Chart deployment

1GB

10. Technology stack

Name Version License Description

Monaco editor

0.34.1

MIT

Visual browser-based code editor

monaco-languageclient

4.0.3

MIT

The language server client connected to the Monaco editor and used to connect to remote language servers using LSP protocol)

vscode-languageclient

8.0.2

MIT

Transitive dependency with monaco-languageclient

LSP4J

0.19

Eclipse Public License - v 2.0

Library for managing LS instances. Used to run LS code.

Groovy language server

-

APACHE LICENSE, v2.0

Implements LSP protocol and performs Groovy code check returning test results in the Json-RPC format

Spring Boot

2.6.1

APACHE LICENSE, v2.0

Spring Framework extension to simplify the construction of applications based on Spring due to the automatic configuration and spring boot starters

spring-boot-starter-websocket

2.6.1

APACHE LICENSE, v2.0

Spring extension for Web Socket management in the server applications (uses spring-websocket:5.3.13)

11. Control interface

BPMN.io will be extended with an additional button to call the modal window editing groovy scripts.

bp groovy script open window
Figure 1. Business process script editor call window
bp groovy script edit window
Figure 2. Script edit window in Monaco Editor

12. High-level development plan

12.1. Required expertise

  • Java

  • Javascript

  • DevOps

  • QA, AQA

12.1.1. Backend Java activities

  • Create Spring Boot-based backend service ddm-language-server.

  • Develop WebSocket proxy component.

  • Upgrade the LSP4J version to 0.19 for GroovyLanguageServer.

12.1.2. Javascript activities

  • Integration of Monaco Editor into the BPMN.IO business process editor.

  • Monaco Editor integration with ddm-language-server using monaco-languageclient.

12.1.3. DevOps activities

  • Onboard https://github.com/GroovyLanguageServer/groovy-language-server: add codebase into gerrit and create pipeline around

  • Create deploy-templates and Dockerfile for service ddm-language-server (openjdk based image).

  • AdminKong configuration for ddm-language-server traffic. Add websocket proxy headers to the Kong configuration.

  • Configuring Kong plugins to check the security limits.

  • Add the languageServerUrl variable to environment-js with the relative ddm-laguage-server address.

13. Security

13.1. Business data

Data Category

Description

Privacy

Integrity

Accessibility

Interim business process data containing open information

Business form and process data that does not contain restricted information

Low

High

Average

Operational logs

Lists of recorded/logged calls to the service and its operation logs

Average

High

High

13.2. Simplified threat model

groovy TM

13.3. Countermeasures against safety risks and compliance with safety requirements

Risk

Security controls

Implementation

Priority

Breach of data integrity and confidentiality during transmission

Use of HTTPS and WSS

Taken into account in the original design

High

Unsafe session termination on the server side

During the user initiated exit from the system or in case of the automatic session timeout, any communication with the web socket must be terminated

Not taken into account in the initial design

High

Denial of service due to depletion of computing resources (DoS) caused by the lack of restrictions for web sockets

  • Implement the maximum request size limit of 30 kb

  • Socket timeout: 60s

  • Limit the number of open sockets to 10 sockets per user per minute

Taken into account in the initial design

High

Denial of service due to depletion of computing resources (DoS) caused by the lack of restrictions for the service at the openshift level

  • Limit RAM usage. The limit itself must be calculated after testing.

  • Limit CPU time consumption. The limit itself must be calculated after testing.

  • Configure the mechanism for restarting the service in case of excessive use of resources.

Taken into account in the initial design

High

Denial of service due to depletion of computing resources (DoS) caused by the lack of restrictions for HTTP requests at the level of the Kong ingress controller

  • The socket limit and the number of requests must be configured separately in the /groovy endpoint. That is, the rate limit plugin for Kong must be set in /groovy

Not taken into account in the initial design

High

Risk of backdoor in the language-server component

  • Embed all the necessary resources and language dictionaries to parse AST in the ddm-language-server image to prevent any calls of this service to external sources

  • Prohibit any communications of the ddm-language-server service with external resources at the level of openshift network policies and allow communications with the logging service and services involved according to the business logics.

Partially taken into account in the initial design. It is required to completely isolate the ddm-language-server service from the external network

High

Risk of executing vulnerability of interactive information systems (XSS)

  • CORS settings

Taken into account in the initial design

High

Risk of disclosing technical information about the system

  • The service must return a general error in case of problems.

  • The service must have the "last resort" mechanism that handles any errors that have not been processed before.

  • Make sure the DEBUG mode is off at all levels in the pre-production and production environments.

  • language-server does not return its version and any technical and/or system information in the HTTP response.

Not taken into account in the initial design

Medium

Deserialization of unreliable data

  • Make sure that there is avoidance of or protection against deserialization of unreliable data both in the developed code and in third-party libraries.

  • Make sure that there is a check of the JSON scheme, and it is checked before accepting the entered data.

Not taken into account in the initial design

Medium

Risk of a group of web vulnerabilities and compliance with security requirements

  • Make sure that requests containing unexpected or missing Content Types are rejected by the corresponding headers (status of the HTTP response: 406 Unacceptable, or 415 Unsupported media type).

  • The web server accepts only approved HTTP methods.

  • Make sure that the HTTP response has the Content-Type header as well as a safe character set (for example, UTF-8, ISO-8859-1).

  • The web page with Monaco Editor must contain the customized Content Security Policy (CSP) headers.

  • Monaco Editor web page must contain the X-Content-Type-Options title: nosniff

Not taken into account in the initial design

Medium

The risk of fixing in the system when exploiting a vulnerability to the system level and subsequent lateral movement. Compliance with the requirements.

  • The system service must not receive the account service key from openshift (unless it is a requirement), and must be run from a non-privileged system user.

Not taken into account in the initial design

Medium

Insufficient logging and safety compliance

  • The target service must log all requests and send them to a centralized logging and monitoring system.

  • Make sure that all unsuccessful requests and errors arising during operations are logged.

  • The logging system must use the unified time and time zone.

  • Logs must have a unified format and contain all the necessary information for investigation of security incidents.

  • Logs must not contain sensitive information, or it must be obfuscated accordingly

Not taken into account in the initial design

Low

Misconfiguration of the service and/or framework

  • Make sure that the server configuration is protected in accordance with the recommendations of the application server and the frameworks used.(web server/app server/framework hardening)

Not taken into account in the initial design

Low

13.4. Comprehensive protection measures testing system

  1. The repository with the source code must be onboarded to the vulnerability management system and undergo regular testing.

  2. The basic image of the service must be scanned and not contain unresolved critical vulnerabilities.

  3. The basic image must be placed in a trusted repository controlled by the organization.

  4. The language-server technology should be added to the list of the used 3rd party products (inventory).