{"id":22828308,"url":"https://github.com/kubewarden/kwctl","last_synced_at":"2025-08-12T15:31:59.556Z","repository":{"id":36985446,"uuid":"360471642","full_name":"kubewarden/kwctl","owner":"kubewarden","description":"Go-to CLI tool for Kubewarden users","archived":false,"fork":false,"pushed_at":"2024-04-12T12:49:59.000Z","size":2704,"stargazers_count":69,"open_issues_count":14,"forks_count":15,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-12T20:19:11.489Z","etag":null,"topics":["hacktoberfest","kubernetes","kubernetes-security","policy-as-code","webassembly"],"latest_commit_sha":null,"homepage":"https://kubewarden.io","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubewarden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-04-22T09:57:11.000Z","updated_at":"2024-04-15T09:38:54.840Z","dependencies_parsed_at":"2023-10-02T02:23:02.735Z","dependency_job_id":"85148fc0-e6b1-4405-83ac-6abc7d1b81a4","html_url":"https://github.com/kubewarden/kwctl","commit_stats":null,"previous_names":[],"tags_count":106,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Fkwctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Fkwctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Fkwctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Fkwctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubewarden","download_url":"https://codeload.github.com/kubewarden/kwctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229694588,"owners_count":18108931,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["hacktoberfest","kubernetes","kubernetes-security","policy-as-code","webassembly"],"created_at":"2024-12-12T19:01:18.845Z","updated_at":"2025-08-12T15:31:59.530Z","avatar_url":"https://github.com/kubewarden.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"[![Kubewarden Core Repository](https://github.com/kubewarden/community/blob/main/badges/kubewarden-core.svg)](https://github.com/kubewarden/community/blob/main/REPOSITORIES.md#core-scope)\n[![Stable](https://img.shields.io/badge/status-stable-brightgreen?style=for-the-badge)](https://github.com/kubewarden/community/blob/main/REPOSITORIES.md#stable)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9180/badge)](https://www.bestpractices.dev/projects/9180)\n[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B25850%2Fgithub.com%2Fkubewarden%2Fkwctl.svg?type=shield)](https://app.fossa.com/projects/cjustom%2B25850%2Fgithub.com%2Fkubewarden%2Fkwctl?ref=badge_shield)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/kubewarden/kwctl/badge)](https://scorecard.dev/viewer/?uri=github.com/kubewarden/kwctl)\n\n# `kwctl`\n\n`kwctl` is the go-to CLI tool for [Kubewarden](https://kubewarden.io)\nusers.\n\nThink of it as the `docker` CLI tool if you were working with\ncontainers.\n\n## How does `kwctl` help me?\n\n### As a policy author\n\n- e2e testing of your policy. Test your policy against crafted\n  Kubernetes requests, and ensure your policy behaves as you\n  expect. You can even test context-aware policies, that require\n  access to a running cluster.\n\n- Embed metadata in your Wasm module, so the binary is annotated with\n  the permissions it needs to execute.\n\n- Publish policies to OCI registries.\n\n- Generate initial `ClusterAdmissionPolicy` scaffolding for your\n  policy.\n\n### As a cluster administrator\n\n- Inspect remote policies. Given a policy in an OCI registry, or in an\n  HTTP server, show all static information about the policy.\n\n- Dry-run of a policy in your cluster. Test the policy against crafted\n  Kubernetes requests, and ensure the policy behaves as you expect\n  given the input data you provide. You can even test context-aware\n  policies, that require access to a running cluster, also in a\n  dry-run mode.\n\n- Generate `ClusterAdmissionPolicy` scaffolding for a given policy.\n\n### Everyone\n\n- The UX of this tool is intended to be as easy and intuitive as\n  possible.\n\n## Install\n\nBuilt binaries for `Linux x86_64`, `Windows x86_64`, `MacOS x86_64` and `MacOS\naarch64 (M1)` are available in [GH Releases](https://github.com/kubewarden/kwctl/releases).\n\nThere is also:\n\n- Community-created [Homebrew 🍺 formula for kwctl](https://formulae.brew.sh/formula/kwctl)\n- Community-created [AUR 🐧 package](https://aur.archlinux.org/packages/kwctl-bin)\n\n## Usage\n\nThese are the commands currently supported by kwctl.\n\nIf you want a complete list of the available commands, you can read the\n[cli-docs.md](./cli-docs.md) file.\n\n### List policies\n\nThe list of policies downloaded on the local machine can be\nobtained by doing:\n\n```console\nkwctl policies\n```\n\n### Download policies\n\nPolicies can be downloaded using the `pull` command.\n\nThe name of the policy must be expressed as a url with one of the\nfollowing protocols:\n\n- `http://`: pull from a HTTP server\n- `https://`: pull from a HTTPS server\n- `registry://`: pull from an OCI registry\n\nPulling from a registry, by tag:\n\n```console\nkwctl pull registry://ghcr.io/kubewarden/policies/psp-capabilities:latest\n```\n\nIt's possible to pull from a registry using an immutable reference (in the\nsame way as with regular container images):\n\n```console\nkwctl pull registry://ghcr.io/kubewarden/policies/psp-capabilities@sha256:61ef63621fa5be8e422881d96d05edfef810992fbf9468e35d1fa5ae815bd97c\n```\n\nNote well, the shasum is the digest of the OCI artifact containing the policy.\nThis value can be obtained using a tool like [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md):\n\n```console\ncrane digest ghcr.io/kubewarden/policies/psp-capabilities:v0.1.6\n```\n\n### Run\n\n`kwctl` can be used to run a policy locally, outside of Kubernetes. This can be used\nto quickly evaluate a policy and find the right settings for it.\n\nThe evaluation is done against a pre-recorded [`AdmissionReview`](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#request).\n\n\u003e **Note:** it's possible to scaffodl an `AdmissionReview` object from a Kubernetes resource.\n\u003e Take a look at [this section](#scaffold-kubernetes-custom-resources) for more details.\n\n#### Run a local policy\n\nTo run a local `.wasm` file containing a policy:\n\n```console\nkwctl run \\\n  --settings-json '{\"constrained_labels\": {\"owner\": \".*\"}}' \\\n  -r test_data/ingress.json \\\n  registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.5\n```\n\nPolicy configuration can be passed on the CLI via the `--settings-json` flag\nor can be loaded from the disk via the `--settings-path` flag.\n\n#### Run a policy defined by a Kubewarden Custom Resource\n\nTo run a local YAML file containing the definition of any of the Kubewarden Custom\nResources:\n\n```console\nkwctl run \\\n  -r test_data/ingress.json \\\n  policy.yaml\n```\n\nThe YAML file can contain any of the Kubewarden CRDs, including policy groups.\n\n**Warning:** kwctl considers only these attributes of the CRD:\n\n- policy module to be evaluated\n- policy settings\n- context aware resources\n\nAll the other fields are ignored. For example, `rules`, `matchConditions`, `objectSelector`,\n`namespaceSelector` and other fields are not taken into account.\n\nMoreover, the YAML file could contain multiple declarations of Kubewarden Custom Resources. In this case\nkwctl will evaluate each policy found inside of the YAML file. However, the same request is going to be used\nduring each evaluation.\n\n### [Scaffold AdmissionReview from a Kubernetes resource](#scaffold-admissionreview-from-a-kubernetes-resource)\n\nIt's possible to scaffold an `AdmissionReview` object from a Kubernetes resource:\n\n```console\nkwctl scaffold \\\n  admission-request \\\n  --operation CREATE \\\n  --object ingress.yaml\n```\n\nThe output of the above command can be used by the `run` command.\n\n### Annotate a policy\n\nKubewarden policies are WebAssembly module, which must contain some\nKubewarden-specific metadata.\n\nThe act of adding metadata to the policy is done by the policy author, right\nbefore policy distribution.\n\nThe `kwctl annotate` command can be used to perform this operation.\n\n### Inspect a policy\n\nThe metadata attached to a policy, plus other details can be seen via the\n`kwctl inspect` command.\n\nThis command works against a policy that has been previously downloaded.\n\n### Publish a policy\n\n`kwctl` can be used to publish a local policy into an OCI registry. This is done\nvia the `push` sub-command.\n\nThe `push` sub-command can also be used to copy a policy into another registry:\n\n```console\nkwctl push registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.5 \\\n  registry://registry.local.lan/kubewarden/safe-labels:v0.1.5\n```\n\nThe above command copies a local policy that was downloaded from the GitHub\nContainer Registry, into a local registry.\n\n\u003e **Note well:** the policy must be previously downloaded locally via `kwctl pull`\n\n### Remove a local policy\n\nLocal policies can be removed via the `rm` sub-command:\n\n```console\nkwctl rm \u003cname of the policy\u003e\n```\n\n### Scaffold Kubernetes Custom Resources\n\nKubewarden policies are enforced on Kubernetes clusters by using\nspecial Custom Resources provided by our [Kubernetes integration](https://docs.kubewarden.io/quick-start.html#kubewarden-policies).\n\nThe `manifest` sub-command can be used to quickly scaffold the definition of\nKubewarden Custom Resources.\n\nThe manifest command shares some of the arguments of the `run` command, it's\ntypical to test a policy locally via the `kwctl run` command and then, once\nsatisfied about the policy settings, create a deployment manifest for it via\nthe `manifest` command.\n\nStep #1, find the right policy settings:\n\n```console\nkwctl run \\\n  --settings-json '{\"constrained_labels\": {\"owner\": \".*\"}}' \\\n  -r test_data/ingress.json \\\n  registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.5\n```\n\nStep #2, generate a manifest to enforce the policy inside of a\nKubernetes cluster:\n\n```console\nkwctl manifest\\\n  --settings-json '{\"constrained_labels\": {\"owner\": \".*\"}}' \\\n  -t ClusterAdmissionPolicy \\\n  registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.5\n```\n\nThis will produce the following output:\n\n```yaml\n---\napiVersion: policies.kubewarden.io/v1\nkind: ClusterAdmissionPolicy\nmetadata:\n  name: generated-policy\nspec:\n  module: \"registry://ghcr.io/kubewarden/policies/safe-labels:v0.1.5\"\n  settings:\n    constrained_labels:\n      owner: \".*\"\n  rules:\n    - apiGroups:\n        - \"*\"\n      apiVersions:\n        - \"*\"\n      resources:\n        - \"*\"\n      operations:\n        - CREATE\n        - UPDATE\n  mutating: false\n```\n\nWhich can then be customized by hand, and then applied into a Kubernetes cluster.\n\n### Shell completion\n\n`kwctl` can generate autocompletion scripts for the following shells:\n\n- bash\n- elvish\n- fish\n- powershell\n- zsh\n\nThe completion script can be generated with the following command:\n\n```console\n$ kwctl completions -s \u003cSHELL\u003e\n```\n\nThe command will print to the stdout the completion script.\n\n#### Bash\n\nTo load completions in your current shell session:\n\n```console\n$ source \u003c(kwctl completions -s bash)\n```\n\nTo load completions for every new session, execute once:\n\n- Linux: `$ kwctl completions -s bash \u003e /etc/bash_completion.d/kwctl`\n- MacOS: `$ kwctl completions -s bash \u003e /usr/local/etc/bash_completion.d/kwctl`\n\nYou will need to start a new shell for this setup to take effect.\n\n#### Fish\n\nTo load completions in your current shell session:\n\n```console\n$ kwctl completions -s fish | source\n```\n\nTo load completions for every new session, execute once:\n\n```console\n$ kwctl completions -s fish \u003e ~/.config/fish/completions/kwctl.fish\n```\n\nYou will need to start a new shell for this setup to take effect.\n\n#### Zsh\n\nTo load completions in your current shell session:\n\n```console\n$ source \u003c(kwctl completions -s zsh)\n```\n\nTo load completions for every new session, execute once:\n\n```console\n$ kwctl completions -s zsh \u003e \"${fpath[1]}/_kwctl\"\n```\n\n##### Oh My Zsh users\n\nThese steps are required by [oh-my-zsh](https://ohmyz.sh/) users:\n\n```console\n$ print -l $fpath | grep '.oh-my-zsh/completions'\n$ mkdir ~/.oh-my-zsh/completions\n$ kwctl completions -s zsh \u003e ~/.oh-my-zsh/completions/_kwctl\nrm ~/.zcompdump*\n```\n\nThen start a new shell or run `source ~/.zshrc` once.\n\n## Verify kwctl binaries\n\nkwctl binaries are signed using [Sigstore's blog signing](https://docs.sigstore.dev/signing/signing_with_blobs/).\nWhen you download a [kwctl release](https://github.com/kubewarden/kwctl/releases/) each zip file contains two\nfiles that can be used for verification: `kwctl.sig` and `kwctl.pem`.\n\nIn order to verify kwctl you need cosign installed, and then execute the following command:\n\n```\ncosign verify-blob \\\n  --signature kwctl-linux-x86_64.sig \\\n  --cert kwctl-linux-x86_64.pem kwctl-linux-x86_64 \\\n  --certificate-identity-regexp 'https://github.com/kubewarden/*' \\\n  --certificate-oidc-issuer https://token.actions.githubusercontent.com\n```\n\nThe output should be:\n\n```\nVerified OK\n```\n\n# Software bill of materials \u0026 provenance\n\nKwctl has its software bill of materials (SBOM) published every release. They\nfollow the [SPDX](https://spdx.dev/) format, you can find them together with\nthe signature and certificate used to sign it in the [releases\nassets](https://github.com/kubewarden/kwctl/releases).\n\nThe build [Provenance](https://slsa.dev/spec/v1.0/provenance) files are\nfollowing the [SLSA](https://slsa.dev/provenance/v0.2#schema) provenance schema\nand are accessible at the GitHub Actions'\n[provenance](https://github.com/kubewarden/kwctl/attestations) tab. For\ninformation on their format and how to verify them, see the [GitHub\ndocumentation](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/verifying-attestations-offline).\n\n## Security disclosure\n\nSee [SECURITY.md](https://github.com/kubewarden/community/blob/main/SECURITY.md) on the kubewarden/community repo.\n\n## Changelog\n\nSee [GitHub Releases content](https://github.com/kubewarden/kwctl/releases).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubewarden%2Fkwctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubewarden%2Fkwctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubewarden%2Fkwctl/lists"}