This support article provides the requirements for installing an on-premises, air-gapped deployment of the ObjectSecurity OT.AI Platform on a Kubernetes cluster. We will also cover the required system specifications to host the deployment, configuration requirements, and an installation process overview.

The ObjectSecurity OT.AI Platform uses Kubernetes to increase binary vulnerability analysis speed and scalability. This is accomplished by parallelizing the computation required for binary assessment across multiple nodes in a Kubernetes cluster.

Technical Requirements:

To facilitate a successful on-prem ObjectSecurity OT.AI Platform Kubernetes deployment, the following system specifications are recommended:

• Each node in the Kubernetes cluster has a minimum of 4GB of RAM (recommended 8-16GB), and one node must be a minimum of 6GB.
• Kubernetes cluster nodes must have a minimum of 80GB of available storage.
• All remaining nodes in the Kubernetes cluster must have a minimum of 20GB of available storage.
• Each node in the Kubernetes cluster has a minimum of 2 CPU cores (recommended 4 CPUs).
• Minimum of 3 nodes in the Kubernetes cluster.

Preparing for an ObjectSecurity OT.AI Platform Kubernetes Cluster Deployment:

Estimated time to completion: two hours

This preparation guide assumes you have multiple virtual machines and bare-metal machines on the same network that the Kubernetes cluster can use.

Preferably, the sole purpose of these machines should be to act as nodes in the ObjectSecurity OT.AI Platform Kubernetes cluster (e.g., the nodes should not be used for other computations). If this is not the case (e.g., you have a pre-configured Kubernetes cluster running pre-existing applications for your organization), then the minimum technical requirements must be increased accordingly. For example, suppose your pre-existing Kubernetes applications consume approximately 4GB of RAM on every node in the cluster. The cluster must have at least 8GB of available RAM to support the ObjectSecurity OT.AI Platform.

Additionally, this guide assumes that a one-time Internet connection can be performed to download the ObjectSecurity OT.AI Platform installer files and container images necessary from the ObjectSecurity Secure SFTP Portal or to run the ObjectSecurity OT.AI Platform Kubernetes deployment. If this is not the case or raises any other concerns, please let the ObjectSecurity Sales and Support Team know. Alternatively, we can send you the installer files and container images that are approved for your air-gapped lab via flash drive, disk, or another offline method.

Cluster Setup and Configuration:

