Skip to content

Commit f651a04

Browse files
VedRatananurag-rajawat
VedRatan
and
anurag-rajawat
authored
(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]>
1 parent 8e8c9c8 commit f651a04

19 files changed

+830
-13
lines changed

‎PROJECT

+16-10
Original file line numberDiff line numberDiff line change
@@ -10,36 +10,42 @@ repo: github.com/5GSEC/nimbus
1010
resources:
1111
- api:
1212
crdVersion: v1
13-
namespaced: true
1413
controller: true
1514
domain: security.nimbus.com
1615
group: intent
1716
kind: SecurityIntent
18-
path: github.com/5GSEC/nimbus/api/v1
19-
version: v1
17+
path: github.com/5GSEC/nimbus/api/v1alpha1
18+
version: v1alpha1
2019
- api:
2120
crdVersion: v1
2221
namespaced: true
2322
controller: true
2423
domain: security.nimbus.com
2524
group: intent
25+
kind: SecurityIntentBinding
26+
path: github.com/5GSEC/nimbus/api/v1alpha1
27+
version: v1alpha1
28+
- api:
29+
crdVersion: v1
30+
namespaced: true
31+
domain: security.nimbus.com
32+
group: intent
2633
kind: NimbusPolicy
27-
path: github.com/5GSEC/nimbus/api/v1
28-
version: v1
34+
path: github.com/5GSEC/nimbus/api/v1alpha1
35+
version: v1alpha1
2936
- api:
3037
crdVersion: v1
31-
controller: true
3238
domain: security.nimbus.com
3339
group: intent
3440
kind: ClusterNimbusPolicy
35-
path: github.com/5GSEC/nimbus/api/v1
36-
version: v1
41+
path: github.com/5GSEC/nimbus/api/v1alpha1
42+
version: v1alpha1
3743
- api:
3844
crdVersion: v1
3945
controller: true
4046
domain: security.nimbus.com
4147
group: intent
4248
kind: ClusterSecurityIntentBinding
43-
path: github.com/5GSEC/nimbus/api/v1
44-
version: v1
49+
path: github.com/5GSEC/nimbus/api/v1alpha1
50+
version: v1alpha1
4551
version: "3"

‎docs/assets/1.jpg

128 KB
Loading

‎docs/assets/2.jpg

181 KB
Loading

‎docs/assets/3.jpg

297 KB
Loading

‎docs/assets/4.jpg

263 KB
Loading

‎docs/crd/Readme.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Nimbus API
2+
3+
This document provides guidance on extending and maintaining the [Nimbus API](../../api)
4+
5+
## Concepts
6+
7+
* https://kubernetes.io/docs/reference/using-api/api-concepts/
8+
* https://kubernetes.io/docs/reference/using-api/
9+
* https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/
10+
* https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
11+
12+
## API Groups
13+
14+
All Nimbus resources are currently defined in the `intent.security.nimbus.com` API group.
15+
16+
## API Versions
17+
18+
This `intent.security.nimbus.com` has the following versions:
19+
20+
* v1alpha1
21+
22+
## Adding a new attribute
23+
24+
New attributes can be added to existing resources without impacting compatibility. They do not require a new version.
25+
26+
## Deleting an attribute
27+
28+
Attributes cannot be deleted in a version. They should be marked for deprecation and removed after 3 releases.
29+
30+
## Modifying an attribute
31+
32+
Attributes cannot be modified in a version. The existing attribute should be marked for deprecation and a new attribute
33+
should be added following version compatibility guidelines.

