Agent Logic

With Network Agents

Users can create and use an unlimited number of Network Agents, each designed to perform a specific network-related automation task.

Agents can detect anomalies and threats, generate reports, export metrics, traces, and logs, enforce network policies, record traffic, and more.

Agent Logic Structure

Each agent’s business logic is written in a JavaScript ES5 script and consists of the following components:

Hooks – Triggered by specific events in the traffic flow.
Helpers – Used to invoke integrations and specific Kubeshark functions.
General Code – Performs calculations and stores information in memory.

Agents process network traffic, perform custom logic, and trigger actions such as generating metrics, exporting logs, producing reports, or automating workflows.

Hooks

Hooks are functions that react to specific network events. They allow the execution of user-defined JavaScript code within Kubeshark’s Golang backend.

For example, the onItemCaptured hook is triggered every time an API call is reassembled. The following example prints the metadata of each captured API call:

function onItemCaptured(data) {
  // Print API call metadata
  console.log("Msg:", data);
}

Hooks run continuously in the background, regardless of whether the dashboard is open or closed.

Common Hooks

Hook	Triggering Event	Executed On	Description
`onItemCaptured`	When an API call is reassembled	Workers	Triggered for each reassembled message. Useful for quick analysis, calculations, or tagging.
`onHubAction`	When `hub.action(action, object)` is called	Hub	Used for transferring or processing objects in the Hub.
`onPodEvent`	On pod events (e.g., restart, crash)	Hub and Workers	Enables response actions like traffic capture before a crash.

Helpers

Helpers trigger actions and integrations, such as sending messages to Slack or exporting data to AWS. They provide access to Kubeshark’s backend features.

Example: sending data to a webhook:

vendor.webhook(
  "POST",
  "https://webhook.site/a42ca96d-4984-45dc-8f72-a601448399dc",
  JSON.stringify(data)
);

Common Helpers

Helper	Purpose	Executed On	Description
`console.log`	Logging messages	Hub and Workers	Used for debugging or generating custom logs and reports.
`jobs.schedule`	Scheduling recurring tasks	Hub and Workers	Runs a function based on a cron expression. Suitable for periodic processing.
`vendor.kinesis.put`	Exporting data to AWS Kinesis	Hub and Workers	Sends data to Kinesis for external processing or storage.

Complete Script Example

This script calculates and logs the number of packets and total traffic (in KB) every minute using the onPacketCaptured hook and a scheduled job:

var packetCount = 0;
var totalKB = 0;

function onPacketCaptured(info) {
  packetCount++;
  totalKB += info.length / 1000;
}

function logPacketCountTotalBytes() {
  console.log("Captured packet count per minute:", packetCount);
  console.log("Total KB captured per minute:", totalKB);
  packetCount = 0;
  totalKB = 0;
}

jobs.schedule("log-packet-count-total-bytes", "0 */1 * * * *", logPacketCountTotalBytes);

Script Storage

Scripts are stored in the kubeshark-config-map. They can be developed locally and synced using the kubeshark scripts command, which automatically detects changes.

Scripts must be compliant with JavaScript ES5 and use the .js file extension.

Example:

kubeshark scripts --set scripting.source=/path/to/your/local/folder

Viewing and Editing Scripts in the Dashboard

All scripts stored in the config map are accessible via the Scripting section in the Kubeshark dashboard:

Accessing the Scripting Dashboard

Script Examples

Example scripts are available in the dashboard and can be loaded via the “Examples” dropdown:

Script Examples

Environment Variables

Define script-specific environment variables using the env section in your configuration:

scripting:
  env:
    SLACK_AUTH_TOKEN: "xo.."
    SLACK_CHANNEL_ID: "C0.."
    WEBHOOK_URL: "https://webh.."
    INFLUXDB_URL: "https://us-e.."
    INFLUXDB_TOKEN: "_9r.."
    INFLUXDB_MEASUREMENT: "st.."
    INFLUXDB_ORGANIZATION: "a.."
    INFLUXDB_BUCKET: "al.."

Reference these variables in your scripts using the env. prefix:

vendor.influxdb(
  env.INFLUXDB_URL,
  env.INFLUXDB_TOKEN,
  env.INFLUXDB_ORGANIZATION,
  env.INFLUXDB_BUCKET,
  "Example Measurement", // Measurement name
  data,                  // Payload
  {"example": "tag"}     // Tags
);

Variable Scopes

Kubeshark scripts support the following scopes:

Function Scope – Defined within a function, accessible only there.
Script Scope – Defined outside functions, accessible throughout the script.
Global Scope – Defined using this, shared across all scripts.