KubeGuard MCP Server

A Model Context Protocol (MCP) server for Kubernetes Role security analysis using LLM-assisted prompt chaining, based on the KubeGuard research paper: "LLM-Assisted Kubernetes Hardening via Configuration Files and Runtime Logs Analysis."

Features

🛡️ Security Analysis

Static Analysis: Rule-based security assessment of Kubernetes Roles
LLM Prompt Chaining: 5-step modular analysis workflow using OpenAI/Anthropic
Runtime Correlation: Analyze actual permission usage vs granted permissions
Security Scoring: 0-100 scale risk assessment with detailed breakdown

🔧 Analysis Tools

analyze_role_security: Comprehensive Role security analysis
generate_hardened_role: Create least-privilege Role configurations
validate_role_security: Validate against security thresholds
get_server_status: Server configuration and capabilities

📊 Analysis Methods

Rule-Based: Fast, reliable analysis using security pattern matching
LLM Chain: Deep analysis using 5-step prompt chaining methodology
Hybrid: Automatic fallback between methods

Quick Start

1. Installation

git clone https://github.com/your-org/kubeguard-mcp cd kubeguard-mcp pip install -r requirements.txt

2. Configuration

cp .env.example .env # Edit .env with your LLM API keys

3. Run Server

python -m kubeguard.main

4. Test Analysis

import asyncio import json from kubeguard import KubeGuardRoleAnalyzer # Example Role manifest role_manifest = { "apiVersion": "rbac.authorization.k8s.io/v1", "kind": "Role", "metadata": {"name": "test-role", "namespace": "default"}, "rules": [{ "apiGroups": [""], "resources": ["*"], "verbs": ["*"] }] } # Analyze security analyzer = KubeGuardRoleAnalyzer() analysis = await analyzer.analyze_role(role_manifest) print(f"Security Score: {analysis.security_score}/100") print(f"Risk Level: {analysis.risk_level.value}")

Configuration

Environment Variables

Variable	Description	Default
`LLM_PROVIDER`	LLM provider (openai/anthropic/none)	`none`
`OPENAI_API_KEY`	OpenAI API key	-
`ANTHROPIC_API_KEY`	Anthropic API key	-
`LLM_MODEL`	Model to use	`gpt-4o-mini`
`SECURITY_SCORE_THRESHOLD`	Security validation threshold	`70`
`ENABLE_RUNTIME_SIMULATION`	Enable usage simulation	`true`

Analysis Configuration

from kubeguard.config import config # Check if LLM is configured if config.has_llm_configured: print(f"LLM Provider: {config.llm.provider}") print(f"Model: {config.llm.model}")

KubeGuard Methodology

5-Step LLM Prompt Chain

Role Understanding: Analyze structure and infer purpose
Permission Analysis: Deep security assessment
Runtime Correlation: Usage pattern analysis
Risk Assessment: Comprehensive risk scoring
Recommendation Generation: Actionable improvements

Security Scoring

90-100: Excellent security posture
70-89: Good security, minor improvements
50-69: Moderate risk, review required
30-49: High risk, immediate action needed
0-29: Critical risk, urgent remediation

Common Issues Detected

Wildcard permissions (*)
Excessive privileges beyond actual usage
Access to sensitive resources (secrets, configmaps)
Dangerous subresources (pods/exec, pods/portforward)
Privilege escalation vectors

Usage Examples

Basic Analysis

# Analyze a Role for security issues analysis = await analyzer.analyze_role(role_manifest) print(json.dumps(analysis.to_dict(), indent=2))

Generate Hardened Role

# Create a hardened version hardened = analyzer.generate_hardened_role(analysis) print(json.dumps(hardened.hardened_role_manifest, indent=2))

Runtime Log Integration

# Include runtime logs for usage correlation runtime_logs = [ '{"verb":"get","resource":"pods","user":"system:serviceaccount:default:app"}', '{"verb":"list","resource":"pods","user":"system:serviceaccount:default:app"}' ] analysis = await analyzer.analyze_role(role_manifest, runtime_logs)

MCP Integration

Available Tools

analyze_role_security
- Input: Role manifest, optional runtime logs
- Output: Comprehensive security analysis
generate_hardened_role
- Input: Role manifest
- Output: Hardened Role with improvements
validate_role_security
- Input: Role manifest, security threshold
- Output: Pass/fail validation with recommendations

Available Resources

kubeguard://security-guidelines: Security best practices
kubeguard://example-roles: Example secure/insecure configurations
kubeguard://prompt-chain-info: LLM methodology details
kubeguard://configuration: Server configuration

Development

Project Structure

kubeguard-mcp/ ├── kubeguard/ │ ├── main.py # MCP server entry point │ ├── analyzer.py # Core analysis engine │ ├── prompts.py # LLM prompt chains │ ├── models.py # Data models │ └── config.py # Configuration ├── tests/ ├── examples/ └── requirements.txt

Testing

# Run tests python -m pytest tests/ # Test specific functionality python -m pytest tests/test_analyzer.py -v

Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push branch (git push origin feature/amazing-feature)
Open Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use KubeGuard in your research, please cite the original paper:

@article{kubeguard2025, title={KubeGuard: LLM-Assisted Kubernetes Hardening via Configuration Files and Runtime Logs Analysis}, author={[Authors]}, journal={arXiv preprint arXiv:2509.04191}, year={2025} }

Support

📧 Email: support@kubeguard.io
🐛 Issues: GitHub Issues
📖 Documentation: Wiki

KubeGuard MCP Server

KubeGuard MCP Server

Features

🛡️ Security Analysis

🔧 Analysis Tools

📊 Analysis Methods

Quick Start

1. Installation

2. Configuration

3. Run Server

4. Test Analysis

Configuration

Environment Variables

Analysis Configuration

KubeGuard Methodology

5-Step LLM Prompt Chain

Security Scoring

Common Issues Detected

Usage Examples

Basic Analysis

Generate Hardened Role

Runtime Log Integration

MCP Integration

Available Tools

Available Resources

Development

Project Structure

Testing

Contributing

License

Citation

Support

Related Resources

Appeared in Searches

New MCP Servers

MCP directory API