Skip to content

Commit 88b55bc

Browse files
JimBugwadiaJimBugwadia
authored
Merge pull request #2 from jvanz/adding-api-files
Migrating the Reports API from Kubernetes working group
2 parents 5e8ee92 + b566d3e commit 88b55bc

File tree

115 files changed

+14800
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

115 files changed

+14800
-0
lines changed

‎go.mod

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
module sigs.k8s.io/wg-policy-prototypes
2+
3+
go 1.22.0
4+
5+
toolchain go1.22.1
6+
7+
require (
8+
k8s.io/api v0.29.3
9+
k8s.io/apimachinery v0.30.0-rc.2
10+
k8s.io/client-go v0.29.3
11+
k8s.io/code-generator v0.30.0-rc.2
12+
sigs.k8s.io/controller-runtime v0.16.3
13+
)
14+
15+
require (
16+
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
17+
github.com/emicklei/go-restful/v3 v3.11.0 // indirect
18+
github.com/evanphx/json-patch v5.7.0+incompatible // indirect
19+
github.com/go-logr/logr v1.4.1 // indirect
20+
github.com/go-openapi/jsonpointer v0.20.0 // indirect
21+
github.com/go-openapi/jsonreference v0.20.2 // indirect
22+
github.com/go-openapi/swag v0.22.4 // indirect
23+
github.com/gogo/protobuf v1.3.2 // indirect
24+
github.com/golang/protobuf v1.5.4 // indirect
25+
github.com/google/gnostic-models v0.6.9-0.20230804172637-c7be7c783f49 // indirect
26+
github.com/google/go-cmp v0.6.0 // indirect
27+
github.com/google/gofuzz v1.2.0 // indirect
28+
github.com/google/pprof v0.0.0-20231023181126-ff6d637d2a7b // indirect
29+
github.com/google/uuid v1.6.0 // indirect
30+
github.com/josharian/intern v1.0.0 // indirect
31+
github.com/json-iterator/go v1.1.12 // indirect
32+
github.com/mailru/easyjson v0.7.7 // indirect
33+
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
34+
github.com/modern-go/reflect2 v1.0.2 // indirect
35+
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
36+
github.com/pkg/errors v0.9.1 // indirect
37+
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
38+
github.com/spf13/pflag v1.0.5 // indirect
39+
github.com/stretchr/testify v1.9.0 // indirect
40+
golang.org/x/mod v0.17.0 // indirect
41+
golang.org/x/net v0.24.0 // indirect
42+
golang.org/x/oauth2 v0.14.0 // indirect
43+
golang.org/x/sync v0.7.0 // indirect
44+
golang.org/x/sys v0.19.0 // indirect
45+
golang.org/x/term v0.19.0 // indirect
46+
golang.org/x/text v0.14.0 // indirect
47+
golang.org/x/time v0.5.0 // indirect
48+
golang.org/x/tools v0.20.0 // indirect
49+
google.golang.org/appengine v1.6.8 // indirect
50+
google.golang.org/protobuf v1.33.0 // indirect
51+
gopkg.in/inf.v0 v0.9.1 // indirect
52+
gopkg.in/yaml.v2 v2.4.0 // indirect
53+
gopkg.in/yaml.v3 v3.0.1 // indirect
54+
k8s.io/gengo/v2 v2.0.0-20240228010128-51d4e06bde70 // indirect
55+
k8s.io/klog/v2 v2.120.1 // indirect
56+
k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 // indirect
57+
k8s.io/utils v0.0.0-20240310230437-4693a0247e57 // indirect
58+
sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
59+
sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
60+
sigs.k8s.io/yaml v1.4.0 // indirect
61+
)

‎go.sum

+185
Large diffs are not rendered by default.

‎policy-report/.gitignore

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
2+
# Binaries for programs and plugins
3+
*.exe
4+
*.exe~
5+
*.dll
6+
*.so
7+
*.dylib
8+
bin
9+
10+
# Test binary, build with `go test -c`
11+
*.test
12+
13+
# Output of the go coverage tool, specifically when used with LiteIDE
14+
*.out
15+
16+
# Kubernetes Generated files - skip generated files, except for vendored files
17+
18+
!vendor/**/zz_generated.*
19+
20+
# editor and IDE paraphernalia
21+
.idea
22+
*.swp
23+
*.swo
24+
*~

