# Security

- Updated on Jul 20, 2026
- Published on Sep 17, 2024

- 6 minute(s) read

## Overview

This article describes the security-related settings available for your Hyperscience instance: TLS / HTTPS for inbound and outbound connections, certificate management, HSTS, TLS version and cipher requirements, listening ports, server-identifying headers, and NGINX issue logging.

All settings are configured through variables in the .env File.

## Configuration reference

The table below lists the ".env" variables described in this article.

| Variable | Purpose | Default | Min. version |
| `NGINX_PORT` | HTTP listening port for inbound connections | `80` | All |
| `NGINX_ENABLE_SSL` | Enables TLS for inbound connections | Disabled | All |
| `NGINX_TLS_CERT` | Certificate filename (in `HS_PATH/certs`) | — | All |
| `NGINX_TLS_KEY` | Private-key filename (in `HS_PATH/certs`) | — | All |
| `SECURE_COOKIES` | Marks cookies as secure; set to `true` when TLS is enabled | — | All |
| `NGINX_ENABLE_SSL_REDIRECT` | Enables HTTP-to-HTTPS redirect | Disabled | All |
| `NGINX_TLS_PORT` | TLS listening port | `443` | All |
| `HS_TLS_VERIFY_ENABLED` | `false` disables outbound certificate validation¹ | `true` | All |
| `HS_TLS_CA_BUNDLE` | Custom CA bundle for validating outbound connections¹ | — | All² |
| `HS_SECURE_HSTS_SECONDS` | Enables HSTS; value is the header's max-age in seconds | Disabled | v37 |
| `HS_SECURE_HSTS_INCLUDE_SUBDOMAINS` | `true` adds _includeSubDomains_ to the HSTS header | `false` | v37 |
| `HS_SECURE_HSTS_PRELOAD` | `true` adds _preload_ to the HSTS header | `false` | v37 |
| `HS_CUSTOM_OPENSSL_CNF_DISABLE` | `yes` restores default OpenSSL cipher options | Not set | All |
| `HS_OPENSSL_SECLEVEL` | OpenSSL security level | `1` | All |
| `HS_OPENSSL_MINPROTOCOL` | Minimum TLS protocol version | `TLSv1.2` | All |
| `NGINX_DISABLE_BACKEND_SERVER_HEADER` | `yes` excludes _X-Extract-Backend-Server_ response headers | Not set | v30.0.7 / v31.0.1 |
| `NGINX_ERROR_LOG_LEVEL` | Minimum severity for logging NGINX issues | `info` | v40 |

¹ Mutually exclusive — use only one of the two. ² Applies to Java Message Service (JMS) connections in v33 and later.

## TLS / HTTPS

To enable TLS in the Hyperscience application, a certificate and a key must be provided.

### Prepare the certificate directory

