Copyright

Copyright © 2019 Balasys IT Ltd.. All rights reserved. This document is protected by copyright and is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this document may be reproduced in any form by any means without prior written authorization of Balasys.

This documentation and the product it describes are considered protected by copyright according to the applicable laws.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

Linux™ is a registered trademark of Linus Torvalds.

Windows™ 10 is registered trademarks of Microsoft Corporation.

The Balasys™ name and the Balasys™ logo are registered trademarks of Balasys IT Ltd.

The Proxedo™ name and the Proxedo™ logo are registered trademarks of Balasys IT Ltd.

AMD Ryzen™ and AMD EPYC™ are registered trademarks of Advanced Micro Devices, Inc.

Intel® Core™ and Intel® Xeon™ are trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries.

All other product names mentioned herein are the trademarks of their respective owners.

DISCLAIMER

Balasys is not responsible for any third-party websites mentioned in this document. Balasys does not endorse and is not responsible or liable for any content, advertising, products, or other material on or available from such sites or resources. Balasys will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through any such sites or resources.

2023-12-07 .Copyright

Preface

Typographical conventions

Before you start using this guide, it is important to understand the terms and typographical conventions used in the documentation. For more information on specialized terms and abbreviations used in the documentation, see the Glossary at the end of this document.

The following text formatting principles and icons identify special information in the document.

Tips provide best practices and recommendations.
Notes provide additional information on a topic, and emphasize important facts and considerations.
Warnings mark situations where loss of data or misconfiguration of the device is possible if the instructions are not obeyed.
Command

Commands you have to execute.

Emphasis

Reference items, additional readings.

/path/to/file

File names.

Parameters

Parameter and attribute names.

In the parameter listing tables the required parameters are also emphasized with bold text:

Key Description

param1

This is a required parameter.

param2

This is an optional parameter.

Additional marks used specifically in the Web User Interface (UI):

Key Description

*

The elements marked with * in the configuration reference tables are mandatory to be configured.

(Default)

For some of the configuration elements there are recommended default values, marked as (Default). In case the value is not defined during the configuration, the default value will be considered for the actual element.

+

By clicking this sign you can add the actual element to the list of configuration elements.

Contact and support information

This product is developed and maintained by Balasys IT Ltd..

Contact:

Balasys IT Ltd.
4 Alíz Street
H-1117 Budapest, Hungary
Tel: +36 1 646 4740
E-mail: <info@balasys.hu>
Web: http://balasys.hu/

Sales contact

You can directly contact us with sales-related topics at the e-mail address <sales@balasys.hu>, or leave us your contact information and we call you back.

Support contact

To access the Balasys Support System, sign up for an account at the Balasys Support System page. Online support is available 24 hours a day.

Balasys Support System is available only for registered users with a valid support package.

Support e-mail address: <support@balasys.hu>.

Training

Balasys IT Ltd. holds courses on using its products for new and experienced users. For dates, details, and application forms, visit the https://www.balasys.hu/en/services#training webpage.

1. Scope of this document

This document describes the Web User Interface for the Proxedo API Security in VM. The purpose of this document is to present the designed approach and the usage for the configuration of Proxedo API Security via Web User Interface (UI). The Web UI allows easy configuration for Proxedo API Security. All the functionalities are grouped visually and logically into thematic units which follow the logical built up of Proxedo API Security’s configuration. The primary intended audience of this document are system engineers and system designers for configuring Proxedo API Security systems.

2. Introduction to Proxedo API Security

2.1. What is Proxedo API Security

The Proxedo API Security (PAS) is a security solution that protects API serving endpoints. It is positioned in the network flow between consumers of the APIs (clients) and backend solutions serving the API (servers) as a transparent HTTP proxy.

Proxedo API Security can:

  • handle incoming Transport Layer Security v1 (TLS) connections from clients & outgoing TLS connections to servers separately and selectively

  • verify that the communication conforms to HTTP specifications

  • verify that the content of the messages conform to their specified content type

  • verify that the content of messages conform to API specification(s) as described in schemas

  • evaluate the level of risk with regards to the API call using the data collected from call data

  • provide rule-based protection against a variety of web-based application layer attacks

  • extract parts of the content of the messages and relay them to external data stores such as log servers, SIEM systems or other data warehouses

2.2. Where to start

Depending on what you need to do the following starting points are suggested:

3. Overview of Proxedo API Security

3.1. Main features

3.1.1. TLS

