@yeet/execsnoop

execsnoop is a lightweight, high-performance tool that monitors and logs the entire execve family of system calls being made to the Linux kernel in real-time. It captures the execution context as well as kernel performance with minimal system overhead. Ideal for real-time monitoring of GitHub Actions, AWS ECS Nodes, and shell scripts for both debugging and compliance / audit purposes.

Installation

Use yeet to install this package

sudo yeet install execsnoop

0.1.0Dual BSD / GPLPublic

Get Started

Video Guide

The above video walks through the following steps:

1. Install yeet

2. Deploy execsnoop

3. Create a collection

4. Monitor events

Data Schema

Each time an exec syscall occurs, a new row is added to the collection with the following schema:

Execsnoop Row

Field	Type	Description
`timestamp`	`DATE`	The time when the exec syscall occurred.
`seq_no`	`INT`	A sequence number for the exec event.
`event`	`JSON`	Contains details about the exec event.

Execsnoop Event

Field	Type	Description
`cgroup_id`	`STRING`	The ID of the control group associated with the process.
`cgroup_name`	`STRING`	The name of the control group associated with the process.
`comm`	`STRING`	The command name of the executed process.
`latency_ns`	`INT`	How long the exec took to complete in nanoseconds.
`uid`	`INT`	The user who triggered the exec.
`gid`	`INT`	The group ID of the user.
`pid`	`INT`	The process ID of the executed command.
`ppid`	`INT`	The parent process ID of the executed command.
`tgid`	`INT`	The thread group ID of the executed command.

Example query:

You can query this collection using the SQL Editor.

SELECT
  timestamp,
  seq_no,
  event->>'$.cgroup_id' AS cgroup_id,
  event->>'$.cgroup_name' AS cgroup_name,
  event->>'$.comm' AS comm,
  CAST(event->>'$.latency_ns' AS INT) AS latency_ns,
  event->>'$.gid' AS gid,
  event->>'$.pid' AS pid,
  event->>'$.ppid' AS ppid,
  event->>'$.tgid' AS tgid
FROM <your_collection_name_here>
ORDER BY seq_no DESC

Key Details:

JSON Path Extraction

The syntax event->>'$.property_name' is used to extract properties from the JSON event object without enclosing them in quotes.

CAST Function

latency_ns is cast to an integer, as it is initially treated as a string. This conversion ensures it can be correctly visualized or processed numerically.

Examples

All examples use execsnoop as the collection name. Change the collection name to match your collection.

Visualize latency of exec calls grouped by command

Query:

SELECT
  SPLIT_PART(event->>'$.comm', ' ', 1) AS comm,
  CAST(event->>'$.latency_ns' AS INT) AS latency_ns
FROM execsnoop;

Chart Configuration:

Chart type: Hierarchical - Treemap

View top 10 commands run on system by frequency

SELECT
  SPLIT_PART(event->>'$.comm', ' ', 1) AS comm,
  COUNT(*) AS exec_count
FROM execsnoop
GROUP BY comm
ORDER BY exec_count DESC
LIMIT 10

Chart Configuration:

Chart type: Bar Chart

Visualize exec call system activity in real-time

SELECT
  timestamp,
  CAST(event->>'$.latency_ns' AS INT) AS latency_ns
FROM execsnoop

Chart Configuration:

Chart type: Bar Chart

Query to find all execsnoop events for a specific command

SELECT
  timestamp,
  seq_no,
  event->>'$.cgroup_id' AS cgroup_id,
  event->>'$.cgroup_name' AS cgroup_name,
  event->>'$.comm' AS comm,
  CAST(event->>'$.latency_ns' AS INT) AS latency_ns,
  event->>'$.gid' AS gid,
  event->>'$.pid' AS pid,
  event->>'$.ppid' AS ppid,
  event->>'$.tgid' AS tgid
FROM execsnoop
WHERE CONTAINS(comm, 'your_command_name');
ORDER BY seq_no DESC