mirrors/kubeshark--kubeshark
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 12:49:06 +08:00
commit 60552ca0ce
144 changed files with 20883 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mcp/README.md
+220
View File
@@ -0,0 +1,220 @@
# Kubeshark MCP Server
[Kubeshark](https://kubeshark.com) MCP (Model Context Protocol) server enables AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to query real-time Kubernetes network traffic.
## AI Skills
The MCP provides the tools — [AI skills](../skills/) teach agents how to use them.
Skills turn raw MCP capabilities into domain-specific workflows like root cause
analysis, traffic filtering, and forensic investigation. See the
[skills README](../skills/README.md) for installation and usage.
| Skill | Description |
|-------|-------------|
| [`network-rca`](../skills/network-rca/) | Network Root Cause Analysis — snapshot-based retrospective investigation with PCAP and dissection routes |
| [`kfl`](../skills/kfl/) | KFL2 filter expert — write, debug, and optimize traffic queries across all supported protocols |
## Features
- **L7 API Traffic Analysis**: Query HTTP, gRPC, Redis, Kafka, DNS transactions
- **L4 Network Flows**: View TCP/UDP flows with traffic statistics
- **Cluster Management**: Start/stop Kubeshark deployments (with safety controls)
- **PCAP Snapshots**: Create and export network captures
- **Built-in Prompts**: Pre-configured prompts for common analysis tasks
## Installation
### 1. Install Kubeshark CLI
```bash
# macOS
brew install kubeshark
# Linux
sh <(curl -Ls https://kubeshark.com/install)
# Windows (PowerShell)
choco install kubeshark
```
Or download from [GitHub Releases](https://github.com/kubeshark/kubeshark/releases).
### 2. Configure Claude Desktop
Add to your Claude Desktop configuration:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### Default (requires kubectl access / kube context)
```json
{
"mcpServers": {
"kubeshark": {
"command": "kubeshark",
"args": ["mcp"]
}
}
}
```
With an explicit kubeconfig path:
```json
{
"mcpServers": {
"kubeshark": {
"command": "kubeshark",
"args": ["mcp", "--kubeconfig", "/path/to/.kube/config"]
}
}
}
```
#### URL Mode (no kubectl required)
Use this when the machine doesn't have kubectl access or a kube context.
Connect directly to an existing Kubeshark deployment:
```json
{
"mcpServers": {
"kubeshark": {
"command": "kubeshark",
"args": ["mcp", "--url", "https://kubeshark.example.com"]
}
}
}
```
#### With Destructive Operations
```json
{
"mcpServers": {
"kubeshark": {
"command": "kubeshark",
"args": ["mcp", "--allow-destructive", "--kubeconfig", "/path/to/.kube/config"]
}
}
}
```
### 3. Generate Configuration
Use the CLI to generate configuration:
```bash
kubeshark mcp --mcp-config --url https://kubeshark.example.com
```
## Available Tools
### Traffic Analysis (All Modes)
| Tool | Description |
|------|-------------|
| `list_workloads` | List pods, services, namespaces with observed traffic |
| `list_api_calls` | Query L7 API transactions with KFL filtering |
| `get_api_call` | Get detailed info about a specific API call |
| `get_api_stats` | Get aggregated API statistics |
| `list_l4_flows` | List L4 (TCP/UDP) network flows |
| `get_l4_flow_summary` | Get L4 connectivity summary |
| `list_snapshots` | List all PCAP snapshots |
| `create_snapshot` | Create a new PCAP snapshot |
| `get_dissection_status` | Check L7 protocol parsing status |
| `enable_dissection` | Enable L7 protocol dissection |
| `disable_dissection` | Disable L7 protocol dissection |
### Cluster Management (Proxy Mode Only)
| Tool | Description | Requires |
|------|-------------|----------|
| `check_kubeshark_status` | Check if Kubeshark is running | - |
| `start_kubeshark` | Deploy Kubeshark to cluster | `--allow-destructive` |
| `stop_kubeshark` | Remove Kubeshark from cluster | `--allow-destructive` |
## Available Prompts
| Prompt | Description |
|--------|-------------|
| `analyze_traffic` | Analyze API traffic patterns and identify issues |
| `find_errors` | Find and summarize API errors and failures |
| `trace_request` | Trace a request path through microservices |
| `show_topology` | Show service communication topology |
| `latency_analysis` | Analyze latency patterns and identify slow endpoints |
| `security_audit` | Audit traffic for security concerns |
| `compare_traffic` | Compare traffic patterns between time periods |
| `debug_connection` | Debug connectivity issues between services |
## Example Conversations
```
User: Show me all HTTP 500 errors in the last hour
Claude: I'll query the API traffic for 500 errors.
[Calling list_api_calls with kfl="http and response.status == 500"]
Found 12 HTTP 500 errors:
1. POST /api/checkout -> payment-service (500)
Time: 10:23:45 | Latency: 2340ms
...
```
```
User: What services are communicating with the database?
Claude: Let me check the L4 flows to the database.
[Calling list_l4_flows with dst_filter="postgres"]
Found 5 services connecting to postgres:5432:
- orders-service: 456KB transferred
- users-service: 123KB transferred
...
```
## CLI Options
| Option | Description |
|--------|-------------|
| `--url` | Direct URL to Kubeshark Hub |
| `--kubeconfig` | Path to kubeconfig file |
| `--allow-destructive` | Enable start/stop operations |
| `--list-tools` | List available tools and exit |
| `--mcp-config` | Print Claude Desktop config JSON |
## KFL (Kubeshark Filter Language)
Query traffic using KFL syntax:
```
# HTTP requests to a specific path
http and request.path == "/api/users"
# Errors only
response.status >= 400
# Specific source pod
src.pod.name == "frontend-.*"
# Multiple conditions
http and src.namespace == "default" and response.status == 500
```
## MCP Registry
Kubeshark is published to the [MCP Registry](https://registry.modelcontextprotocol.io/) automatically on each release.
The `server.json` in this directory is a reference file. The actual registry metadata (version, SHA256 hashes) is auto-generated during the release workflow. See [`.github/workflows/release.yml`](../.github/workflows/release.yml) for details.
## Links
- [Documentation](https://docs.kubeshark.com/en/mcp)
- [GitHub](https://github.com/kubeshark/kubeshark)
- [Website](https://kubeshark.com)
- [MCP Registry](https://registry.modelcontextprotocol.io/)
## License
Apache-2.0
mcp/server.json
+178
View File
@@ -0,0 +1,178 @@
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.kubeshark/mcp",
"displayName": "Kubeshark",
"description": "Real-time Kubernetes network traffic visibility and API analysis for HTTP, gRPC, Redis, Kafka, DNS.",
"icon": "https://raw.githubusercontent.com/kubeshark/assets/refs/heads/master/logo/ico/icon.ico",
"repository": {
"url": "https://github.com/kubeshark/kubeshark",
"source": "github"
},
"homepage": "https://kubeshark.com",
"license": "Apache-2.0",
"version": "AUTO_GENERATED_AT_RELEASE",
"authors": [
{
"name": "Kubeshark",
"url": "https://kubeshark.com"
}
],
"categories": [
"kubernetes",
"networking",
"observability",
"debugging",
"security"
],
"_note": "version and packages.fileSha256 are auto-generated at release time by .github/workflows/release.yml",
"tags": ["kubernetes", "network", "traffic", "api", "http", "grpc", "kafka", "redis", "dns", "pcap", "wireshark", "tcpdump", "observability", "debugging", "microservices"],
"packages": [
{
"registryType": "mcpb",
"identifier": "https://github.com/kubeshark/kubeshark/releases/download/vX.Y.Z/kubeshark-mcp_darwin_arm64.mcpb",
"fileSha256": "AUTO_GENERATED",
"transport": { "type": "stdio" }
},
{
"registryType": "mcpb",
"identifier": "https://github.com/kubeshark/kubeshark/releases/download/vX.Y.Z/kubeshark-mcp_darwin_amd64.mcpb",
"fileSha256": "AUTO_GENERATED",
"transport": { "type": "stdio" }
},
{
"registryType": "mcpb",
"identifier": "https://github.com/kubeshark/kubeshark/releases/download/vX.Y.Z/kubeshark-mcp_linux_arm64.mcpb",
"fileSha256": "AUTO_GENERATED",
"transport": { "type": "stdio" }
},
{
"registryType": "mcpb",
"identifier": "https://github.com/kubeshark/kubeshark/releases/download/vX.Y.Z/kubeshark-mcp_linux_amd64.mcpb",
"fileSha256": "AUTO_GENERATED",
"transport": { "type": "stdio" }
},
{
"registryType": "mcpb",
"identifier": "https://github.com/kubeshark/kubeshark/releases/download/vX.Y.Z/kubeshark-mcp_windows_amd64.mcpb",
"fileSha256": "AUTO_GENERATED",
"transport": { "type": "stdio" }
}
],
"tools": [
{
"name": "check_kubeshark_status",
"description": "Check if Kubeshark is currently running in the cluster. Read-only operation.",
"mode": "proxy"
},
{
"name": "start_kubeshark",
"description": "Deploy Kubeshark to the Kubernetes cluster. Requires --allow-destructive flag.",
"mode": "proxy",
"destructive": true
},
{
"name": "stop_kubeshark",
"description": "Remove Kubeshark from the Kubernetes cluster. Requires --allow-destructive flag.",
"mode": "proxy",
"destructive": true
},
{
"name": "list_workloads",
"description": "List pods, services, namespaces, and nodes with observed L7 traffic.",
"mode": "all"
},
{
"name": "list_api_calls",
"description": "Query L7 API transactions (HTTP, gRPC, Redis, Kafka, DNS) with KFL filtering.",
"mode": "all"
},
{
"name": "get_api_call",
"description": "Get detailed information about a specific API call including headers and body.",
"mode": "all"
},
{
"name": "get_api_stats",
"description": "Get aggregated API statistics and metrics.",
"mode": "all"
},
{
"name": "list_l4_flows",
"description": "List L4 (TCP/UDP) network flows with traffic statistics.",
"mode": "all"
},
{
"name": "get_l4_flow_summary",
"description": "Get L4 connectivity summary including top talkers and cross-namespace traffic.",
"mode": "all"
},
{
"name": "list_snapshots",
"description": "List all PCAP snapshots.",
"mode": "all"
},
{
"name": "create_snapshot",
"description": "Create a new PCAP snapshot of captured traffic.",
"mode": "all"
},
{
"name": "get_dissection_status",
"description": "Check L7 protocol parsing status.",
"mode": "all"
},
{
"name": "enable_dissection",
"description": "Enable L7 protocol dissection.",
"mode": "all"
},
{
"name": "disable_dissection",
"description": "Disable L7 protocol dissection.",
"mode": "all"
}
],
"prompts": [
{ "name": "analyze_traffic", "description": "Analyze API traffic patterns and identify issues" },
{ "name": "find_errors", "description": "Find and summarize API errors and failures" },
{ "name": "trace_request", "description": "Trace a request path through microservices" },
{ "name": "show_topology", "description": "Show service communication topology" },
{ "name": "latency_analysis", "description": "Analyze latency patterns and identify slow endpoints" },
{ "name": "security_audit", "description": "Audit traffic for security concerns" },
{ "name": "compare_traffic", "description": "Compare traffic patterns between time periods" },
{ "name": "debug_connection", "description": "Debug connectivity issues between services" }
],
"configuration": {
"properties": {
"url": {
"type": "string",
"description": "Direct URL to Kubeshark Hub (e.g., https://kubeshark.example.com). When set, connects directly without kubectl/proxy.",
"examples": ["https://kubeshark.example.com", "http://localhost:8899"]
},
"kubeconfig": {
"type": "string",
"description": "Path to kubeconfig file for proxy mode.",
"examples": ["~/.kube/config", "/path/to/.kube/config"]
},
"allow-destructive": {
"type": "boolean",
"description": "Enable destructive operations (start_kubeshark, stop_kubeshark). Default: false for safety.",
"default": false
}
}
},
"modes": {
"url": {
"description": "Connect directly to an existing Kubeshark deployment via URL. Cluster management tools are disabled.",
"args": ["mcp", "--url", "${url}"]
},
"proxy": {
"description": "Connect via kubectl port-forward. Requires kubeconfig access to the cluster.",
"args": ["mcp", "--kubeconfig", "${kubeconfig}"]
},
"proxy-destructive": {
"description": "Proxy mode with destructive operations enabled.",
"args": ["mcp", "--kubeconfig", "${kubeconfig}", "--allow-destructive"]
}
}
}