diff --git a/README.md b/README.md index 5cabb44..f830bc0 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,34 @@ # compliance-to-policy Compliance-to-Policy (C2P) provides the framework to bridge Compliance administration and Policy administration by [OSCAL](https://pages.nist.gov/OSCAL/). OSCAL (Open Security Controls Assessment Language) is a standardized framework developed by NIST for expressing and automating the assessment and management of security controls in machine-readable format (xml, json, yaml) -## Continuous Compliance by C2P +![C2P Overview](/docs/images/e2e-pm.png) -https://github.com/IBM/compliance-to-policy/assets/113283236/4b0b5357-4025-46c8-8d88-1f4c00538795 - -## Usage of C2P commands - -### C2P for Kyverno -Prepare Kyverno Policy Resources -- You can use [policy-resources for test](/pkg/testdata/kyverno/policy-resources) -- For bring your own policies, please see [Bring your own Kyverno Policy Resources](#bring-your-own-kyverno-policy-resources) - -#### Convert OSCAL to Kyverno Policy -``` -$ go run cmd/c2pcli/main.go kyverno oscal2policy -c ./pkg/testdata/kyverno/c2p-config.yaml -o /tmp/kyverno-policies -2023-10-31T07:23:56.291+0900 INFO kyverno/c2pcr kyverno/configparser.go:53 Component-definition is loaded from ./pkg/testdata/kyverno/component-definition.json - -$ tree /tmp/kyverno-policies -/tmp/kyverno-policies -└── allowed-base-images - ├── 02-setup-cm.yaml - └── allowed-base-images.yaml -``` - -#### Convert Policy Report to OSCAL Assessment Results +## Usage of C2P CLI ``` -$ go run cmd/c2pcli/main.go kyverno result2oscal -c ./pkg/testdata/kyverno/c2p-config.yaml -o /tmp/assessment-results +$ c2pcli -h +C2P CLI -$ tree /tmp/assessment-results -/tmp/assessment-results -└── assessment-results.json -``` +Usage: + c2pcli [flags] + c2pcli [command] -#### Reformat in human-friendly format (markdown file) -``` -$ go run cmd/c2pcli/main.go kyverno tools oscal2posture -c ./pkg/testdata/kyverno/c2p-config.yaml --assessment-results /tmp/assessment-results/assessment-results.json -o /tmp/compliance-report.md -``` +Available Commands: + completion Generate the autocompletion script for the specified shell + help Help about any command + kyverno C2P CLI Kyverno plugin + ocm C2P CLI OCM plugin + version Display version -``` -$ head -n 15 /tmp/compliance-report.md -## Catalog +Flags: + -h, --help help for c2pcli -## Component: Kubernetes -#### Result of control: cm-8.3_smt.a - -Rule ID: allowed-base-images -
Details - - - Subject UUID: 0b1adf1c-f6e2-46af-889e-39255e669655 - - Title: ApiVersion: v1, Kind: Pod, Namespace: argocd, Name: argocd-application-controller-0 - - Result: fail - - Reason: - ``` - validation failure: This container image's base is not in the approved list or is not specified. Only pre-approved base images may be used. Please contact the platform team for assistance. - ``` +Use "c2pcli [command] --help" for more information about a command. ``` -### Bring your own Kyverno Policy Resources -- You can download Kyverno Policies (https://github.com/kyverno/policies) as Policy Resources and modify them - 1. Run `kyverno tools load-policy-resources` command - ``` - $ go run cmd/c2pcli/main.go kyverno tools load-policy-resources --src https://github.com/kyverno/policies --dest /tmp/policies - ``` - ``` - $ tree /tmp/policies - /tmp/policies - ├── add-apparmor-annotations - │ └── add-apparmor-annotations.yaml - ├── add-capabilities - │ └── add-capabilities.yaml - ├── add-castai-removal-disabled - │ └── add-castai-removal-disabled.yaml - ├── add-certificates-volume - │ └── add-certificates-volume.yaml - ├── add-default-resources - ... - ``` - - You can check result.json about what resources are downloaded. - ``` - $ cat /tmp/policies/result.json - - ``` - - There are some policies that depend on context. Please add the context resources manually. result.json contains list of the policies that have context field - ``` - $ jq -r .summary.resourcesHavingContext /tmp/policies/result.json - [ - "allowed-podpriorities", - "allowed-base-images", - "advanced-restrict-image-registries", - ... - "require-linkerd-server" - ] - ``` +C2P is targeting a plugin architecture to cover not only OCM Policy Framework but also other types of PVPs. +Please go to the docs for each usage. +- [C2P for OCM](/docs/ocm/README.md) +- [C2P for Kyverno](/docs/kyverno/README.md) ## Build at local ``` diff --git a/docs/images/e2e-pm.drawio b/docs/images/e2e-pm.drawio new file mode 100644 index 0000000..0adb5b5 --- /dev/null +++ b/docs/images/e2e-pm.drawio @@ -0,0 +1,165 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/e2e-pm.png b/docs/images/e2e-pm.png new file mode 100644 index 0000000..5a96786 Binary files /dev/null and b/docs/images/e2e-pm.png differ diff --git a/docs/kyverno/README.md b/docs/kyverno/README.md new file mode 100644 index 0000000..068f86b --- /dev/null +++ b/docs/kyverno/README.md @@ -0,0 +1,112 @@ +## C2P for Kyverno + +### Continuous Compliance by C2P + +https://github.com/IBM/compliance-to-policy/assets/113283236/4b0b5357-4025-46c8-8d88-1f4c00538795 + +### Usage of C2P CLI +``` +$ c2pcli ocm -h +C2P CLI Kyverno plugin + +Usage: + c2pcli kyverno [command] + +Available Commands: + oscal2policy Compose deliverable Kyverno policies from OSCAL + result2oscal Generate OSCAL Assessment Results from Kyverno policies and the policy reports + tools Tools + +Flags: + -h, --help help for kyverno + +Use "c2pcli kyverno [command] --help" for more information about a command. +``` + +### Prerequisites + +1. Prepare Kyverno Policy Resources + - You can use [policy-resources for test](/pkg/testdata/kyverno/policy-resources) + - For bring your own policies, please see [Bring your own Kyverno Policy Resources](#bring-your-own-kyverno-policy-resources) + +#### Convert OSCAL to Kyverno Policy +``` +$ c2pcli kyverno oscal2policy -c ./pkg/testdata/kyverno/c2p-config.yaml -o /tmp/kyverno-policies +2023-10-31T07:23:56.291+0900 INFO kyverno/c2pcr kyverno/configparser.go:53 Component-definition is loaded from ./pkg/testdata/kyverno/component-definition.json + +$ tree /tmp/kyverno-policies +/tmp/kyverno-policies +└── allowed-base-images + ├── 02-setup-cm.yaml + └── allowed-base-images.yaml +``` + +#### Convert Policy Report to OSCAL Assessment Results +``` +$ c2pcli kyverno result2oscal -c ./pkg/testdata/kyverno/c2p-config.yaml -o /tmp/assessment-results + +$ tree /tmp/assessment-results +/tmp/assessment-results +└── assessment-results.json +``` + +#### Reformat in human-friendly format (markdown file) +``` +$ c2pcli kyverno tools oscal2posture -c ./pkg/testdata/kyverno/c2p-config.yaml --assessment-results /tmp/assessment-results/assessment-results.json -o /tmp/compliance-report.md +``` + +``` +$ head -n 15 /tmp/compliance-report.md +## Catalog + +## Component: Kubernetes +#### Result of control: cm-8.3_smt.a + +Rule ID: allowed-base-images +
Details + + - Subject UUID: 0b1adf1c-f6e2-46af-889e-39255e669655 + - Title: ApiVersion: v1, Kind: Pod, Namespace: argocd, Name: argocd-application-controller-0 + - Result: fail + - Reason: + ``` + validation failure: This container image's base is not in the approved list or is not specified. Only pre-approved base images may be used. Please contact the platform team for assistance. + ``` +``` + +### Bring your own Kyverno Policy Resources +- You can download Kyverno Policies (https://github.com/kyverno/policies) as Policy Resources and modify them + 1. Run `kyverno tools load-policy-resources` command + ``` + $ c2pcli kyverno tools load-policy-resources --src https://github.com/kyverno/policies --dest /tmp/policies + ``` + ``` + $ tree /tmp/policies + /tmp/policies + ├── add-apparmor-annotations + │ └── add-apparmor-annotations.yaml + ├── add-capabilities + │ └── add-capabilities.yaml + ├── add-castai-removal-disabled + │ └── add-castai-removal-disabled.yaml + ├── add-certificates-volume + │ └── add-certificates-volume.yaml + ├── add-default-resources + ... + ``` + - You can check result.json about what resources are downloaded. + ``` + $ cat /tmp/policies/result.json + + ``` + - There are some policies that depend on context. Please add the context resources manually. result.json contains list of the policies that have context field + ``` + $ jq -r .summary.resourcesHavingContext /tmp/policies/result.json + [ + "allowed-podpriorities", + "allowed-base-images", + "advanced-restrict-image-registries", + ... + "require-linkerd-server" + ] + ``` \ No newline at end of file diff --git a/docs/ocm/README.md b/docs/ocm/README.md index edfbe7a..a3259a6 100644 --- a/docs/ocm/README.md +++ b/docs/ocm/README.md @@ -1,6 +1,6 @@ ## C2P for OCM -### Usage +### Usage of C2P CLI ``` $ c2pcli ocm -h C2P CLI OCM plugin @@ -21,6 +21,9 @@ Use "c2pcli ocm [command] --help" for more information about a command. ### Prerequisites 1. Install [Policy Generator Plugin](https://github.com/open-cluster-management-io/policy-generator-plugin#as-a-kustomize-plugin) +1. Prepare OCM Policy Resources + - You can use [policy-resources for test](/pkg/testdata/ocm/policies) + - You can also use [Policy Collection](https://github.com/open-cluster-management-io/policy-collection). Please see [C2P Decomposer](#c2p-decomposer) ### Manual end-to-end use case @@ -150,7 +153,10 @@ Compose OCM Policy from policy resources from compliance information (for exampl └── policy-sets.yaml ``` -### Setup pipeline +### GitOps automation use case + +https://github.com/IBM/compliance-to-policy/assets/113283236/da3518d0-53de-4bd6-8703-04ce94e9dfba + 1. Create two repositories (one is configuration repository that's used for pipeline from OSCAL to Policy and another is evidence repository that's used for pipeline from OCM statuses to Compliance result) - For example, c2p-for-ocm-pipeline01-config and c2p-for-ocm-pipeline01-evidence 1. Create Github Personal Access Token having following permissions