{"id":22930762,"url":"https://github.com/kubewarden/audit-scanner","last_synced_at":"2025-08-12T15:31:56.224Z","repository":{"id":65947210,"uuid":"554050550","full_name":"kubewarden/audit-scanner","owner":"kubewarden","description":"Reports evaluation of existing Kubernetes resources with your already deployed Kubewarden policies.","archived":false,"fork":false,"pushed_at":"2025-08-12T08:26:01.000Z","size":1642,"stargazers_count":8,"open_issues_count":9,"forks_count":9,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-08-12T10:23:23.849Z","etag":null,"topics":["hacktoberfest","kubernetes","kubernetes-security","policy-as-code","webassembly"],"latest_commit_sha":null,"homepage":"https://kubewarden.io","language":"Go","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-INSIGHTS.yml","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-19T07:04:40.000Z","updated_at":"2025-08-12T08:25:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"e8e82414-78d6-40ea-926d-f03982d1c8d3","html_url":"https://github.com/kubewarden/audit-scanner","commit_stats":null,"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/kubewarden/audit-scanner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Faudit-scanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Faudit-scanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Faudit-scanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Faudit-scanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubewarden","download_url":"https://codeload.github.com/kubewarden/audit-scanner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubewarden%2Faudit-scanner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270086760,"owners_count":24524636,"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","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"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":["hacktoberfest","kubernetes","kubernetes-security","policy-as-code","webassembly"],"created_at":"2024-12-14T10:29:41.923Z","updated_at":"2025-08-12T15:31:55.927Z","avatar_url":"https://github.com/kubewarden.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Audit scanner\n\n[![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[![Artifact HUB](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/kubewarden-controller)](https://artifacthub.io/packages/helm/kubewarden/kubewarden-controller)\n[![codecov](https://codecov.io/gh/kubewarden/audit-scanner/graph/badge.svg?token=EDPPGWJFSK)](https://codecov.io/gh/kubewarden/audit-scanner)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/7439/badge)](https://www.bestpractices.dev/projects/7439)\n[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B25850%2Fgithub.com%2Fkubewarden%2Faudit-scanner.svg?type=shield\u0026issueType=license)](https://app.fossa.com/projects/custom%2B25850%2Fgithub.com%2Fkubewarden%2Faudit-scanner?ref=badge_shield\u0026issueType=license)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/kubewarden/audit-scanner/badge)](https://scorecard.dev/viewer/?uri=github.com/kubewarden/audit-scanner)\n\n\u003e **Note well:** don't forget to checkout [Kubewarden's Audit Scanner documentation](https://docs.kubewarden.io/explanations/audit-scanner)\n\u003e for more information\n\nThe Audit scanner inspects the resources defined in the cluster and\nidentifies the ones that are violating Kubewarden policies.\n\nThe results of the scan are stored in `PolicyReport` and `ClusterPolicyReports` custom resources.\nEach resource has its own dedicated `PolicyReport` or `ClusterPolicyReport`, depending on the type of the resource.\n\nSee [Querying the reports](#querying-the-reports) for more information.\n\n# Usage\n\n```console\naudit-scanner [flags]\n\nFlags:\n  -c, --cluster                       scan cluster wide resources\n      --disable-store                 disable storing the results in the k8s cluster\n  -f, --extra-ca string               File path to CA cert in PEM format of PolicyServer endpoints\n  -h, --help                          help for audit-scanner\n  -i, --ignore-namespaces strings     comma separated list of namespace names to be skipped from scan. This flag can be repeated\n      --insecure-ssl                  skip SSL cert validation when connecting to PolicyServers endpoints. Useful for development\n  -k, --kubewarden-namespace string   namespace where the Kubewarden components (e.g. PolicyServer) are installed (required) (default \"kubewarden\")\n  -l, --loglevel string               level of the logs. Supported values are: [trace debug info warn error fatal] (default \"info\")\n  -n, --namespace string              namespace to be evaluated\n  -o, --output-scan                   print result of scan in JSON to stdout\n      --page-size int                 number of resources to fetch from the Kubernetes API server when paginating (default 100)\n      --parallel-namespaces int       number of Namespaces to scan in parallel (default 1)\n      --parallel-policies int         number of policies to evaluate for a given resource in parallel (default 5)\n      --parallel-resources int        number of resources to scan in parallel (default 100)\n  -u, --policy-server-url string      URI to the PolicyServers the Audit Scanner will query. Example: https://localhost:3000. Useful for out-of-cluster debugging\n```\n\n## Examples\n\nScan the whole cluster:\n\n```shell\naudit-scanner  --kubewarden-namespace kubewarden --cluster\n```\n\nScan a single namespace:\n\n```shell\naudit-scanner  --kubewarden-namespace kubewarden --namespace default\n```\n\nDisable storing the results in etcd and print the reports to stdout in JSON format:\n\n```shell\naudit-scanner  --kubewarden-namespace kubewarden --disable-store --output-scan\n```\n\n## Tuning\n\nThe audit scanner works by entering each Namespace of the cluster and finding all the policies that are \"looking\" at the contents of the Namespace.\nIt then identifies all the resource types that are relevant to these policies (e.g. Deployments, Pods, etc.) and iterates over each resource type.\n\nWhen looking into a specific type of resource, audit-scanner fetches these objects in chunks. The size of the chunk can be set using the `--page-size` flag.\nThe scanner fetches one chunk of resources, then iterates over each one of them, evaluating all the policies that are looking at that specific resource.\n\nEach iteration step can be done in parallel. The number of Namespaces to be evaluated at the same time can be set using the `--parallel-namespaces` flag.\nThe number of resources to be evaluated at the same time can be set using the `--parallel-resources` flag.\nWhen evaluating the policies for a specific resource, the number of policies to be evaluated at the same time can be set using the `--parallel-policies` flag.\n\nA concrete example:\n\n- We have 5 namespaces, each with 1000 Pods.\n- We have 10 `ClusterAdmissionPolicy` resources that are looking at Pods.\n- We have set `--page-size=200`, `--parallel-namespaces=2`, `--parallel-resources=100`, and `--parallel-policies=5`.\n\nThe scanner will:\n\n- Work on 2 Namespaces at the same time.\n- Inside of each Namespace:\n  - Fetch 200 Pods at the same time (`--page-size=200`).\n  - Evaluate 100 Pods at the same time (`--parallel-resources=100`).\n  - Evaluate 5 policies at the same time (`--parallel-policies=5`).\n\nThings to consider:\n\n- The pagination size has a direct impact on\n  - The number of API calls that the scanner will make.\n  - The amount of memory that the scanner will use.\n- The maximum number of outgoing evaluation requests is the product of `--parallel-namespaces`, `--parallel-resources`, and `--parallel-policies`.\n\n# Querying the reports\n\nUsing the `kubectl` command line tool, you can query the results of the scan:\n\nList the reports in the default namespace:\n\n```console\n$ kubectl get polr -o wide\n\nNAME                                   KIND         NAME                        PASS   FAIL   WARN   ERROR   SKIP   AGE\n009805e4-6e16-4b70-80c9-cb33b6734c82   Deployment   deployment1                 5      1      0      0       0      1h\n011e8ca7-40d5-4e76-8c89-6f820e24f895   Deployment   deployment2                 2      4      0      0       0      1h\n02c28ab7-e332-47a2-9cc2-fe0fad5cd9ad   Pod          pod1                        10     0      0      0       0      1h\n04937b2b-e68b-47d5-909d-d0ae75527f07   Pod          pod2                        9      1      0      0       0      1h\n...\n```\n\nList the cluster-wide reports:\n\n```console\n$ kubectl get cpolr -o wide\n\nNAME                                   KIND        NAME                 PASS   FAIL   WARN   ERROR   SKIP   AGE\n261c9492-deec-4a09-8aa9-cd464bb4b8d1   Namespace   namespace1           3      1     0       0       0      1h\n35ca342f-685b-4162-a342-8d7a52a61749   Namespace   namespace2           0      4     0       0       0      1h\n3a8f8a88-338b-4905-b9e4-f13397a0d7b5   Namespace   namespace3           4      0     0       0       0      15h\n```\n\nGet the details of a specific report:\n\n```console\n$ kubectl get polr 009805e4-6e16-4b70-80c9-cb33b6734c82 -o yaml\n```\n\nResult:\n\n```yaml\napiVersion: wgpolicyk8s.io/v1beta1\nkind: PolicyReport\nmetadata:\n  creationTimestamp: \"2024-02-29T06:55:37Z\"\n  generation: 6\n  labels:\n    app.kubernetes.io/managed-by: kubewarden\n  name: 009805e4-6e16-4b70-80c9-cb33b6734c82\n  namespace: default\n  ownerReferences:\n    - apiVersion: apps/v1\n      kind: Deployment\n      name: deployment1\n      uid: 009805e4-6e16-4b70-80c9-cb33b6734c82\n  resourceVersion: \"2685996\"\n  uid: c5a88847-d678-4733-8120-1b83fd6330cb\nresults:\n  - category: Resource validation\n    message: \"The following mandatory labels are missing: cost-center\"\n    policy: clusterwide-safe-labels\n    properties:\n      policy-resource-version: \"2684810\"\n      policy-uid: 826dd4ef-9db5-408e-9482-455f278bf9bf\n      policy-name: safe-labels\n      validating: \"true\"\n    resourceSelector: {}\n    result: fail\n    scored: true\n    severity: low\n    source: kubewarden\n    timestamp:\n      nanos: 0\n      seconds: 1709294251\n# other results...\nscope:\n  apiVersion: apps/v1\n  kind: Deployment\n  name: deployment1\n  namespace: default\n  resourceVersion: \"3\"\n  uid: 009805e4-6e16-4b70-80c9-cb33b6734c82\nsummary:\n  error: 0\n  fail: 10\n  pass: 0\n  skip: 0\n  warn: 0\n```\n\n# Deployment\n\nThe Audit Scanner is deployed as a part of the [Kubewarden Controller helm chart](https://github.com/kubewarden/helm-charts).\nPlease refer to the [Kubewarden Controller documentation](https://docs.kubewarden.io/installation/installation) for more information.\n\n# Building\n\nYou can use the container image we maintain inside of our\n[GitHub Container Registry](https://github.com/orgs/kubewarden/packages/container/package/audit-scanner).\n\nAlternatively, the `audit-scanner` binary can be built in this way:\n\n```shell\nmake build\n```\n\nPlease refer [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to contribute to this project.\n\nFor implementation details, see [RFC-11](https://github.com/kubewarden/rfc/blob/main/rfc/0011-audit-checks.md),\n[RFC-12](https://github.com/kubewarden/rfc/blob/main/rfc/0012-policy-report.md).\n\n# Software bill of materials\n\nAudit scanner has its software bill of materials (SBOM\n[SPDX](https://spdx.dev/)) and\n[Provenance](https://slsa.dev/spec/v1.0/provenance) files published every\nrelease. Both files are generated by [Docker\nbuildx](https://docs.docker.com/build/metadata/attestations/) during the build\nprocess and stored in the container registry together with the container image\nas well as uploaded to the release page. \n\nAfter the container image building, the container image and their attestations\nare signed using cosign. The attestation files are stored inside a tarball with\nthe checksum file with the sha256sum for the files there. Therefore, after\ndownloading the attestation files from the [release\npage](https://github.com/kubewarden/audit-scanner/releases), extracting them,\nyou can verify the checksum file signature using the following command:\n\n```shell\ncosign verify-blob --certificate-oidc-issuer=https://token.actions.githubusercontent.com \\\n    --certificate-identity=\"https://github.com/kubewarden/audit-scanner/.github/workflows/attestation.yml@refs/tags/v1.17.0\" \\\n    --bundle audit-scanner-attestation-arm64-checksum-cosign.bundle \\\n    audit-scanner-attestation-arm64-checksum.txt\n```\n\nIf you want to verify the attestation manifest and its layer signatures, you\ncan use the following command:\n\n```shell\ncosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com  \\\n    --certificate-identity=\"https://github.com/kubewarden/audit-scanner/.github/workflows/attestation.yml@refs/tags/v1.17.0 \\\n    ghcr.io/kubewarden/audit-scanner@sha256:1abc0944378d9f3ee2963123fe84d045248d320d76325f4c2d4eb201304d4c4e\n```\n\nRemember that the sha256 hash is the digest of the attestation manifest or its\nlayers. Therefore, you need to find this info in the registry using the UI or\ntools like `crane`. For example, the following command will show you all the\nattestation manifests of the `latest` tag:\n\n```shell\ncrane manifest  ghcr.io/kubewarden/audit-scanner:latest | jq '.manifests[] | select(.annotations[\"vnd.docker.reference.type\"]==\"attestation-manifest\")'\n{\n  \"mediaType\": \"application/vnd.oci.image.manifest.v1+json\",\n  \"digest\": \"sha256:fc01fa6c82cffeffd23b737c7e6b153357d1e499295818dad0c7d207f64e6ee8\",\n  \"size\": 1655,\n  \"annotations\": {\n    \"vnd.docker.reference.digest\": \"sha256:611d499ec9a26034463f09fa4af4efe2856086252d233b38e3fc31b0b982d369\",\n    \"vnd.docker.reference.type\": \"attestation-manifest\"\n  },\n  \"platform\": {\n    \"architecture\": \"unknown\",\n    \"os\": \"unknown\"\n  }\n}\n{\n  \"mediaType\": \"application/vnd.oci.image.manifest.v1+json\",\n  \"digest\": \"sha256:e0cd736c2241407114256e09a4cdeef55eb81dcd374c5785c4e5c9362a0088a2\",\n  \"size\": 1655,\n  \"annotations\": {\n    \"vnd.docker.reference.digest\": \"sha256:03e5db83a25ea2ac498cf81226ab8db8eb53a74a2c9102e4a1da922d5f68b70f\",\n    \"vnd.docker.reference.type\": \"attestation-manifest\"\n  },\n  \"platform\": {\n    \"architecture\": \"unknown\",\n    \"os\": \"unknown\"\n  }\n}\n```\n\nThen you can use the `digest` field to verify the attestation manifest and its\nlayers signatures.\n\n```shell\ncosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com  \\\n    --certificate-identity=\"https://github.com/kubewarden/audit-scanner/.github/workflows/attestation.yml@refs/tags/v1.17.0 \\\n    ghcr.io/kubewarden/audit-scanner@sha256:fc01fa6c82cffeffd23b737c7e6b153357d1e499295818dad0c7d207f64e6ee8\n\ncrane manifest  ghcr.io/kubewarden/audit-scanner@sha256:fc01fa6c82cffeffd23b737c7e6b153357d1e499295818dad0c7d207f64e6ee8\n{\n  \"schemaVersion\": 2,\n  \"mediaType\": \"application/vnd.oci.image.manifest.v1+json\",\n  \"config\": {\n    \"mediaType\": \"application/vnd.oci.image.config.v1+json\",\n    \"digest\": \"sha256:eda788a0e94041a443eca7286a9ef7fce40aa2832263f7d76c597186f5887f6a\",\n    \"size\": 463\n  },\n  \"layers\": [\n    {\n      \"mediaType\": \"application/vnd.in-toto+json\",\n      \"digest\": \"sha256:563689cdee407ab514d057fe2f8f693189279e10bfe4f31f277e24dee00793ea\",\n      \"size\": 94849,\n      \"annotations\": {\n        \"in-toto.io/predicate-type\": \"https://spdx.dev/Document\"\n      }\n    },\n    {\n      \"mediaType\": \"application/vnd.in-toto+json\",\n      \"digest\": \"sha256:7ce0572628290373e17ba0bbb44a9ec3c94ba36034124931d322ca3fbfb768d9\",\n      \"size\": 7363045,\n      \"annotations\": {\n        \"in-toto.io/predicate-type\": \"https://spdx.dev/Document\"\n      }\n    },\n    {\n      \"mediaType\": \"application/vnd.in-toto+json\",\n      \"digest\": \"sha256:dacf511c5ec7fd87e8692bd08c3ced2c46f4da72e7271b82f1b3720d5b0a8877\",\n      \"size\": 71331,\n      \"annotations\": {\n        \"in-toto.io/predicate-type\": \"https://spdx.dev/Document\"\n      }\n    },\n    {\n      \"mediaType\": \"application/vnd.in-toto+json\",\n      \"digest\": \"sha256:594da3e8bd8c6ee2682b0db35857933f9558fd98ec092344a6c1e31398082f4d\",\n      \"size\": 980,\n      \"annotations\": {\n        \"in-toto.io/predicate-type\": \"https://spdx.dev/Document\"\n      }\n    },\n    {\n      \"mediaType\": \"application/vnd.in-toto+json\",\n      \"digest\": \"sha256:7738d8d506c6482aaaef1d22ed920468ffaf4975afd28f49bb50dba2c20bf2ca\",\n      \"size\": 13838,\n      \"annotations\": {\n        \"in-toto.io/predicate-type\": \"https://slsa.dev/provenance/v0.2\"\n      }\n    }\n  ]\n}\n\ncosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com  \\\n    --certificate-identity=\"https://github.com/kubewarden/audit-scanner/.github/workflows/attestation.yml@refs/tags/v1.17.0 \\\n    ghcr.io/kubewarden/audit-scanner@sha256:594da3e8bd8c6ee2682b0db35857933f9558fd98ec092344a6c1e31398082f4d\n```\n\nNote that each attestation manifest (for each architecture) has its own layers.\nEach layer is a different SBOM SPDX or provenance files generated by Docker\nBuildx during the multi stage build process. You can also use `crane` to\ndownload the attestation file:\n\n```shell\ncrane blob ghcr.io/kubewarden/audit-scanner@sha256:7738d8d506c6482aaaef1d22ed920468ffaf4975afd28f49bb50dba2c20bf2ca\n```\n\n# Security\n\nThe Kubewarden team is security conscious. You can find our [threat model\nassessment](https://docs.kubewarden.io/security/threat-model) and\n[responsible disclosure approach](https://docs.kubewarden.io/security/disclosure)\nin our Kubewarden docs.\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/audit-scanner/releases).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubewarden%2Faudit-scanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubewarden%2Faudit-scanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubewarden%2Faudit-scanner/lists"}