Skip to content

Commit 8e63ed3

Browse files
anurag-rajawatanurag-rajawat
authoredJul 9, 2024··
docs: Update user-facing docs (#219)
Signed-off-by: Anurag Rajawat <[email protected]>
·
v0.4
1 parent d0532ae commit 8e63ed3

File tree

5 files changed

+282
-140
lines changed

5 files changed

+282
-140
lines changed
 

‎CONTRIBUTING.md

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Want to contribute?
2+
3+
Great! We welcome contributions of all kinds, big or small! This includes bug reports, code fixes, documentation
4+
improvements, and code examples.
5+
6+
Before you dive in, please take a moment to read through this guide.
7+
8+
# Reporting issue
9+
10+
We use [GitHub](https://github.com/5GSEC/nimbus) to manage the issues. Please open
11+
a [new issue](https://github.com/5GSEC/nimbus/issues/new) directly there.
12+
13+
# Getting Started
14+
15+
## Setting Up Your Environment
16+
17+
- Head over to [GitHub](https://github.com/5GSEC/nimbus) and fork the 5GSec Nimbus repository.
18+
- Clone your forked repository onto your local machine.
19+
```shell
20+
git clone git@github.com:<your-username>/nimbus.git
21+
```
22+
23+
## Install development tools
24+
25+
You'll need these tools for a smooth development experience:
26+
27+
- [Make](https://www.gnu.org/software/make/#download)
28+
- [Go](https://go.dev/doc/install) SDK, version 1.21 or later
29+
- Go IDE ([Goland](https://www.jetbrains.com/go/) / [VS Code](https://code.visualstudio.com/download))
30+
- Container tools ([Docker](https://www.docker.com/) / [Podman](https://podman.io/))
31+
- [Kubernetes cluster](https://kubernetes.io/docs/setup/) running version 1.26 or later.
32+
- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) version 1.26 or later.
33+
34+
# Project Setup
35+
36+
## Building Locally
37+
38+
- Install development tools (mentioned above).
39+
40+
- Build Nimbus using:
41+
```shell
42+
make build
43+
```
44+
45+
## Testing Local Build
46+
47+
### Against the Cluster (without installing as workload):
48+
49+
#### Nimbus operator
50+
51+
- Generate code and manifests:
52+
```shell
53+
make manifests generate
54+
```
55+
56+
- Install CRDs:
57+
```shell
58+
make install
59+
```
60+
61+
- Run the operator:
62+
```shell
63+
make run
64+
```
65+
66+
#### Adapters
67+
68+
- Navigate to adapter's directory:
69+
```shell
70+
cd pkg/adapter/<adapter-name>
71+
```
72+
- Run it:
73+
```shell
74+
make run
75+
```
76+
77+
### In the Cluster (installing as workload):
78+
79+
Follow [this](deployments/nimbus/Readme.md) guide to install Nimbus or the complete suite.
80+
81+
Alternatively, follow [this](docs/adapters.md) guide to install individual adapters.
82+
83+
# Contributing Code
84+
85+
### Understanding the Project
86+
87+
Before contributing to any Open Source project, it's important to have basic understanding of what the project is about.
88+
It is advised to try out the project as an end user.
89+
90+
### Pull Requests and Code Reviews
91+
92+
We use GitHub [pull requests](https://github.com/5GSEC/nimbus/pulls) for code contributions. All submissions, including
93+
those from project members, require review before merging.
94+
We typically aim for two approvals per pull request, with reviews happening within a week or two.
95+
Feel free to ping reviewers if you haven't received feedback within that timeframe.
96+
97+
#### Commit Messages
98+
99+
We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for clear and
100+
consistent commit messages.
101+
102+
Please make sure you have added the **Signed-off-by:** footer in your git commit. In order to do it automatically, use
103+
the **--signoff** flag:
104+
105+
```shell
106+
git commit --signoff
107+
```
108+
109+
With this command, git would automatically add a footer by reading your name and email from git config.
110+
111+
# Testing and Documentation
112+
113+
Tests and documentation are not optional, make sure your pull requests include:
114+
115+
- Tests that verify your changes and don't break existing functionality.
116+
- Updated [documentation](docs) reflecting your code changes.
117+
- Reference information and any other relevant details.
118+
119+
## Commands to run tests
120+
121+
- Integration tests:
122+
```shell
123+
make integration-test
124+
```
125+
126+
- End-to-end tests:
127+
**Requires installing the complete suite, follow [this](deployments/nimbus/Readme.md)**
128+
```shell
129+
make e2e-test
130+
```

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ best implementation method available given the deployment.
3030

3131
* [Getting Started](docs/getting-started.md)
3232
* [Quick Tutorials](docs/quick-tutorials.md)
33+
* [Contribution guide](CONTRIBUTING.md)
3334

3435
# Credits
3536

‎docs/adapters.md

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Adapters
2+
3+
Clone your forked repository onto your local machine.
4+
5+
```shell
6+
git clone git@github.com:<your-username>/nimbus.git
7+
```
8+
9+
## nimbus-kubearmor
10+
11+
### From source
12+
13+
**Requires installing corresponding security engine**:
14+
Follow [this](https://docs.kubearmor.io/kubearmor/quick-links/deployment_guide) guide to install
15+
KubeArmor.
16+
17+
Navigate to `nimbus-kubearmor` directory:
18+
19+
```shell
20+
cd nimbus/pkg/adapter/nimbus-kubearmor
21+
```
22+
23+
Run adapter:
24+
25+
```shell
26+
make run
27+
```
28+
29+
### From Helm chart
30+
31+
Follow [this](../../deployments/nimbus-kubearmor/Readme.md) guide to install using a helm cahrt.
32+
33+
## nimbus-netpol
34+
35+
> [!Note]
36+
> The `nimbus-netpol` adapter leverages
37+
> the [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/).
38+
> To use network policies, you must be using a networking solution which supports NetworkPolicy. Creating a
39+
> NetworkPolicy resource without a controller that implements it will have no effect.
40+
41+
### From source
42+
43+
Navigate to `nimbus-netpol` directory:
44+
45+
```shell
46+
cd nimbus/pkg/adapter/nimbus-netpol
47+
```
48+
49+
Run adapter:
50+
51+
```shell
52+
make run
53+
```
54+
55+
### From Helm chart
56+
57+
Follow [this](../../deployments/nimbus-netpol/Readme.md) to install using a helm chart.
58+
59+
## nimbus-kyverno
60+
61+
**Requires installing corresponding security engine**:
62+
Follow [this](https://kyverno.io/docs/installation/) guide to install
63+
Kyverno.
64+
65+
### From source
66+
67+
Navigate to `nimbus-kyverno` directory:
68+
69+
```shell
70+
cd nimbus/pkg/adapter/nimbus-kyverno
71+
```
72+
73+
Run adapter:
74+
75+
```shell
76+
make run
77+
```
78+
79+
### From Helm chart
80+
81+
Follow [this](../../deployments/nimbus-kyverno/Readme.md) to install using a helm chart.
82+
83+
## nimbus-k8tls
84+
85+
### From source
86+
87+
Navigate to `nimbus-k8tls` directory:
88+
89+
```shell
90+
cd nimbus/pkg/adapter/nimbus-kyverno
91+
```
92+
93+
Run adapter:
94+
95+
```shell
96+
make run
97+
```
98+
99+
### From Helm chart
100+
101+
Follow [this](../../deployments/nimbus-k8tls/Readme.md) to install using a helm chart.

‎docs/getting-started.md

-113
Original file line numberDiff line numberDiff line change
@@ -25,32 +25,6 @@ gcloud compute instances create $VM_NAME --zone=$VM_ZONE --machine-type=$VM_MACH
2525

2626

2727
# Nimbus
28-
29-
There are various ways of installing Nimbus.
30-
31-
## From source
32-
33-
Install [go](https://go.dev/doc/install) version 1.20 or later.
34-
35-
Clone the repository:
36-
37-
```shell
38-
git clone https://github.com/5GSEC/nimbus.git
39-
cd nimbus
40-
```
41-
42-
Install CRDs:
43-
44-
```shell
45-
make install
46-
```
47-
48-
Run the operator:
49-
50-
```shell
51-
make run
52-
```
53-
5428
## From Helm Chart
5529

5630
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
10983
kata-qemu-snp kata-qemu-snp 10d
11084
kata-qemu-tdx kata-qemu-tdx 10d
11185
```
112-
113-
# Adapters
114-
115-
Just like Nimbus, there are various ways of installing Security engine adapters.
116-
117-
- ## nimbus-kubearmor
118-
### From source
119-
120-
Clone the repository:
121-
122-
```shell
123-
git clone https://github.com/5GSEC/nimbus.git
124-
```
125-
126-
Go to nimbus-kubearmor directory:
127-
128-
```shell
129-
cd nimbus/pkg/adapter/nimbus-kubearmor
130-
```
131-
132-
Run `nimbus-kubearmor` adapter:
133-
134-
```shell
135-
make run
136-
```
137-
138-
### From Helm Chart
139-
140-
Follow [this](../deployments/nimbus-kubearmor/Readme.md) guide to install `nimbus-kubearmor` adapter.
141-
142-
- ## nimbus-netpol
143-
144-
> [!Note]
145-
> The `nimbus-netpol` adapter leverages
146-
> the [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/).
147-
> To use network policies, you must be using a networking solution which supports NetworkPolicy. Creating a
148-
> NetworkPolicy resource without a controller that implements it will have no effect.
149-
150-
### From source
151-
152-
Clone the repository:
153-
154-
```shell
155-
git clone https://github.com/5GSEC/nimbus.git
156-
```
157-
158-
Go to nimbus-netpol directory:
159-
160-
```shell
161-
cd nimbus/pkg/adapter/nimbus-netpol
162-
```
163-
164-
Run `nimbus-netpol` adapter:
165-
166-
```shell
167-
make run
168-
```
169-
170-
### From Helm Chart
171-
172-
Follow [this](../deployments/nimbus-netpol/Readme.md) guide to install `nimbus-netpol` adapter.
173-
174-
- ## nimbus-kyverno
175-
176-
### From source
177-
178-
Clone the repository:
179-
180-
```shell
181-
git clone https://github.com/5GSEC/nimbus.git
182-
```
183-
184-
Go to nimbus-kyverno directory:
185-
186-
```shell
187-
cd nimbus/pkg/adapter/nimbus-kyverno
188-
```
189-
190-
Run `nimbus-kyverno` adapter:
191-
192-
```shell
193-
make run
194-
```
195-
196-
### From Helm Chart
197-
198-
Follow [this](../deployments/nimbus-kyverno/Readme.md) guide to install `nimbus-kyverno` adapter.

‎docs/quick-tutorials.md

+50-27
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
## Prerequisites
44

5-
- **Nimbus suite**: Follow [this](../deployments/nimbus/Readme.md) guide to install `nimbus` operator and its adapters.
5+
- **Nimbus suite**: Follow [this](../deployments/nimbus/Readme.md) guide to install complete suite.
66

77
## Create a sample deployment
88

99
```shell
10-
kubectl apply -f ./examples/env/nginx-deploy.yaml
10+
kubectl create deploy nginx --image=nginx
1111
```
1212

1313
## Create SecurityIntent and SecurityIntentBinding
@@ -17,9 +17,30 @@ kubectl apply -f ./examples/env/nginx-deploy.yaml
1717
Create SecurityIntent and SecurityIntentBinding to prevent DNS Manipulation.
1818

1919
```shell
20-
$ kubectl apply -f ./examples/namespaced/dns-manipulation-si-sib.yaml
21-
securityintent.intent.security.nimbus.com/dns-manipulation created
22-
securityintentbinding.intent.security.nimbus.com/dns-manipulation-binding created
20+
cat << EOF | kubectl apply -f -
21+
apiVersion: intent.security.nimbus.com/v1alpha1
22+
kind: SecurityIntent
23+
metadata:
24+
name: dns-manipulation
25+
spec:
26+
intent:
27+
id: dnsManipulation
28+
description: "An adversary can manipulate DNS requests to redirect network traffic and potentially reveal end user activity."
29+
action: Block
30+
severity: medium
31+
---
32+
apiVersion: intent.security.nimbus.com/v1alpha1
33+
kind: SecurityIntentBinding
34+
metadata:
35+
name: dns-manipulation-binding
36+
spec:
37+
intents:
38+
- name: dns-manipulation
39+
selector:
40+
workloadSelector:
41+
matchLabels:
42+
app: nginx
43+
EOF
2344
```
2445

2546
## Verify Resources
@@ -64,20 +85,20 @@ Name: dns-manipulation-binding
6485
Namespace: default
6586
Labels: <none>
6687
Annotations: <none>
67-
API Version: intent.security.nimbus.com/v1
88+
API Version: intent.security.nimbus.com/v1alpha1
6889
Kind: NimbusPolicy
6990
Metadata:
70-
Creation Timestamp: 2024-02-20T06:04:32Z
91+
Creation Timestamp: 2024-07-09T08:03:40Z
7192
Generation: 1
7293
Owner References:
73-
API Version: intent.security.nimbus.com/v1
94+
API Version: intent.security.nimbus.com/v1alpha1
7495
Block Owner Deletion: true
7596
Controller: true
7697
Kind: SecurityIntentBinding
7798
Name: dns-manipulation-binding
78-
UID: c3b7046f-26c7-4edb-ad82-de243e9ee378
79-
Resource Version: 56960
80-
UID: 109a7b54-8643-487e-9454-6a79c5f4cacc
99+
UID: 58ca4f82-c930-42ad-b3d3-7486805abeb9
100+
Resource Version: 4307
101+
UID: e942a5dc-397b-4ea5-ae59-54521ca520de
81102
Spec:
82103
Rules:
83104
Description: An adversary can manipulate DNS requests to redirect network traffic and potentially reveal end user activity.
@@ -91,7 +112,7 @@ Status:
91112
Adapter Policies:
92113
KubeArmorPolicy/dns-manipulation-binding-dnsmanipulation
93114
NetworkPolicy/dns-manipulation-binding-dnsmanipulation
94-
Last Updated: 2024-02-20T06:04:32Z
115+
Last Updated: 2024-07-09T08:03:40Z
95116
Number Of Adapter Policies: 2
96117
Status: Created
97118
Events: <none>
@@ -122,19 +143,19 @@ kind: KubeArmorPolicy
122143
metadata:
123144
annotations:
124145
app.kubernetes.io/managed-by: nimbus-kubearmor
125-
creationTimestamp: "2024-02-20T06:04:32Z"
146+
creationTimestamp: "2024-07-09T08:03:40Z"
126147
generation: 1
127148
name: dns-manipulation-binding-dnsmanipulation
128149
namespace: default
129150
ownerReferences:
130-
- apiVersion: intent.security.nimbus.com/v1
151+
- apiVersion: intent.security.nimbus.com/v1alpha1
131152
blockOwnerDeletion: true
132153
controller: true
133154
kind: NimbusPolicy
134155
name: dns-manipulation-binding
135-
uid: 109a7b54-8643-487e-9454-6a79c5f4cacc
136-
resourceVersion: "56955"
137-
uid: 03afa2ec-ea86-4248-9f63-243493aa1db9
156+
uid: e942a5dc-397b-4ea5-ae59-54521ca520de
157+
resourceVersion: "4303"
158+
uid: 7644a152-ca15-45be-8659-3bd7a28fa40d
138159
spec:
139160
action: Block
140161
capabilities: { }
@@ -155,7 +176,7 @@ spec:
155176
### NetworkPolicy
156177
157178
```shell
158-
$ kubectl get networkpolicy
179+
$ kubectl get networkpolicy
159180
NAME POD-SELECTOR AGE
160181
dns-manipulation-binding-dnsmanipulation app=nginx 6m43s
161182
```
@@ -172,19 +193,19 @@ kind: NetworkPolicy
172193
metadata:
173194
annotations:
174195
app.kubernetes.io/managed-by: nimbus-netpol
175-
creationTimestamp: "2024-02-20T06:04:32Z"
196+
creationTimestamp: "2024-07-09T08:03:40Z"
176197
generation: 1
177198
name: dns-manipulation-binding-dnsmanipulation
178199
namespace: default
179200
ownerReferences:
180-
- apiVersion: intent.security.nimbus.com/v1
201+
- apiVersion: intent.security.nimbus.com/v1alpha1
181202
blockOwnerDeletion: true
182203
controller: true
183204
kind: NimbusPolicy
184205
name: dns-manipulation-binding
185-
uid: 109a7b54-8643-487e-9454-6a79c5f4cacc
186-
resourceVersion: "56956"
187-
uid: 473c293e-3006-4843-9eb3-2a21f142d6e3
206+
uid: e942a5dc-397b-4ea5-ae59-54521ca520de
207+
resourceVersion: "4304"
208+
uid: 61a3f401-6725-4791-84cc-3ec701e90a62
188209
spec:
189210
egress:
190211
- ports:
@@ -216,31 +237,33 @@ From the `DNSManipulation` SecurityIntent two security policies were generated:
216237
`kube-dns` pods within the `kube-system` namespace. This restricts access to the DNS server, enhancing security while
217238
enabling pods to resolve DNS names.
218239

240+
**Enforcement is handled by the relevant security engines. Here, KubeArmor and a NetworkPolicy-enforcing CNI solution.**
241+
219242
## Cleanup
220243

221244
* The SecurityIntent and SecurityIntentBinding created earlier are no longer needed and can be deleted:
222245

223246
```shell
224-
$ kubectl delete -f ./examples/namespaced/dns-manipulation-si-sib.yaml
247+
$ kubectl delete securityintent,securityintentbinding --all
225248
securityintent.intent.security.nimbus.com "dns-manipulation" deleted
226249
securityintentbinding.intent.security.nimbus.com "dns-manipulation-binding" deleted
227250
```
228251

229252
* Delete deployment
230253

231254
```shell
232-
$ kubectl delete -f ./examples/env/nginx-deploy.yaml
255+
$ kubectl delete deploy nginx
233256
deployment.apps "nginx" deleted
234257
```
235258

236259
* Confirm all resources have been deleted (Optional)
237260

238261
```shell
239-
$ kubectl get securityintent,securityintentbinding,nimbuspolicy,kubearmorpolicy,netpol -A
262+
$ kubectl get securityintent,securityintentbinding,nimbuspolicy,kubearmorpolicy,netpol
240263
No resources found
241264
```
242265

243266
## Next steps
244267

245-
- Try out other sample [SecurityIntents](../examples/namespaced) and review the policy generation.
268+
- Try out other [SecurityIntents](../examples/namespaced) and review the policy generation.
246269
- Checkout [Security Intents](https://github.com/5GSEC/security-intents).

0 commit comments

Comments
 (0)
Please sign in to comment.