‎docs/crd/v1alpha1/clustersecurityintentbinding.md

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Nimbus ClusterSecurityIntentBinding Specification
2+
3+
## Description
4+
5+
A `ClusterSecurityIntentBinding` binds specific `SecurityIntent` resources to targeted resources within a cluster.
6+
Unlike its namespaced counterpart (`SecurityIntentBinding`), it operates at the cluster level, enabling intent
7+
application across multiple namespaces.
8+
9+
```text
10+
apiVersion: intent.security.nimbus.com/v1alpha1
11+
kind: ClusterSecurityIntentBinding
12+
metadata:
13+
name: [ ClusterSecurityIntentBinding name ]
14+
spec:
15+
intents:
16+
- name: [ intent-to-bind-name ]
17+
selector:
18+
workloadSelector: # --> optional
19+
matchLabels:
20+
[ key1 ]: [ value1 ]
21+
[ keyN ]: [ valueN ]
22+
nsSelector: # --> optional
23+
excludeNames: # --> optional
24+
- [ namespace-to-exclude ]
25+
matchNames: # --> optional
26+
- [ namespace-to-include ]
27+
```
28+
29+
### Explanation of Fields
30+
31+
### Common Fields
32+
33+
- `apiVersion`: Identifies the version of the API group for this resource. This remains constant for all Nimbus
34+
policies.
35+
- `kind`: Specifies the resource type, which is always `ClusterSecurityIntentBinding` in this case.
36+
- `metadata`: Contains standard Kubernetes metadata like the resource name, which you define in the `.metadata`
37+
placeholder.
38+
39+
```yaml
40+
apiVersion: intent.security.nimbus.com/v1alpha1
41+
kind: ClusterSecurityIntentBinding
42+
metadata:
43+
name: cluster-security-intent-binding-name
44+
```
45+
46+
### Intents
47+
48+
- `.spec.intents` **(Required)**: An array containing one or more objects specifying the names of `SecurityIntent`
49+
resources to be
50+
bound. Each object has a single field:
51+
- `name` **(Required)**: The name of the `SecurityIntent` that should be applied to resources selected by this
52+
binding.
53+
54+
```yaml
55+
...
56+
spec:
57+
intents:
58+
- name: assess-tls-scheduled
59+
...
60+
```
61+
62+
### Selector
63+
64+
`ClusterSecurityIntentBinding` has different selector to bind intent(s) to resources across namespaces.
65+
66+
- `.spec.selector` **(Required)**: Defines resources targeted by the bound `SecurityIntent` policies.
67+
- `workloadSelector` **(Optional)**: Same selector as `SecurityIntentBinding`.
68+
- `nsSelector` **(Optional)**: Namespace selection criteria.
69+
- `excludeNames` **(Optional)**: Exclude namespaces from the binding.
70+
- `matchNames` **(Optional)**: Include namespaces in the binding.
71+
Note: At least one of `matchNames` or `excludeNames` must be specified in `nsSelector`.
72+
73+
Here are some examples:
74+
75+
- [Apply to all namespaces](../../../examples/clusterscoped/csib-1-all-ns-selector.yaml)
76+
- [Apply to specific namespaces](../../../examples/clusterscoped/csib-2-match-names.yaml)
77+
- [Apply to all namespaces excluding specific namespaces](../../../examples/clusterscoped/csib-3-exclude-names.yaml)

‎docs/crd/v1alpha1/securityintent.md

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Nimbus `SecurityIntent` Specification
2+
3+
## Description
4+
5+
A `SecurityIntent` resource defines the desired security state for your Kubernetes cluster at a high level. It describes
6+
**_what security outcome you want_**, not how to achieve it. This resource is cluster-scoped resource.
7+
8+
## Spec
9+
10+
```text
11+
apiVersion: intent.security.nimbus.com/v1alpha1
12+
kind: SecurityIntent
13+
metadata:
14+
name: [SecurityIntent name]
15+
spec:
16+
intent:
17+
id: [supported intent ID] # ID from the predefined pool
18+
action: [Audit|Block] # Block by default.
19+
params: # Optional. Parameters allows fine-tuning of intents to specific requirements.
20+
key: ["value1", "value2"]
21+
```
22+
23+
### Explanation of Fields
24+
25+
### Common Fields
26+
27+
- `apiVersion`: Identifies the version of the API group for this resource. This remains constant for all Nimbus
28+
policies.
29+
- `kind`: Specifies the resource type, which is always `SecurityIntent` in this case.
30+
- `metadata`: Contains standard Kubernetes metadata like the resource name, which you define in the `.metadata.name`
31+
placeholder.
32+
33+
```yaml
34+
apiVersion: intent.security.nimbus.com/v1alpha1
35+
kind: SecurityIntent
36+
metadata:
37+
name: securityIntent-name
38+
```
39+
40+
### Intent Fields
41+
42+
The `.spec.intent` field defines the specific security behavior you want:
43+
44+
- `id` **(Required)**: This refers to a predefined intent ID from the [pool]( ../../intents/supportedIntents).
45+
Security engines use this ID to generate corresponding security policies.
46+
- `action` **(Required)**: This defines how the generated policy will be enforced. Supported actions are `Audit` (logs
47+
the violation) and `Block` (prevents the violation). By default, the action is set to `Block`.
48+
- `params` **(Optional)**: Parameters are key-value pairs that allow you to customize the chosen intent for your
49+
specific needs. Refer to the [supported intents]( ../../intents/supportedIntents) for details on available
50+
parameters and their valid values.
51+
52+
```yaml
53+
...
54+
spec:
55+
intent:
56+
id: assessTLS
57+
action: Audit
58+
params:
59+
schedule: [ "* * * * *" ]
60+
...
61+
```

