kubepolicy

A fast, CI-native Kubernetes policy engine with clean UX and GitHub Security integration.

Not "just a linter"—kubepolicy evaluates your Kubernetes YAML against security, reliability, cost, and best-practice rules, with SARIF output so findings appear in the GitHub Security tab.

Features

• Recursive YAML scanning with multi-document support
• Parallel scanning for speed
• 10 built-in rules (security, reliability, cost, best practice)
• Config file (.kubepolicy.yaml) to disable rules or override severity
• Output formats: table (default), JSON, SARIF (GitHub Code Scanning)
• Exit code control: fail CI when findings meet a severity threshold (--fail-on)

Install

From PyPI (recommended)

pip install kubepolicy

From source

git clone https://github.com/akintunero/kube-guard.git
cd kube-guard
pip install -e .

Development setup

git clone https://github.com/akintunero/kube-guard.git
cd kube-guard
pip install -e ".[dev]"
pytest tests -v

Quick start

# Scan current directory (default: table output)
kubepolicy scan ./

# JSON output
kubepolicy scan ./ --format json

# SARIF for GitHub Security tab (e.g. in CI)
kubepolicy scan ./ --format sarif > results.sarif

# Fail CI on MEDIUM or higher
kubepolicy scan ./ --fail-on MEDIUM

# List all rules
kubepolicy list-rules

# Explain a rule
kubepolicy explain SEC001

# Create sample config
kubepolicy init

Built-in rules (10)

ID	Title	Severity	Category
SEC001	Privileged container	CRITICAL	security
SEC002	Missing resource limits	MEDIUM	security
SEC003	Use of latest tag	MEDIUM	security
SEC004	hostPath usage	HIGH	security
SEC005	Run as root	HIGH	security
SEC006	Allow privilege escalation	HIGH	security
REL001	Missing liveness probe	MEDIUM	reliability
REL002	Missing readiness probe	MEDIUM	reliability
COST001	No resource requests	MEDIUM	cost
BP001	Image pull policy misconfig	LOW	best_practice

Config file

Create .kubepolicy.yaml in your repo (or run kubepolicy init):

disable:
  - BP001

severity_overrides:
  COST001: HIGH

GitHub Security integration (SARIF)

In GitHub Actions, run kubepolicy and upload the SARIF file:

- name: Run kubepolicy
  run: kubepolicy scan ./ --format sarif > kubepolicy-results.sarif || true
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: kubepolicy-results.sarif

Findings will appear under Security → Code scanning in your repository.

Pre-commit

Example hook (run kubepolicy on staged YAML):

# .pre-commit-hooks.yaml
- repo: local
  hooks:
    - id: kubepolicy
      name: kubepolicy scan
      entry: kubepolicy scan
      language: system
      types: [yaml]
      args: [.]

Comparison with kube-linter

	kubepolicy	kube-linter
SARIF / GitHub Security	✅ Native	Via custom
Config file	✅ .kubepolicy.yaml	✅
Fail-on severity	✅	✅
Parallel scan	✅	—
Python 3.11+	✅	Go
Extensibility	Rule registry	Custom checks

kubepolicy is designed to be CI-first and GitHub-native, with a small, focused rule set and minimal dependencies.

Requirements

• Python 3.11+
• Typer, ruamel.yaml, Rich (see pyproject.toml)

Development

See CONTRIBUTING.md for guidelines on contributing to kubepolicy.

Quick start:

# Clone the repository
git clone https://github.com/akintunero/kube-guard.git
cd kube-guard

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests -v

# Run with coverage
pytest tests --cov=kubepolicy --cov-report=html

Project Status

kubepolicy is in active development. We welcome contributions, bug reports, and feature requests!

• 🐛 Found a bug? Open an issue
• 💡 Have a feature idea? Start a discussion
• 🤝 Want to contribute? See CONTRIBUTING.md

Roadmap

• Additional security rules (network policies, RBAC, etc.)
• Custom rule support via plugins
• Integration with other CI/CD platforms (GitLab, Jenkins, etc.)
• Performance optimizations for large codebases
• Rule severity auto-tuning based on context

Changelog

See CHANGELOG.md for a list of changes and version history.

License

MIT License. See LICENSE for details.

Author

Olúmáyòwá Akinkuehinmi

• Email: akintunero101@gmail.com
• GitHub: @akintunero

Acknowledgments

• Inspired by tools like kube-linter and kube-score
• Built with Typer, ruamel.yaml, and Rich