Skip to main content
Version: 25.7.0

Portal On-boarding Process

Requirements​

The RASP Java Agent must be installed in order to onboard it. See the relevant RASP Java Agent Installation Guide for more information.

The following filesystem permissions are required:

  • read and write permission to the Portal installation directories;
  • read and write permissions to the rules file as well as the rules file parent directory. The rules file location is set by the value of the com.waratek.rules.local property defined in the waratek.properties file.

If the RASP Java Agent is behind a firewall then TCP connections need to be configured from the Agent to agent-api-2.waratek.com.

If the Agent is running on an older JDK that does not support TLS version 1.2 by default then additional domains may be required.

The Agent must also trust the certificate authorities that the Portal is served with. See Configuring a trustStore below.

On-boarding Steps​

Step 1: Setup Agent Properties File​

  1. Open (or create if it does not already exist) the waratek.properties file;

  2. Ensure the file contains the following waratek.properties:

    com.waratek.ControllerHost=<Address of the Portal>
    com.waratek.OrgId=<Your organization ID>
    com.waratek.accessKey=<An access key>
    com.waratek.secretKey=<A secret key>
    com.waratek.rules.local=<full/path/to/policy.armr>
    com.waratek.log.file=<full/path/to/security.log>
    com.waratek.rules.autoreload=true

The waratek.properties file may contain additional, optional, waratek.properties.

This feature automatically assigns an Agent to an application in the Portal without any manual intervention. The user does not need to assign the agent to the application.

  1. In the Portal, navigate to “Applications” ---> [An Application Page] ---> “Configure”;
  2. Copy the on-boarding key;
  3. Paste the on-boarding key as the value of the com.waratek.ControllerKey property in the waratek.properties file.

Step 3: Launch the Agent and Assign it to an Application​

Launch the RASP Java Agent.

  1. If automatic on-boarding is enabled, the agent will be automatically assigned to the specified application;

  2. If automatic on-boarding is not enabled, the Agents assigned to an Application as follows:

    1. In the Portal navigate to “Applications” ---> [An Application Page] ---> “Agents”;
    2. Click the “Unassigned Agents” dropdown menu;
    3. Select the checkbox for the Agent that was launched;
    4. Click the “Assign” button.

Successful On-boarding​

Successful on-boarding results in the Agent credentials persisting in the instance.waratek.properties file. For example:

########################################################
# THIS WAS GENERATED BY THE CONTROLLER - DO NOT MODIFY #
com.waratek.NodeId=ENC(DYIImFBaaL3QP+uauK6Y5Q==)
com.waratek.NodePassword=ENC(sBq6EmmsBOGd9K2iafh9+Uud3MlryAY4IOtOMEjhr7c=)
########################################################

If an agent is ungracefully shutdown, which could happen during a DoS type of attack against an application, the agent might not send the very latest events to the Portal. Please check the local log file for the events when necessary.

Configuring a trustStore​

The Agent must trust the certificate authorities that the Portal is served with. For Portal SaaS these are the Amazon Trust Services roots, which current JDKs already trust through their default cacerts file.

Supply a trustStore explicitly if:

  • the Agent runs on an older JDK whose cacerts predates those roots;
  • the application starts with a custom trustStore that does not contain those roots, or whose password is not available to the Agent.

A failure of this kind usually appears in the Agent log as PKIX path building failed or unable to find valid certification path to requested target.

A ready-made trustStore containing the roots required for Portal SaaS can be downloaded from Agent trustStore. To apply it, set the following in the waratek.properties file, using an absolute path:

com.waratek.trustStore=<absolute_directory_path_to>/waratek-portal-saas-truststore.jks
com.waratek.trustStorePassword=changeit

com.waratek.trustStorePassword can be encrypted using Encrypting the Properties file

Restart the application afterwards. Java reads a trustStore once at startup, so a restart is required for any change to take effect.

Custom trust store flags are honored for any Portal connection on RASP Java Agent v25.7.0+. On earlier versions these properties apply only to Elasticsearch TLS and external HTTPS relays, not to the Portal connection.

If the Agent cannot validate the Portal certificate against the configured trustStore, it falls back to the JVM default trust manager. Setting these properties therefore does not restrict the Agent to the supplied trustStore, and does not provide certificate pinning.

Connecting Agents via Proxy​

It is necessary to create rules in your firewall to allow each new agent to talk to the Portal. Rather than doing this on a per-agent basis, a single rule in the firewall is much easier to manage and is more secure.

To achieve this you need to have each agent connect to a proxy that sits within your network. The agent requests are then proxied to the Portal, allowing a single firewall rule to be created for the proxy. RASP Java Agent supports an on-premise proxy for agents to connect to the Portal. The requirements for a successful connection are:

  • SSL using a CA-signed certificate
  • TLS 1.2
  • The proxy must set the X-Forwarded-For header
  • The proxy must set the X-WTK-Proxy header to the hostname of the proxy.

Any proxy tool which supports these requirements may be used. See below for an example Nginx configuration extract:

http {
// ... other settings go here

server {
listen 443;
ssl on;
ssl_certificate "/path/to/fullchain.pem";
ssl_certificate_key "/path/to/privkey.pem";
location / {
proxy_pass https://agent-api-2.waratek.com/;
proxy_ssl_server_name on;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-WTK-Proxy wrtk-proxy.myorg.com;
}

Specifying a custom port number​

The agent connects to the Portal using port 443 by default. If the agent is connecting to the Portal via a proxy, the port number can be set using the following property;

com.waratek.ControllerPort=<port number>

The com.waratek.ControllerPort property is supported only on RASP Java Agent v25.0.0+

If com.waratek.ControllerPort is not specified, the default value is 443

Specifying insecure Agent-Portal communication​

The following property is supported only on RASP Java Agent v25.0.0+, for agents connecting to the Portal:

com.waratek.ControllerSecure=<true|false>

If the agent is connecting to the Portal via a proxy, and the proxy is not configured for SSL communication, then com.waratek.ControllerSecure can be set to false

If com.waratek.ControllerSecure is not specified, the default value is true

The following properties are supported on RASP Java Agent v25.7.0+, for agents connecting to the Portal via a proxy configured for SSL communication:

 com.waratek.ControllerSSLCertificateValidation=<true|false>
 com.waratek.trustStore=<absolute_directory_path_to>/<keystore_generated from_proxy_cert>
 com.waratek.trustStorePassword=<keystore_password>

com.waratek.trustStorePassword can be encrypted using Encrypting the Properties file

If com.waratek.ControllerSSLCertificateValidation is not specified, the default value is true If the above trustStore properties are specified then the value of com.waratek.ControllerSSLCertificateValidation property will be ignored.