Kubeshark Traffic

Kubeshark Kubernetes Traffic Analysis

MCP Server

How to Run

# Install Kubeshark with MCP enabled
helm install kubeshark kubeshark/kubeshark \
  --set mcp.enabled=true \
  --set mcp.port=8898

# Port-forward for local access (if not in-cluster)
kubectl port-forward svc/kubeshark-hub 8898:8898

# MCP endpoint is now available at:
# http://localhost:8898/mcp

Environment Variables

Tools

Resources Exposed

• Real-time L7 API streams (HTTP, gRPC, GraphQL, Redis, Kafka, DNS) with full request/response payloads
• Historical traffic queries within the configured retention window
• Decrypted TLS/HTTPS traffic via eBPF (no manual key management)
• TCP/UDP connection flows with timing, RTT, and byte statistics
• Kubernetes pod identity and service mapping (source → destination with namespace/labels)

Workflow: Kubernetes Service Troubleshooting

When investigating connectivity or latency issues between Kubernetes services:

1. Capture traffic: capture_traffic(filter="src.pod.name == 'frontend'") — start targeted capture
2. List flows: list_l4_flows — see all TCP/UDP connections with RTT and stats
3. Flow summary: get_l4_flow_summary — identify top talkers and protocol breakdown
4. Apply filter: apply_filter(kfl_expression="response.status >= 500") — isolate errors
5. Export pcap: export_pcap(filter="dst.pod.name == 'api-gateway'") — export for deep analysis
6. Cross-reference: Use packet-analysis skill to analyze exported pcap with tshark
7. Report: Service communication analysis with latency, error rates, and traffic patterns
8. GAIT: Record all captures and findings in audit trail

Example: API Gateway Latency Investigation

capture_traffic(filter="dst.pod.name == 'api-gateway'", duration="5m")
list_l4_flows(filter="dst.pod.name == 'api-gateway'")
get_l4_flow_summary(filter="dst.pod.name == 'api-gateway'")
apply_filter(kfl_expression="response.latency > 500ms")
export_pcap(filter="response.latency > 500ms")

Workflow: TLS Traffic Inspection

When investigating encrypted service-to-service communication:

1. Capture: capture_traffic — Kubeshark automatically decrypts TLS via eBPF
2. Filter: apply_filter(kfl_expression="request.headers['content-type'] == 'application/grpc'") — isolate gRPC
3. Flows: list_l4_flows — see encrypted connections with decrypted payload summaries
4. Export: export_pcap — export decrypted traffic for offline analysis
5. Report: TLS communication audit with certificate info and payload analysis

Workflow: Incident Traffic Forensics

When performing post-incident traffic analysis:

1. Snapshot: create_snapshot — capture current traffic state
2. Historical query: apply_filter with time range — find traffic around incident time
3. Flow analysis: list_l4_flows — identify unusual connections or traffic spikes
4. Top talkers: get_l4_flow_summary — find services with abnormal traffic volume
5. Export evidence: export_pcap — preserve traffic for incident report
6. Cross-reference: Correlate with Prometheus metrics, Grafana alerts, and pyATS device state

Integration with Other Skills

Kubeshark Filter Language (KFL) Examples

# Filter by pod name
src.pod.name == "frontend"

# Filter by namespace
dst.namespace == "production"

# HTTP status codes
response.status >= 400

# Latency threshold
response.latency > 200ms

# Protocol type
protocol == "grpc"

# Combined filters
src.namespace == "default" and response.status >= 500 and response.latency > 1s

# DNS queries
protocol == "dns" and request.query contains "api.internal"

# Kafka messages
protocol == "kafka" and request.topic == "orders"

Important Rules

• All tools are read-only — Kubeshark captures and analyzes traffic but does not modify it
• Cluster access required — Kubeshark must be deployed in the target Kubernetes cluster via Helm
• Port-forward for remote access — use kubectl port-forward svc/kubeshark-hub 8898:8898 when not in-cluster
• Retention window — historical queries are limited to the configured retention period
• Large captures — use KFL filters to scope captures and avoid overwhelming context with large traffic volumes
• Sensitive data — captured traffic may contain PII, credentials, or secrets in request/response payloads; handle exports accordingly
• GAIT audit mandatory — record all traffic captures, pcap exports, and analysis findings
• No secrets in filters — never embed credentials or sensitive data in KFL expressions

Error Handling

• Connection refused: Verify Kubeshark is running (kubectl get pods -n kubeshark) and port-forward is active.
• No traffic captured: Check KFL filter syntax; verify target pods exist and are generating traffic.
• MCP endpoint not found: Ensure mcp.enabled=true in Helm values; verify MCP port matches KUBESHARK_MCP_URL.
• Permission denied: Check RBAC — Kubeshark needs cluster-wide read access for traffic capture.
• Empty pcap exports: Verify retention window covers the requested time range; check that traffic matching the filter exists.