Transport Layer Security v1 (TLS) (successor of the now obsoleted Secure Socket Layer v3 (SSL)) is a widely used crypto protocol, guaranteeing data integrity and confidentiality in many PKI and e-commerce systems.

The TLS framework inspects TLS connections, and also any other connections embedded into the encrypted TLS channel. TLS connections initiated from the client are terminated on the Proxedo API Security, and two separate TLS connections are built: one between the client and the firewall, and one between the firewall and the server. If both connections match the configuration settings of PAS (for example, the certificates are valid, and only the allowed encryption algorithms are used), PAS inspects the protocol embedded into the secure channel as well. Note that the configuration settings can be different for the two connections, for example, it is possible to permit different protocol versions and encryption settings.

3.1.2. Enforcement

Proxedo API Security acts as an HTTP proxy and verifies that the traffic passing through conforms to HTTP’s specifications. By using OpenAPI schemas, as defined in OpenAPI specifications (also known as Swagger), it also verifies that the traffic passing through conforms to the API endpoint’s specification and can log or deny non-conforming traffic.

PAS also provides its own versatile filtering system to control passing traffic.

3.1.3. Fraud Detection

The Fraud Detection module of Proxedo API Security reduces the number of fraudulent transactions by harnessing device fingerprinting and enriching incoming data with alternate sources to provide the best accuracy and details about transactions.

3.1.4. Rule-based Enforcement

Besides its positive security model approach, Proxedo API Security also has a web application firewall module. The WAF Enforcer protects against a variety of application layer attacks including credential theft, code injection, cross-site scripting (XSS), cookie poisoning, CSRF, SQL injection, DoS, ransomware, and more.

3.1.5. Insights

With Proxedo API Security it is possible to extract business-relevant information with extremely high resolution from the traffic and relay it to external data stores where further analysis can be implemented.

Thus, it is possible to feed Log Management solutions, Monitoring and SIEM systems, Data visualization tools with data extracted from the traffic, even to the level of specific fields deep inside API calls or URI parameters.

3.1.6. Security flow

The security flow binds most of PAS’s features together. It allows flexible configuration for handling the traffic. Multiple Enforcement, Filter and Insight plugins can be mix-and-matched with control over error policies.

3.1.7. High Availability

Proxedo API Security offers the high availability (HA) feature optionally. With the help of this feature, two identical PAS servers provide redundancy so that the network traffic is not disturbed in case any of the nodes fails. Support for synchronizing configuration and setting remote services' state is also implemented.

3.1.8. Monitoring

The Monitoring system of Proxedo API Security core leverages the widely accepted Simple Network Management Protocol (SNMP) to monitor its network components and to collect data on the components systematically. The monitoring capability of PAS core relies on the SNMP daemon. The collected data, organized into an information database and shared between the SNMP daemon and the Monitoring Manager is called Management Information Base (MIB). For the analysis of the collected data, the BALASYS-SNMP-MIB and the PAS-SNMP-MIB Management Information Base (MIB) documents can be downloaded from Balasys customer documentation. Further recommended MIB files are, SNMPv2-MIB, IF-MIB and UCD-SNMP-MIB.

For the monitoring implementation, PAS depends on the snmpd service on the underlying host operating system. Therefore if snmpd fails or is stopped, PAS also stops.

3.2. Main Concepts in Proxedo API Security

This chapter provides an overview of the Proxedo API Security solution, introduces its main concepts, and explains the relationship of the various components.

API Endpoint

Proxedo API Security protects API endpoints. An API endpoint is the serving part of the communication channel and is the collection of all functions of a service. It resides at a list of well-known top URIs under which all the functions are accessible. APIs have well-defined HTTP Endpoints for all exposed calls, resources etc., usually through providing a schema that describes all parameters of these URI paths, including possible HTTP response codes, the format and fields of the data structure in the request’s and response’s body.

Client

It is a consumer of API endpoints. It is the source of the requests.

Backend

The backend constitutes of one or more servers that serve the API endpoint. It receives the requests of the client and sends the responses.

HTTP message

It can be an HTTP request coming from the client or an HTTP response coming from the backend.

Call

An HTTP conversation constitutes of a request — response interchange of HTTP messages between the client and the backend. Whenever the direction is irrelevant in the context — it applies to both requests and responses — the message is named Call.

Listener

It is the part of PAS that listens to incoming traffic for given API Endpoints. It is bound to a network port. Clients address this port when accessing API Endpoints through the gateway.

TLS