It is preferred that a net-new Kubernetes cluster be configured using MicroK8s (https://microk8s.io/), as the Kubernetes distribution will primarily support the ObjectSecurity OT.AI Platform. Other Kubernetes distributions (e.g., Rancher, K3s, etc.) are also supported.

Instructions for installing and starting with MicroK8s can be found here: https://microk8s.io/docs/getting-started. It is important that the add-ons mentioned in Step 6 of the article be enabled:

$ microk8s enable dns
$ microk8s enable hostpath-storage

Instructions for using MicroK8s to create a multi-node cluster (i.e., adding nodes) can be found here: https://microk8s.io/docs/clustering. Once complete, a Kubernetes cluster containing at least three nodes that meet the required system specs should be running.

Additional documentation for configuring and managing a production Kubernetes cluster can be found here: https://kubernetes.io/docs/setup/production-environment/.

If you are using an insecure docker image registry (e.g., a registry exposed over HTTP instead of HTTPS), you must configure microk8s to be aware of the insecure registry. This can be done by following the instructions here: https://microk8s.io/docs/registry-private. Other Kubernetes distribution may have different requirements for working with insecure registries, so please refer to your Kubernetes distribution’s documentation for details.

Kubectl

A Kubernetes cluster is managed using a command-line tool called Kubectl. Kubectl is used to create, destroy, and update Kubernetes resources. MicroK8s comes with Kubectl pre-installed and can be aliased using the following command (which may be placed in ~/.bash_aliases):

$ alias kubectl='microk8s kubectl'

$ microk8s.kubectl config view –raw > $HOME/.kube/config

$ sudo apt-get install nfs-kernel-server
$ sudo modprobe nfs
$ sudo modprobe nfsd

$ # removes a single image
$ docker rmi -f 

$ # removes all images
$ docker rmi $(docker images -a -q)

$ helm install --set registry=registry:5000 --set registryUsername=admin --set registryPassword=password –set memLimit=16 otai otai.tgz

Installed Kubernetes Objects:

A successful installation of the ObjectSecurity OT.AI Platform Kubernetes deployment will install the following Kubernetes Objects (https://kubernetes.io/docs/concepts/overview/working-with-objects/):

• otai Namespace: This namespace incorporates all the following Kubernetes objects together so that they may be cleanly separated from other applications running on pre-existing Kubernetes clusters.
• otai-registry-secret Secret: This secret encodes the local container image registry’s username and password such that images may be pulled from it at runtime.
• otai-nfs-server Deployment: This deployment hosts a Network File System used by other Deployments/Pods running in the cluster.
• otai-nfs-service Service: This service exposes the otai-nfs-server IP address for use inside the cluster.
• otai-operator Deployment: This deployment performs the bulk of the ObjectSecurity OT.AI Platform’s assessment orchestration, authentication, extraction, and input handling. It spawns other assessment containers at runtime to perform binary analyses.
• otai-operator Service: This service exposes the user interface of the otai-operator outside of the cluster as a NodePort (i.e., port 30004).
• otai-operator-service-account ServiceAccount, otai-operator-role Role, and otai-operator-rolebinding RoleBinding: These objects are used to give the otai-operator deployment permissions to run binary assessment pods within the cluster.
• otai-pv Persistent Volume, otai-pvc Persistent Volume Claim, otai-nfs Storage Class: These objects are used to wrap the Network File System such that other Deployment/Pods may perform read/writes to/from it.

At runtime, ephemeral Pods are spawned and despawned within the cluster by the otai-operator while performing binary analyses.

Uninstallation

To uninstall the ObjectSecurity OT.AI Platform from the Kubernetes cluster, the following command may be used:

$ helm uninstall otai

To facilitate a transparent user experience and to enable full third-party integration with the ObjectSecurity OT.AI Platform, OpenAPI Initiative functionality is natively integrated into the platform.

The “OpenAPI Page” details the API routes for interacting with the OT.AI Platform. The API routes, corresponding description, and ‘Send” button are all listed on the left panel. Clicking the “Send” button queries the route, producing output on the right panel. Additionally, you may toggle between different API routes via a dropdown menu:

Additionally, some API routes require additional parameters or arguments. These parameters and arguments are listed on the left panel if needed:

External Usage

Our API may also be queried externally from any network connection with access to your deployment. Depending on your deployment type, the URL used to query the routes will differ.

Offline/On-Prem Virtual Machine:

Typically, an Offline/On-Prem virtual machine will be accessible via localhost. In this case, the following URL format will suffice:

https://localhost/rbui/<route>

If your On-Prem virtual machine is hosted on a private network, the following URL format will suffice, with ip_address referring to the IP address of your deployment on your local network.

https://<ip_address>/rbui/<route>

(The here refers to any route described in the Available Routes section.)

Cloud Deployment:

For Cloud Deployments, the API will be accessible from anywhere on the Internet. The following URL will be used, with deployment_name referring to the name of your cloud deployment.

https://<deployment_name>.objectsecurity.io/rbui/<route>

(The here refers to any route described in the Available Routes section.)

Note on bearer token:

Most OT.AI Platform API routes require a Bearer authentication token. You can learn to get this Bearer token under Authentication in the Available Routes section.

You can read more about Bearer tokens here.

Available Routes

This section provides a general overview of the purpose and output of each route. Information regarding the specific parameters and exact output schema can be found in the application itself.

General:

General routes handle the most basic usage of the OT.AI Platform, mainly including fetching data to view.

• GET /assessor/getassets
  You can use this route to get a list of your assets. Assets have a set of binaries that have each been analyzed.

• POST /assessor/getbinaries
  Use this route to get the set of analyzed binaries in a given asset.

• POST /assessor/getresults
  Use this route to get analysis results for a given binary.
  

• POST /assessor/getcwe
  Get additional information on specific CWEs.
  

Assessments & Analysis:

These routes handle the analysis process, including the ability to queue up and start various assessments.

• GET /assessor/getassetprogress
  Gets the current analysis progress of all ongoing analyses in the user’s current organization. 

• GET /assessor/listbinaries
  Gets the set of binaries uploaded to the dropzone.

• POST /saas/addfile
  Uploads a binary to the dropzone. 

• POST /saas/rmfile
  Removes a binary from the dropzone.
  

• POST /saas/start
  Starts the analysis procedure on the binaries in the dropzone. 

Asset Management:

These routes handle the managing of assets after they have been analyzed. Various actions can be taken on assets, including deleting or updating multiple asset fields.

• GET /assessor/getnumnew
  Gets the number of new assets in an organization. New assets are those that haven’t been viewed yet after being analyzed. 

• POST /assessor/deleteasset
  Deletes an asset from an organization. 

• POST /assessor/renameasset
  Renames an asset.

• POST /assessor/update/assetdescription
  Updates an asset’s description.

• POST /assessor/updateassettype
  Updates an asset’s type.
  
  

• POST /assessor/markassetviewed
  Marks an asset as viewed.

• GET /saas/asset/{assetid}/audit
  Gets the audit log for an asset. 

Facility Management:

These routes handle the management of facilities. Facilities each have a location and set of child assets located within the facility.

• GET /assessor/getfacilities
  Gets all the facilities in the organization. 

• POST /assessor/createfacility
  Creates a new facility.

• POST /assessor/updatefacility
  Updates an existing facility. 

• GET /assessor/getassetsinfacility/{facility_id}
  Get the assets in a facility.

• GET /assessor/deletefacility/{facility_id}
  Deletes a facility. 

• GET /assessor/getdefaultfacility
  Each organization has a default facility that cannot be deleted. All assets in an organization are analyzed in this default facility by default.

Authentication:

Authentication routes manage user login, role-based querying, and 2FA.

• POST /saas/mfalogin
  Gets an “access_token” that may be set as the Bearer Token when calling the “/saas/validate_totp” route. This route acts as the first factor of 2-factor authentication. “/saas/validate_totp” acts as the second factor. 

• GET /saas/generate_totp
  Generates a time-based one-time password for the current user. This TOTP can be converted into a QR code and scanned with Google Authenticator for 2 Factor Authentication.

• POST /saas/validate_totp
  Validates a user’s time-based one-time password and returns to them a token that may be set as the Bearer Token when accessing all other routes of the API. This route acts as the second factor of 2-factor authentication, with “/saas/mfalogin” being the first. 

• POST /saas/auth/user/add
  Creates a new user.

• POST /saas/auth/password
  Updates a user’s password. 

• GET /saas/auth/userinvite/user/{user_id}
  Invites a user to the server. Returns a token specific to the “user_id” set in the API route. The token may be redeemed by the user using the “/saas/auth/userinvite/redeem/{invite}” route. 

• GET /saas/auth/userinvite/redeem/{invite}
  Redeems an invite generated using the “/auth/userinvite/user/{user_id}” route. Returns a token that may be used to set up a new account. 

• POST /saas/auth/user/eula/accept
  Accepts the EULA for the calling user. 

• GET /saas/auth/user/{userid}/profile
  Gets a user’s profile.

Organization Management:

These routes handle the managing of organizations. Organizations each have a set of child facilities and a set of child users. Organizations may have multiple administrators. The server SUPERADMIN is a part of every organization, and there may only ever be one SUPERADMIN at a time.

• GET /assessor/getdashboard
  Gets the data needed to generate the dashboard on the UI. 

• GET /saas/auth/userall
  Gets all the users in an organization. 

• POST /saas/auth/user/addroles
  Assigns a user new roles in an organization. This is equivalent to adding a user to an organization, should the user not already have roles in the organization.

• POST /saas/auth/user/removeroles
  Remove roles from a user in an organization. This is equivalent to removing a user from an organization, should the user not have any remaining roles in the organization after this route has been called. 

• POST /saas/auth/user/setorg
  Swaps the org a user is currently viewing.  

• POST /saas/auth/organization/add
  Adds an organization.

• POST /saas/auth/organization/update
  Updates an organization.

• GET /saas/org/audit
  Gets the audit log of an organization. The audit log tracks the history of all analyzed assets in the organization. 

How-To Unzip Files Using 7-Zip File Manager

Certain binary file types are not supported for analysis until decompressed. For example, a .zip file will raise the following error when uploaded for analysis:

If you encounter this, refer to the following instructions on decompressing and uploading these file types for analysis.

The following file types are compressed:

• .upn
• .bin
• .zip
• .rar
• .tar

The user must first install a file decompression utility on their device to upload these file types. 

There are some popular, free, and open-source file archivers available (ObjectSecurity is not endorsing any of these tools, nor do we receive any form of benefit from you using these tools.):

PC and Mac compatible options:
7-Zip File Manager – 7-Zip File Manager | download
WinRAR – WinRAR | download

Also available for Mac users is the built-in Archive Utility. 

For this tutorial, we will be showing how to decompress files using 7-Zip File Manager. However, the process is the same for all tools above. 

1. Once installed, open 7-Zip File Manager. 

2. Within the 7-Zip File Manager, navigate to the location of the compressed binary file. In this example, we are uploading the contents of uconnect.upn for analysis. Once found, double-click the file to unpack.

3. Once unpacked, the file contents will be visible within the active directory. From here, locate the file contents you want to run binary analysis on, select all of the associated files, and right-click.

4. Choose the “Copy To…” option.

5. Choose the location where you would like to copy the files and hit “OK.”

6. Now, navigate to the ObjectSecurity OT.AI Platform and select “Upload Files” on the binary upload prompt. Select your files from the location you chose to copy and upload the binary files.   

Download each of the .ova fragment files (.001, .002 etc.) and the license file. Downloading the .ova files may take anywhere from 30-60 minutes.

Next, open 7-Zip File Manager and navigate to the file location where the downloaded files are being kept. Within 7-Zip File Manager, right-click on the first file titled “OT_AI_V…_.zip” and select the “Combine files…” option.

Now you will have access to an .ova file called otai.ova. Proceed to the next part of this tutorial for how to import the .ova into your virtual machine platform.

Next, select the icon highlighted in red and locate the otai.zip file obtained from the steps listed above in the download portion of this tutorial. Once the file has been selected, click Open and then Next.

Set the configuration, so there are at least 4 Cores for CPU and 16000 MB for RAM. To set the property, double-click on the field and enter the value. Once finished, click Import in the bottom right corner to continue. The Import may take a few minutes. 

You are now ready to log in to the platform! Click Start within VirtualBox to boot up the virtual machine containing the OT.AI Platform. 

[PART 3] How-To Import the ObjectSecurity OT.AI Platform Using VMWare

Open VMWare and select “Open a Virtual Machine.” Next, please navigate to the location where your otai.ova file is stored, ensure it is selected, and click Open.

Next, enter a name for the virtual machine:

Name: ObjectSecurity OT.AI Platform

The storage path will automatically be filled in once you enter a name. 

Once finished, click Import. The Import may take a few minutes.

Once the Import has been completed, click “Edit virtual machine settings.”

Set the configuration, so there are at least 4 Cores for Processors (CPU) and 16000 MB for RAM (Memory). Once finished, click OK in the bottom right corner.

ObjectSecurity OT.AI Platform Offline VM version is ready to be deployed. 

How-To Import a Pre-Built ObjectSecurity OT.AI Platform Metrics Kibana Dashboard

This article will explain importing a pre-built ObjectSecurity OT.AI Platform Metrics Dashboard into Kibana. A sample dashboard will be included towards the end of this article.

This article aims to expedite the process of building a custom ObjectSecurity OT.AI Platform metrics dashboard by showing how to import one that already shows some useful metrics about assets, binaries, and analysis results. For more instructions on configuring Kibana dashboards, please refer to the Kibana documentation.

Importing a Dashboard

1. First, log in to Kibana. From within Kibana, open the hamburger menu (three lines in the top left corner) and navigate to “Stack Management” under the “Management” settings.

2. On the left side menu, navigate to “Saved Objects” under the “Kibana” settings.

3. In the top right corner, select “Import”.

4. Click in the “Import” section and then select the dashboard file, which can be downloaded from the attachments of this article, then click the blue “Import” button.

5. The dashboard has now been imported and can be viewed under the “Dashboard” section of the hamburger menu in the top left corner. The dashboard will be imported under the name “Demo Dashboard.”

This dashboard can be modified however the user pleases. 

How-To Install the ObjectSecurity OT.AI Platform Server Logs and seek help from the support team

If you ever encounter an issue with the ObjectSecurity OT.AI Platform, it may be useful to look through the server logs for any indication of failure. Once you’ve identified an issue with the OT.AI Platform and obtained the server logs covering the time when the issue emerged, you can submit a ticket through the support portal with the server logs attached and request for a team member to take a look. 

Obtaining server logs:
To obtain the server logs, navigate to the right-hand navigation panel, near the logout and knowledge base buttons.

Click on the “Download Server Logs” button.

Once clicked, a download will begin and the server logs will be found in a text file within your downloads.

After you’ve obtained your server logs, submit them to a team member to receive support regarding OT.AI Platform issues

How to Customize a Report

Some organizations may value the detection of certain vulnerabilities over others. For example, a specific CVE may be considered highly threatening in one organization, whereas the same CVE is considered unimportant in another. For this reason, Report Customization is necessary,

To begin customizing a report, either navigate to the “Reports Page” icon, using the left-side menu bar, or by selecting the “Customize Report” option while viewing a binary assessment on the Binary Analysis page.

After selecting a specific binary to customize a report for, the following screen will appear:

Here, you can see a PDF preview of your custom report on the left, with customization options on the right. Specific vulnerabilities appear listed out in the report like so:

You may toggle report content on or off using the right-side-bar. For compliance reasons, no new content may be added to the report. Report content is simply shown or hidden.

How to Share/Download a Report

Customized reports may be downloaded and then shared via a single button press. Once you have customized the report to your liking, simply press the download button to the right of the report PDF:

This will produce and download a PDF file that may then be printed, emailed, or shared with anyone you like.

How-To Apply a Patch to the ObjectSecurity OT.AI Platform Offline VM Version

To apply a patch to the ObjectSecurity OT.AI Platform, you first need to download the ObjectSecurity OT.AI Platform patch files from the ObjectSecurity SFTP download portal. 

Before You Get Started:
– Track down your SFTP download portal credentials, or ask an ObjectSecurity support team member for your login information.

Once you have your ObjectSecurity SFTP login credentials on hand, navigate to the SFTP Download portal here and sign in.

Once you’ve logged in, accept the EULA

Once you’ve accepted the EULA, download all of the patch.zip files from the portal.

Now that you’ve downloaded the patch.zip files, navigate to your OT.AI Platform instance and go to the settings page. From the settings page, go to “Patch Management”. Click “Choose File” to select your downloaded patch file and apply it to your instance.

While the patch applies a spinning wheel will be visible on screen to indicate that the patch is loading. This will take 1-2 minutes.

Once the patch has completed applying, shut down the virtual machine using the “Send the shutdown signal” option.

After shutting down, restart the VM. Once the VM has restarted, the web page UI can be refreshed and the new patch will be active.

This article will explain configuring the ObjectSecurity OT.AI Platform to send logs to Elasticsearch, Logstash, and Kibana (ELK) Stack for more accessible logkeeping and parsing.

The ObjectSecurity OT.AI Platform UI provides an excellent interface for viewing results from your analyses. However, sometimes, users would like to search for assessment results with more granularity or create more complicated search queries for their results. This can be accomplished with the assistance of ELK Stack, which provides the Kibana query language interface for finer search support.

TABLE OF CONTENTS

• Configuring ELK Stack to Accept Logs from ObjectSecurity OT.AI Platform
• Configuring ELK Stack Location within ObjectSecurity OT.AI Platform
• Other Useful Resources:

Configuring ELK Stack to Accept Logs from ObjectSecurity OT.AI Platform

To receive logs from the ObjectSecurity OT.AI Platform, the user must first configure a Logstash pipeline to accept logs from the ObjectSecurity OT.AI Platform. To do this, the user will need root access to the computer or server hosting their ELK stack.

1. Creating a Logstash Config file. First, the user must create a new Logstash configuration file.
   
   With root access, navigate to ~/etc/logstash/conf. d on the ELK server. Once there, the user should create a new configuration file, “objectsecurity.conf,” for ObjectSecurity-specific logs. By default, Logstash reads any file with the extension “.conf” as a valid configuration file. ObjectSecurity OT.AI Platform supports HTTP, UDP, and TCP protocols for sending logs to the ELK stack, so depending on which protocol the user would like to use, they may edit the following configuration file as they wish. Paste the contents below within the file to open ports for receiving logs via all three protocols (the user may delete whichever input blocks they don’t plan on using):

   input {
     http {
       port => 31311
     }
   }
   input {
     tcp {
       port => 31312
       codec => json
     }
   }
   input {
     udp {
       port => 31313
       codec => json
     }
   }
   output {
           elasticsearch {
                   hosts => ["0.0.0.0:9200"]
           }
   }

   This file will create a Logstash configuration file that will receive logs via HTTP at port 31311, TCP at port 31312, and UDP at port 31313. Please note that this configuration expects Elasticsearch to be hosted on port 9200, the default port for Elasticsearch. If you have changed the Elasticsearch location, you must update the port number accordingly. 

   In addition to this, if your Elasticsearch has authentication configured, you will need to update the output fields with the information used to authenticate for your Elasticsearch instance: 
   
   

   output {
     elasticsearch {
       hosts => ["0.0.0.0:9200"]
       user => "elasticusername"
       password => "elasticpassword"
     }
   }

2. Activating a Logstash Pipeline. The user must start the pipeline after creating the configuration file for ObjectSecurity OT.AI Platform logs.

   Navigate to the ~/etc/logstash directory on the ELK server. From here, use your favorite editor (vi, vim, or nano for example) to open the “pipelines.yml” file. Add the following lines to the file to enable the pipeline, then save the file. Please note that if you have named your logstash config file something other than “obejctsecurity.conf”, you will need to update the path.config line to agree with your chosen file name.

   - pipeline.id: objectsecurity
     path.config: "/etc/logstash/conf.d/objectsecurity.conf"

   Once these steps have been completed, your logstash configuration file is now active and your pipeline is ready to receive logs at the ports you have enabled in the configuration. Now that this is done, you are ready to configure ObjectSecurity OT.AI Platform settings to point to your ELK stack and begin sending logs. 
   
   

Configuring ELK Stack Location within ObjectSecurity OT.AI Platform

To get started using the ELK stack integration feature, the user will need to go to the ObjectSecurity OT.AI Platform settings and insert the information for the Elasticsearch IP and port that will be receiving the logs. To find the ELK stash configuration settings within ObjectSecurity OT.AI Platform, go to Settings > Deployment > Configure ELK Stack. From here, the user must select the protocol they would like to use to send the logs, the IP to send the logs to, and the port which the IP will be receiving the logs.

The protocol you select should agree with the whichever protocols you enabled in the Logstash configuration, which you set within the “Creating a Logstash Config file” step of the “Configuring ELK Stack to Accept Logs from ObjectSecurity OT.AI Platform” section outline above.

Note: The user must configure the port from within the Logstash configuration files (these files are stored at /etc/logstash/conf. d). For more info about how to configure the Logstash and the inputs, please refer to the “Configuring ELK Stack to Accept Logs from ObjectSecurity OT.AI Platform” section above on how to set up Logstash and ELK Stack for the purposes of this feature.

To clarify, the IP entry should be the IP of the instance hosting the user’s ELK stack. Once the information has been entered correctly, select Submit to save the settings for ObjectSecurity OT.AI Platform logging destination.

To verify that the configuration is set up properly, each time the submit button is clicked, a test log will be sent to the configured ELK stack instance. The best way to test the configuration is to modify the fields and click submit until the ELK Stack instance receives the test log.

This Getting Started Guide serves to help new users login into the ObjectSecurity OT.AI Platform for the first time. This guide also briefly explains how to analyze your first OT/ICS asset binary files for weaknesses (CWEs), vulnerabilities (CVEs), and unpublished vulnerabilities (Zero-Days).

1. Receiving the first invite link to and navigating to the application.

In order to begin using the application, another user must send you an invitation link.

Click on the asset to view it in detail. The binary files you uploaded with your asset will also appear and may be clicked on to view in further detail.

Congratulations on analyzing your first asset!