🛡️ Guardon — Catch Kubernetes Security Issues Before They Hit Production

Spot Kubernetes security misconfigurations instantly while reviewing code on GitHub/GitLab. No CI setup required.

🚀 Quick Start (30 seconds)

1. Install from Chrome Web Store →
2. Open any Kubernetes YAML on GitHub/GitLab
3. Click the Guardon icon — violations appear instantly with suggested fixes

📺 2-minute demo video →

Trailor

1. **
2. **
3. **

✨ Why Developers Love Guardon

• 🔍 Instant feedback — No waiting for CI pipelines or security scans
• 🎯 Context-aware — Works directly in your GitHub/GitLab workflow
• ⚡ Zero setup — Browser extension, no infrastructure changes
• 🛠️ Actionable fixes — Copy-paste ready YAML patches
• 🔧 Fully customizable — Import your own rules or Kyverno policies

🎯 Common Issues Guardon Catches

# ❌ Privileged containers
securityContext:
  privileged: true  # Guardon flags this

# ❌ Missing resource limits  
containers:
- name: app
  image: nginx  # Guardon suggests adding limits

# ❌ Latest tags in production
containers:
- name: app
  image: nginx:latest  # Guardon suggests specific version

💡 Pro tip: Guardon shows you exactly what to fix and provides copy-paste ready solutions.

👥 Who Uses Guardon

• Platform Engineers — Catch misconfigurations during code review
• Security Teams — Enforce governance policies without blocking developers
• DevOps Engineers — Prevent production incidents from bad YAML
• Kubernetes Newcomers — Learn security best practices as you code

"Guardon caught a privileged container in our deployment that would have been a security incident. Saved us hours of debugging!" — Platform Engineering Team

🛠️ Features That Save Time

Feature	Benefit
Multi-document YAML parsing	Handles complex manifests with multiple resources
Kyverno policy import	Reuse your existing governance policies
Smart fix suggestions	Get patches you can copy-paste directly
Custom rule engine	Add your organization's specific requirements
Dark mode support	Easy on the eyes during late-night deployments
Offline-first	No network calls, works anywhere

🔧 Development Setup (2 minutes)

For Contributors & Custom Rules:

# 1. Clone and setup
git clone https://github.com/guardon-dev/guardon.git
cd guardon
npm install

# 2. Load into Chrome
# Open chrome://extensions → Enable Developer mode → Load unpacked (select this folder)

# 3. Test your changes
npm test

Requirements: Node.js 16+ (for tests), any Chromium-based browser

💡 How It Works

Simple workflow:

1. Browse Kubernetes YAML on GitHub/GitLab
2. Click the Guardon extension icon
3. Review security issues with explanations
4. Copy suggested fixes and apply them

Advanced usage:

• Paste YAML directly for ad-hoc validation
• Import Kyverno policies from your governance tooling
• Create custom rules for your organization's standards
• Batch validate multiple YAML documents

Popup Actions

• 🔧 Preview patch — See exactly what the fix looks like
• 📋 Copy snippet — Grab just the fixed value
• ℹ️ Explain — Understand why this matters (with CIS/NIST references)

---

📚 Technical Documentation

🔧 Custom Rules & Configuration

Rule Schema

• Rules are stored in extension storage and editable via the Options page (src/options/options.html).

• Rule schema (important fields):

  • id: unique rule identifier
  • description: human description
  • kind: optional comma-separated kinds to scope the rule
  • match: dot/array path to inspect (supports [*] for arrays)
  • pattern: a JavaScript RegExp string to evaluate against the target value
  • required: boolean — mark field as required
  • severity: info | warning | error
  • fix: optional JSON describing a suggested fix (action/value/hint)
  • explain: optional object { rationale: string, refs: string[] }

Options Page Features

• Add/Edit/Delete rules
• Import from file or URL (background fetch fallback)
• Kyverno policy detection + preview of converted rules
• Import panel buttons: "Paste from clipboard" and "Cancel" (convenience and clear/close the import UI)
• Quick "Suggest resource fix" helper to populate the Fix JSON textarea with a sensible requests/limits suggestion for resource-related rules

📦 Kyverno Policy Import

• Located at src/utils/kyvernoImporter.js.
• Detects Kyverno Policy manifests (apiVersion contains kyverno.io and kind Policy/ClusterPolicy).
• Converts simple validate.pattern leaves into required checks and pattern-based rules. Also detects common env name/value entries and converts negative checks (!value) into pattern rules with sibling conditions.
• Converted rules are previewed in the Options page; you can import converted rules or store raw Kyverno policies for audit.

Limitations: the importer is heuristic and intentionally conservative — complex policies are not fully converted and are left for manual review.

🏗️ Architecture Overview

High-level architecture:

• Popup UI: user-triggered validation, YAML paste, and results/suggestions UI.
• Content script: message-driven page extractor that returns raw YAML when requested by the popup.
• Background (service worker): performs fallback fetches (raw content, import-from-URL), accesses storage.
• Rules engine & utilities: multi-doc YAML parsing, rule evaluation (kind filtering, wildcard per-element checks), suggestion generation and preview helpers, and Kyverno importer.

This diagram shows the main data flow: the popup requests YAML from the content script (or falls back to background fetch), sends YAML to the rules engine for validation, and displays violations and optional fix suggestions to the user.

🧪 Development & Testing

Run unit tests and collect coverage:

npm install
npm test

• Tests use Jest and target utility modules under src/utils. Coverage reports are stored in coverage/.

📦 Building Distribution

We provide small scripts that create a trimmed ZIP containing only the runtime files needed by the extension (manifest, popup/options, background, content script, runtime libs). Use these to produce the ZIP you upload to the Chrome Web Store.

PowerShell (Windows):

.\scripts\build-dist.ps1
# or specify a custom filename
.\scripts\build-dist.ps1 -OutFile guardon-latest.zip

Bash (Linux/macOS/WSL):

chmod +x ./scripts/build-dist.sh
./scripts/build-dist.sh
# or with explicit output name
./scripts/build-dist.sh guardon-latest.zip

🔧 Troubleshooting

Issue	Solution
"Validation engine not available"	Open DevTools for popup and check console for import errors
Suggestions not appearing	Verify rules in Options page include fix and explain metadata
npm install fails	Check Node version (node -v) and share npm error logs for help

---

📖 Additional Resources

• Governance & Maintainers — Project governance and decision-making process
• Contributing Guidelines — Detailed contribution instructions and DCO process
• Roadmap — Planned features, milestones, and time horizons
• Security Policy — Responsible disclosure and security practices

📄 License

Apache-2.0 — See the LICENSE file for details.

---

Made with ❤️ for the Kubernetes community

⭐ Star this project • 🐛 Report a bug • 💡 Request a feature

🏷️ Versioning and Release Identification

Every release of Guardon includes a unique version identifier, visible in both the browser extension and the project files:

• The extension version is set in manifest.json (e.g., "version": "0.4").
• The npm/package version is set in package.json (e.g., "version": "0.1.0").
• Each release and distribution is tagged with its version for traceability.

Users and contributors can always find the current version in the extension details, manifest.json, and package.json.