SKI Sensor

A SKI Sensor should be deployed on a node where you wish to discover session secrets. SKI Sensors can be deployed as containers on Linux, Kubernetes and OpenShift using Docker or CRI-O as well as a MS-Windows service. SKI Sensors send keys to a Key Server using Nubeva’s FastKey protocol.

../_images/SensorHighlightedwithDec.png

System Requirements

A single SKI sensor is required on a physical (bare metal) or virtual node. For example a virtual node could be an EC2 instance on AWS, an Azure virtual machine or a GCP compute engine instance. A node could also be part of an EKS, AKS, or GKS Kubernetes or OpenShift cluster. The SKI Sensor extracts session keys from all the processes and containers running on the node even if a container is up for less than a second, which is possible in cloud native environments. Once launched, a SKI Sensor periodically checks and downloads code and signature updates and does not require maintenance.

When a SKI Sensor detects a new process or container it checks which TLS library the process uses, and selects that signature to extract TLS session keys. If the process does not use a known library, the sensor looks for an application specific signature. If such a signature is found, the signature is used. In the rare case that both lookups fail, the sensor sends a KeySense notification.

Sensor Command Line Parameters

SKI Sensors read their basic setup from command line parameters listed below. Highlighted parameters indicate parameters used in the command lines provided in this guide.

  • accept_eula: adding this flag indicates you accept the Nubeva’s EULA
  • baseurl: (string) For simple integration with orchestration systems, SKI sensors check for configuration changes by reading from local files. On Linux this is done by setting the baseurl to file:///host/ followed by the path to the directory where the configuration files are stored, for example file:///host/home/ubuntu/ (including the trailing slash). On Windows baseurl should be set to file://c: followed by the path to the directory that contains the configuration files, for example file://c:/nubeva (a trailing slash should not be included). The files are described in the next section.
  • debug: value [ all | none | main | nutap | nuagentclient | argparser | docker | ssl | keys | keyability ] default:none
  • disable: value [ all | none | panicwrapper | ssl | tagupdates | containerssl | metrics | keyability ] default:none
  • noautoupdate: When set the panic-wrapper will not automatically update the sensor binary.
  • nocloudwatch: Stops logging to CloudWatch if this flag is set. Don’t even start the thing.
  • nutoken: (string) Nubeva token for authenticating to the API
  • ssl-baseurl (string) the base URL for signature updates.

Note

For the most recent signatures please point to Nubeva’s SaaS backend: https://i.nuos.io/api/1.1/wf/.

  • sslcredobj (string) defines a key store authentication parameters. This string is a base64 encoded json object that can be generated using the following command:

Note

# Encode
echo '{"type":"dtls","domain":"key.nubedge.com:4433","region":"test","ak":"user","sk":"password"}' | base64
# Decode
echo 'eyJ0eXBlIjoiZHRscyIsImRvbWFpbiI6ImtleS5udWJlZGdlLmNvbTo0NDMzIiwicmVnaW9uIjoidGVzdCIsImFrIjoidXNlciIsInNrIjoicGFzc3dvcmQifQo=' | base64 --decode

Type “dtls” value means a Key Server, ‘domain’ is the key server’s destination host name, ‘region’ is ‘test’, user, and password fields can be left the same. They are not used but they are required. You should change the domain.

To export session keys to a local file in nsskeylog format, set the type to lcl and region to specify a file:

#Encode
echo '{"type":"lcl","region":"/host/tmp/","domain":"keys.log"}' | base64

#Decode
echo 'eyJ0eXBlIjoibGNsIiwicmVnaW9uIjoiL2hvc3QvdG1wLyIsImRvbWFpbiI6ImtleXMubG9nIn0K' | base64 --decode

#Windows local files encode
echo '{"type":"lcl","region":"c:\\\\nubeva\\\\","domain":"keys.log"}' | base64