Transport Layer Security is the cryptographic protocol that secures HTTPS communications. PAS can apply TLS encryption both when communicating with Clients and Backends. TLS encryption can also be used with Syslog Insight Target and Elastic Insight Target.

Security flow

It provides a collection of security rules that PAS applies to a Call. It is two series of Plugins: one for requests and one for responses.

Plugin

It is an element of the security flow that applies a specific security function. It has different types based on the role they do.

Decompressor

A Plugin responsible for decompressing compressed content in the HTTP message’s body. This ensures that the original content of the message is available for processing.

Compressor

A Plugin responsible for compressing the result of a flow and forwarding the compressed content.

Deserializer

A Plugin responsible for parsing the HTTP message’s body to structured data. This ensures that a message is well-formed. The structured data will also be consumed by other Plugins that operate on the body of the message.

Serializer

A Plugin responsible for serializing the structured data to the format of the HTTP message’s body.

Filter

A Plugin that rejects calls when they match defined rules.

Enforcer

A Plugin that validates calls against externally defined schemas.

Insight

A Plugin that extracts various data from the call and sends it to external systems (log servers, SIEMs, and other data analysis tools).

Brick

They are reusable components of Plugins. They can be defined on their own and then shared by multiple Plugins.

Error policy

It is a brick that defines what happens if the Plugin has found an error. It decides if calls are rejected or merely logged, and defines the details of the HTTP error response sent to the client if a call is rejected.

Matcher

It is a brick that decides if the Plugin should be executed for a given call by checking various data in the HTTP message.

Selector

Selector is a brick that can extract a piece of information from a call. It is used by Insight plugins.

Insight Target

It is a brick that defines an external system to send extracted data to. It is used by Insight plugins.

High Availability

This feature enables two nodes serving as redundant PAS endpoints. It helps ensure service continuity in case of a node failure while being transparent to clients.

3.3. Architecture for Proxedo API Security

Proxedo API Security is based on a micro-services architecture.

The components of the architecture are each responsible for well-defined subset of handling traffic between the client and the backend. Proxedo API Security is built up of three components:

Transport Director

It manages the transport layer of API connections:

  • handles network connections from the client

  • handles network connections towards the backends

  • handles TLS on these connections

  • load-balances between multiple backend servers

  • load-balances between multiple Flow Directors

  • enforces HTTP protocol validity in calls

Flow Director

It is responsible for the execution of the Plugins in the Endpoint’s flow and for applying Error Policies as necessary.

Insight Director

It manages the connections to Insight Targets. It is responsible for sending the data collected by Insight plugins to Insight Target systems.

The handling of a connection with the help of components is shown in this figure:

PAS Architecture
Figure 1. PAS Architecture
  1. Incoming connections are accepted by the Transport Director.

    • It handles TLS with the client if necessary.

  2. It hands over the connection to the Flow Director.

    • The Flow Director chooses the Endpoint based on the URL.

    • The Flow Director applies the Endpoint specific Request Security Flow.

  3. If an Insight plugin needs to send data to an external Insight Target it sends the collected data to the Insight Director.

  4. The Insight Director sends the data further to the Insight Target with the appropriate protocol.

  5. The Flow Director hands the connection back to the Transport Director.

  6. The Transport Director then sends the data to the Backend.

    • It handles TLS with the backends if necessary.

    • It performs load balancing among Backend servers if necessary.

The same procedure is executed with the response coming from the Backend.

3.3.1. Understanding processing flow

The figure on Proxedo API Security architecture and the steps following that describe how client connection is handled. The following figure explains how calls are processed in more details:

PAS processing flow
Figure 2. PAS processing flow
  1. As shown in the figure above, the incoming connection from the client is handled by the Transport Director, applying TLS if needed.

  2. The Transport Director hands over the connection to the Flow Director, indicating which Listener the connection belongs to.

  3. The Flow Director then chooses the Endpoint based on the URL in the request. First endpoint has matching URL is chosen.

  4. The Flow Director then starts applying the request part of the Security Flow definition.

  5. For each Plugin the Flow Director:

    • Checks if the Plugin's matcher matches the request.

    • If so, it executes the Plugin, if not, it executes the next Plugin.

    • If the Plugin indicates success it executes the next Plugin.

    • If the Plugin indicates an error it applies the Plugin's error policy. If the policy dictates to abort the connection:

      • It fills error details and hands back the connection to the Transport Director, aborting the execution of the flow.

      • The Transport Director closes the connection, sending error details to the client if allowed by the policy.

  6. Once, the last Plugin has been executed the connection is handed back to the Transport Director.

  7. The Transport Director initiates the connection towards the Backend:

    • It handles load balancing if necessary.

    • It handles TLS if necessary.

    • It sends the request itself to the Backend server.

  8. The Backend server sends its response to the Transport Director.

  9. Once, the response has been received the Transport Director again hands over the connection to the Flow Director.

  10. The Flow Director then starts applying the response part of the Security Flow definition, executing the Plugins as above.

  11. Once, the last Plugin has been executed the connection is handed back to the Transport Director.

  12. Finally, the Transport Director sends the response to the client.

