From 8e63ed38eb52edadaaec5c13721a7d5372f04154 Mon Sep 17 00:00:00 2001 From: Anurag Rajawat Date: Tue, 9 Jul 2024 19:16:06 +0530 Subject: [PATCH] docs: Update user-facing docs (#219) Signed-off-by: Anurag Rajawat --- CONTRIBUTING.md | 130 ++++++++++++++++++++++++++++++++++++++++ README.md | 1 + docs/adapters.md | 101 +++++++++++++++++++++++++++++++ docs/getting-started.md | 113 ---------------------------------- docs/quick-tutorials.md | 77 +++++++++++++++--------- 5 files changed, 282 insertions(+), 140 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/adapters.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e25c272a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,130 @@ +# Want to contribute? + +Great! We welcome contributions of all kinds, big or small! This includes bug reports, code fixes, documentation +improvements, and code examples. + +Before you dive in, please take a moment to read through this guide. + +# Reporting issue + +We use [GitHub](https://github.com/5GSEC/nimbus) to manage the issues. Please open +a [new issue](https://github.com/5GSEC/nimbus/issues/new) directly there. + +# Getting Started + +## Setting Up Your Environment + +- Head over to [GitHub](https://github.com/5GSEC/nimbus) and fork the 5GSec Nimbus repository. +- Clone your forked repository onto your local machine. + ```shell + git clone git@github.com:/nimbus.git + ``` + +## Install development tools + +You'll need these tools for a smooth development experience: + +- [Make](https://www.gnu.org/software/make/#download) +- [Go](https://go.dev/doc/install) SDK, version 1.21 or later +- Go IDE ([Goland](https://www.jetbrains.com/go/) / [VS Code](https://code.visualstudio.com/download)) +- Container tools ([Docker](https://www.docker.com/) / [Podman](https://podman.io/)) +- [Kubernetes cluster](https://kubernetes.io/docs/setup/) running version 1.26 or later. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) version 1.26 or later. + +# Project Setup + +## Building Locally + +- Install development tools (mentioned above). + +- Build Nimbus using: + ```shell + make build + ``` + +## Testing Local Build + +### Against the Cluster (without installing as workload): + +#### Nimbus operator + +- Generate code and manifests: + ```shell + make manifests generate + ``` + +- Install CRDs: + ```shell + make install + ``` + +- Run the operator: + ```shell + make run + ``` + +#### Adapters + +- Navigate to adapter's directory: + ```shell + cd pkg/adapter/ + ``` +- Run it: + ```shell + make run + ``` + +### In the Cluster (installing as workload): + +Follow [this](deployments/nimbus/Readme.md) guide to install Nimbus or the complete suite. + +Alternatively, follow [this](docs/adapters.md) guide to install individual adapters. + +# Contributing Code + +### Understanding the Project + +Before contributing to any Open Source project, it's important to have basic understanding of what the project is about. +It is advised to try out the project as an end user. + +### Pull Requests and Code Reviews + +We use GitHub [pull requests](https://github.com/5GSEC/nimbus/pulls) for code contributions. All submissions, including +those from project members, require review before merging. +We typically aim for two approvals per pull request, with reviews happening within a week or two. +Feel free to ping reviewers if you haven't received feedback within that timeframe. + +#### Commit Messages + +We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for clear and +consistent commit messages. + +Please make sure you have added the **Signed-off-by:** footer in your git commit. In order to do it automatically, use +the **--signoff** flag: + +```shell +git commit --signoff +``` + +With this command, git would automatically add a footer by reading your name and email from git config. + +# Testing and Documentation + +Tests and documentation are not optional, make sure your pull requests include: + +- Tests that verify your changes and don't break existing functionality. +- Updated [documentation](docs) reflecting your code changes. +- Reference information and any other relevant details. + +## Commands to run tests + +- Integration tests: + ```shell + make integration-test + ``` + +- End-to-end tests: + **Requires installing the complete suite, follow [this](deployments/nimbus/Readme.md)** + ```shell + make e2e-test + ``` diff --git a/README.md b/README.md index c45e502f..84a66501 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ best implementation method available given the deployment. * [Getting Started](docs/getting-started.md) * [Quick Tutorials](docs/quick-tutorials.md) +* [Contribution guide](CONTRIBUTING.md) # Credits diff --git a/docs/adapters.md b/docs/adapters.md new file mode 100644 index 00000000..eefab14c --- /dev/null +++ b/docs/adapters.md @@ -0,0 +1,101 @@ +# Adapters + +Clone your forked repository onto your local machine. + +```shell +git clone git@github.com:/nimbus.git +``` + +## nimbus-kubearmor + +### From source + +**Requires installing corresponding security engine**: +Follow [this](https://docs.kubearmor.io/kubearmor/quick-links/deployment_guide) guide to install +KubeArmor. + +Navigate to `nimbus-kubearmor` directory: + +```shell +cd nimbus/pkg/adapter/nimbus-kubearmor +``` + +Run adapter: + +```shell +make run +``` + +### From Helm chart + +Follow [this](../../deployments/nimbus-kubearmor/Readme.md) guide to install using a helm cahrt. + +## nimbus-netpol + +> [!Note] +> The `nimbus-netpol` adapter leverages +> the [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/). +> To use network policies, you must be using a networking solution which supports NetworkPolicy. Creating a +> NetworkPolicy resource without a controller that implements it will have no effect. + +### From source + +Navigate to `nimbus-netpol` directory: + +```shell +cd nimbus/pkg/adapter/nimbus-netpol +``` + +Run adapter: + +```shell +make run +``` + +### From Helm chart + +Follow [this](../../deployments/nimbus-netpol/Readme.md) to install using a helm chart. + +## nimbus-kyverno + +**Requires installing corresponding security engine**: +Follow [this](https://kyverno.io/docs/installation/) guide to install +Kyverno. + +### From source + +Navigate to `nimbus-kyverno` directory: + +```shell +cd nimbus/pkg/adapter/nimbus-kyverno +``` + +Run adapter: + +```shell +make run +``` + +### From Helm chart + +Follow [this](../../deployments/nimbus-kyverno/Readme.md) to install using a helm chart. + +## nimbus-k8tls + +### From source + +Navigate to `nimbus-k8tls` directory: + +```shell +cd nimbus/pkg/adapter/nimbus-kyverno +``` + +Run adapter: + +```shell +make run +``` + +### From Helm chart + +Follow [this](../../deployments/nimbus-k8tls/Readme.md) to install using a helm chart. diff --git a/docs/getting-started.md b/docs/getting-started.md index 3ad4a8be..5cf928e3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -25,32 +25,6 @@ gcloud compute instances create $VM_NAME --zone=$VM_ZONE --machine-type=$VM_MACH # Nimbus - -There are various ways of installing Nimbus. - -## From source - -Install [go](https://go.dev/doc/install) version 1.20 or later. - -Clone the repository: - -```shell -git clone https://github.com/5GSEC/nimbus.git -cd nimbus -``` - -Install CRDs: - -```shell -make install -``` - -Run the operator: - -```shell -make run -``` - ## From Helm Chart Follow [this](../deployments/nimbus/Readme.md) guide to install `nimbus` operator. By default the install of the `nimbus` operator installs the adapters also, and all the security engines - except confidential containers - too. @@ -109,90 +83,3 @@ kata-qemu-sev kata-qemu-sev 10d kata-qemu-snp kata-qemu-snp 10d kata-qemu-tdx kata-qemu-tdx 10d ``` - -# Adapters - -Just like Nimbus, there are various ways of installing Security engine adapters. - -- ## nimbus-kubearmor - ### From source - - Clone the repository: - - ```shell - git clone https://github.com/5GSEC/nimbus.git - ``` - - Go to nimbus-kubearmor directory: - - ```shell - cd nimbus/pkg/adapter/nimbus-kubearmor - ``` - - Run `nimbus-kubearmor` adapter: - - ```shell - make run - ``` - - ### From Helm Chart - - Follow [this](../deployments/nimbus-kubearmor/Readme.md) guide to install `nimbus-kubearmor` adapter. - -- ## nimbus-netpol - - > [!Note] - > The `nimbus-netpol` adapter leverages - > the [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/). - > To use network policies, you must be using a networking solution which supports NetworkPolicy. Creating a - > NetworkPolicy resource without a controller that implements it will have no effect. - - ### From source - - Clone the repository: - - ```shell - git clone https://github.com/5GSEC/nimbus.git - ``` - - Go to nimbus-netpol directory: - - ```shell - cd nimbus/pkg/adapter/nimbus-netpol - ``` - - Run `nimbus-netpol` adapter: - - ```shell - make run - ``` - - ### From Helm Chart - - Follow [this](../deployments/nimbus-netpol/Readme.md) guide to install `nimbus-netpol` adapter. - -- ## nimbus-kyverno - - ### From source - - Clone the repository: - - ```shell - git clone https://github.com/5GSEC/nimbus.git - ``` - - Go to nimbus-kyverno directory: - - ```shell - cd nimbus/pkg/adapter/nimbus-kyverno - ``` - - Run `nimbus-kyverno` adapter: - - ```shell - make run - ``` - - ### From Helm Chart - - Follow [this](../deployments/nimbus-kyverno/Readme.md) guide to install `nimbus-kyverno` adapter. diff --git a/docs/quick-tutorials.md b/docs/quick-tutorials.md index 5ce53700..ac5a6fe5 100644 --- a/docs/quick-tutorials.md +++ b/docs/quick-tutorials.md @@ -2,12 +2,12 @@ ## Prerequisites -- **Nimbus suite**: Follow [this](../deployments/nimbus/Readme.md) guide to install `nimbus` operator and its adapters. +- **Nimbus suite**: Follow [this](../deployments/nimbus/Readme.md) guide to install complete suite. ## Create a sample deployment ```shell -kubectl apply -f ./examples/env/nginx-deploy.yaml +kubectl create deploy nginx --image=nginx ``` ## Create SecurityIntent and SecurityIntentBinding @@ -17,9 +17,30 @@ kubectl apply -f ./examples/env/nginx-deploy.yaml Create SecurityIntent and SecurityIntentBinding to prevent DNS Manipulation. ```shell -$ kubectl apply -f ./examples/namespaced/dns-manipulation-si-sib.yaml -securityintent.intent.security.nimbus.com/dns-manipulation created -securityintentbinding.intent.security.nimbus.com/dns-manipulation-binding created +cat << EOF | kubectl apply -f - +apiVersion: intent.security.nimbus.com/v1alpha1 +kind: SecurityIntent +metadata: + name: dns-manipulation +spec: + intent: + id: dnsManipulation + description: "An adversary can manipulate DNS requests to redirect network traffic and potentially reveal end user activity." + action: Block + severity: medium +--- +apiVersion: intent.security.nimbus.com/v1alpha1 +kind: SecurityIntentBinding +metadata: + name: dns-manipulation-binding +spec: + intents: + - name: dns-manipulation + selector: + workloadSelector: + matchLabels: + app: nginx +EOF ``` ## Verify Resources @@ -64,20 +85,20 @@ Name: dns-manipulation-binding Namespace: default Labels: Annotations: -API Version: intent.security.nimbus.com/v1 +API Version: intent.security.nimbus.com/v1alpha1 Kind: NimbusPolicy Metadata: - Creation Timestamp: 2024-02-20T06:04:32Z + Creation Timestamp: 2024-07-09T08:03:40Z Generation: 1 Owner References: - API Version: intent.security.nimbus.com/v1 + API Version: intent.security.nimbus.com/v1alpha1 Block Owner Deletion: true Controller: true Kind: SecurityIntentBinding Name: dns-manipulation-binding - UID: c3b7046f-26c7-4edb-ad82-de243e9ee378 - Resource Version: 56960 - UID: 109a7b54-8643-487e-9454-6a79c5f4cacc + UID: 58ca4f82-c930-42ad-b3d3-7486805abeb9 + Resource Version: 4307 + UID: e942a5dc-397b-4ea5-ae59-54521ca520de Spec: Rules: Description: An adversary can manipulate DNS requests to redirect network traffic and potentially reveal end user activity. @@ -91,7 +112,7 @@ Status: Adapter Policies: KubeArmorPolicy/dns-manipulation-binding-dnsmanipulation NetworkPolicy/dns-manipulation-binding-dnsmanipulation - Last Updated: 2024-02-20T06:04:32Z + Last Updated: 2024-07-09T08:03:40Z Number Of Adapter Policies: 2 Status: Created Events: @@ -122,19 +143,19 @@ kind: KubeArmorPolicy metadata: annotations: app.kubernetes.io/managed-by: nimbus-kubearmor - creationTimestamp: "2024-02-20T06:04:32Z" + creationTimestamp: "2024-07-09T08:03:40Z" generation: 1 name: dns-manipulation-binding-dnsmanipulation namespace: default ownerReferences: - - apiVersion: intent.security.nimbus.com/v1 + - apiVersion: intent.security.nimbus.com/v1alpha1 blockOwnerDeletion: true controller: true kind: NimbusPolicy name: dns-manipulation-binding - uid: 109a7b54-8643-487e-9454-6a79c5f4cacc - resourceVersion: "56955" - uid: 03afa2ec-ea86-4248-9f63-243493aa1db9 + uid: e942a5dc-397b-4ea5-ae59-54521ca520de + resourceVersion: "4303" + uid: 7644a152-ca15-45be-8659-3bd7a28fa40d spec: action: Block capabilities: { } @@ -155,7 +176,7 @@ spec: ### NetworkPolicy ```shell -$ kubectl get networkpolicy +$ kubectl get networkpolicy NAME POD-SELECTOR AGE dns-manipulation-binding-dnsmanipulation app=nginx 6m43s ``` @@ -172,19 +193,19 @@ kind: NetworkPolicy metadata: annotations: app.kubernetes.io/managed-by: nimbus-netpol - creationTimestamp: "2024-02-20T06:04:32Z" + creationTimestamp: "2024-07-09T08:03:40Z" generation: 1 name: dns-manipulation-binding-dnsmanipulation namespace: default ownerReferences: - - apiVersion: intent.security.nimbus.com/v1 + - apiVersion: intent.security.nimbus.com/v1alpha1 blockOwnerDeletion: true controller: true kind: NimbusPolicy name: dns-manipulation-binding - uid: 109a7b54-8643-487e-9454-6a79c5f4cacc - resourceVersion: "56956" - uid: 473c293e-3006-4843-9eb3-2a21f142d6e3 + uid: e942a5dc-397b-4ea5-ae59-54521ca520de + resourceVersion: "4304" + uid: 61a3f401-6725-4791-84cc-3ec701e90a62 spec: egress: - ports: @@ -216,12 +237,14 @@ From the `DNSManipulation` SecurityIntent two security policies were generated: `kube-dns` pods within the `kube-system` namespace. This restricts access to the DNS server, enhancing security while enabling pods to resolve DNS names. +**Enforcement is handled by the relevant security engines. Here, KubeArmor and a NetworkPolicy-enforcing CNI solution.** + ## Cleanup * The SecurityIntent and SecurityIntentBinding created earlier are no longer needed and can be deleted: ```shell -$ kubectl delete -f ./examples/namespaced/dns-manipulation-si-sib.yaml +$ kubectl delete securityintent,securityintentbinding --all securityintent.intent.security.nimbus.com "dns-manipulation" deleted securityintentbinding.intent.security.nimbus.com "dns-manipulation-binding" deleted ``` @@ -229,18 +252,18 @@ securityintentbinding.intent.security.nimbus.com "dns-manipulation-binding" dele * Delete deployment ```shell -$ kubectl delete -f ./examples/env/nginx-deploy.yaml +$ kubectl delete deploy nginx deployment.apps "nginx" deleted ``` * Confirm all resources have been deleted (Optional) ```shell -$ kubectl get securityintent,securityintentbinding,nimbuspolicy,kubearmorpolicy,netpol -A +$ kubectl get securityintent,securityintentbinding,nimbuspolicy,kubearmorpolicy,netpol No resources found ``` ## Next steps -- Try out other sample [SecurityIntents](../examples/namespaced) and review the policy generation. +- Try out other [SecurityIntents](../examples/namespaced) and review the policy generation. - Checkout [Security Intents](https://github.com/5GSEC/security-intents).