| Try Spyderbat Community Edition for Free | Set up your test organization and deploy up to 5 Nano Agents | |
| Spyderbat System Requirements | Learn about infrastructure prerequisites and supported OS types before deploying Spyderbat | |
| How to Install a Spyderbat Nano Agent onto a K8s Cluster | How-To guide and a 6-minute video to get you started |
| How to navigate Spyderbat Investigation | Get started with monitoring your environment at runtime | ||
| Spyderbat Dashboards from A to Z | Latest runtime security findings at your fingertips | ||
| Invite your team to experience Spyderbat potential | Manage your users and their access permissions |
| Spyderbat API Integrations | View complete list of integrations |
Amazon Linux 2
Bottlerocket
Ubuntu
GCOS
helm template nanoagent nanoagent/nanoagent
--set nanoagent.agentRegistrationCode=<agent registration code>
--set nanoagent.orcurl=https://orc.spyderbat.com/
--create-namespace
--set spyderbat_tags='CLUSTER_NAME=mycluster:environment=dev'
Click to enlarge
spyctl --version
Select a source to explore in Spydertop.
Spydertop displays CPU, memory, disk, and network usage alongside a detailed process table. Use the timeline at the bottom to step through time.
MCP Inspector connected to Spyderbat MCP server
The Guardian Fingerprints page displays all observed container fingerprints with filtering by cluster, namespace, machine, status, image, and pod labels.
The Guardian Policies page lists all workload policies with their mode, status, and recent deviation counts.
Select one or more Spydertraces from Search, then click Start Process Investigation in the toast bar.
The Investigation view: Records on the left, Causal Tree on the right, Details below.
Run the query to verify it returns results before saving.
Click Save Search to open the saved search configuration dialog.
Configure the name, description, and notification status for the saved search.
Select a notification channel and configure its destination.
Alert triggered at {{ __hr_time__ }}
Details: {{ description }}
" body_text: "Alert triggered at {{ __hr_time__ }}. Details: {{ description }}" ``` ### Slack Slack Notification Templates define the message structure for Slack notifications. Notification templates can be generated in YAML or JSON format as desired. ```yaml apiVersion: spyderbat/v1 kind: NotificationTemplate metadata: name: slack type: slack spec: text: '' blocks: [] ``` After populating template: ```yaml apiVersion: spyderbat/v1 kind: NotificationTemplate metadata: name: slack type: slack spec: text: "Alert: {{ severity }} - {{ description }}" blocks: - type: section text: type: mrkdwn text: "*Alert Triggered at:* {{ __hr_time__ }}\n*Details:* {{ description }}" ``` ### Webhook Webhook Notification Templates define the payload structure for webhook notifications. ```yaml apiVersion: spyderbat/v1 kind: NotificationTemplate metadata: name: webhook-template type: webhook spec: payload: {} entire_object: false ``` After populating template: ```yaml spec: payload: severity: "{{ severity }}" details: "{{ description }}" timestamp: "{{ __hr_time__ }}" ``` ### PagerDuty PagerDuty Notification Templates define the format for alerts sent to PagerDuty. ```yaml apiVersion: spyderbat/v1 kind: NotificationTemplate metadata: name: pg type: pagerduty spec: class: null component: null source: '' summary: '' severity: '' dedup_key: null custom_details: {} group: null ``` After populating template: ```yaml spec: summary: "Spyderbat Saved Query '{{ __query_name__ }}' Matched" source: "{{ __source__ }}" severity: "{{ __pd_severity__ }}" custom_details: "description": "{{ description }}" "cluster": "{{ __cluster__ }}" "time": "{{ __hr_time__ }}" "linkback": "{{ __linkback__ }}" ``` Use these templates to ensure consistent and structured notifications across different channels. ## Placeholder Fields and Dynamic Variables Some fields in Notification Templates are dynamically calculated and replaced at runtime using placeholders. These placeholders allow real-time data insertion into notification messages. ### Understanding Placeholder Fields Placeholder fields allow dynamic values to be inserted into notification templates. These fields are replaced with actual data when a notification is sent. They're represent with syntax: `__field__` **Some Common Spyderbat Internal Placeholder Fields are:** {{ \_\_source\_\_ }} - Source of the event {{ \_\_cluster\_\_ }} - Cluster where the event occurred {{ \_\_hr\_time\_\_ }} - Human-readable timestamp {{ \_\_linkback\_\_ }} - Link to view the event in Spyderbat {{ \_\_time\_int\_\_ }} - Timestamp in integer format {{ \_\_origin\_\_ }} - Origin of the event {{ \_\_hostname\_\_ }} - Hostname where the event occurred {{ \_\_percent\_\_ }} - Percentage value related to the event {{ \_\_pd\_severity\_\_ }} - Severity level formatted for PagerDuty {{ \_\_query\_name\_\_ }} - Name of the saved query that triggered the event Example Usage in Email Body: ```Spyderbat Custom Flag "{{ custom_flag_name }}" Emitted
{{ description }}
``` ### Dereferencing Values from the Object: Static fields or regular placeholders ({{ severity }}, {{ description }}) are fields that are passed directly from the model object. Static text remains unchanged and does not need placeholders. * {{ severity }} - Severity level of the event * {{ description }} - Description of the event By customizing Notification Templates with placeholders, users can ensure notifications provide meaningful and actionable information tailored to their needs. **To learn more about Placeholder fields and Constructing templates** [**Read this**](https://github.com/spyderbat/spyderbat-docs/tree/main/concepts/notifications/reference/notifications/README.md) ## Conclusion By following this guide, you can create well-structured, dynamic Notification Templates for different destinations. Using placeholders correctly ensures your notifications contain relevant, real-time data. ## Manage Notification Templates Using Spyctl To start creating Templates follow our tutorial using Spyctl : [Manage Notification Templates Using Spyctl](/reference/spyctl/notification-template-management-spyctl) ## Quick Start Tutorial To quickly get started using using Spyderbat Notifications follow our tutorial using spyctl. [How to setup Spyderbat Notifications (Spyctl CLI)](/tutorials/notifications/how-to-set-up-spyderbat-notifications-spyctl) # Actions Overview of manual response actions that can be executed in the UI, including killing a process or killing a pod. The Spyderbat platform features include a powerful response capability: the option to kill processes on Linux machines or pods within Kubernetes clusters directly through the UI. This feature empowers security teams to take immediate action during an investigation, stopping active threats as soon as they are identified. Whether dealing with malicious processes on a machine or a compromised pod within a Kubernetes cluster, users can mitigate the threat swiftly and efficiently. This capability ensures real-time responsiveness by terminating the identified threat within seconds. The action is recorded in an audit log for accountability and compliance purposes. ### Who Can Kill a Process or Pod? Killing a process or pod requires specific permissions for the logged in user. By default these permissions are preset for the following Spyderbat Roles: * Admin * Power User Roles for users can be assigned or modiefied in the Admin section, Organization management. For more details, see [User and role management overview](/getting-started/spyderbat-user-and-role-management-overview) ### How to Kill a Process or Pod #### 1. Initiating an Investigation The process starts with an investigation, which can be the result of pivoting from a high scoring trace, or a security redflag, drilling down from a dashboard card, or just from the output of the search results to find specific proccess or kubernetes resources of interest. Once you have identified the process of interest in the Investigation section of the UI, you can take action. In this example, we identified a netcat server running on port 9000  #### 2. Taking the Kill Action The kill action can be taken either at the bottom of the graph view, or within the process details view. You can opt to kill the process, or, if the process is running in a container from a Kubernetes cluster, to kill the entire pod. #### 3. Providing a Reason, and Confirming the Kill Action After selecting the "Kill Process" action, a confirmation dialog will appear, prompting you to provide a reason for the action. This reason will be recorded in the audit log for accountability and future reference. Input a clear and concise reason for the kill action, for example "Terminating malicious process" or "Shutting down compromised pod."  To prevent accidental terminations, Spyderbat requires confirmation before executing the kill action. After entering your reason, click 'YES, KILL PROCESS' to proceed with the process termination. The process for killing a pod is exactly the same, just select Kill Pod and follow the confirmation prompt.  #### 5. Action Execution Once confirmed, Spyderbat will automatically terminate the process or pod within seconds. A popup at the bottom-page will provide confirmation. #### 6. Review and Audit Logging After a process is killed, its icon will be updated to reflect it is now defunct, and the process details will contain action audit log information  Every kill action, including the reason for the termination and user details, is recorded in Spyderbat’s comprehensive audit log. You can review this log to track all interventions taken during an investigation. You can find a full log of all actions taken in your account by navigating to the Reports, Action Log section  In the actions log you will find what type of action was taken, the action status, when it was created, the action result code, who took the action, the reason provided and what process or pod was impacted. You can filter for specific actions you are looking for by clicking on "Filters", and adjust the columns view by clicking on "Columns". #### 7. Next Steps After the kill action, you should continue to identify root-cause of the unexpected behavior you chose to terminate. It is possible another process is still active that could respawn the same type of process you just killed, so reviewing processes again would be a great idea. Similarly, if you chose to kill the pod, be mindful a new pod might be automatically created by the cluster, exhibiting the same threat you tried to eliminate. Confirm that the behavior you want to see addressed is not introduced by a higher-up kubernetes resource manager, such as a deployment or statefulset that was compromised. # Integrations Integrate Spyderbat with your existing security infrastructure — route events to your SIEM, connect AWS accounts, and forward data to external tools. Spyderbat integrates with your security stack in two ways. | Integration | What it does | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | [SIEM Forwarding](/concepts/integrations/siem-forwarding) | Route events matching saved queries to your SIEM — via the [Event Forwarder](/concepts/integrations/spyderbat-event-forwarder) or direct API polling | | [AWS Integration](/concepts/integrations/aws) | Connect Spyderbat to your AWS environment for cloud-native visibility | # SIEM Forwarding How Spyderbat SIEM forwarding works — enabling forwarding on saved queries and deploying the Event Forwarder to deliver events to your SIEM. {% hint style="success" %} Just want to get started? See the [SIEM Forwarding Quickstart](/tutorials/integrations/siem-forwarding-quickstart). {% endhint %} SIEM forwarding in Spyderbat is a two-part system. First, you enable forwarding on one or more saved searches (also called saved queries in the API and spyctl CLI), which tells Spyderbat which events to collect. Second, you deploy the Event Forwarder (or poll the API directly), which retrieves those collected events and delivers them to your SIEM. The Event Forwarder only receives events that a saved search has already selected for forwarding — without step one, step two delivers nothing. You can install the Event Forwarder before or after enabling forwarding on a saved search — the forwarder polls continuously and picks up new forwarding-enabled queries automatically. ## How it works ```mermaid flowchart TD A["Saved query (SIEM Forwarding: enabled)"] -->|record matches| B["Buffered events"] B -->|Event Forwarder polls| C["Event Forwarder"] B -.->|or direct API polling| E["Your SIEM"] C --> D["File / Webhook / Stdout / Syslog"] D --> E ``` When an incoming record matches a saved search that has SIEM forwarding enabled, Spyderbat buffers that record for your organization. The Event Forwarder polls for new records, enriches each one with a `runtime_details` object containing host metadata, and writes to your configured destination. You can also skip the Event Forwarder and poll the API directly, but this requires custom scripting to manage the cursor. ## Step 1: Enable forwarding on a saved query If you don't have a saved query yet, [create one first](/concepts/search/saved-search). Then enable the **SIEM Forwarding** toggle in **Additional Settings** when editing the query. Scroll to the bottom of the edit dialog to find **Additional Settings** — this section may not be visible without scrolling. Forwarding takes effect immediately for new matching records — it does not retroactively forward records that were created before forwarding was enabled. No forwarder restart is needed. You can enable it on as many queries as you want, across any Spyderbat schema. If a record matches multiple forwarding-enabled queries, it is forwarded once. **Example queries:** | Intent | Schema | Filter | | ------------------------ | ------------------- | ------------------- | | All Spydertraces | `model_spydertrace` | `*` | | High-scoring traces only | `model_spydertrace` | `score > 50` | | All security flags | `event_redflag` | `*` | | High-severity flags only | `event_redflag` | `severity = "high"` | | All network connections | `model_connection` | `*` | {% hint style="info" %} The Schema values above (`model_spydertrace`, `event_redflag`, etc.) are the API and spyctl identifiers. The search UI uses friendlier display names — for example, the UI shows "Spydertrace" for `model_spydertrace`. Select the matching display name from the schema dropdown when building queries in the console. {% endhint %}Enable SIEM Forwarding in Additional Settings when editing a saved search.
The Causal Tree (right) displays nodes added from the Records panel (left). The Details panel (bottom) shows metadata for the selected node.
Right-click a node to access load, remove, and search options.
The Options dropdown with display toggles. Show Relative Time is enabled, displaying timestamps on each node.
curl https://api.prod.spyderbat.com/api/v1/org/ -H "Authorization: Bearer API_key"
curl https://api.prod.spyderbat.com/api/v1/org/Org_id/source/ -H "Authorization: Bearer API_key"
Cluster
Machine
Service
makeRedFlag
makeOpsFlag
agentKillProcess
agentKillProcessGroup
Cluster
Machine
Namespace
Pod
Container
makeRedFlag
makeOpsFlag
agentKillProcess
agentKillProcessGroup
agentKillPod
makeRedFlag
makeOpsFlag
agentKillPod
Cluster
Machine
Trace
User
Severity: {{ severity }}
Description: {{ description }}
Process: {{ name }} (Executed by {{ auser }}, Effective user: {{ euser }})
Command: {{ args | join(" ") }}
Detection Time: {{ time }}
MITRE Technique: {{ mitre_mapping[0].technique_name }}
body_text: | Spyderbat Alert Severity: {{ severity }} Description: {{ description }} Process: {{ name }} (Executed by {{ auser }}, Effective user: {{ euser }}) Command: {{ args | join(" ") }} Detection Time: {{ time }} ``` These examples demonstrate how you can leverage dereferencing to dynamically include specific values from the JSON object in your notifications for more context on alert. Feel free to adjust the examples based on your specific use cases and requirements. ## Internal Functions In Spyderbat's Notification Templates, you can enhance the template alert by using internal functions as well in each Template type. The syntax for using functions is as follows: * `{{ __FUNCTION_NAME__ [| ARG1, ARG2, ..., ARGN] }}` Arguments are optional, depending on the function used. The return value of the function will replace the `{{ __FUNCTION_NAME__ }}` placeholder, or an error message will be displayed if something goes wrong. ### Example JSON object used in function examples: This metrics record is used to monitor the resource utilization of the Spyderbat Nano Agent. ```json { "schema": "event_metric:agent:1.0.0", "id": "event_metrics:07Ax6uRpB606065sYozQ:ZWXXXX", "ref": "agent:07Ax6uRpB606065sXXXX", "version": 1, "muid": "mach:5sZN4f2mXXX", "time": 1701460978.1299076, "cpu_cores": 2, "total_mem_B": 8173600768, "hostname": "example_machine", "cluster_name": null, "bandwidth_1min_Bps": 1616, "cpu_1min_P": { "agent": 0.0417, "authUID": 0.0002, "bashbatUID": 0.0002, "grimreaperUID": 0.0034, "procmonUID": 0.0003, "scentlessUID": 0.0355, "snapshotUID": 0 }, "mem_1min_B": { "agent": 355326000, "authUID": 29440000, "bashbatUID": 37820000, "grimreaperUID": 42692000, "procmonUID": 38005000, "scentlessUID": 71352000, "snapshotUID": 45604000 }, "mem_1min_P": { "agent": 0.04347239485822658, "authUID": 0.003601839732038158, "bashbatUID": 0.004627091666633258, "grimreaperUID": 0.005223156991853704, "procmonUID": 0.004649725510058091, "scentlessUID": 0.008729567546208785, "snapshotUID": 0.005579425921870522 }, "missed_messages": { "scentless": { "pcap_dropped": 0, "data_drop_delayq": 0, "data_drop_dns": 0, "missed_events": 0 } } } ``` ### Functions: *** #### **{{ \_\_cluster\_\_ }}** * *Arguments:* This function takes 0 arguments * *Description:* Returns the name of the cluster the object is associated with or "No Cluster." **Pagerduty Template spec Example:** ```yaml spec: custom_details: "cluster": "{{ __cluster__ }}" ``` *** This would result in a list displayed in the notification: * Cluster: No Cluster This is because in the metrics object above, the cluster\_name field is null. *** #### **{{ \_\_hr\_time\_\_ }}** * *Arguments:* This function takes 0 arguments * *Description:* Returns a human-readable version of the time field found in the object. **PagerDuty Template Spec Example:** ```yaml spec: custom_details: "time": "{{ __hr_time__ }}" ``` This would result in a list displayed in the notification: * Time: 2023-12-01 20:02:58UTC This converts the epoch time 1701460978.1299076 in the `time` field in the record above to something human readable. *** #### **{{ \_\_linkback\_\_ }}** * *Arguments:* This function takes 0 arguments * *Description:* Returns a relevant URL linking back to the Spyderbat Console for the object being evaluated. **PagerDuty Template Spec Example:** ```yaml spec: custom_details: "linkback": "{{ __linkback__ }}" ``` This would result in a linkback URL being generated, pointing to the Agent Health page for the agent referenced above `"ref": "agent:07Ax6uRpB606065sXXXX"`. It would display as a link "View in Spyderbat" at the bottom of your notification. *** #### **{{ \_\_origin\_\_ }}** * *Arguments:* This function takes 0 arguments * *Description:* Returns a string explaining why the notification was generated. **PagerDuty Template Spec Example:** ```yaml spec: custom_details: "origin": "{{ __origin__ }}" ``` This would result in a message like: `Notification Origin:`\ `This notification was generated because an event_metric record matched the condition specified in notification config "Agent CPU Usage - notif:6voXLIYfRPmTky-XVAaXXX".` *** #### **{{ \_\_percent\_\_ | number }}** * *Arguments:* This function takes exactly 1 argument * number: * type: String or Number * description: If a String is supplied, the string must be a field in the object with a numerical value. * *Description:* Multiplies an input number by 100, caps the precision at 2 decimal places, and appends a percent (%) symbol. **PagerDuty Template Spec Example:** ```yaml spec: custom_details: "CPU Usage": "{{ __percent__ | cpu_1min_P.agent }}" ``` This would result in a list displayed in the notification: * CPU Usage: 4.17% **Here’s an all list of the field names along with their actual function:** * `__hr_time__` – Human-readable timestamp of the event. * `__time_int__` – Timestamp in integer format. * `__linkback__` – URL linking back to the event in Spyderbat. * `__origin__` – The origin or source of the event. * `__cluster__` – The cluster where the event occurred. * `__source__` – The source component or entity that generated the event. * `__hostname__` – The hostname where the event took place. * `__percent__` – A percentage value associated with the event. * `__pd_severity__` – Severity level formatted specifically for PagerDuty. * `__query_name__` – The name of the saved query that triggered the event. Conclusion: You can use a mix of both Static values from the Object by dereferencing and using Spyderbat's Internal function to enhance templates for direct context on Notification Alert. # Spyctl CLI # Spyctl Commands ### Readthedocs Spyctl's commands are documented on [readthedocs.io](https://spyctl.readthedocs.io/en/latest/commands.html) ### Spyctl CLI If you have already installed Spyctl you can also see the command documentation by running `spyctl --help`. You can also run `spyctlspyctl get notification-targets
spyctl get notification-targets -o yaml OperationsTeam
spyctl get notification-targets -o yaml OperationsTeam > target.yaml