GitBook: [master] 24 pages modified

PrimalPimmy · Feb 21, 2021 · 73f41ba · 73f41ba
1 parent 621461a
commit 73f41ba
Show file tree

Hide file tree

Showing 14 changed files with 113 additions and 133 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# README
+# KubeArmor
 
 ## Introduction to KubeArmor
 
@@ -44,15 +44,15 @@ KubeArmor aims to protect containers themselves rather than interactions among c
 
 Please take a look at the following documents.
 
-1. [Deployment Guide](documentation/deployment_guide.md)
-2. [Security Policy Specification](documentation/security_policy_specification.md)
-3. [Security Policy Examples](documentation/security_policy_examples.md)
-4. [Technical Roadmap](documentation/technical_roadmap.md)
+1. [Deployment Guide](getting-started/deployment_guide.md)
+2. [Security Policy Specification](getting-started/security_policy_specification.md)
+3. [Security Policy Examples](getting-started/security_policy_examples.md)
+4. [Technical Roadmap](contribution/technical_roadmap.md)
 
 If you want to make a contribution, please refer to the following documents too.
 
-1. [Contribution Guide](documentation/contribution_guide.md)
-2. [Development Guide](documentation/development_guide.md)
+1. [Contribution Guide](contribution/contribution_guide.md)
+2. [Development Guide](contribution/development_guide.md)
 
 ## Community
 
@@ -64,3 +64,4 @@ If you want to make a contribution, please refer to the following documents too.
 
 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.
+
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -1,26 +1,29 @@
 # Table of contents
 
+* [KubeArmor](README.md)
+
 ## Getting Started
 
-  * [Deployment Guide](documentation/deployment_guide.md)
-  * [Security Policy Specification](documentation/security_policy_specification.md)
-  * [Security Policy Examples](documentation/security_policy_examples.md)
-  * [Consideration in Policy Action](documentation/consideration_in_policy_action.md)
+* [Deployment Guide](getting-started/deployment_guide.md)
+* [Security Policy Specification](getting-started/security_policy_specification.md)
+* [Security Policy Examples](getting-started/security_policy_examples.md)
+* [Consideration in Policy Action](getting-started/consideration_in_policy_action.md)
 
 ## Contribution
 
-  * [Contribution Guide](documentation/contribution_guide.md)
-  * [Development Guide](documentation/development_guide.md)
-  * [Docker and Kubernetes Installation](documentation/k8s_installation_guide.md)
-  * [Technical Roadmap](documentation/technical_roadmap.md)
+* [Contribution Guide](contribution/contribution_guide.md)
+* [Development Guide](contribution/development_guide.md)
+* [Docker and Kubernetes Installation](contribution/k8s_installation_guide.md)
+* [Technical Roadmap](contribution/technical_roadmap.md)
 
 ## Examples
 
-  * [Multiubuntu](examples/multiubuntu.md)
-  * [Sock-Shop](examples/sock-shop.md)
-  * [Wordpress-MySQL](examples/wordpress-mysql.md)
+* [Multiubuntu](examples/multiubuntu.md)
+* [Sock-Shop](examples/sock-shop.md)
+* [Wordpress-MySQL](examples/wordpress-mysql.md)
 
 ## Reference
 
-  * [Supported Capability List](documentation/supported_capability_list.md)
-  * [Supported Operation List](documentation/supported_operation_list.md)
+* [Supported Capability List](reference/supported_capability_list.md)
+* [Supported Operation List](reference/supported_operation_list.md)
+
diff --git a/documentation/contribution_guide.md → contribution/contribution_guide.md b/documentation/contribution_guide.md → contribution/contribution_guide.md
@@ -65,3 +65,4 @@ If you want to make a contribution, please follow the steps below.
    Finally, click the "Create pull request" button.
 
    Now, please let us review your code. We will merge all your changes into the master branch of KubeArmor. Once your changes are merged, you will get a notification, and the issue that you fixed will be closed as well.
+
diff --git a/documentation/development_guide.md → contribution/development_guide.md b/documentation/development_guide.md → contribution/development_guide.md
@@ -3,7 +3,6 @@
 ## Development
 
 1. Self-managed Kubernetes
-
    * Requirements
 
      Here is the list of requirements for self-managed Kubernetes.
