🛡️ Kube-Shepherd

Kube-Shepherd is an autonomous incident response and digital forensics orchestration system designed to investigate compromised Kubernetes clusters using the Opencode AI Agent framework.

The system dynamically discovers compromised Kubernetes workloads, extracts high-fidelity runtime and cluster-plane evidence, parses unstructured telemetry data into an interconnected relational knowledge graph, maps findings directly to the MITRE ATT&CK Matrix for Containers, and compiles an executive-ready incident readout.

---

🚀 Overview & Architecture

Kube-Shepherd contains declarative skill definitions and core missions that dictate the behavior of our autonomous security engineer agent. The agent executes tasks through a deterministic, 5-phase pipeline with strict anti-loop and error-handling guardrails:

[Phase 1: Dynamic Triage] ──> [Phase 2: Collector Skill] ──> [Phase 3: Audit Parser Skill] │ ▼ [Phase 5: Final Report] <── [Phase 4: Investigator Skill] <── [Obsidian Vault Graph]

Core Architecture Components:

1. Dynamic Target Discovery: The agent autonomously triages non-system namespaces to isolate target pods experiencing active workload churn (CrashLoopBackOff, OOMKilled, or an intense frequency of Warning events).
2. Deterministic Forensic Skills: Single-purpose, modular sub-agents (collector, audit_parser, investigator, reporter) configured via optimized relative system prompts.
3. Advanced Cloud Heuristics: Cross-container sidecar pivot tracking, live-state to manifest deployment configuration drift detection, and automated ServiceAccount RBAC blast radius mapping.
4. Multi-Layer Daemon Logging: Beyond standard API audit logs, the system captures host-level container runtime journals (Containerd, CRI-O, and Docker) to detect low-level engine exploits, namespace breakouts, and host escapes.

---

🛠️ Installed Agent Skills

The project defines four primary operational modules executed from the relative repository context under ./skills/:

1. 📦 Collector (collector)

• Role: Advanced Data Collection Specialist
• Task: Pulls Tier-1 context metrics from workloads (YAML configuration manifests, full multi-container log streams via --all-containers=true, and local namespace event logs).
• Hybrid Forensic Extraction: * Primary Path (SSH MCP): Leverages a secure SSH tunnel to connect out-of-band directly to worker nodes, extracting host container daemon journals (containerd, cri-o, docker) while minimizing cluster noise.
  • Fallback Path (K8s Debug): Deploys an out-of-band privileged host mount (kubectl debug node/) to safely siphon files like /var/log/kubernetes/audit.log if direct SSH access is restricted.

2. 🔍 Audit Parser (audit_parser)

• Role: Core Telemetry Parser & Knowledge Registrar
• Task: Runs a dedicated Python parsing engine (canary_parser.py) to normalize raw, high-volume audit logs into an interconnected network of atomic Markdown files inside a local Obsidian Vault (./vault/).
• Output: Generates a structured tracking ledger including Master_Forensic_Timeline.md and hyperlinked relationship folders for Actors/, Pods/, Alerts/, and Verbs/.

3. 🧠 Investigator (investigator)

• Role: Senior Forensic & Threat Intelligence Specialist
• Task: Ingests the parsed relational vault graph folders and correlates them with raw workload configurations along three specialized cloud-native axes:
  • Axis A: Sidecar & auxiliary container pivot tracking via asymmetric network flow differentials.
  • Axis B: Live state vs. Declared manifest drift analysis (detecting runtime registry mutations).
  • Axis C: ServiceAccount RBAC blast radius evaluation via programmatic permission vector mapping (kubectl auth can-i).
• Output: Isolates indicators of compromise (IoCs) and drops structured logs into ./vault/Analysis_Scratchpad.md.

4. 📝 Reporter (reporter)

• Role: Security Documentation Principal
• Task: Ingests the investigator's matrix scratchpad and outputs a production-ready, executive-ready incident readout document at ./vault/Final_Incident_Report.md.

---

⚙️ Installation & Workspace Setup

This project is designed to execute from a SANS SIFT Forensic Workstation, serving as the centralized incident response and analytical hub.

📋 Prerequisites & Tooling Requirements

• Investigation Host: SANS SIFT Workstation (Ubuntu-based) with Python 3.8+ installed.
• Target Environment: Kubernetes Cluster (v1.26+) with standard API audit logging enabled (/var/log/kubernetes/audit.log).
• Access Vector: Direct network connectivity from the SIFT workstation to the cluster API server and target worker nodes.

---

🛠️ Step-by-Step Workstation Bootstrap

1. Install Node.js Ecosystem & Setup MCP Runtimes

The Model Context Protocol (MCP) infrastructure requires Node.js and package management utilities. Install the environment on your SIFT Workstation:

# Update local package manager indexes
sudo apt-get update

# Install Node.js and NPM package managers natively
sudo apt-get install -y nodejs npm

sudo npm install -g @modelcontextprotocol/server-kubernetes
sudo npm install -g mcp-ssh

The kubernetes MCP server relies on native kubectl binaries to query cluster states. Download and install the stable binary:

# Download the stable kubectl binary
curl -LO "[https://dl.k8s.io/release/$](https://dl.k8s.io/release/$)(curl -L -s [https://dl.k8s.io/release/stable.txt](https://dl.k8s.io/release/stable.txt))/bin/linux/amd64/kubectl"

# Make the binary executable and move it into the system PATH
chmod +x ./kubectl
sudo mv ./kubectl /usr/local/bin/kubectl

# Verify installation
kubectl version --client

For the agent to securely pivot across telemetry layers, place your cluster administration config and private forensic SSH keys into the default root directories expected by your MCP config.json environment:

# 1. Setup Kubernetes API Access
mkdir -p /root/.kube
# [Action Required] Copy your target cluster's admin config file here:
# cp /path/to/your/cluster/kubeconfig /root/.kube/config
chmod 600 /root/.kube/config

# 2. Setup Node-Level SSH Forensic Access
mkdir -p /root/.ssh
# [Action Required] Place the private forensic SSH key linked to the worker nodes here:
# cp /path/to/forensics_id_rsa /root/.ssh/forensics_id_rsa
chmod 600 /root/.ssh/forensics_id_rsa

Clone the repository and verify the core processing assets like skiils folder, config, log parser file are in place. 

Before passing execution User prompts to Opencode framework instance, verify connectivity from the SIFT workstation to the target cluster to avoid runtime tool exceptions. Test with basic prompt if you are getting remote cluster details like hostname, pod details its.

Once everything is in place give the UserPrompt and wait for Forensic Report :) 





# Verify node ecosystem meets version baselines
node -v
npm -v