#Decode
echo 'eyJ0eXBlIjoibGNsIiwicmVnaW9uIjoiYzpcXFxcbnViZXZhXFxcXCIsImRvbWFpbiI6ImtleXMubG9nIn0K' | base64 --decode
  • version: show current code/binary version

Sensor Configuration Files

The simplest way configure SKI Sensors is by using three configuration files: sensor_login, sensor_create and sensor_get. The contents of the files are listed below.

  • sensor_login:
{
        "status": "success",
        "response": {
                "user_id": "default",
                "token": "default",
                "expires": 31536000
        }
}
  • sensor_create:
{
        "status": "success",
        "response": {
                "sensorid": "i-0216d54994df6bcc1x631140662218946579075626",
                "account_id": "default",
                "plan_id": "default"
    }
}

Note

Sensor ids are not random. You should not modify the value of the sensorid unless you have a valid alternative.

  • sensor_get:
{
        "status": "success",
        "response": {
        "SslCredObj": "eyJ0eXBlIjoiZHRscyIsImRvbWFpbiI6ImtleS5udWJlZGdlLmNvbTo0NDMzIiwicmVnaW9uIjoidGVzdCIsImFrIjoidXNlciIsInNrIjoicGFzc3dvcmQifQo=",
        "SrcGroups": [
                {
                        "_type": "custom.srcgroup",
                        "sensorlist_list_custom_sensor": [
                        "i-0216d54994df6bcc1x631140662218946579075626"
                        ],
                "ssl": true,
                "_id": "1234567890AAAA"
                }
        ]
    }
}

Running SKI Sensors

You should modify baseurl file path the and the value of sslcredobj to the domain of your key server. The key server’s DNS name must resolve to its IP address (usually with /etc/hosts).

Linux Container

The following command launches a SKI Sensor container.

docker run -v /:/host -v /var/run/docker.sock:/var/run/docker.sock  \
--cap-add NET_ADMIN --cap-add SYS_ADMIN \
--cap-add SYS_RESOURCE --cap-add SYS_PTRACE \
--name nubeva-agent -d --restart=always  \
--net=host --pid host nubeva/nuagent \
--accept-eula --contained on \
-nutoken YOUR_NUTOKEN \
-noautoupdate --nocloudwatch  --debug=none \
--disable metrics --disable tagupdates \
--sslcredobj eyJ0eXBlIjoiZHRscyIsImRvbWFpbiI6ImtleS5udWJlZGdlLmNvbTo0NDMzIiwicmVnaW9uIjoidGVzdCIsImFrIjoidXNlciIsInNrIjoicGFzc3dvcmQifQo= \
--baseurl file:///host/<path>/ \
--ssl-baseurl https://i.nuos.io/api/1.1/wf/

You may use a Traffic Generator to create encrypted traffic from which the SKI Sensor extracts keys.

Windows Sensor

To run a Windows sensor that sends keys to key.nubedge.com run the following PowerShell command:

$DownloadDir = $env:TEMP;   $BaseUrl="file:///c:/<path>"; $SSLUrl="https://i.nuos.io/api/1.1/wf/";
$InstallerArg="--noautoupdate --nocloudwatch  -debug none -disable metrics -disable tagupdates --accept-eula -baseurl ${BaseUrl} -ssl-baseurl ${SSLUrl} -sslcredobj eyJ0eXBlIjoiZHRscyIsImRvbWFpbiI6ImtleS5udWJlZGdlLmNvbTo0NDMzIiwicmVnaW9uIjoidGVzdCIsImFrIjoidXNlciIsInNrIjoicGFzc3dvcmQifQo=";
$NubevaTok="YOUR_NUTOKEN";
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri "https://i.nuos.io/NubevaSensor.latest.setup.exe" -OutFile "$DownloadDir\installer.exe"; & "$DownloadDir\installer.exe" NUTOKEN_USERINPUT=$NubevaTok  API_URL_ARG=${InstallerArg} /q;