Usually, Plugins are organized in the following manner:

  • A Decompressor Plugin extracts the compressed body.

  • A Deserializer Plugin processes the decompressed request to understand the details in the body.

  • Filters are applied to filter unnecessary traffic.

  • Enforcers are applied for detailed validation of calls.

  • Insights are applied to collect data from the call.

  • Serializer Plugin serializes the body

  • Compressor Plugin compresses the serialized body

Though the order of the plugins can be changed based on the needs, note the followings:

  • When a Plugin needs access to the request body it requires Deserialized data. It is therefore strongly recommended that the first plugin is a Decompressor followed by a Deserializer.

  • At the end of the flow it is strongly recommended to place a Serializer plugin followed by a Compressor.

  • Generally Insights are applied after Filters and Enforcers so that they are not executed on possibly invalid calls.

  • Anything that operates on the HTTP headers or the body of the message will be aware of the call direction: The same Plugin in the request and response flow will act on the request or response data.

  • However, the Flow Director handles a request-response exchange together, so you can still use details from the request in Plugins of the response flow. The most notable example of this is using URI or method matchers in the response flow.

  • Plugins in the request flow, however, cannot access details of the response flow (since they are not available yet.)

It is also worth noting that Insight Plugins instantly hand over data to the Insight Director, and let the execution continue.

3.3.2. Architecture with High Availability

In case of HA operation, the core component is configured on both nodes participating in the HA operation. The architecture and the process are identical on both nodes, but they are set up to work redundantly. Only one node (the master) of the cluster is receiving traffic actively.

This operation uses the following additional resources:

  • two nodes with PAS core installed

    At the moment, only clusters of two are supported. It also means, that you will need to have a node with both management and core components installed, and a node with only core installed.
  • a virtual IP address through which the service is supposed to be accessible

The technical foundation of our HA solution is the Virtual Router Redundancy Protocol (VRRP). Once the requirements are properly set up, it operates as follows:

  • At startup, the nodes send keepalive messages to each other to see if the other node is available. Both of them consider themselves to be in BACKUP state until they make sure the other node is not in MASTER state. If both nodes are newly connected to the cluster, they participate in an election and the one with the higher priority becomes the MASTER.

  • After one of the nodes has become the MASTER, both of them keep sending keepalive messages so that they notice when the other node disappears.

  • A node (re)connecting to the cluster does not result in the reelection of the MASTER.

4. Installation of Proxedo API Security based on VMs

PAS is mainly distributed as Docker images, and is also completed with a .deb package that sets up the operational environment.

You can install the management and the core components either on one single node in Standalone setup or on two separate ones in Multi node setup using the automated deployment tool. The synchronization of the core configuration is provided by the storage component.

The specific sections on the installation of the different components provide details on how to install them on a node. The installation order of the components is described in section Installation scenarios.

For the multi node setup, we provide a core deployment tool along with the management component. Using that, you can deploy and configure the core and the storage components on the remote node. The main starting points of its usage are described in section Multi node setup using the automated deployment tool.

4.1. Prerequisites for installing PAS

The followings are needed prior to the installation of Proxedo API Security:

  • the licence for PAS

  • a technical user for accessing Balasys' download site and docker registry

  • the PAS storage, core and management .deb packages

    You can download the .deb packages from the Balasys Download website.
  • one or two servers with Ubuntu 22.04 Operating System installed. See Installation scenarios.

Make sure, that there is no user or group named "pas" in the environment where Proxedo API Security is planned to be installed.

4.1.1. Minimum system requirements

Each server of the PAS installation must meet the following minimum system requirements:

Table 1. Minimum system requirements

Operating system

Ubuntu 22.04 LTS

CPU cores

4

Memory

4 GB

Disk

40 GB

Network

1 interface, 1 Gbps

This minimum configuration can run a maximum of two Flow Director instances on servers with the core component installed.

4.2. Installation scenarios

4.2.1. Standalone setup

For a standalone setup one server is needed.

