Added detailed documentation

* kubearmor README updates * use-cases * hardening policies * least-permissive policies * workload visibility * why kubearmor is different? Signed-off-by: Rahul Jadhav <nyrahul@gmail.com>
TnGadaria · Jan 8, 2023 · ce18fee · ce18fee
1 parent 88ef12c
commit ce18fee
Show file tree

Hide file tree

Showing 21 changed files with 2,322 additions and 162 deletions.
diff --git a/.gitbook/assets/app-behavior.png b/.gitbook/assets/app-behavior.png
diff --git a/.gitbook/assets/app-behavior2.png b/.gitbook/assets/app-behavior2.png
diff --git a/.gitbook/assets/bpf-lsm.png b/.gitbook/assets/bpf-lsm.png
diff --git a/.gitbook/assets/differentiation.png b/.gitbook/assets/differentiation.png
diff --git a/.gitbook/assets/harden-workloads.png b/.gitbook/assets/harden-workloads.png
diff --git a/.gitbook/assets/multi-cloud.png b/.gitbook/assets/multi-cloud.png
diff --git a/.gitbook/assets/network-segmentation.png b/.gitbook/assets/network-segmentation.png
diff --git a/.gitbook/assets/pod security context.png b/.gitbook/assets/pod security context.png
diff --git a/.gitbook/assets/post-attack-mitigation.png b/.gitbook/assets/post-attack-mitigation.png
diff --git a/.gitbook/assets/zero-trust.png b/.gitbook/assets/zero-trust.png
diff --git a/README.md b/README.md
@@ -5,76 +5,46 @@
 [![Slack](https://img.shields.io/badge/Join%20Our%20Community-Slack-blue)](https://join.slack.com/t/kubearmor/shared_invite/zt-1ltmqdbc6-rSHw~LM6MesZZasmP2hAcA)
 [![Discussions](https://img.shields.io/badge/Got%20Questions%3F-Chat-Violet)](https://github.com/kubearmor/KubeArmor/discussions)
 
-KubeArmor is a cloud-native runtime security enforcement system that restricts the behavior \(such as process execution, file access, and networking operations\) of containers and nodes (VMs) at the system level.
+KubeArmor is a cloud-native runtime security enforcement system that restricts the behavior \(such as process execution, file access, and networking operations\) of pods, containers, and nodes (VMs) at the system level.
 
-KubeArmor leverages [Linux security modules \(LSMs\)](https://en.wikipedia.org/wiki/Linux_Security_Modules) such as [AppArmor](https://en.wikipedia.org/wiki/AppArmor), [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux), or [BPF-LSM](https://lwn.net/Articles/808048/)\) to enforce the user-specified policies. KubeArmor generates alerts/telemetry events with container/pod/namespace identities by leveraging eBPF.
+KubeArmor leverages [Linux security modules \(LSMs\)](https://en.wikipedia.org/wiki/Linux_Security_Modules) such as [AppArmor](https://en.wikipedia.org/wiki/AppArmor), [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux), or [BPF-LSM](https://docs.kernel.org/bpf/prog_lsm.html) to enforce the user-specified policies. KubeArmor generates rich alerts/telemetry events with container/pod/namespace identities by leveraging eBPF.
 
-![KubeArmor High Level Design](.gitbook/assets/kubearmor_overview.png)
-
-## Functionality Overview
-
-### Use-cases
-- Restrict the behavior of containers and nodes (VMs) at the system level
-
-  Traditional container security solutions protect containers by determining their inter-container relations \(i.e., service flows\) at the network level. In contrast, KubeArmor prevents malicious or unknown behaviors in containers by specifying their desired actions \(e.g., a specific process should only be allowed to access a sensitive file\). KubeArmor also allows operators to restrict the behaviors of nodes (VMs) based on node identities.
-
-- Enforce security policies to containers and nodes (VMs) at runtime
-
-  In general, security policies \(e.g., Seccomp and AppArmor profiles\) are statically defined within pod definitions for Kubernetes, and they are applied to containers at creation time. Then, the security policies are not allowed to be updated in runtime.
-
-  To address those problems, KubeArmor users k8s CRDs to define security policies, such that the orchestration of the policy is handled by the k8s control plane. KubeArmor leverages Linux Security Modules (LSMs) to enforce the security policies at the container level according to the labels of given containers and security policies. Similiarly, KubeArmor support policy enforcement at the Host/Node/VM level using `KubeArmorHostSecurityPolicy` k8s resource.
-
-- Produce container-aware alerts and system logs
-
-  LSMs do not have any container-related information; thus, they generate alerts and system logs only based on system metadata \(e.g., User ID, Group ID, and process ID\). It is hard to figure out what containers cause policy violations. KubeArmor uses an eBPF-based system monitor to keep track of process life cycles in containers and even nodes, and converts system metadata to container/node identities when LSMs generate alerts and system logs for any policy violations from containers and nodes (VMs).
+|  |   |
+|:---|:---|
+| :muscle: **[Harden Infrastructure](getting-started/hardening_guide.md)** <hr>:small_blue_diamond: Protect critical paths such as cert bundles :chains: <br>:small_blue_diamond: MITRE, STIGs, CIS based rules :clamp: <br>:small_blue_diamond: Restrict access to raw DB table :left_luggage: | :ring: **[Least Permissive Access](getting-started/least_permissive_access.md)** <hr>:small_blue_diamond: Process Whitelisting :traffic_light:<br>:small_blue_diamond: Network Whitelisting :traffic_light:<br>:small_blue_diamond: Control access to sensitive assets :control_knobs:|
+| :snowflake: **[Network Segmentation](getting-started/network_segmentation.md)** <hr>:small_blue_diamond: Communication Graph between services/pods :spider_web:<br>:small_blue_diamond: Generate k8s network policies :magic_wand:<br>:small_blue_diamond: Keep policies in sync with app updates :inbox_tray:| :telescope: **[Workload Visibility](getting-started/workload_visibility.md)** <hr>:small_blue_diamond: Process execs, File System accesses :dna:<br>:small_blue_diamond: Service binds, Ingress, Egress connections :compass: <br>:small_blue_diamond: Sensitive system call profiling :microscope:|
 
-- Provide easy-to-use semantics for policy definitions
+## Architecture Overview
 
-  KubeArmor provides the ability to monitor the life cycles of containers' processes and take policy decisions based on them. In general, it is much easier to deny a specific action, but it is more difficult to allow only specific actions while denying all. KubeArmor manages internal complexities associated with handling such policy decisions and provides easy semantics towards policy language.
-
-- Support network security enforcement among containers
-
-  KubeArmor aims to protect containers and nodes (VMs) themselves rather than inter-container/inter-node communications. However, using KubeArmor a user can add policies that could apply policy settings at the level of network system calls \(e.g., bind\(\), listen\(\), accept\(\), and connect\(\)\), thus controlling interactions among containers and nodes (VMs).
-
-## Getting Started
-
-Please take a look at the following documents.
+![KubeArmor High Level Design](.gitbook/assets/kubearmor_overview.png)
 
-1. [Getting Started](getting-started/deployment_guide.md)
-2. [Security Policy Specification for Containers](getting-started/security_policy_specification.md)
-3. [Security Policy Examples for Containers](getting-started/security_policy_examples.md)
-4. [Security Policy Specification for Nodes (VMs)](getting-started/host_security_policy_specification.md)
-5. [Security Policy Examples for Nodes (VMs)](getting-started/host_security_policy_examples.md)
+## Documentation :notebook:
 
-If you want to make a contribution, please refer to the following documents too.
+* :point_right: [Getting Started](getting-started/deployment_guide.md)
+* :dart: [Use Cases](getting-started/use-cases.md)
+* :heavy_check_mark: [KubeArmor Support Matrix](getting-started/support_matrix.md)
+* :medal_sports: [How is KubeArmor different?](getting-started/differentiation.md)
+* :scroll: Security Policy for Pods/Containers [[Spec](getting-started/security_policy_specification.md)] [[Examples](getting-started/security_policy_examples.md)]
+* :scroll: Security Policy for Hosts/Nodes [[Spec](getting-started/host_security_policy_specification.md)] [[Examples](getting-started/host_security_policy_examples.md)]
 
-1. [Contribution Guide](contribution/contribution_guide.md)
-2. [Development Guide](contribution/development_guide.md)
-3. [Testing Guide](contribution/testing_guide.md)
+### Contributors :busts_in_silhouette:
 
-## Community
+* :octocat: [Contribution Guide](contribution/contribution_guide.md)
+* :technologist: [Development Guide](contribution/development_guide.md), [Testing Guide](contribution/testing_guide.md)
+* :raising_hand_woman: [Join KubeArmor Slack](https://join.slack.com/t/kubearmor/shared_invite/zt-1ltmqdbc6-rSHw~LM6MesZZasmP2hAcA)
+* :question: [FAQs](FAQ.md)
 
 ### Biweekly Meetup
 
-- Where: [Zoom Link](https://bit.ly/kubearmor-zoom)
-- Minutes: [Document](https://docs.google.com/document/d/1IqIIG9Vz-PYpbUwrH0u99KYEM1mtnYe6BHrson4NqEs/edit)
-- Calendar invite: [Google Calendar](https://calendar.google.com/event?action=TEMPLATE&tmeid=MWN0MTlzYWFoM2tkcXZidTk1cHZjNjNyOGtfMjAyMjAyMTBUMTUwMDAwWiBjXzJmMXRiYnNqNWdrNmdnbGpzMzA4NnAwamw4QGc&tmsrc=c_2f1tbbsj5gk6ggljs3086p0jl8%40group.calendar.google.com&scp=ALL)
-- ICS: [ICS file](getting-started/resources/KubeArmorMeetup.ics) for setting up meeting on your calendar
-
-### Slack
-
-Please join the [KubeArmor Slack channel](https://join.slack.com/t/kubearmor/shared_invite/zt-1ltmqdbc6-rSHw~LM6MesZZasmP2hAcA) to communicate with KubeArmor community.
-
-## License
-
-KubeArmor is licensed under the Apache License, Version 2.0.  
-The eBPF-based container monitor is licensed under the General Public License, Version 2.0.
+- :speaking_head: [Zoom Link](https://bit.ly/kubearmor-zoom)
+- :page_facing_up: Minutes: [Document](https://docs.google.com/document/d/1IqIIG9Vz-PYpbUwrH0u99KYEM1mtnYe6BHrson4NqEs/edit)
+- :calendar: Calendar invite: [Google Calendar](https://calendar.google.com/event?action=TEMPLATE&tmeid=MWN0MTlzYWFoM2tkcXZidTk1cHZjNjNyOGtfMjAyMjAyMTBUMTUwMDAwWiBjXzJmMXRiYnNqNWdrNmdnbGpzMzA4NnAwamw4QGc&tmsrc=c_2f1tbbsj5gk6ggljs3086p0jl8%40group.calendar.google.com&scp=ALL), [ICS file](getting-started/resources/KubeArmorMeetup.ics)
 
-## Notice/Credits
+## Notice/Credits :handshake:
 
-- KubeArmor uses [Tracee](https://github.com/aquasecurity/tracee/)'s system call utility functions developed by [Aqua Security](https://aquasec.com).
+- KubeArmor uses [Tracee](https://github.com/aquasecurity/tracee/)'s system call utility functions.
 
 ## CNCF
 
-KubeArmor is Sandbox Project of the Cloud Native Computing Foundation
+KubeArmor is [Sandbox Project](https://www.cncf.io/projects/kubearmor/) of the Cloud Native Computing Foundation.
 ![CNCF SandBox Project](.gitbook/assets/cncf-sandbox.png)
diff --git a/contribution/KubeArmor Design.pdf b/contribution/KubeArmor Design.pdf