Wrappers

Wrappers are a kind of helpers who wrap a certain piece of JavaScript code for ease of use. They are like bigger functions that perform multiple tasks and hide the complexity of the code behind them. Wrappers start with the wrapper.* prefix.

wrapper.kflPcapS3

This wrapper receives a list of KFL queries as input, monitors traffic and generates PCAP repositories that match any of the KFL entries. The compressed PCAP repositories are uploaded to AWS S3 and optionally sends a Slack notification.

Here’s an example of how to use the helper:

var KFL_PCAP_S3_KFL_ARR = [
    "http and response.status == 500",
    "dns",
];

function onItemCaptured(data) {
    wrapper.kflPcapS3(data, {
        kflArr:             KFL_PCAP_S3_KFL_ARR,
    });
}
  • http and response.status == 500 - HTTP traffic only where response status is 500
  • dns - all DNS traffic

The Input Object

The wrapper.kflPcapS3 expects the following input object:

{
    kflArr:             string[],   // the only mandatory field
    awsRegion:          string,     // default: env.AWS_REGION
    awsAccessKeyId:     string,     // default: env.AWS_ACCESS_KEY_ID
    awsSecretAccessKey: string,     // default: env.AWS_SECRET_ACCESS_KEY
    s3Bucket:           string,     // default: env.S3_BUCKET
    slackWebhook:       string,     // if doesn't exist, no slack message will be sent
    slackAuthToken:     string,     // if doesn't exist, no slack message will be sent
    slackChannelId:     string,     // if doesn't exist, no slack message will be sent
    active:             bool,       // default: true
    verbose:            bool,       // default: false
    maxMinutes:         int,        // default: 60
    maxL4Streams:       int         // default: 100000
}

Here’s an example of how to use the wrapper with a complete input object, overriding all defaults:

wrapper.kflPcapS3(data, {
  kflArr:             KFL_PCAP_S3_KFL_ARR, // Mandatory
  /* AWS S3 credential must be present, either here or in the config file as env variables */
  awsRegion:          env.AWS_REGION,
  awsAccessKeyId:     env.AWS_ACCESS_KEY_ID,
  awsSecretAccessKey: env.AWS_SECRET_ACCESS_KEY,
  s3Bucket:           env.S3_BUCKET,
  /* Optional: A slack message is fired only if these properties are provided. There's no default value */
  slackWebhook:       env.SLACK_WEBHOOK,
  slackAuthToken:     env.SLACK_AUTH_TOKEN,
  slackChannelId:     env.SLACK_CHANNEL_ID,
  /* The rest of the properties are optional */
  active:             true,   // set to false to deactivate this helper
  verbose:            false,  // set to true to see verbose log
  maxMinutes:         60,     // maximum time for a single PCAP file
  maxL4Streams:       10000,  // maximum L4 streams for a single PCAP file
});

Kubeshark uploads the compressed PCAP repositories to AWS S3, making them available in your AWS S3 console:

S3 FIles

Progress Log File

wrapper.kflPcapS3 maintains a progress log file in the AWS S3 bucket. Here’s the progress log file matching the above example:

[
  {
    "file": "kfl_0_kubeshark_1678808288.tar.gz",
    "kfl_index": 0,
    "kfl_query": "http and response.status == 500",
    "s3_url": "https://kubeshark-helper-test.s3.us-east-2.amazonaws.com/my-cluster_192.168.49.2/kfl_0_kubeshark_1678808288.tar.gz",
    "time": "Tue, 14 Mar 2023 15:38:26 GMT"
  },
  {
    "file": "kfl_1_kubeshark_1678808543.tar.gz",
    "kfl_index": 1,
    "kfl_query": "dns",
    "s3_url": "https://kubeshark-helper-test.s3.us-east-2.amazonaws.com/my-cluster_192.168.49.2/kfl_1_kubeshark_1678808543.tar.gz",
    "time": "Tue, 14 Mar 2023 15:42:53 GMT"
  },
  {
    "file": "kfl_0_kubeshark_1678808758.tar.gz",
    "kfl_index": 0,
    "kfl_query": "http and response.status == 500",
    "s3_url": "https://kubeshark-helper-test.s3.us-east-2.amazonaws.com/my-cluster_192.168.49.2/kfl_0_kubeshark_1678808758.tar.gz",
    "time": "Tue, 14 Mar 2023 15:46:18 GMT"
  },
  {
    "file": "kfl_1_kubeshark_1678808954.tar.gz",
    "kfl_index": 1,
    "kfl_query": "dns",
    "s3_url": "https://kubeshark-helper-test.s3.us-east-2.amazonaws.com/my-cluster_192.168.49.2/kfl_1_kubeshark_1678808954.tar.gz",
    "time": "Tue, 14 Mar 2023 15:49:32 GMT"
  }
]

Optional Slack Alerts

To get Slack alerts upon new PCAP repository available in S3, include Slack credentials as part of the input object. If Slack credentials are not provided, no Slack message will be sent.

PCAP Repository Content

The PCAP repositories include additional meta-data information that accompanies the PCAP files.

The content of each repository The repository file name includes the KFL query index and the UNIX timestamp it was generated.

The repository includes a content.json file that includes some meta-data about the PCAP file. The meta-data includes:

  • KFL query index
  • KFL query
  • The L4 streams
  • The PCAP file name
  • The time of creation

It looks something like this:

{
  "kfl_index": 1,
  "kfl_query": "dns",
  "l4_streams": [
    "000000007221_udp.pcap",
    "000000007222_udp.pcap",
    "000000007223_udp.pcap"
  ],
  "pcap_file_name": "1678819560.pcap",
  "time": "Tue, 14 Mar 2023 18:46:13 GMT"
}

Next in the repository is the name_resolution_history.json. As L4 streams contain only IPs and no identities, this file includes a history log and timing of all the name to IP resolutions made at the node where the PCAP was generated.

The file looks something like this:

{
  "1678818739": {
    "10.103.193.44": {
      "FullAddress": "kubeshark-front.kubeshark",
      "Namespace": "kubeshark"
    },
    "10.103.193.44:80": {
      "FullAddress": "kubeshark-front.kubeshark",
      "Namespace": "kubeshark"
    },
    "10.106.97.98": {
      "FullAddress": "kubeshark-hub.kubeshark",
      "Namespace": "kubeshark"
    }
  }
}

You can view the content of the repository using Kubeshark with the kubeshark tap --pcap <pcap-repo-name>

Read more in the PCAP section