There are two major installation methods available for the standalone setup:

  • Simplified installation - This simplified installation method directs the user with prompt windows throughout the installation process, offers default values.

Follow the instructions for simplified installation for standalone setup:

The simplified installation method is only available for the standalone setup.

4.2.2. Multi node setup

For a multi node setup two servers are needed, one server for the PAS core and another server for the management component.

In a multi node setup there will be a management node and another node with the core component. The storage component must be installed and configured on both nodes. The installation must be done in the following order:

  1. Management node

  2. Core node

    The core node can be set up with the automation tool or manually installing the components in the following order:

4.2.3. Multi node HA setup

Multi node HA setup is similar to the standard multi node setup, but in this scenario the management node will run the core component, as well. The installation order is the following:

  1. Management node

  2. Core node

    Core node can be set up with the automation tool or manually installing the components in the following order:

The HA component is included in the core component, and it must be configured after the installation. See High availability configuration.

4.3. Simplified installation method for the standalone setup

This simplified installation method is only available for the standalone setup. By choosing this installation method, the user is directed through the installation with the help of prompt windows and suggested default values.

4.3.1. Simplified installation for the storage component

  1. Log in as root.

  2. Update the OS' package list: apt update.

  3. Install the PAS storage .deb package: apt install <path/to/deb>/proxedo-api-security-storage_<version>.deb.

    This will:

    • Create a user named pas for running and configuring PAS, if it has not been created yet by the installation of other components previously.

      pas user must not be created manually beforehand.
    • Install the necessary configuration files and helper scripts under /opt/balasys.

    • Create systemd services for managing the PAS storage component.

      You need to use apt to install the .deb package locally as it installs its dependencies as well. dpkg will not resolve dependencies, and apt-get cannot install from a local file. Also note that to install PAS from the current directory, you must use the path ./ before the .deb package, or apt will try to download the package from a repository.
  1. Define the registry you want to download the docker images from. Define it in the following format: example.com.

Registry to download the docker image from
Figure 3. Registry to download the docker image from
  1. Provide your user name for this registry.

User name for the docker registry
Figure 4. User name for the docker registry
  1. Define the password for the docker registry.

Password for the docker registry
Figure 5. Password for the docker registry
  1. Name the node.

This name will appear in the Service status dashboard. As this value is optional, you can leave it blank to skip naming the node.

Naming the node
Figure 6. Naming the node
  1. Generate a TLS certificate to secure the storage access. Define the identifier to be used in the storage TLS certificate.

TLS certificate identifier
Figure 7. Identifier for TLS certificate
  1. Provide a valid DNS name for the storage’s TLS certificate.

DNS name of the storage’s TLS certificate
Figure 8. DNS name of the storage’s TLS certificate
  1. Define if the existing configuration files need to be overwritten or not.

Confirming the need of existing configuration details
Figure 9. Confirming the need of existing configuration details

If the login to the docker registry is not successful, the following warnings are displayed:

Docker login error warning
Figure 10. Docker login error warning
Automatic generation of storage component failed
Figure 11. Automatic generation of storage component failed
  1. Change to the PAS user: su - pas.

    1. Run pas-storage-update to download the docker images.

    2. Start PAS storage: systemctl start proxedo-api-security-storage.

      This service is enabled by default, so the service starts on system restart.

4.3.2. Simplified installation for the management component

  1. Log in as root.

  2. Update the OS' package list: apt update.

  3. Install the PAS storage .deb package: apt install <path/to/deb>/proxedo-api-security-mgmt_<version>.deb.

    This will:

    • Create a user named pas for running and configuring PAS, if it has not been created yet by the installation of other components previously.

      pas user must not be created manually beforehand.
    • Install the necessary configuration files and helper scripts under /opt/balasys.

    • Create systemd services for managing the PAS storage component.

      You need to use apt to install the .deb package locally as it installs its dependencies as well. dpkg will not resolve dependencies, and apt-get cannot install from a local file. Also note that to install PAS from the current directory, you must use the path ./ before the .deb package, or apt will try to download the package from a repository.
  1. Provide the number of the port where you want the PAS Web UI to be available at, over HTTP:

Defining port number for PAS Web UI Over HTTP
Figure 12. Defining port number for PAS Web UI over HTTP
  1. Provide the number of the port where you want the PAS Web UI to be available at, over HTTPS:

Defining port number for PAS Web UI over HTTPS
Figure 13. Defining port number for PAS Web UI over HTTPS
  1. Define if the existing configuration files shall be overwritten by this generated configuration.