diff --git a/ci/spelling-config.json b/ci/spelling-config.json index cabc2fda1..b23a27f69 100644 --- a/ci/spelling-config.json +++ b/ci/spelling-config.json @@ -235,6 +235,13 @@ "Aurélie", "Vache", "Kanabar", - "Michaely" + "Michaely", + "guardon", + "Guardon", + "Sajal", + "Nigam", + "Sajal Nigam", + "guardon", + "Guardon" ] } diff --git a/community/assessments/projects/guardon/DCO.md b/community/assessments/projects/guardon/DCO.md new file mode 100644 index 000000000..11e09d866 --- /dev/null +++ b/community/assessments/projects/guardon/DCO.md @@ -0,0 +1,33 @@ +# Developer Certificate of Origin (DCO) + +By contributing to this project, you agree to the Developer Certificate of Origin: + +```text +Developer Certificate of Origin +Version 1.1 + +By making a contribution to this project, I certify that: + +1. The contribution was created in whole or in part by me and I have the right to + submit it under the open source license indicated in the file; +2. The contribution is based upon previous work that, to the best of my knowledge, + is covered under an appropriate open source license and I have the right under + that license to submit that work with modifications, whether created in whole + or in part by me, under the same open source license (unless I am permitted to + submit under a different license), as indicated in the file; +3. The contribution was provided directly to me by some other person who certified + (1), (2) or (3) and I have not modified it. +4. I understand and agree that this project and the contribution are public and that + a record of the contribution (including all personal information I submit with + it, including my sign-off) is maintained indefinitely and may be redistributed + consistent with this project or the open source license(s) involved. +``` + +To sign off your commits, use the `--signoff` flag: + +```sh +git commit --signoff +``` + +This will add a `Signed-off-by: Sajal Nigam ` line to your +commit message, certifying your compliance with the DCO. diff --git a/community/assessments/projects/guardon/self-assessment.md b/community/assessments/projects/guardon/self-assessment.md new file mode 100644 index 000000000..051d45e5d --- /dev/null +++ b/community/assessments/projects/guardon/self-assessment.md @@ -0,0 +1,258 @@ +# Guardon — CNCF TAG-Security Self-Assessment + +**Project:** Guardon +**Type:** Browser-based Kubernetes YAML & Policy Validator +**Website:** [Guardon](https://chromewebstore.google.com/detail/jhhegdmiakbocegfcfjngkodicpjkgpb?utm_source=item-share-cb) +**Contact:** [sajalnigam@gmail.com](mailto:sajalnigam@gmail.com) +**Assessment Version:** v1.0 +**Last Updated:** 2025-11-28 + +--- + +## 1. Project Overview + +Guardon is a **fully client-side browser extension** (Chrome/Edge/Brave) that performs: + +- **Instant Kubernetes YAML validation** — Flags security misconfigurations as you browse GitHub/GitLab, with no CI/CD required. + +- **Schema-aware checks** — Validates manifests against uploaded Kubernetes OpenAPI/CRD schemas to ensure required fields and type safety. + +- **Customizable rule engine** — Supports JSON-based rules and Kyverno policy import for organization-specific governance standards. + +- **Multi-document YAML support** — Handles complex manifests containing multiple resources in a single file. + +- **Actionable fix suggestions** — Generates copy-paste-ready YAML patches for every violation. + +- **Dark mode UI** — Provides a seamless experience across day and night workflows. + +- **Offline-first** — All validation runs fully locally in your browser with zero network calls. + +- **Manual paste & validation** — Validate any YAML by pasting it directly into the extension popup, even outside GitHub/GitLab. + +- **Enterprise-ready** — Import/manage custom rules, preview Kyverno policies, and enforce governance at organizational scale. + +Guardon shifts Kubernetes security **far left**, helping developers identify misconfigurations +**before** they reach CI pipelines or clusters. +All validation happens locally inside the browser using **JavaScript**. +No backend, no cloud service, and **no user data ever leaves the machine**. + +--- + +## 2. Security Boundary + +Guardon has a strict and minimal security boundary: + +- Runs entirely within browser WebExtension APIs +- No backend infrastructure +- No telemetry or analytics +- No transmission of YAML or policies to external systems +- Instead, Guardon converts Kyverno policies to its own internal rule format for validation in the browser +- No Kubernetes cluster access, no secrets, no tokens +- Only interacts with user-selected YAML files or GitHub/GitLab DOM content + +**Trusted Computing Base (TCB):** + +- Browser (Chrome/Brave/Edge) +- Guardon WebExtension JS/TS code +- Embedded Kyverno-rules engine +- Local storage for rules and configuration + +--- + +## 3. Goals and Non-Goals + +### **Goals** + +- Detect Kubernetes misconfigurations early, at authoring time +- Enforce governance standards using Kyverno rules +- Provide deterministic and reproducible validation results +- Work entirely offline and locally +- Improve developer productivity by embedding checks inside workflow +- Offer zero-trust handling of user data (no outbound calls) + +### **Non-Goals** + +- Not a runtime security tool +- Not a replacement for PSP, PSA, Gatekeeper, or Kyverno in-cluster +- Not a network or API security solution +- Does not detect runtime attacks, malware, or CVEs +- Does not handle supply-chain validation outside YAML/policies +- Does not attest image provenance or signatures + +--- + +## System Architecture + +![Guardon Architecture](https://github.com/user-attachments/assets/765d980f-2fad-412a-b6d5-07252a46c462) + +Guardon is built around four core modules: + +### **1. Content Script** + +- Injected directly into GitHub/GitLab pages +- Extracts Kubernetes YAML from PRs, files, and diffs +- Displays inline annotations and highlights misconfigurations + +### **2. Validation Engine** + +- Parses YAML and performs schema validation using `js-yaml` +- Evaluates JSON-based custom rules and imported Kyverno policies +- Generates actionable, copy-paste-ready fix suggestions for every issue + +### **3. Background Service Worker** + +- Manages cross-tab communication and extension lifecycle events +- Handles background tasks such as rule bundle loading and remote fetches +- Coordinates storage, caching, and sync of custom rules + +### **4. Extension UI** + +- Popup interface for instant YAML validation and fix previews +- Options page for rule import, export, and advanced customization +- Built-in rule editor for creating and managing custom rule bundles + +--- + +## 5. Actors and Data Flow + +### **Actors** + +- **Developer**: Uses Guardon while browsing YAML on GitHub/GitLab +- **Browser**: Provides sandboxed execution environment +- **Local Guardon Engine**: Performs validation +- **Kyverno-JS**: Evaluates policies locally +- **Rule Sources**: User-imported Kyverno rules stored locally + +### **Data Flow Summary** + +1. User views Kubernetes YAML on GitHub/GitLab +2. Guardon content script extracts YAML into memory +3. Data is sent to the Worker Engine (local only) +4. Worker evaluates schema + policies +5. Results returned to content script +6. Inline annotations displayed +7. No data is logged, stored externally, or transmitted + +--- + +## 6. Critical Security Functions + +### **Critical (Non-Configurable)** + +- Kubernetes schema validation +- Local Kyverno-JS policy execution +- Secure sandboxing of rule engine +- YAML isolation and strict parsing +- Immutable validation results +- No-network guarantee +- No access to browser cookies, tokens, or secrets +- Extension CSP preventing inline script execution +- Architecture and policies minimize dependency risk, but ongoing vigilance is required + +### **Security-Relevant (Configurable)** + +- Custom rule bundle imports +- Background fetch helper for related YAMLs +- Organization-specific governance packs +- Optional CIS/NIST best-practice packages + +--- + +## 7. Threat Model (High-Level) + +### Guardon mitigates + +- Misconfigured workloads (privileged pods, hostPath, missing limits, etc.) +- RBAC over-permission +- Pod Security violations +- YAML structural errors +- Drift from organizational governance standards +- Incorrect multi-document YAML compositions +- Unsafe defaults (no resource limits, insecure capabilities) + +### Guardon does NOT mitigate + +- Runtime container escape +- Host/kernel compromise +- Image-level supply-chain attacks +- Network-level exploits +- Malicious browser extensions +- Insider threat or malicious developer intent +- Attacks on GitHub/GitLab itself + +Full threat model available in `guardon-threat-model.md`. + +--- + +## 8. Secure Development Practices + +- Public source code on GitHub +- MIT License +- CI pipeline with: + - Static code analysis (ESLint) + - npm audit +- Automated dependency scanning +- Consistent and Auditable Build Process +- Release bundles signed with GitHub provenance +- Mandatory code review for PRs +- SECURITY.md published in repository +- Obtaining a OpenSSF badge is also on the roadmap + +--- + +## 9. Vulnerability Reporting & Incident Response + +**Contact:** [sajalnigam@gmail.com](mailto:sajalnigam@gmail.com) +**Policy:** SECURITY.md follows TAG-Security template + +Incident handling workflow: + +1. Triage and reproduce issue +2. Assign CVSS score +3. Apply patch in a protected branch +4. Issue temporary private release for reporters if needed +5. Public security advisory via GitHub Security Advisories +6. Patch release with clear changelog +7. Update community channels + +Guardon follows a **90-day disclosure window** or faster if required. + +--- + +## 10. Known Limitations + +- Limited by GitHub/GitLab DOM stability +- Multi-GB YAML files not supported +- Will not detect runtime or CVE-level vulnerabilities +- No distributed policy cache (local only) +- Not compatible with Firefox yet (pending MV3 support) + +--- + +## 11. Roadmap (Security-Focused) + +- Signed rule packs +- Rule provenance verification +- In-extension SBOM viewer +- AI-assisted policy recommendations +- Support for JetBrains/VScode extensions +- Organization-managed rule registries +- Policy drift detection across repo + +--- + +## Appendix + +### Example Use Cases + +- Detect privileged pod before code review +- Validate RBAC roles from GitHub UI +- Local evaluation of Kyverno policies before commits +- Quick governance compliance checks for microservices teams + +### Example Policies + +- “Disallow hostPath” +- “Require resource limits/requests” +- “Block privileged containers” +- “Prevent hostNetwork usage” diff --git a/community/assessments/projects/guardon/threat-model.md b/community/assessments/projects/guardon/threat-model.md new file mode 100644 index 000000000..82371f9e7 --- /dev/null +++ b/community/assessments/projects/guardon/threat-model.md @@ -0,0 +1,161 @@ +# Guardon — Threat Model (STRIDE-Based) + +**Methodology:** STRIDE +**Scope:** Browser extension + JS policy engine + YAML parsing +**Version:** v1.0 + +--- + +## 1. Assets + +- Kubernetes YAML documents +- User-defined policy bundles +- Validation results +- Local rule storage +- Browser’s trust environment +- JS engine integrity +- Guardon extension code + +--- + +## 2. Actors + +### **Primary** + +- Developer (authorized) +- Guardon Extension +- Kyverno-JS engine +- Browser sandbox + +### **Secondary** + +- GitHub/GitLab interface (untrusted but expected) +- External rule sources (trusted only through user import) + +### **Adversaries** + +- Malicious developer +- Compromised browser extension ecosystem +- Supply-chain attacker +- Browser exploit attacker +- User with malicious intent +- Malicious JavaScript in GitHub/GitLab DOM + +--- + +## 3. STRIDE Analysis + +### **S — Spoofing** + +**Risks:** + +- Impersonation of rule sources +- Malicious JS module tampering +- Fake extension versions + +**Mitigations:** + +- Signed releases +- No remote rule fetching +- CSP restricting script injection +- User-controlled rule import only + +--- + +### **T — Tampering** + +**Risks:** + +- Modification of rules in local storage +- DOM-based manipulation of annotations +- Altering validation logic via supply-chain JS + +**Mitigations:** + +- Local storage schema validation +- Immutable rule parsing +- Content-Security-Policy enforcement + +--- + +### **R — Repudiation** + +**Risks:** + +- No server logs (intentional design) +- Hard to prove who changed rule bundles + +**Mitigations:** + +- User confirmation flows for rule changes +- Optional local audit log (planned) +- Clearly documented local-only behavior + +--- + +### **I — Information Disclosure** + +**Risks:** + +- YAML content exposure if extension leaks +- Cross-tab data leakage +- Extension accessing unrelated browser data + +**Mitigations:** + +- Strict MV3 permissions +- Zero telemetry design +- No cookie/storage access +- No external endpoints +- Runtime isolation via WASM + +--- + +### **D — Denial of Service** + +**Risks:** + +- Large YAML files freeze extension +- Malicious rule packs causing infinite evaluation +- DOM mutation overload from CI diffs + +**Mitigations:** + +- Worker timeouts +- Rule execution limits +- Graceful fallback mode + +--- + +### **E — Elevation of Privilege** + +**Risks:** + +- Extension gaining access to tokens +- DOM injection attacks escalating permissions + +**Mitigations:** + +- No access to cookies, tokens, or storage +- Browser sandbox isolation +- Restricted extensions permissions (read-only) + +--- + +## 4. Out-of-Scope Threats + +- Kubernetes runtime attacks +- Host/kernel exploitation +- Network/TLS attacks +- GitHub/GitLab authentication flows +- Supply-chain attacks unrelated to Guardon code +- Cross-extension interference + +--- + +## 5. Attack Surfaces + +- Browser DOM +- Local rule storage +- YAML parser +- Extension update mechanism