# Security Policy

## Reporting a vulnerability

If you find a security vulnerability in Kuberoku, please report it responsibly.

**Do not open a public issue.**

Instead, use [GitHub's private security advisory](https://github.com/amanjain/kuberoku/security/advisories/new).

Include:
- Description of the vulnerability
- Steps to reproduce
- Impact assessment
- Suggested fix (if you have one)

You'll receive a response within 72 hours.

## Security architecture

Kuberoku is a **client-side only** tool. There are no server-side components, no daemons, no webhooks, and no admission controllers installed on your cluster. The CLI talks directly to the Kubernetes API using your existing kubeconfig credentials.

### What is stored locally

| Location | Contents |
|---|---|
| `~/.kube/config` | Standard kubeconfig (not managed by Kuberoku) |
| `~/.kuberoku/config.yaml` | Cluster registry: context names, namespaces, resource prefixes. **No credentials or secrets.** |
| `.kuberoku` (project dir) | Optional project marker with default app name. No secrets. |

**That's it.** Kuberoku does not store credentials, tokens, secrets, or sensitive data on disk. It delegates all authentication to your kubeconfig and the Kubernetes client library.

### How secrets are handled

- **Config vars** set with `config:set --secret` are stored as [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) using `stringData` (not base64-encoded `data`).
- Secrets are **never written to local disk**, logs, or crash reports.
- Secret values are **masked in CLI output** — only key names are shown.
- Addon credentials (database passwords, etc.) are stored in K8s Secrets and injected into pods via environment variables.
- **Secrets at rest encryption** is your cluster's responsibility (`EncryptionConfiguration`). Kuberoku uses whatever protection your cluster provides.

### Network posture

- **Outbound only**: CLI → Kubernetes API server (HTTPS). No inbound connections.
- No telemetry, analytics, or phone-home behavior.
- Plugin install/search talks to PyPI (HTTPS) — only when explicitly invoked.

### RBAC permissions

Kuberoku follows least-privilege. Run `kuberoku clusters:doctor` to audit your permissions, or `clusters:doctor --fix` to generate minimal Role/RoleBinding YAML.

**Required** (core functionality):

| Resource | API Group | Verbs | Used by |
|---|---|---|---|
| namespaces | core | get, list | apps |
| configmaps | core | get, list, create, update, patch, delete | apps, config, releases |
| deployments | apps | get, list, create, update, patch, delete | deploy, ps |
| pods | core | get, list, delete | ps, restart |
| pods/log | core | get | logs |
| pods/exec | core | create | exec |
| services | core | get, list, create, update, delete | deploy, addons |
| jobs | batch | get, list, create, delete | run |

**Elevated** (optional features — only needed if you use them):

| Resource | API Group | Verbs | Used by |
|---|---|---|---|
| secrets | core | get, list, create, update, patch, delete | config --secret |
| ingresses | networking.k8s.io | get, list, create, update, delete | domains |
| statefulsets | apps | get, list, create, update, patch, delete | addons |
| persistentvolumeclaims | core | get, list, create, delete | addons |
| networkpolicies | networking.k8s.io | get, list, create, update, delete | networking |

### Scope of responsibility

| Kuberoku handles | Cluster admin handles |
|---|---|
| Safe CLI input validation | Secrets at rest encryption (`EncryptionConfiguration`) |
| No secrets in logs/output | RBAC enforcement between namespaces |
| Namespace isolation of resources | Network-level encryption (mTLS) |
| Minimal RBAC requirements | Cluster authentication (OIDC, certificates) |

### Dependencies

Kuberoku has 3 runtime dependencies, minimizing supply chain surface:

- `kubernetes` — official Kubernetes Python client
- `click` — CLI framework
- `pyyaml` — YAML parsing

All PyPI releases use [OIDC trusted publishing](https://docs.pypi.org/trusted-publishers/) (no long-lived API tokens).
