Kuberef

Kuberef is a lightweight, cloud-native CLI tool designed to validate Kubernetes Secret references before you deploy. It bridges the gap between static YAML manifests and your live cluster state, preventing "silent failures" caused by missing secrets or incorrect data keys.

---

Features

• Batch & Recursive Spec Discovery: Automatically scans single files or entire directories for Kubernetes resources including Deployments, StatefulSets, Jobs, and CronJobs to find nested Pod specifications.

• Deep-Key Validation: Verifies not only that a Secret exists, but that the specific keys required are present in the Secret's data, preventing runtime container crashes.

• Comprehensive Pattern Matching: Audits all common Secret reference patterns, including env.valueFrom, bulk envFrom loads, volumes (Secret mounts), and imagePullSecrets.

• Live Cluster Auditing: Performs real-time cross-referencing against the live Kubernetes API using your active kubeconfig context.

• Pre-Flight Environment Checks: Validates cluster connectivity and ensures the target namespace exists before executing the audit to prevent false positives.

• Global Automation Reporting: Built with Typer to provide aggregate summary statistics accross multiple files and standard exit codes (0 for success, 1 for failures/warnings) to automatically break pipeline builds on misconfigurations.

• Rich Terminal UI: Utilizes the Rich library to deliver a clean, color-coded terminal interface with clear PASS/FAIL/WARNING status tables for every file scanned.

---

Installation

From PyPI (Recommended)

Install the tool globally using pip:

pip install kuberef

From Source (Development)

If you want to run the tool from source or contribute:

git clone https://github.com/hudazaan/kuberef.git
cd kuberef
poetry install
poetry run kuberef path/to/your/k8s-manifest.yaml

Using Docker (Containerized)

If you don't want to install Python locally, you can run Kuberef as a container. You must mount your local kubeconfig and the directory containing your manifests.

Build the image locally:

docker build -t kuberef https://github.com/hudazaan/kuberef.git

Run the audit:

# Linux / macOS (zsh, bash)
docker run -it --rm --network="host" -v ~/.kube/config:/root/.kube/config -v "$(pwd):/app" kuberef /app

# Windows (PowerShell)
docker run -it --rm --network="host" -v "${HOME}/.kube/config:/root/.kube/config" -v "C:/PATH/TO/YOUR/MANIFESTS:/app" kuberef /app

Verification Commands (For Debugging):

# Inspect package
pip show kuberef

# Run as a module
python -m kuberef --help

---

Usage

Audit a single manifest against the default namespace:

kuberef deployment.yaml

Audit an entire directory of manifests:

kuberef ./k8s-manifests/

Audit a specific namespace by using -n or --namespace flag to validate secrets:

kuberef deployment.yaml --namespace production

General Syntax to add path to your Kubernetes manifest:

kuberef <YOUR_FILE>.yaml --namespace <YOUR_NAMESPACE>

Example Output:

![Audit](./docs/images/audit-kuberef.png)

---

Technical Architecture

• Recursive Discovery Engine: Implements a depth-first search to locate Pod specifications across all resource types (Deployments, Jobs, CronJobs, etc).
• Live Validation: Interfaces with the kubernetes Python client to perform real-time read_namespaced_secret calls for existence and key-level verification.
• Stream Parser: Leverages PyYAML and safe_load_all to parse multi-document manifests in a single pass.
• Directory Processing Engine: Implements a file-system crawler that identifies and filters YAML manifests for batch processing across directories.
• CLI Framework: Built on Typer to provide a high-performance interface with accumulated state counters for global multi-file reporting and standard Unix exit codes for automation.
• CI/CD Pipeline: Integrated with GitHub Actions to automatically build and test the tool on every code push, ensuring production readiness on Cloud-hosted runners.
• Containerization: Multi-stage Docker build optimized for minimal image size.

---

Testing

Kuberef includes a suite of unit tests to ensure the recursive discovery engine and parser remain stable. These tests use pytest and mock data to verify logic without requiring a live cluster.

To run the tests:

poetry run pytest

Verification Results:

• Recursive Discovery: Confirms secrets are found deep within nested controllers.
• Resilience: Ensures the tool handles empty or non-Kubernetes YAML gracefully.

---

🤝 Contributing

Contributions are welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b YOUR-BRANCH-NAME)
3. Run tests (poetry run pytest)
4. Commit your Changes (git commit -m 'your message')
5. Push to the Branch (git push origin YOUR-BRANCH-NAME)
6. Open a Pull Request

---

Author

Built with ❤️ by Huda Naaz

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---