(docs): added intent description (#265)

* fix: Fix CRDs version in PROJECT file Signed-off-by: Anurag Rajawat <[email protected]> * doc: Add Intent and CRDs spec docs Signed-off-by: Anurag Rajawat <[email protected]> * feat: added intent description Signed-off-by: VedRatan <[email protected]> * docs: added pkg-mgr-execution intent desc Signed-off-by: VedRatan <[email protected]> * docs: added coco-workload intent details Signed-off-by: VedRatan <[email protected]> * docs: update exploit-pfa Signed-off-by: VedRatan <[email protected]> * update command Signed-off-by: VedRatan <[email protected]> * doc: Update docs Signed-off-by: Anurag Rajawat <[email protected]> * refactored the docs Signed-off-by: VedRatan <[email protected]> * updated quick-tutorials Signed-off-by: VedRatan <[email protected]> --------- Signed-off-by: Anurag Rajawat <[email protected]> Signed-off-by: VedRatan <[email protected]> Co-authored-by: Anurag Rajawat <[email protected]>
5GSEC · Oct 14, 2024 · f651a04 · f651a04
1 parent 8e8c9c8
commit f651a04
Show file tree

Hide file tree

Showing 19 changed files with 830 additions and 13 deletions.
diff --git a/PROJECT b/PROJECT
@@ -10,36 +10,42 @@ repo: github.com/5GSEC/nimbus
 resources:
 - api:
     crdVersion: v1
-    namespaced: true
   controller: true
   domain: security.nimbus.com
   group: intent
   kind: SecurityIntent
-  path: github.com/5GSEC/nimbus/api/v1
-  version: v1
+  path: github.com/5GSEC/nimbus/api/v1alpha1
+  version: v1alpha1
 - api:
     crdVersion: v1
     namespaced: true
   controller: true
   domain: security.nimbus.com
   group: intent
+  kind: SecurityIntentBinding
+  path: github.com/5GSEC/nimbus/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  domain: security.nimbus.com
+  group: intent
   kind: NimbusPolicy
-  path: github.com/5GSEC/nimbus/api/v1
-  version: v1
+  path: github.com/5GSEC/nimbus/api/v1alpha1
+  version: v1alpha1
 - api:
     crdVersion: v1
-  controller: true
   domain: security.nimbus.com
   group: intent
   kind: ClusterNimbusPolicy
-  path: github.com/5GSEC/nimbus/api/v1
-  version: v1
+  path: github.com/5GSEC/nimbus/api/v1alpha1
+  version: v1alpha1
 - api:
     crdVersion: v1
   controller: true
   domain: security.nimbus.com
   group: intent
   kind: ClusterSecurityIntentBinding
-  path: github.com/5GSEC/nimbus/api/v1
-  version: v1
+  path: github.com/5GSEC/nimbus/api/v1alpha1
+  version: v1alpha1
 version: "3"
diff --git a/docs/assets/1.jpg b/docs/assets/1.jpg
diff --git a/docs/assets/2.jpg b/docs/assets/2.jpg
diff --git a/docs/assets/3.jpg b/docs/assets/3.jpg
diff --git a/docs/assets/4.jpg b/docs/assets/4.jpg
diff --git a/docs/crd/Readme.md b/docs/crd/Readme.md
@@ -0,0 +1,33 @@
+# Nimbus API
+
+This document provides guidance on extending and maintaining the [Nimbus API](../../api)
+
+## Concepts
+
+* https://kubernetes.io/docs/reference/using-api/api-concepts/
+* https://kubernetes.io/docs/reference/using-api/
+* https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/
+* https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
+
+## API Groups
+
+All Nimbus resources are currently defined in the `intent.security.nimbus.com` API group.
+
+## API Versions
+
+This `intent.security.nimbus.com` has the following versions:
+
+* v1alpha1
+
+## Adding a new attribute
+
+New attributes can be added to existing resources without impacting compatibility. They do not require a new version.
+
+## Deleting an attribute
+
+Attributes cannot be deleted in a version. They should be marked for deprecation and removed after 3 releases.
+
+## Modifying an attribute
+
+Attributes cannot be modified in a version. The existing attribute should be marked for deprecation and a new attribute
+should be added following version compatibility guidelines.
diff --git a/docs/crd/v1alpha1/clustersecurityintentbinding.md b/docs/crd/v1alpha1/clustersecurityintentbinding.md
@@ -0,0 +1,77 @@
+# Nimbus ClusterSecurityIntentBinding Specification
+
+## Description
+
+A `ClusterSecurityIntentBinding` binds specific `SecurityIntent` resources to targeted resources within a cluster.
+Unlike its namespaced counterpart (`SecurityIntentBinding`), it operates at the cluster level, enabling intent
+application across multiple namespaces.
+
+```text
+apiVersion: intent.security.nimbus.com/v1alpha1
+kind: ClusterSecurityIntentBinding
+metadata:
+  name: [ ClusterSecurityIntentBinding name ]
+spec:
+  intents:
+    - name: [ intent-to-bind-name ]
+  selector:
+    workloadSelector:                              # --> optional
+      matchLabels:
+        [ key1 ]: [ value1 ]
+          [ keyN ]: [ valueN ]
+    nsSelector:                                   # --> optional
+      excludeNames:                               # --> optional
+        - [ namespace-to-exclude ]
+      matchNames:                                 # --> optional
+        - [ namespace-to-include ]
+```
+
+### Explanation of Fields
+
+### Common Fields
+
+- `apiVersion`: Identifies the version of the API group for this resource. This remains constant for all Nimbus
+  policies.
+- `kind`: Specifies the resource type, which is always `ClusterSecurityIntentBinding` in this case.
+- `metadata`: Contains standard Kubernetes metadata like the resource name, which you define in the  `.metadata`
+  placeholder.
+
+```yaml
+apiVersion: intent.security.nimbus.com/v1alpha1
+kind: ClusterSecurityIntentBinding
+metadata:
+  name: cluster-security-intent-binding-name
+```
+
+### Intents
+
+- `.spec.intents` **(Required)**: An array containing one or more objects specifying the names of `SecurityIntent`
+  resources to be
+  bound. Each object has a single field:
+    - `name` **(Required)**: The name of the `SecurityIntent` that should be applied to resources selected by this
+      binding.
+
+```yaml
+...
+spec:
+  intents:
+    - name: assess-tls-scheduled
+...
+```
+
+### Selector
+
+`ClusterSecurityIntentBinding` has different selector to bind intent(s) to resources across namespaces.
+
+- `.spec.selector` **(Required)**: Defines resources targeted by the bound `SecurityIntent` policies.
+    - `workloadSelector` **(Optional)**: Same selector as `SecurityIntentBinding`.
+    - `nsSelector` **(Optional)**: Namespace selection criteria.
+        - `excludeNames` **(Optional)**: Exclude namespaces from the binding.
+        - `matchNames` **(Optional)**: Include namespaces in the binding.
+          Note: At least one of `matchNames` or `excludeNames` must be specified in `nsSelector`.
+
+Here are some examples:
+
+- [Apply to all namespaces](../../../examples/clusterscoped/csib-1-all-ns-selector.yaml)
+- [Apply to specific namespaces](../../../examples/clusterscoped/csib-2-match-names.yaml)
+- [Apply to all namespaces excluding specific namespaces](../../../examples/clusterscoped/csib-3-exclude-names.yaml)
diff --git a/docs/crd/v1alpha1/securityintent.md b/docs/crd/v1alpha1/securityintent.md
@@ -0,0 +1,61 @@
+# Nimbus `SecurityIntent` Specification
+
+## Description
+
+A `SecurityIntent` resource defines the desired security state for your Kubernetes cluster at a high level. It describes
+**_what security outcome you want_**, not how to achieve it. This resource is cluster-scoped resource.
+
+## Spec
+
+```text
+apiVersion: intent.security.nimbus.com/v1alpha1
+kind: SecurityIntent
+metadata:
+  name: [SecurityIntent name]
+spec:
+  intent:
+    id: [supported intent ID]                    # ID from the predefined pool
+    action: [Audit|Block]                        # Block by default.
+    params:                                      # Optional. Parameters allows fine-tuning of intents to specific requirements.
+     key: ["value1", "value2"]
+```
+
+### Explanation of Fields
+
+### Common Fields
+
+- `apiVersion`: Identifies the version of the API group for this resource. This remains constant for all Nimbus
+  policies.
+- `kind`: Specifies the resource type, which is always `SecurityIntent` in this case.
+- `metadata`: Contains standard Kubernetes metadata like the resource name, which you define in the  `.metadata.name`
+  placeholder.
+
+```yaml
+apiVersion: intent.security.nimbus.com/v1alpha1
+kind: SecurityIntent
+metadata:
+  name: securityIntent-name
+```
+
+### Intent Fields
+
+The `.spec.intent` field defines the specific security behavior you want:
+
+- `id` **(Required)**: This refers to a predefined intent ID from the [pool]( ../../intents/supportedIntents).
+  Security engines use this ID to generate corresponding security policies.
+- `action` **(Required)**: This defines how the generated policy will be enforced. Supported actions are `Audit` (logs
+  the violation) and `Block` (prevents the violation). By default, the action is set to `Block`.
+- `params` **(Optional)**: Parameters are key-value pairs that allow you to customize the chosen intent for your
+  specific needs. Refer to the [supported intents]( ../../intents/supportedIntents) for details on available
+  parameters and their valid values.
+
+```yaml
+...
+spec:
+  intent:
+    id: assessTLS
+    action: Audit
+    params:
+      schedule: [ "* * * * *" ]
+...
+```
diff --git a/docs/crd/v1alpha1/securityintentbinding.md b/docs/crd/v1alpha1/securityintentbinding.md
@@ -0,0 +1,76 @@
+# Nimbus `SecurityIntentBinding` Specification
+
+## Description
+
+A `SecurityIntentBinding` object defines how a specific `SecurityIntent` is applied to resources within a namespace. It
+essentially binds an intent to target resources like pods.
+
+## Spec
+
+```text
+apiVersion: intent.security.nimbus.com/v1alpha1
+kind: SecurityIntentBinding
+metadata:
+  name: [ securityIntentBinding name ]
+  namespace: [ namespace name ]                  # Namespace where the binding applies
+spec:
+  intents:
+    - name: [ intent-to-bind-name ]              # Name of the SecurityIntent to apply 
+  selector:
+    workloadSelector:
+      matchLabels:
+        key1: value1
+       # ... (additional label selectors)
+```
+
+### Explanation of Fields
+
+### Common Fields
+
+- `apiVersion`: Identifies the version of the API group for this resource. This remains constant for all Nimbus
+  policies.
+- `kind`: Specifies the resource type, which is always `SecurityIntentBinding` in this case.
+- `metadata`: Contains standard Kubernetes metadata like the resource name, which you define in the  `.metadata`
+  placeholder.
+
+```yaml
+apiVersion: intent.security.nimbus.com/v1alpha1
+kind: SecurityIntentBinding
+metadata:
+  name: securityIntentBinding-name
+```
+
+### Intents
+
+- `.spec.intents` **(Required)**: An array containing one or more objects specifying the names of `SecurityIntent`
+  resources to be
+  bound. Each object has a single field:
+    - `name` **(Required)**: The name of the `SecurityIntent` that should be applied to resources selected by this
+      binding.
+
+```yaml
+...
+spec:
+  intents:
+    - name: dns-manipulation
+...
+```
+
+### Selector
+
+- `spec.selector` **(Required)**: Defines the Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/) that
+  will be
+  subject to the bound `SecurityIntent` policies.
+    - `workloadSelector` : Selects resources based on labels.
+        - `matchLabels`: A key-value map where each key represents a label on the target resource and its corresponding
+          value specifies the expected value for that label. Resources with matching labels will be targeted by the
+          bound `SecurityIntent`.
+
+```yaml
+...
+selector:
+  workloadSelector:
+    matchLabels:
+      key1: value
+...
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -9,9 +9,10 @@ Before you begin, set up the following:
 
 - [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) version 1.26 or later.
 - A Kubernetes cluster running version 1.26 or later.
-- In case of kind clusters, bpf-lsm module needs to be installed ([bpf-lsm](https://docs.kubearmor.io/kubearmor/documentation/faq#how-to-enable-kubearmorhostpolicy-for-k8s-cluster)).
+- Make sure that the bpf-lsm module needs is installed ([bpf-lsm](https://docs.kubearmor.io/kubearmor/documentation/faq#how-to-enable-kubearmorhostpolicy-for-k8s-cluster)).
 - The Kubernetes clusters should be configured with a CNI that supports network policy.
-  - For kind clusters, this reference ([kind-calico](https://docs.tigera.io/calico/latest/getting-started/kubernetes/kind)) has the details.
+  - For kind clusters, this reference ([calico-kind](https://docs.tigera.io/calico/latest/getting-started/kubernetes/kind)) has the details.
+  - For on-prem clusters, this reference ([calico-onprem](https://docs.tigera.io/calico/latest/getting-started/kubernetes/self-managed-onprem/onpremises)) has the details.
   - For AWS EKS clusters, the VPC CNI supports kubernetes network policies ([vpc-cni-policy](https://aws.amazon.com/blogs/containers/amazon-vpc-cni-now-supports-kubernetes-network-policies/)).
 - K8s cluster nodes need to have nested virtualization enabled for the confidential containers intent. Additionally kvm needs to be installed ([ubuntu-kvm](https://help.ubuntu.com/community/KVM/Installation)). 
   - For GCP VMs, nested virtualization can be enabled at create time using below command. The machine types which support nested virtualization are listed here ([cpu-virt](https://cloud.google.com/compute/docs/machine-resource#machine_type_comparison)).