From d5504756a1b7f28dc754ef0a6e09b09b89741afd Mon Sep 17 00:00:00 2001 From: Fede Barcelona Date: Wed, 11 Feb 2026 17:09:22 +0100 Subject: [PATCH] docs: organize tools documentation by product (Monitor/Secure) --- README.md | 90 ++++++++++++++++-------------- internal/infra/mcp/tools/README.md | 58 +++++++++++-------- 2 files changed, 83 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 2b2001a..25d9be0 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ ## Description -This is an implementation of an [MCP (Model Context Protocol) Server](https://modelcontextprotocol.io/quickstart/server) to allow different LLMs to query information from Sysdig Secure platform. New tools and functionalities will be added over time following semantic versioning. The goal is to provide a simple and easy-to-use interface for querying information from Sysdig Secure platform using LLMs. +This is an implementation of an [MCP (Model Context Protocol) Server](https://modelcontextprotocol.io/quickstart/server) to allow different LLMs to query information from the Sysdig platform (Monitor and Secure). New tools and functionalities will be added over time following semantic versioning. The goal is to provide a simple and easy-to-use interface for querying information from the Sysdig platform using LLMs. ## Quickstart Guide @@ -82,31 +82,7 @@ Get up and running with the Sysdig MCP Server quickly using our pre-built Docker The server dynamically filters the available tools based on the permissions associated with the API token used for the request. If the token lacks the required permissions for a tool, that tool will not be listed. -- **`get_event_info`** - - **Description**: Retrieve detailed information for a specific security event by its ID. - - **Required Permission**: `policy-events.read` - - **Sample Prompt**: "Get full details for event ID 123abc" - -- **`list_runtime_events`** - - **Description**: List runtime security events from the last given hours, optionally filtered by severity level. - - **Required Permission**: `policy-events.read` - - **Sample Prompt**: "Show me high severity events from the last 2 hours in cluster1" - -- **`get_event_process_tree`** - - **Description**: Retrieve the process tree for a specific event (if available). - - **Required Permission**: `policy-events.read` - - **Sample Prompt**: "Get the process tree for event ID abc123" - -- **`generate_sysql`** - - **Description**: Generates a SysQL query from a natural language question. - - **Required Permission**: `sage.exec` - - **Sample Prompt**: "List top 10 pods by memory usage in the last hour" - - **Note**: The `generate_sysql` tool currently does not work with Service Account tokens and will return a 500 error. For this tool, use an API token assigned to a regular user account. - -- **`run_sysql`** - - **Description**: Execute a pre-written SysQL query directly (use only when user provides explicit query). - - **Required Permission**: `sage.exec`, `risks.read` - - **Sample Prompt**: "Run this query: MATCH CloudResource WHERE type = 'aws_s3_bucket' LIMIT 10" +### Sysdig Monitor - **`k8s_list_clusters`** - **Description**: Lists the cluster information for all clusters or just the cluster specified. @@ -133,6 +109,11 @@ The server dynamically filters the available tools based on the permissions asso - **Required Permission**: `metrics-data.read` - **Sample Prompt**: "List all cronjobs in cluster 'prod' and namespace 'default'" +- **`k8s_list_count_pods_per_cluster`** + - **Description**: List the count of running Kubernetes Pods grouped by cluster and namespace. + - **Required Permission**: `metrics-data.read` + - **Sample Prompt**: "List the count of running Kubernetes Pods in cluster 'production'" + - **`k8s_list_top_unavailable_pods`** - **Description**: Shows the top N pods with the highest number of unavailable or unready replicas in a Kubernetes cluster, ordered from highest to lowest. - **Required Permission**: `metrics-data.read` @@ -153,21 +134,6 @@ The server dynamically filters the available tools based on the permissions asso - **Required Permission**: `metrics-data.read` - **Sample Prompt**: "Show the top 10 pods with the most network errors in cluster 'production'" -- **`k8s_list_count_pods_per_cluster`** - - **Description**: List the count of running Kubernetes Pods grouped by cluster and namespace. - - **Required Permission**: `metrics-data.read` - - **Sample Prompt**: "List the count of running Kubernetes Pods in cluster 'production'" - -- **`k8s_list_underutilized_pods_cpu_quota`** - - **Description**: List Kubernetes pods with CPU usage below 25% of the quota limit. - - **Required Permission**: `metrics-data.read` - - **Sample Prompt**: "Show the top 10 underutilized pods by CPU quota in cluster 'production'" - -- **`k8s_list_underutilized_pods_memory_quota`** - - **Description**: List Kubernetes pods with memory usage below 25% of the limit. - - **Required Permission**: `metrics-data.read` - - **Sample Prompt**: "Show the top 10 underutilized pods by memory quota in cluster 'production'" - - **`k8s_list_top_cpu_consumed_workload`** - **Description**: Identifies the Kubernetes workloads (all containers) consuming the most CPU (in cores). - **Required Permission**: `metrics-data.read` @@ -188,7 +154,47 @@ The server dynamically filters the available tools based on the permissions asso - **Required Permission**: `metrics-data.read` - **Sample Prompt**: "Show the top 10 containers consuming the most memory in cluster 'production'" - ## Requirements +- **`k8s_list_underutilized_pods_cpu_quota`** + - **Description**: List Kubernetes pods with CPU usage below 25% of the quota limit. + - **Required Permission**: `metrics-data.read` + - **Sample Prompt**: "Show the top 10 underutilized pods by CPU quota in cluster 'production'" + +- **`k8s_list_underutilized_pods_memory_quota`** + - **Description**: List Kubernetes pods with memory usage below 25% of the limit. + - **Required Permission**: `metrics-data.read` + - **Sample Prompt**: "Show the top 10 underutilized pods by memory quota in cluster 'production'" + +### Sysdig Secure + +- **`list_runtime_events`** + - **Description**: List runtime security events from the last given hours, optionally filtered by severity level. + - **Required Permission**: `policy-events.read` + - **Sample Prompt**: "Show me high severity events from the last 2 hours in cluster1" + +- **`get_event_info`** + - **Description**: Retrieve detailed information for a specific security event by its ID. + - **Required Permission**: `policy-events.read` + - **Sample Prompt**: "Get full details for event ID 123abc" + +- **`get_event_process_tree`** + - **Description**: Retrieve the process tree for a specific event (if available). + - **Required Permission**: `policy-events.read` + - **Sample Prompt**: "Get the process tree for event ID abc123" + +- **`run_sysql`** + - **Description**: Execute a pre-written SysQL query directly (use only when user provides explicit query). + - **Required Permission**: `sage.exec`, `risks.read` + - **Sample Prompt**: "Run this query: MATCH CloudResource WHERE type = 'aws_s3_bucket' LIMIT 10" + +### Sysdig Monitor & Sysdig Secure + +- **`generate_sysql`** + - **Description**: Generates a SysQL query from a natural language question. + - **Required Permission**: `sage.exec` + - **Sample Prompt**: "List top 10 pods by memory usage in the last hour" + - **Note**: The `generate_sysql` tool currently does not work with Service Account tokens and will return a 500 error. For this tool, use an API token assigned to a regular user account. + +## Requirements - [Go](https://go.dev/doc/install) 1.25 or higher (if running without Docker). ## Configuration diff --git a/internal/infra/mcp/tools/README.md b/internal/infra/mcp/tools/README.md index a40a70f..f69c95a 100644 --- a/internal/infra/mcp/tools/README.md +++ b/internal/infra/mcp/tools/README.md @@ -2,29 +2,41 @@ The handler filters tools dynamically based on the Sysdig user's permissions. Each tool declares mandatory permissions via `WithRequiredPermissions`. -| Tool | File | Capability | Required Permissions | Useful Prompts | -|-------------------------------------------------------------------|---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------------------------|--------------------------------------------------------------------------------------| -| `generate_sysql` | `tool_generate_sysql.go` | Convert natural language to SysQL via Sysdig Sage. | `sage.exec` (does not work with Service Accounts) | “Create a SysQL to list S3 buckets.” | -| `get_event_info` | `tool_get_event_info.go` | Pull full payload for a single policy event. | `policy-events.read` | “Fetch event `abc123` details.” | -| `get_event_process_tree` | `tool_get_event_process_tree.go` | Retrieve the process tree for an event when available. | `policy-events.read` | “Show the process tree behind event `abc123`.” | -| `k8s_list_clusters` | `tool_k8s_list_clusters.go` | Lists Kubernetes cluster information. | `metrics-data.read` | "List all Kubernetes clusters" | -| `k8s_list_cronjobs` | `tool_k8s_list_cronjobs.go` | Retrieves information from the cronjobs in the cluster. | `metrics-data.read` | "List all cronjobs in cluster 'prod' and namespace 'default'" | -| `k8s_list_nodes` | `tool_k8s_list_nodes.go` | Lists Kubernetes node information. | `metrics-data.read` | "List all Kubernetes nodes in the cluster 'production-gke'" | -| `k8s_list_pod_containers` | `tool_k8s_list_pod_containers.go` | Retrieves information from a particular pod and container. | `metrics-data.read` | "Show me info for pod 'my-pod' in cluster 'production-gke'" | -| `k8s_list_workloads` | `tool_k8s_list_workloads.go` | Lists Kubernetes workload information. | `metrics-data.read` | "List all desired workloads in the cluster 'production-gke' and namespace 'default'" | -| `list_runtime_events` | `tool_list_runtime_events.go` | Query runtime events with filters, cursor, scope. | `policy-events.read` | “Show high severity runtime events from last 2h.” | -| `run_sysql` | `tool_run_sysql.go` | Execute caller-supplied Sysdig SysQL queries safely. | `sage.exec`, `risks.read` | “Run the following SysQL…”. | -| `k8s_list_count_pods_per_cluster` | `tool_k8s_list_count_pods_per_cluster.go` | List the count of running Kubernetes Pods grouped by cluster and namespace. | `metrics-data.read` | "List the count of running Kubernetes Pods in cluster 'production'" | -| `k8s_list_top_http_errors_in_pods` | `tool_k8s_list_top_http_errors_in_pods.go` | Lists the pods with the highest rate of HTTP 4xx and 5xx errors over a specified time interval. | `metrics-data.read` | "Show the top 20 pods with the most HTTP errors in cluster 'production'" | -| `k8s_list_top_cpu_consumed_container` | `tool_k8s_list_top_cpu_consumed_container.go` | Identifies the Kubernetes containers consuming the most CPU (in cores). | `metrics-data.read` | "Show the top 10 containers consuming the most CPU in cluster 'production'" | -| `k8s_list_top_cpu_consumed_workload` | `tool_k8s_list_top_cpu_consumed_workload.go` | Identifies the Kubernetes workloads (all containers) consuming the most CPU (in cores). | `metrics-data.read` | "Show the top 10 workloads consuming the most CPU in cluster 'production'" | -| `k8s_list_top_memory_consumed_container` | `tool_k8s_list_top_memory_consumed_container.go` | Lists memory-intensive containers. | `metrics-data.read` | "Show the top 10 containers consuming the most memory in cluster 'production'" | -| `k8s_list_top_memory_consumed_workload` | `tool_k8s_list_top_memory_consumed_workload.go` | Lists memory-intensive workloads (all containers). | `metrics-data.read` | "Show the top 10 workloads consuming the most memory in cluster 'production'" | -| `k8s_list_top_network_errors_in_pods` | `tool_k8s_list_top_network_errors_in_pods.go` | Shows the top network errors by pod over a given interval. | `metrics-data.read` | "Show the top 10 pods with the most network errors in cluster 'production'" | -| `k8s_list_top_restarted_pods` | `tool_k8s_list_top_restarted_pods.go` | Lists the pods with the highest number of container restarts. | `metrics-data.read` | "Show the top 10 pods with the most container restarts in cluster 'production'" | -| `k8s_list_top_unavailable_pods` | `tool_k8s_list_top_unavailable_pods.go` | Shows the top N pods with the highest number of unavailable or unready replicas. | `metrics-data.read` | "Show the top 20 unavailable pods in cluster 'production'" | -| `k8s_list_underutilized_pods_cpu_quota` | `tool_k8s_list_underutilized_pods_cpu_quota.go` | List Kubernetes pods with CPU usage below 25% of the quota limit. | `metrics-data.read` | "Show the top 10 underutilized pods by CPU quota in cluster 'production'" | -| `k8s_list_underutilized_pods_memory_quota` | `tool_k8s_list_underutilized_pods_memory_quota.go` | List Kubernetes pods with memory usage below 25% of the limit. | `metrics-data.read` | "Show the top 10 underutilized pods by memory quota in cluster 'production'" | +### Sysdig Monitor + +| Tool | File | Capability | Required Permissions | Useful Prompts | +|---|---|---|---|---| +| `k8s_list_clusters` | `tool_k8s_list_clusters.go` | Lists Kubernetes cluster information. | `metrics-data.read` | "List all Kubernetes clusters" | +| `k8s_list_nodes` | `tool_k8s_list_nodes.go` | Lists Kubernetes node information. | `metrics-data.read` | "List all Kubernetes nodes in the cluster 'production-gke'" | +| `k8s_list_workloads` | `tool_k8s_list_workloads.go` | Lists Kubernetes workload information. | `metrics-data.read` | "List all desired workloads in the cluster 'production-gke' and namespace 'default'" | +| `k8s_list_pod_containers` | `tool_k8s_list_pod_containers.go` | Retrieves information from a particular pod and container. | `metrics-data.read` | "Show me info for pod 'my-pod' in cluster 'production-gke'" | +| `k8s_list_cronjobs` | `tool_k8s_list_cronjobs.go` | Retrieves information from the cronjobs in the cluster. | `metrics-data.read` | "List all cronjobs in cluster 'prod' and namespace 'default'" | +| `k8s_list_count_pods_per_cluster` | `tool_k8s_list_count_pods_per_cluster.go` | List the count of running Kubernetes Pods grouped by cluster and namespace. | `metrics-data.read` | "List the count of running Kubernetes Pods in cluster 'production'" | +| `k8s_list_top_unavailable_pods` | `tool_k8s_list_top_unavailable_pods.go` | Shows the top N pods with the highest number of unavailable or unready replicas. | `metrics-data.read` | "Show the top 20 unavailable pods in cluster 'production'" | +| `k8s_list_top_restarted_pods` | `tool_k8s_list_top_restarted_pods.go` | Lists the pods with the highest number of container restarts. | `metrics-data.read` | "Show the top 10 pods with the most container restarts in cluster 'production'" | +| `k8s_list_top_http_errors_in_pods` | `tool_k8s_list_top_http_errors_in_pods.go` | Lists the pods with the highest rate of HTTP 4xx and 5xx errors over a specified time interval. | `metrics-data.read` | "Show the top 20 pods with the most HTTP errors in cluster 'production'" | +| `k8s_list_top_network_errors_in_pods` | `tool_k8s_list_top_network_errors_in_pods.go` | Shows the top network errors by pod over a given interval. | `metrics-data.read` | "Show the top 10 pods with the most network errors in cluster 'production'" | +| `k8s_list_top_cpu_consumed_workload` | `tool_k8s_list_top_cpu_consumed_workload.go` | Identifies the Kubernetes workloads (all containers) consuming the most CPU (in cores). | `metrics-data.read` | "Show the top 10 workloads consuming the most CPU in cluster 'production'" | +| `k8s_list_top_cpu_consumed_container` | `tool_k8s_list_top_cpu_consumed_container.go` | Identifies the Kubernetes containers consuming the most CPU (in cores). | `metrics-data.read` | "Show the top 10 containers consuming the most CPU in cluster 'production'" | +| `k8s_list_top_memory_consumed_workload` | `tool_k8s_list_top_memory_consumed_workload.go` | Lists memory-intensive workloads (all containers). | `metrics-data.read` | "Show the top 10 workloads consuming the most memory in cluster 'production'" | +| `k8s_list_top_memory_consumed_container` | `tool_k8s_list_top_memory_consumed_container.go` | Lists memory-intensive containers. | `metrics-data.read` | "Show the top 10 containers consuming the most memory in cluster 'production'" | +| `k8s_list_underutilized_pods_cpu_quota` | `tool_k8s_list_underutilized_pods_cpu_quota.go` | List Kubernetes pods with CPU usage below 25% of the quota limit. | `metrics-data.read` | "Show the top 10 underutilized pods by CPU quota in cluster 'production'" | +| `k8s_list_underutilized_pods_memory_quota` | `tool_k8s_list_underutilized_pods_memory_quota.go` | List Kubernetes pods with memory usage below 25% of the limit. | `metrics-data.read` | "Show the top 10 underutilized pods by memory quota in cluster 'production'" | + +### Sysdig Secure + +| Tool | File | Capability | Required Permissions | Useful Prompts | +|---|---|---|---|---| +| `list_runtime_events` | `tool_list_runtime_events.go` | Query runtime events with filters, cursor, scope. | `policy-events.read` | "Show high severity runtime events from last 2h." | +| `get_event_info` | `tool_get_event_info.go` | Pull full payload for a single policy event. | `policy-events.read` | "Fetch event `abc123` details." | +| `get_event_process_tree` | `tool_get_event_process_tree.go` | Retrieve the process tree for an event when available. | `policy-events.read` | "Show the process tree behind event `abc123`." | +| `run_sysql` | `tool_run_sysql.go` | Execute caller-supplied Sysdig SysQL queries safely. | `sage.exec`, `risks.read` | "Run the following SysQL…". | + +### Sysdig Monitor & Sysdig Secure + +| Tool | File | Capability | Required Permissions | Useful Prompts | +|---|---|---|---|---| +| `generate_sysql` | `tool_generate_sysql.go` | Convert natural language to SysQL via Sysdig Sage. | `sage.exec` (does not work with Service Accounts) | "Create a SysQL to list S3 buckets." | # Adding a New Tool