‎policy-report/Makefile

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
GO_CMD ?= go
2+
3+
PROJECT_DIR := $(shell dirname $(abspath $(lastword $(MAKEFILE_LIST))))
4+
5+
# Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set)
6+
ifeq (,$(shell go env GOBIN))
7+
GOBIN=$(shell go env GOPATH)/bin
8+
else
9+
GOBIN=$(shell go env GOBIN)
10+
endif
11+
12+
## Location to install dependencies to
13+
LOCALBIN ?= $(shell pwd)/bin
14+
$(LOCALBIN):
15+
mkdir -p $(LOCALBIN)
16+
17+
CONTROLLER_TOOLS_VERSION ?= v0.14.0
18+
CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
19+
GEN_CRD_API_REFERENCE_DOCS ?= $(LOCALBIN)/crd-ref-docs
20+
GEN_CRD_API_REFERENCE_DOCS_VERSION ?= latest
21+
22+
all: manifests generate generate-api-docs generate-client build fmt vet
23+
24+
.PHONY: manifests
25+
manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
26+
$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./apis/reports.x-k8s.io/v1beta2" output:crd:artifacts:config=crd/reports.x-k8s.io/v1beta2
27+
28+
.PHONY: generate
29+
generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
30+
$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./apis/..."
31+
32+
.PHONY: generate-client
33+
generate-client:
34+
./hack/update-codegen.sh
35+
36+
37+
# Run go build against code
38+
build:
39+
go build ./...
40+
41+
# Run go fmt against code
42+
fmt:
43+
go fmt ./...
44+
45+
# Run go vet against code
46+
vet:
47+
go vet ./...
48+
49+
.PHONY: controller-gen
50+
controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary. If wrong version is installed, it will be overwritten.
51+
$(CONTROLLER_GEN): $(LOCALBIN)
52+
test -s $(LOCALBIN)/controller-gen && $(LOCALBIN)/controller-gen --version | grep -q $(CONTROLLER_TOOLS_VERSION) || \
53+
GOBIN=$(LOCALBIN) $(GO_CMD) install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION)
54+
55+
# Use same code-generator version as k8s.io/api
56+
CODEGEN_VERSION := v0.30.0-rc.2
57+
CODEGEN = $(shell pwd)/bin/code-generator
58+
CODEGEN_ROOT = $(shell $(GO_CMD) env GOMODCACHE)/k8s.io/code-generator@$(CODEGEN_VERSION)
59+
.PHONY: code-generator
60+
code-generator:
61+
@GOBIN=$(PROJECT_DIR)/bin GO111MODULE=on $(GO_CMD) install k8s.io/code-generator/cmd/client-gen@$(CODEGEN_VERSION)
62+
cp -f $(CODEGEN_ROOT)/generate-groups.sh $(PROJECT_DIR)/bin/
63+
cp -f $(CODEGEN_ROOT)/generate-internal-groups.sh $(PROJECT_DIR)/bin/
64+
cp -f $(CODEGEN_ROOT)/kube_codegen.sh $(PROJECT_DIR)/bin/
65+
66+
# generate-api-docs will create api docs
67+
generate-api-docs: $(GEN_CRD_API_REFERENCE_DOCS)
68+
$(GEN_CRD_API_REFERENCE_DOCS) --source-path=./apis/reports.x-k8s.io/v1beta2 --config=./docs/config.yaml --renderer=markdown --output-path=./docs/api-docs.md
69+
70+
$(GEN_CRD_API_REFERENCE_DOCS): $(LOCALBIN)
71+
$(call go-install-tool,$(GEN_CRD_API_REFERENCE_DOCS),github.com/elastic/crd-ref-docs,$(GEN_CRD_API_REFERENCE_DOCS_VERSION))
72+
73+
.PHONY: codegen-api-docs
74+
codegen-api-docs: $(PACKAGE_SHIM) $(GEN_CRD_API_REFERENCE_DOCS) $(GENREF) ## Generate API docs
75+
@echo Generate api docs... >&2
76+
$(GEN_CRD_API_REFERENCE_DOCS) -v=4 \
77+
-api-dir pkg/api \
78+
-config docs/config.json \
79+
-template-dir docs/template \
80+
-out-file docs/index.html
81+
82+
# go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
83+
# $1 - target path with name of binary (ideally with version)
84+
# $2 - package url which can be installed
85+
# $3 - specific version of package
86+
define go-install-tool
87+
@[ -f $(1) ] || { \
88+
set -e; \
89+
package=$(2)@$(3) ;\
90+
echo "Downloading $${package}" ;\
91+
GOBIN=$(LOCALBIN) go install $${package} ;\
92+
mv "$$(echo "$(1)" | sed "s/-$(3)$$//")" $(1) ;\
93+
}
94+
endef