Hyperscience expects PEM-formatted certificates. [This page](https://www.cloudera.com/documentation/enterprise/5-10-x/topics/cm_sg_openssl_jks.html) discusses how to convert DER-encoded certificates and Java Keystore (JKS) certificates to the PEM format.

1. Create the directory that will hold the certificate and key. Assuming `/mnt/hs/` is used as the `HS_PATH`:

```bash
   mkdir -p /mnt/hs/certs
   ```

2. Copy the certificate and key to this directory.
3. If SELinux is enabled, execute:

```bash
   chcon -t container_file_t -R /mnt/hs/certs/
   ```

### Obtain outbound server's CA certificate in PEM format

To validate outbound HTTPS connections, the application needs the external service's certificate in PEM format, placed in the `HS_PATH/certs` directory. If you don't have the certificate on hand, you can retrieve it directly from the server in one of two ways.

**Option 1: Command line (OpenSSL)**

Run the following command, replacing `<hostname>` with the server's domain name:

```bash
   openssl s_client -showcerts -connect <hostname>:443 </dev/null | sed -n -e '/-.BEGIN/,/-.END/ p' > certifs.pem
   ```

**Option 2: Browser (Chrome)**

1. Go to the server's URL, and click the **View site information** icon to the left of the address bar. 
2. Click **Connection is secure**, and then click **Certificate is valid**.
3. In the **Details** tab, select the bottom certificate in the hierarchy and click **Export**.
4. In the Save dialog, set the file format to **Base64-encoded ASCII, select the certificate chain**, and save the file.

### TLS configuration for inbound connections

Add the following to the “.env” file, where `NGINX_TLS_CERT` and `NGINX_TLS_KEY` are the names of the two files copied into the certs directory:

```ini
   NGINX_ENABLE_SSL=yes
   NGINX_TLS_CERT=<cert filename (without folder path)>
   NGINX_TLS_KEY=<key filename (without folder path)>
   SECURE_COOKIES=true
   ```

Optionally, enable the HTTP-to-HTTPS redirect with `NGINX_ENABLE_SSL_REDIRECT=yes`, and override the default TLS port (443) with `NGINX_TLS_PORT` .

### TLS configuration for outbound connections

Depending on how it is configured, the application may connect to various external services, such as a UiPath Orchestrator instance, over HTTPS or TLS. The mutually exclusive settings described below control how these connections are validated.

#### HS_TLS_CA_BUNDLE (recommended)

This setting specifies a custom bundle of CA certificates to validate against when establishing an HTTPS or TLS connection:

```ini
   HS_TLS_CA_BUNDLE=<CA_bundle_filename>
   ```

To give the application read access to the CA bundle file, run:

```bash
   chmod 644 $HS_PATH/certs/*
   ```

If using SELinux, also run:

```bash
   chcon -t container_file_t .
   ```

This bundle replaces the default set of trusted CA certificates, so it must include all root certificates used by external services. To combine multiple certificates, simply concatenate them together into a single file.

#### HS_TLS_VERIFY_ENABLED

Setting `HS_TLS_VERIFY_ENABLED=false` disables certificate validation entirely, allowing the use of self-signed or enterprise-signed certificates. However, because it leaves connections open to man-in-the-middle attacks, we recommend using `HS_TLS_CA_BUNDLE` instead wherever possible.

```ini
   HS_TLS_VERIFY_ENABLED=false
   ```

### HTTP Strict Transport Security (HSTS)

In v37 and later, you can force users' browsers to connect to your instance via HTTPS rather than HTTP by enabling HSTS. Doing so adds the Strict-Transport-Security HTTP response header to your application URL's responses, preventing cookie-hijacking and downgrade attacks, among other types of malicious activity.

**HSTS is disabled by default**. To enable it, set `HS_SECURE_HSTS_SECONDS` — the number of seconds that users' browsers should remember the URL's enforcement of HTTPS-only access:

```ini
   HS_SECURE_HSTS_SECONDS=<value for max-age for the Strict-Transport-Security header>
   ```

Optionally, set `HS_SECURE_HSTS_INCLUDE_SUBDOMAINS` to `true` to apply HSTS protections across all of the URL's subdomains, and `HS_SECURE_HSTS_PRELOAD` to `true` to add preload to the header. Preload requires `HS_SECURE_HSTS_SECONDS` of at least `31536000` (1 year) and `HS_SECURE_HSTS_INCLUDE_SUBDOMAINS` set to `true`.

### TLS versions and cipher suites

By default, we only support TLS versions 1.2 and above. However, our OpenSSL library configuration options allow you to use TLS 1.0 or 1.1, if necessary.

The OpenSSL library is the default TLS protocol implementation in Linux. For compatibility reasons, we use a custom OpenSSL configuration to relax TLS cipher suite requirements. The following “.env” variables let you fine-tune your TLS cipher suites:

```ini
   HS_CUSTOM_OPENSSL_CNF_DISABLE=<yes/no, default is not set>
   HS_OPENSSL_SECLEVEL=<sec level, default is 1>
   HS_OPENSSL_MINPROTOCOL=<TLS version, default is TLSv1.2>
   ```

- `HS_CUSTOM_OPENSSL_CNF_DISABLE` — `yes` disables the custom configuration and restores the default OpenSSL cipher options; any other value enables the custom configuration.
- `HS_OPENSSL_SECLEVEL` — see OpenSSL's [SSL_CTX_set_security_level](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_security_level.html) documentation for options.
- `HS_OPENSSL_MINPROTOCOL` — see the “-min_protocol, -max_protocol” section of OpenSSL's [SSL_CONF_cmd](https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html) documentation for options.

### Load balancer

To achieve HA/DR goals for the application, we encourage customers to deploy the application on multiple VMs and to use a load balancer for the web requests. To learn more, see [Load Balancer](https://help.hyperscience.ai/deployment/docs/load-balancer).

## Ports and HTTP headers

### HTTP listening port

To change the HTTP listening port for inbound connections (default 80), set:

```ini
   NGINX_PORT=<listening port number>
   ```

### Excluding X-Extract-Backend-Server HTTP headers

The X-Extract-Backend-Server HTTP header of each application response contains the hostname of the VM that processed the request. In v30.0.7+ and v31.0.1+, you can exclude these headers from your application's responses:

```ini
   NGINX_DISABLE_BACKEND_SERVER_HEADER=yes
   ```

## Logging NGINX-related issues

With the `NGINX_ERROR_LOG_LEVEL` “.env” variable in v40 and later, you can specify the minimum severity level an issue must have in order for it to be logged by the syslog utility.

Possible values, from least severe to most severe, are:

- _debug_
- _info (default)_
- _notice_
- _warn_
- _error_
- _crit_
- _alert_
- _emerg_

Choose the level that helps you debug most effectively — at the default _info_ level, issues with _info_ severity and above are logged.

For more details, see NGINX's [Configuring Logging](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/#logging-to-syslog).