kubepolicy 1.0.0
A fast, CI-native Kubernetes policy engine with clean UX and GitHub Security integration
License: MIT
Requires Python: >=3.11
Keywords: kubernetes, policy, security, lint, sarif, ci

# kubepolicy

[![PyPI version](https://badge.fury.io/py/kubepolicy.svg)](https://badge.fury.io/py/kubepolicy)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub](https://img.shields.io/github/stars/akintunero/kube-guard?style=social)](https://github.com/akintunero/kube-guard)

**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)

```bash
pip install kubepolicy
```

### From source

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

### Development setup

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

## Quick start

```bash
# 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`):

```yaml
disable:
  - BP001

severity_overrides:
  COST001: HIGH
```

## GitHub Security integration (SARIF)

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

```yaml
- 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):

```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](CONTRIBUTING.md) for guidelines on contributing to kubepolicy.

Quick start:

```bash
# 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](https://github.com/akintunero/kube-guard/issues)
- 💡 **Have a feature idea?** [Start a discussion](https://github.com/akintunero/kube-guard/discussions)
- 🤝 **Want to contribute?** See [CONTRIBUTING.md](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](CHANGELOG.md) for a list of changes and version history.

## License

MIT License. See [LICENSE](LICENSE) for details.

## Author

**Olúmáyòwá Akinkuehinmi**

- Email: akintunero101@gmail.com
- GitHub: [@akintunero](https://github.com/akintunero)

## Acknowledgments

- Inspired by tools like [kube-linter](https://github.com/stackrox/kube-linter) and [kube-score](https://github.com/zegl/kube-score)
- Built with [Typer](https://typer.tiangolo.com/), [ruamel.yaml](https://yaml.readthedocs.io/), and [Rich](https://rich.readthedocs.io/)