‎policy-report/README.md

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Report API
2+
3+
The Report API enables uniform reporting of results and findings from policy engines, scanners, or other tooling.
4+
5+
This repository contains the API specification and Custom Resource Definitions (CRDs).
6+
7+
## Concepts
8+
9+
The API provides a `ClusterReport` and its namespaced variant `Report`.
10+
11+
Each `Report` contains a set of `results` and a `summary`. Each `result` contains attributes such as the source policy and rule name, severity, timestamp, and the resource.
12+
13+
## Reference
14+
15+
* [API Reference](./docs/api-docs.md)
16+
17+
## Demonstration
18+
19+
Typically the Report API is installed and managed by a [producer](#producers). However, to try out the API in a test cluster you can follow the steps below:
20+
21+
1. Add Report API CRDs to your cluster (v1beta2):
22+
23+
```sh
24+
kubectl create -f crd/reports.x-k8s.io/v1beta2/
25+
```
26+
2. Create a sample policy report resource:
27+
28+
```sh
29+
kubectl create -f samples/sample-cis-k8s.yaml
30+
```
31+
3. View policy report resources:
32+
33+
```sh
34+
kubectl get reports
35+
```
36+
37+
## Implementations
38+
39+
The following is a list of projects that produce or consume policy reports:
40+
41+
*(To add your project, please create a [pull request](https://github.com/kubernetes-sigs/wg-policy-prototypes/pulls).)*
42+
43+
### Producers
44+
45+
* [Falco](https://github.com/falcosecurity/falcosidekick/blob/master/outputs/policyreport.go)
46+
* [Image Scanner](https://github.com/statnett/image-scanner-operator)
47+
* [jsPolicy](https://github.com/loft-sh/jspolicy/)
48+
* [Kyverno](https://kyverno.io/docs/policy-reports/)
49+
* [Netchecks](https://docs.netchecks.io/)
50+
* [Tracee Adapter](https://github.com/fjogeleit/tracee-polr-adapter)
51+
* [Trivy Operator](https://aquasecurity.github.io/trivy-operator/v0.15.1/tutorials/integrations/policy-reporter/)
52+
* [Kubewarden](https://docs.kubewarden.io/explanations/audit-scanner/policy-reports)
53+
54+
### Consumers
55+
56+
* [Fairwinds Insights](https://fairwinds.com/insights)
57+
* [Kyverno Policy Reporter](https://kyverno.github.io/policy-reporter/)
58+
* [Open Cluster Management](https://open-cluster-management.io/)
59+
60+
## Building
61+
62+
```sh
63+
make all
64+
```
65+
66+
## Community, discussion, contribution, and support
67+
68+
You can reach the maintainers of this project at:
69+
70+
- [Slack](https://kubernetes.slack.com/messages/wg-policy)
71+
- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-wg-policy)
72+
- [WG Policy](https://github.com/kubernetes/community/blob/master/wg-policy/README.md)
73+
74+
### Code of conduct
75+
76+
Participation in the OpenReport community is governed by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
77+
78+
[owners]: https://git.k8s.io/community/contributors/guide/owners.md
79+
[Creative Commons 4.0]: https://git.k8s.io/website/LICENSE
80+
81+
# Historical References
82+
83+
See the [Kubernetes policy working group](https://github.com/kubernetes-sigs/wg-policy-prototypes/tree/master) and the [proposal](https://docs.google.com/document/d/1nICYLkYS1RE3gJzuHOfHeAC25QIkFZfgymFjgOzMDVw/edit#) for background and details.
84+

‎policy-report/apis/reports.x-k8s.io/v1beta2/clusterpolicyreport_types.go

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
/*
2+
Copyright 2024 The Kubernetes authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package v1beta2
18+
19+
import (
20+
corev1 "k8s.io/api/core/v1"
21+
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
22+
)
23+
24+
// EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN!
25+
// NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized.
26+
27+
// +genclient
28+
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
29+
// +genclient:nonNamespaced
30+
// +kubebuilder:storageversion
31+
// +kubebuilder:object:root=true
32+
// +kubebuilder:resource:path=clusterreports,scope="Cluster",shortName=creps
33+
// +kubebuilder:printcolumn:name="Kind",type=string,JSONPath=`.scope.kind`,priority=1
34+
// +kubebuilder:printcolumn:name="Name",type=string,JSONPath=`.scope.name`,priority=1
35+
// +kubebuilder:printcolumn:name="Pass",type=integer,JSONPath=`.summary.pass`
36+
// +kubebuilder:printcolumn:name="Fail",type=integer,JSONPath=`.summary.fail`
37+
// +kubebuilder:printcolumn:name="Warn",type=integer,JSONPath=`.summary.warn`
38+
// +kubebuilder:printcolumn:name="Error",type=integer,JSONPath=`.summary.error`
39+
// +kubebuilder:printcolumn:name="Skip",type=integer,JSONPath=`.summary.skip`
40+
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
41+
42+
// ClusterReport is the Schema for the clusterpolicyreports API
43+
type ClusterReport struct {
44+
metav1.TypeMeta `json:",inline"`
45+
metav1.ObjectMeta `json:"metadata,omitempty"`
46+
47+
// Source is an identifier for the source e.g. a policy engine that manages this report.
48+
// Use this field if all the results are produced by a single policy engine.
49+
// If the results are produced by multiple sources e.g. different engines or scanners,
50+
// then use the Source field at the ReportResult level.
51+
// +optional
52+
Source string `json:"source"`
53+
54+
// Scope is an optional reference to the report scope (e.g. a Deployment, Namespace, or Node)
55+
// +optional
56+
Scope *corev1.ObjectReference `json:"scope,omitempty"`
57+
58+
// ScopeSelector is an optional selector for multiple scopes (e.g. Pods).
59+
// Either one of, or none of, but not both of, Scope or ScopeSelector should be specified.
60+
// +optional
61+
ScopeSelector *metav1.LabelSelector `json:"scopeSelector,omitempty"`
62+
63+
// Configuration is an optional field which can be used to specify
64+
// a contract between Report generators and consumers
65+
// +optional
66+
Configuration *ReportConfiguration `json:"configuration,omitempty"`
67+
68+
// ReportSummary provides a summary of results
69+
// +optional
70+
Summary ReportSummary `json:"summary,omitempty"`
71+
72+
// ReportResult provides result details
73+
// +optional
74+
Results []ReportResult `json:"results,omitempty"`
75+
}
76+
77+
// ClusterReportList contains a list of ClusterReport
78+
// +kubebuilder:object:root=true
79+
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
80+
type ClusterReportList struct {
81+
metav1.TypeMeta `json:",inline"`
82+
metav1.ListMeta `json:"metadata,omitempty"`
83+
Items []ClusterReport `json:"items"`
84+
}
85+
86+
func init() {
87+
SchemeBuilder.Register(&ClusterReport{}, &ClusterReportList{})
88+
}

‎policy-report/apis/reports.x-k8s.io/v1beta2/doc.go

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
/*
2+
Copyright 2024 The Kubernetes authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Package v1beta2 contains API Schema definitions for the policy v1beta2 API group
18+
// +k8s:deepcopy-gen=package
19+
// +kubebuilder:object:generate=true
20+
// +k8s:openapi-gen=true
21+
// +groupName=reports.x-k8s.io
22+
package v1beta2

0 commit comments

Comments
 (0)