Note

To troubleshoot a Windows Seneor and see its log:

  • Stop the Nubeva Sensor service from the GUI or run this cli command: net stop nusensorexe.
  • Go to the Nubeva installation directory: C:\Program Files\Nubeva Technologies Ltd\Nubeva Sensor
  • Run the following command with your Nubeva token from the command line:
.\nuagent.exe --nocloudwatch -disable metrics --accept-eula -nutoken YOUR_TOKEN -sslcredobj eyJ0eXBlIjoiZHRscyIsImRvbWFpbiI6ImtleS5udWJlZGdlLmNvbTo0NDMzIiwicmVnaW9uIjoidGVzdCIsImFrIjoidXNlciIsInNrIjoicGFzc3dvcmQifQo= -baseurl file://c:/nubeva -ssl-baseurl https://i.nuos.io/api/1.1/wf/

Kubernetes DaemonSet

SKI Sensors can be deployed as a DaemonSet in K8s. To launch a SKI Sensor DaemonSet modify the following command with a appropriate baseurl and sslcredobj values.

kubectl apply -f https://nubevalabs.s3.amazonaws.com/nuAgentDaemonSet.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: nuagent
spec:
  selector:
    matchLabels:
      name: nuagent
  template:
    metadata:
      labels:
        name: nuagent
    spec:
      hostNetwork: true
      containers:
      - name: nuagent
        image: nubeva/nuagent
        imagePullPolicy: Always
        args: ["--accept-eula", "--nutoken", "YOUR_NUTOKEN", "--sslcredobj", "eyJ0eXBlIjoiZHRscyIsImRvbWFpbiI6ImtleS5udWJlZGdlLmNvbTo0NDMzIiwicmVnaW9uIjoidGVzdCIsImFrIjoidXNlciIsInNrIjoicGFzc3dvcmQifQo=","-noautoupdate", "--nocloudwatch", "--disable", "metrics", "--disable", "tagupdates", "--baseurl", "file:///host/<path>", "--ssl-baseurl", "https://i.nuos.io/api/1.1/wf/"]
        securityContext:
          capabilities:
            add: ["NET_ADMIN", "SYS_ADMIN", "SYS_PTRACE", "SYS_RESOURCE"]
        volumeMounts:
          - name: dockersocket
            mountPath: /var/run/docker.sock
          - name: vhost
            mountPath: /host
      volumes:
        - hostPath:
            path: /var/run/docker.sock
          name: dockersocket
        - hostPath:
            path: /
          name: vhost

TLS Traffic Generator

kubectl apply -f <path of file containing the code below>

You can create a batch job that will spawn a TLS traffic generator every minute using the following yaml file:

apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: tlstraffic
spec:
  schedule: "* * * * *"
  jobTemplate:
    spec: # JOB
      template:
        spec:
          containers:
          - name: tlsgenerator
            image: nubevalab/tlsgenerator
          restartPolicy: Never
      backoffLimit: 2

Native Linux Sensor

SKI Sensors can be deployed as native Linux services by running the following command:

curl -s https://nubevalabs.s3.amazonaws.com/install_linux.sh | sudo bash -s -- \
--accept-eula --versionurl https://i.nuos.io/api/1.1/wf/ \
--nutoken YOUR_TOKEN \
--baseurl file:///host/<path>/ \
--ssl-baseurl https://i.nuos.io/api/1.1/wf/ \
--sslcredobj eyJ0eXBlIjoiZHRscyIsImRvbWFpbiI6ImtleS5udWJlZGdlLmNvbTo0NDMzIiwicmVnaW9uIjoidGVzdCIsImFrIjoidXNlciIsInNrIjoicGFzc3dvcmQifQo= \
--debug none --disable metrics --noautoupdate --nocloudwatch

Note

The parameter versionurl instructs the installation script from where to download the sensor executable. This parameter is not passed to the sensor.