‎docs/crd/v1alpha1/securityintentbinding.md

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Nimbus `SecurityIntentBinding` Specification
2+
3+
## Description
4+
5+
A `SecurityIntentBinding` object defines how a specific `SecurityIntent` is applied to resources within a namespace. It
6+
essentially binds an intent to target resources like pods.
7+
8+
## Spec
9+
10+
```text
11+
apiVersion: intent.security.nimbus.com/v1alpha1
12+
kind: SecurityIntentBinding
13+
metadata:
14+
name: [ securityIntentBinding name ]
15+
namespace: [ namespace name ] # Namespace where the binding applies
16+
spec:
17+
intents:
18+
- name: [ intent-to-bind-name ] # Name of the SecurityIntent to apply
19+
selector:
20+
workloadSelector:
21+
matchLabels:
22+
key1: value1
23+
# ... (additional label selectors)
24+
```
25+
26+
### Explanation of Fields
27+
28+
### Common Fields
29+
30+
- `apiVersion`: Identifies the version of the API group for this resource. This remains constant for all Nimbus
31+
policies.
32+
- `kind`: Specifies the resource type, which is always `SecurityIntentBinding` in this case.
33+
- `metadata`: Contains standard Kubernetes metadata like the resource name, which you define in the `.metadata`
34+
placeholder.
35+
36+
```yaml
37+
apiVersion: intent.security.nimbus.com/v1alpha1
38+
kind: SecurityIntentBinding
39+
metadata:
40+
name: securityIntentBinding-name
41+
```
42+
43+
### Intents
44+
45+
- `.spec.intents` **(Required)**: An array containing one or more objects specifying the names of `SecurityIntent`
46+
resources to be
47+
bound. Each object has a single field:
48+
- `name` **(Required)**: The name of the `SecurityIntent` that should be applied to resources selected by this
49+
binding.
50+
51+
```yaml
52+
...
53+
spec:
54+
intents:
55+
- name: dns-manipulation
56+
...
57+
```
58+
59+
### Selector
60+
61+
- `spec.selector` **(Required)**: Defines the Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/) that
62+
will be
63+
subject to the bound `SecurityIntent` policies.
64+
- `workloadSelector` : Selects resources based on labels.
65+
- `matchLabels`: A key-value map where each key represents a label on the target resource and its corresponding
66+
value specifies the expected value for that label. Resources with matching labels will be targeted by the
67+
bound `SecurityIntent`.
68+
69+
```yaml
70+
...
71+
selector:
72+
workloadSelector:
73+
matchLabels:
74+
key1: value
75+
...
76+
```

‎docs/getting-started.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@ Before you begin, set up the following:
99

1010
- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) version 1.26 or later.
1111
- A Kubernetes cluster running version 1.26 or later.
12-
- 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)).
12+
- 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)).
1313
- The Kubernetes clusters should be configured with a CNI that supports network policy.
14-
- For kind clusters, this reference ([kind-calico](https://docs.tigera.io/calico/latest/getting-started/kubernetes/kind)) has the details.
14+
- For kind clusters, this reference ([calico-kind](https://docs.tigera.io/calico/latest/getting-started/kubernetes/kind)) has the details.
15+
- For on-prem clusters, this reference ([calico-onprem](https://docs.tigera.io/calico/latest/getting-started/kubernetes/self-managed-onprem/onpremises)) has the details.
1516
- 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/)).
1617
- 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)).
1718
- 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)).

0 commit comments

Comments
 (0)