{"id":32571702,"url":"https://github.com/kguardian-dev/kguardian","last_synced_at":"2026-06-01T12:01:00.634Z","repository":{"id":203406800,"uuid":"664206244","full_name":"kguardian-dev/kguardian","owner":"kguardian-dev","description":"A Kubernetes tool leveraging eBPF for advanced Kubernetes security, auto-generating Network Policies, Seccomp Profiles, and more.","archived":false,"fork":false,"pushed_at":"2026-05-28T09:44:40.000Z","size":191612,"stargazers_count":59,"open_issues_count":48,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T11:21:17.905Z","etag":null,"topics":["ebpf","kubernetes","security"],"latest_commit_sha":null,"homepage":"https://docs.kguardian.dev","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kguardian-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/future-resources.mdx","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-09T08:34:57.000Z","updated_at":"2026-05-20T03:36:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"fe74818b-2382-45ff-81e5-7dcb9fe0b3f5","html_url":"https://github.com/kguardian-dev/kguardian","commit_stats":null,"previous_names":["xentra-ai/advisor-client","kguardian-dev/kguardian","xentra-ai/kube-guardian"],"tags_count":140,"template":false,"template_full_name":null,"purl":"pkg:github/kguardian-dev/kguardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguardian-dev%2Fkguardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguardian-dev%2Fkguardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguardian-dev%2Fkguardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguardian-dev%2Fkguardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kguardian-dev","download_url":"https://codeload.github.com/kguardian-dev/kguardian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguardian-dev%2Fkguardian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33773782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ebpf","kubernetes","security"],"created_at":"2025-10-29T09:01:01.207Z","updated_at":"2026-06-01T12:01:00.627Z","avatar_url":"https://github.com/kguardian-dev.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# kguardian: Kubernetes Security Profile Generator\n\n- **What it does:** Generates least-privilege Kubernetes NetworkPolicies, CiliumNetworkPolicies, and seccomp profiles from observed runtime behavior.\n- **Who it's for:** Platform and security teams running Kubernetes who want policy-as-code without writing rules by hand.\n- **What it costs to run:** lightweight control plane (~60 MiB/node for the eBPF agent; tens of MiB for the services) plus a PostgreSQL you size to your fleet — see [Performance](#performance) for measured reference figures.\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/kguardian-dev/kguardian)](https://goreportcard.com/report/github.com/kguardian-dev/kguardian)\n[![License](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](https://mariadb.com/bsl11/)\n\nkguardian watches pod traffic and syscalls with eBPF, then writes Kubernetes NetworkPolicies, CiliumNetworkPolicies, and seccomp profiles from what it sees — no hand-authored rules.\n\n## What is kguardian?\n\nA Kubernetes runtime-observability tool that turns the network and syscall behavior of your pods into the policy YAML you would otherwise have to write by hand.\n\n## What does it do?\n\nThe Controller (eBPF DaemonSet) captures every TCP/UDP connection and syscall on each node. The Broker stores the per-pod baseline in PostgreSQL. The `kubectl kguardian` plugin queries that baseline and synthesizes a least-privilege policy for the pod, namespace, or whole cluster you ask about.\n\n## What does it generate?\n\nFor each target you select, kguardian emits:\n\n- a Kubernetes [`NetworkPolicy`](docs/policy-gallery/) YAML,\n- a Cilium [`CiliumNetworkPolicy`](docs/policy-gallery/) YAML (for Cilium CNI users),\n- a [seccomp](docs/policy-gallery/) JSON profile.\n\nWorked examples for nginx, Postgres, kube-dns, Prometheus, an Istio sidecar, and a Go microservice are in the [Generated Policy Gallery](docs/policy-gallery/).\n\n## Distro Compatibility\n\nkguardian's eBPF Controller requires Linux kernel **6.2 or newer** on every node that runs the DaemonSet. Verify with `uname -r` per node before installing.\n\n| Distro | Default kernel | Compatible? |\n|---|---|---|\n| Ubuntu 24.04 | 6.8 | ✅ |\n| Ubuntu 22.04 | 5.15 | ❌ (need HWE 6.2+) |\n| RHEL 9 | 5.14 | ❌ |\n| Amazon Linux 2023 | 6.1 | ❌ |\n| Debian 12 | 6.1 | ❌ (need backports) |\n| Talos / Bottlerocket | usually 6.1+ | check distro version |\n\nKernel versions reflect the GA/server defaults shipped by each distro as of May 2026. Newer kernels are typically available via opt-in channels (Ubuntu HWE, AL2023 kernel-6.12+ AMI, Debian backports, RHEL 9 kernel modules from third parties).\n\n## Features\n\n- **Network Policy Generation:** Least-privilege Kubernetes `NetworkPolicy` and Cilium `CiliumNetworkPolicy` / `CiliumClusterwideNetworkPolicy` resources from observed pod-to-pod traffic.\n- **Seccomp Profile Generation:** Per-container syscall allowlists derived from runtime traces.\n- **Targeting:** Generate per-pod, per-namespace, or cluster-wide.\n- **Dry-Run Default:** YAML is written to `--output-dir` and not applied unless you pass `--dry-run=false` (NetworkPolicies only).\n- **File Output:** YAML/JSON files for review or GitOps pipelines.\n- Optional natural-language LLM bridge for querying traffic/syscall data — see [docs/ai-assistant](docs/ai-assistant/).\n\n## Comparison with Other Tools\n\nHow kguardian compares to Inspektor Gadget and Security Profiles Operator (NetworkPolicy support, seccomp generation, operational model, …): see the [feature comparison table](https://docs.kguardian.dev/#comparison-with-other-tools) on the docs site.\n\n## Performance\n\nReference figures from a real-world deployment: a **3-node cluster (18\nvCPU / 47 GiB RAM per node, kernel 6.18, Cilium CNI)** observing **234\npods across 26 namespaces** of mixed traffic (web apps, databases,\nstorage/Ceph, media, game servers). This is one real-world data point,\nnot a synthetic sweep — treat it as an order-of-magnitude envelope, and\nexpect numbers to scale with flow cardinality, not raw pod count.\n\n- **Controller (eBPF DaemonSet):** ~60 MiB memory per node; ~0.1–0.6\n  vCPU per node, tracking the node's connection/syscall rate.\n- **Broker + evaluator (control plane):** evaluator ~26 MiB / \u003c0.01 vCPU\n  idle; broker sized at 512 MiB request / 2 GiB limit and stays well\n  within it at this scale.\n- **PostgreSQL** is the dominant consumer (here ~0.4–2 GiB RAM, CPU\n  spiking under ingest + autovacuum) — size it generously.\n- **Baseline captured:** ~4.0 M traffic rows, ~1.37 M audit verdicts,\n  13.2 k pod records in a **1.8 GiB** database.\n- **Storage growth is dedup-bounded:** once a workload's flow set is\n  learned, new rows drop to ~0/min in steady state (identical flows are\n  collapsed), so the database grows with *new* behavior, not with time\n  or traffic volume. Configure `broker.audit.retention.days` to cap the\n  audit-verdict history.\n\n_A formal, reproducible benchmark on standardized instance types is still\nplanned; the figures above are measured, not projected._\n\n## Prerequisites\n\n- Linux Kernel 6.2+ on every node running the Controller DaemonSet\n- Kubernetes cluster v1.19+\n- `kubectl` v1.19+\n- The Controller **MUST** be installed and running in the cluster to collect the necessary data\n- (For Seccomp) Linux Kernel supporting seccomp (most modern kernels)\n\n## Installation\n\nInstall the Controller, Broker, and UI into your cluster, then install the `kubectl` plugin:\n\n```bash\nhelm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \\\n  --version 1.9.1 --namespace kguardian --create-namespace\nsh -c \"$(curl -fsSL https://raw.githubusercontent.com/kguardian-dev/kguardian/main/scripts/quick-install.sh)\"\n```\n\nManual download, custom Helm values, Kind setup, verification, upgrades, and uninstall are all covered in the [Installation Guide](https://docs.kguardian.dev/installation).\n\n## Quick Start\n\nOnce the Controller is running and collecting data, you can generate policies. For curated examples of what the generator produces against representative workloads (nginx, Postgres, kube-dns, Prometheus, Istio sidecar, Go microservice), see the [Generated Policy Gallery](docs/policy-gallery/).\n\n1.  **Generate a Network Policy (Dry Run, Save to File):**\n\n    ```bash\n    # Generate for a specific pod in the 'default' namespace\n    kubectl kguardian gen networkpolicy my-pod -n default --output-dir ./policies\n\n    # Generate for all pods in the 'staging' namespace\n    kubectl kguardian gen networkpolicy --all -n staging --output-dir ./policies\n    ```\n\n2.  **Generate a Seccomp Profile (Save to File):**\n\n    ```bash\n    # Generate for a specific pod in the 'default' namespace\n    kubectl kguardian gen seccomp my-pod -n default --output-dir ./seccomp\n\n    # Generate for all pods in all namespaces\n    kubectl kguardian gen seccomp -A --output-dir ./seccomp\n    ```\n\n3.  **Review** the generated YAML files in the specified output directories.\n\n4.  **(Optional) Apply the policies:** `--dry-run=true` is the default and only writes YAML to `--output-dir`. To apply network policies, either re-run with `--dry-run=false` or run `kubectl apply -f \u003cdirectory\u003e` against the saved files. *Note: Seccomp profiles currently only support saving to files.*\n\n## Usage\n\nThe plugin follows the standard `kubectl` command structure:\n\n```bash\nkubectl kguardian [command] [subcommand] [flags]\n```\n\n### Global Flags\n\nThese flags are available for most commands:\n\n- `--kubeconfig \u003cpath\u003e`: Path to the kubeconfig file to use.\n- `--context \u003cname\u003e`: The name of the kubeconfig context to use.\n- `--namespace \u003cname\u003e`, `-n \u003cname\u003e`: The namespace scope for this CLI request.\n- `--debug`: Enable debug logging.\n\n### Generate Resources (`gen`)\n\nThis is the main command group for generating security resources.\n\n#### Network Policies (`networkpolicy`, `netpol`)\n\nGenerates Kubernetes or Cilium Network Policies based on observed traffic.\n\n**Usage:**\n\n```bash\nkubectl kguardian gen networkpolicy [pod-name] [flags]\n```\n\n**Arguments:**\n\n- `[pod-name]` (Optional): The name of the specific pod to generate a policy for. Required unless `-a` or `-A` is used.\n\n**Flags:**\n\n- `-n, --namespace \u003cstring\u003e`: Namespace scope (defaults to current context namespace if not `-A`).\n- `-a, --all`: Generate policies for all pods in the specified/current namespace.\n- `-A, --all-namespaces`: Generate policies for all pods in all namespaces.\n- `-t, --type \u003cstring\u003e`: Type of policy: `kubernetes` (default) or `cilium`.\n- `--output-dir \u003cstring\u003e`: Directory to save generated policies (default: `network-policies`). If empty, policies are only printed in dry-run mode.\n- `--dry-run`: If true (default), generate policies and save/print them without applying to the cluster. Set to `false` to apply Kubernetes policies directly.\n\n**Examples:**\n\n```bash\n# Generate Kubernetes policy for 'my-app-pod' in 'prod' namespace (dry-run, save to ./netpols)\nkubectl kguardian gen networkpolicy my-app-pod -n prod --output-dir ./netpols\n\n# Generate Cilium policies for all pods in 'dev' namespace (dry-run, save to ./cilium-pols)\nkubectl kguardian gen netpol --all -n dev --type cilium --output-dir ./cilium-pols\n\n# Generate and APPLY Kubernetes policies for all pods in all namespaces (save to default dir)\nkubectl kguardian gen netpol -A --dry-run=false\n\n# Generate Kubernetes policy for 'my-pod' (dry-run, print to stdout only)\nkubectl kguardian gen netpol my-pod --output-dir=\"\"\n```\n\n#### Seccomp Profiles (`seccomp`, `secp`)\n\nGenerates Seccomp profiles based on observed syscalls.\n\n**Usage:**\n\n```bash\nkubectl kguardian gen seccomp [pod-name] [flags]\n```\n\n**Arguments:**\n\n- `[pod-name]` (Optional): The name of the specific pod to generate a profile for. Required unless `-a` or `-A` is used.\n\n**Flags:**\n\n- `-n, --namespace \u003cstring\u003e`: Namespace scope (defaults to current context namespace if not `-A`).\n- `-a, --all`: Generate profiles for all pods in the specified/current namespace.\n- `-A, --all-namespaces`: Generate profiles for all pods in all namespaces.\n- `--output-dir \u003cstring\u003e`: Directory to save generated profiles (default: `seccomp-profiles`). *Required for seccomp.* `--default-action \u003cstring\u003e`: Default action for unlisted syscalls (default: `SCMP_ACT_ERRNO`). Options: `SCMP_ACT_ERRNO`, `SCMP_ACT_LOG`, `SCMP_ACT_KILL`.\n\n**Examples:**\n\n```bash\n# Generate seccomp profile for 'db-pod' in 'data' namespace (save to ./secp)\nkubectl kguardian gen seccomp db-pod -n data --output-dir ./secp\n\n# Generate seccomp profiles for all pods in 'staging' namespace (save to default dir)\nkubectl kguardian gen secp --all -n staging\n\n# Generate seccomp profiles for all pods in all namespaces, logging unlisted calls (save to ./all-secp)\nkubectl kguardian gen secp -A --default-action SCMP_ACT_LOG --output-dir ./all-secp\n```\n\n## Contributing\n\nContributions are welcome. Please read the [contributing guide](CONTRIBUTING.md) to get started.\n\nFor information on the release process and versioning strategy, see [RELEASES.md](RELEASES.md).\n\n## License\n\nThis project is licensed under the Business Source License 1.1 — see the [LICENSE](LICENSE) file for details.\n\n**Summary:**\n- **Free for:** Development, testing, evaluation, and non-production/non-commercial use\n- **Commercial use:** Requires a commercial license (contact the licensors)\n- **Converts to:** Apache License 2.0 on January 1, 2029\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkguardian-dev%2Fkguardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkguardian-dev%2Fkguardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkguardian-dev%2Fkguardian/lists"}