@@ -19,14 +18,14 @@
 
      Note that KubeArmor does not work on MiniKube because MiniKube does not support AppArmor. In addition, KubeArmor does not work with Docker Desktops on Windows and MacOS because such engines do not have a full Linux file system.
 
-      * \(Optional\) MicroK8s Setup
+     * \(Optional\) MicroK8s Setup
 
-        In order to install MicroK8s, please run the following command.
+       In order to install MicroK8s, please run the following command.
 
-        ```text
-        $ cd contributions/bare-metal/microk8s
-        (microk8s) $ ./install_microk8s.sh
-        ```
+       ```text
+       $ cd contributions/bare-metal/microk8s
+       (microk8s) $ ./install_microk8s.sh
+       ```
 
    * Environmetal Setup
 
@@ -40,9 +39,7 @@
      [setup.sh](https://github.com/accuknox/KubeArmor/blob/master/contributions/bare-metal/setup.sh) will automatically install BCC \(latest\), Go \(v1.15.2\), and Protobuf \(3.14.0\).
 
      Now, you are ready to develop any code for KubeArmor. Enjoy your journey with KubeArmor.
-
 2. Vagrant Environment
-
    * Requirements
 
      Here is the list of requirements for a Vagrant environment
@@ -59,74 +56,75 @@
      (vagrant) $ ./setup.sh
      ```
 
-    * VM Setup using Vagrant
+     * VM Setup using Vagrant
 
-      If you do not have ssh keys in '~/.ssh' yet, you need to run the following command in advance.
+       If you do not have ssh keys in '~/.ssh' yet, you need to run the following command in advance.
 
-      ```text
-      (vagrant) $ ssh-keygen -> [Enter] -> [Enter] -> [Enter]
-      ```
+       ```text
+       (vagrant) $ ssh-keygen -> [Enter] -> [Enter] -> [Enter]
+       ```
 
-      Now, it is time to create a VM for development. You can directly use the vagrant command to create a VM.
+       Now, it is time to create a VM for development. You can directly use the vagrant command to create a VM.
 
-      ```text
-      (vagrant) $ vagrant up
-      ```
+       ```text
+       (vagrant) $ vagrant up
+       ```
 
-      If you want to remove the created VM, please run the following command.
+       If you want to remove the created VM, please run the following command.
 
-      ```text
-      (vagrant) $ vagrant destroy
-      ```
+       ```text
+       (vagrant) $ vagrant destroy
+       ```
 
-      You are ready to develop the code for KubeArmor. Enjoy your journey with KubeArmor.
+       You are ready to develop the code for KubeArmor. Enjoy your journey with KubeArmor.
 
-      ```text
-      (vagrant) $ vagrant ssh
-      ```
+       ```text
+       (vagrant) $ vagrant ssh
+       ```
 
 ## Code Directories
 
 Here, we briefly give you the overview of KubeArmor's directories.
 
-  * Source code for KubeArmor \(/KubeArmor\)
+* Source code for KubeArmor \(/KubeArmor\)
+
+  ```text
+  KubeArmor/
+    common      - Libraries internally used
+    core        - The main body (start point) of KubeArmor
+    discovery   - Automated security policy discovery (under development)
+    enforcer    - Runtime policy enforcer (enforcing security policies into LSMs)
+    feeder      - gRPC-based feeder (sending audit/system logs to a log server)
+    monitor     - eBPF-based container monitor (mapping process IDs to container IDs)
+    BPF         - eBPF code for container monitor
+    log         - Message logger (stdout) for KubeArmor
+    types       - Type definitions
+  protobuf/     - Protocol buffer
+  ```
 
-    ```text
-    KubeArmor/
-      common      - Libraries internally used
-      core        - The main body (start point) of KubeArmor
-      discovery   - Automated security policy discovery (under development)
-      enforcer    - Runtime policy enforcer (enforcing security policies into LSMs)
-      feeder      - gRPC-based feeder (sending audit/system logs to a log server)
-      monitor     - eBPF-based container monitor (mapping process IDs to container IDs)
-      BPF         - eBPF code for container monitor
-      log         - Message logger (stdout) for KubeArmor
-      types       - Type definitions
-    protobuf/     - Protocol buffer
-    ```
+* Source code for KubeArmor's log client
 
-  * Source code for KubeArmor's log client
+  ```text
+  LogClient/    - gRPC-based log server
+  protobuf/     - Protocol buffer
+  ```
 
-    ```text
-    LogClient/    - gRPC-based log server
-    protobuf/     - Protocol buffer
-    ```
+* Source code for KubeArmor's custom resource defintion \(CRD\)
 
-  * Source code for KubeArmor's custom resource defintion \(CRD\)
+  ```text
+  pkg/k8s/      - CRD Code generated by Kube-Builder
+  ```
 
-    ```text
-    pkg/k8s/      - CRD Code generated by Kube-Builder
-    ```
+* Scripts for GKE
 
-  * Scripts for GKE
+  ```text
+  GKE/          - scripts to set up the enforcer in a container-optimized OS (COS)
+  ```
 
-    ```text
-    GKE/          - scripts to set up the enforcer in a container-optimized OS (COS)
-    ```
+* Files for testing
 
-  * Files for testing
+  ```text
+  examples/     - Example microservices for testing
+  tests/        - Automated test framework for KubeArmor
+  ```
 
-    ```text
-    examples/     - Example microservices for testing
-    tests/        - Automated test framework for KubeArmor
-    ```
diff --git a/documentation/k8s_installation_guide.md → contribution/k8s_installation_guide.md b/documentation/k8s_installation_guide.md → contribution/k8s_installation_guide.md
@@ -1,4 +1,4 @@
-# Self-managed Kubernetes Installation
+# Docker and Kubernetes Installation
 
 * Requirements
 
@@ -61,3 +61,4 @@
     ```text
     $ sudo kubeadm ... (the command that you get from the master node)
     ```
+
diff --git a/documentation/technical_roadmap.md → contribution/technical_roadmap.md b/documentation/technical_roadmap.md → contribution/technical_roadmap.md
@@ -3,33 +3,25 @@
 Here, we briefly share a plan for next releases \(e.g., including features, specs, and platform supports\).
 
 * Current Release
-
   * Kubernetes Environments
-
-    - Self-managed Kubernetes \(using kubeadm), MicroK8s, Google Kubernetes Engine \(GKE\)
-
+    * Self-managed Kubernetes \(using kubeadm\), MicroK8s, Google Kubernetes Engine \(GKE\)
   * Container Platforms
-
-    - Docker, Containerd
-
+    * Docker, Containerd
   * LSM Supports
-
-    - AppArmor
-
+    * AppArmor
   * Features
 
-    - Monitor container behaviors at the system level
-
-    - Enforce security policies against:
+    * Monitor container behaviors at the system level
+    * Enforce security policies against:
 
     ```text
       Process executions  
       File accesses  
       Network operations  
-      Capabilities permitted  
+      Capabilities permitted
     ```
 
-    - Produce container-aware audit logs and system logs \(for failed system calls\) and write them into:
+    * Produce container-aware audit logs and system logs \(for failed system calls\) and write them into:
 
     ```text
       Standard output  
@@ -38,29 +30,25 @@ Here, we briefly share a plan for next releases \(e.g., including features, spec
     ```
 * Next Release
   * Kubernetes Environments
-
-    - \(extension\) Amazon Elastic Kubernetes Service \(EKS\), Azure Kubernetes Service \(AKS\)
-
+    * \(extension\) Amazon Elastic Kubernetes Service \(EKS\), Azure Kubernetes Service \(AKS\)
   * LSM Supports
-
-    - \(extension\) KRSI \(requiring Linux kernel v5.8 or newer\)
-
+    * \(extension\) KRSI \(requiring Linux kernel v5.8 or newer\)
   * Features
 
-    - \(extension\) Produce container-aware logs and write them into:
+    * \(extension\) Produce container-aware logs and write them into:
 
     ```text
       Database (e.g., MySQL and MongoDB)
     ```
 
-    - Automatically generate security policies for given containers against:
+    * Automatically generate security policies for given containers against:
 
     ```text
       Process executions  
-      Files accesses  
+      Files accesses
     ```
 
-    - Enforce security policies \(using KRSI\) against:
+    * Enforce security policies \(using KRSI\) against:
 
     ```text
       Process executions  
@@ -69,30 +57,27 @@ Here, we briefly share a plan for next releases \(e.g., including features, spec
       Capabilities permitted
     ```
 
-    - Produce telemetry data to monitoring systems
+    * Produce telemetry data to monitoring systems
 
     ```text
       Prometheus
     ```
 * Future Releases
   * Container Platforms
-
-    - \(extension\) Podman
-
+    * \(extension\) Podman
   * LSM Supports
-
-    - \(extension\) SELinux
-
+    * \(extension\) SELinux
   * Features
 
-    - Produce container-aware logs and write them into:
+    * Produce container-aware logs and write them into:
 
     ```text
       Other systems (e.g., Kafka and Elasticsearch)
     ```
 
-    - Enforce security policies against inter-container communications at the network level
+    * Enforce security policies against inter-container communications at the network level
 
     ```text
       Integration with network security solutions (e.g., Cilium)
     ```
+
diff --git a/examples/sock-shop.md b/examples/sock-shop.md
@@ -8,3 +8,4 @@ To deploy the sock-shop microservice, please run the following commands.
 $ cd examples/sock-shop
 (examples/sock-shop) $ kubectl apply -f .
 ```
+
diff --git a/examples/wordpress-mysql.md b/examples/wordpress-mysql.md
@@ -8,3 +8,4 @@ To deploy the wordpress-mysql microservice, please run the following commands.
 $ cd examples/wordpress-mysql
 (examples/wordpress-mysql) $ kubectl apply -f .
 ```
+
diff --git a/...ntation/consideration_in_policy_action.md → ...started/consideration_in_policy_action.md b/...ntation/consideration_in_policy_action.md → ...started/consideration_in_policy_action.md
@@ -7,3 +7,4 @@ If the actions of all security policies for a container are 'Block', then these
 Here, we introduce an example of how security policies are handled differently. There are two pods: pod A with \(grp=1, role=A\) and pod B with \(grp=1, role=B\). Let us say that an operator wants to block the execution of a bash shell in those pods, so the operator first defines a policy with \(selector → grp=1, process → /bin/bash, action → block\). Then, /bin/bash cannot be executed in the pods while some other applications are still executable \(blacklist\).
 
 After that, let us say that the operator also wants for the pods with role=A to execute /app only. Then, this policy will be enforced into Pod A. At this point, a problem may occur. Since Pod A has an 'Allow' policy and a 'Block' policy together, the way to handle those policies is changed from a blacklist manner to a whitelist manner, which means that Pod A will be only able to execute /app. Here, if Pod A needs to only run /app, then everything will be fine. However, what if Pod A had to implicitly execute some other applications \(e.g., /agent\)? Then, there will be a severe problem since all applications except for /app will be blocked in Pod A.
+
diff --git a/documentation/deployment_guide.md → getting-started/deployment_guide.md b/documentation/deployment_guide.md → getting-started/deployment_guide.md
@@ -52,3 +52,4 @@
      ```text
        Coming soon
      ```
+
Original file line number	Diff line number	Diff line change
Expand Up		@@ -65,3 +65,4 @@ If you want to make a contribution, please follow the steps below.
		Finally, click the "Create pull request" button.

		Now, please let us review your code. We will merge all your changes into the master branch of KubeArmor. Once your changes are merged, you will get a notification, and the issue that you fixed will be closed as well.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,3 +8,4 @@ To deploy the sock-shop microservice, please run the following commands.
		$ cd examples/sock-shop
		(examples/sock-shop) $ kubectl apply -f .
		```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,3 +8,4 @@ To deploy the wordpress-mysql microservice, please run the following commands.
		$ cd examples/wordpress-mysql
		(examples/wordpress-mysql) $ kubectl apply -f .
		```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,3 +7,4 @@ If the actions of all security policies for a container are 'Block', then these
		Here, we introduce an example of how security policies are handled differently. There are two pods: pod A with \(grp=1, role=A\) and pod B with \(grp=1, role=B\). Let us say that an operator wants to block the execution of a bash shell in those pods, so the operator first defines a policy with \(selector → grp=1, process → /bin/bash, action → block\). Then, /bin/bash cannot be executed in the pods while some other applications are still executable \(blacklist\).

		After that, let us say that the operator also wants for the pods with role=A to execute /app only. Then, this policy will be enforced into Pod A. At this point, a problem may occur. Since Pod A has an 'Allow' policy and a 'Block' policy together, the way to handle those policies is changed from a blacklist manner to a whitelist manner, which means that Pod A will be only able to execute /app. Here, if Pod A needs to only run /app, then everything will be fine. However, what if Pod A had to implicitly execute some other applications \(e.g., /agent\)? Then, there will be a severe problem since all applications except for /app will be blocked in Pod A.