Merge pull request kubearmor#95 from nam-jaehyun/master

fix typos

README.md

@@ -1,6 +1,6 @@
 # KubeArmor
 
-![Alt Text](documentation/resources/logo.png)
+![KubeArmor Logo](documentation/resources/logo.png)
 
 ## Introduction to KubeArmor
 
@@ -10,11 +10,11 @@ KubeArmor is a container-aware runtime security enforcement system that restrict
 
 KubeArmor operates with [Linux security modules \(LSMs\)](https://en.wikipedia.org/wiki/Linux_Security_Modules), meaning that it can work on top of any Linux platforms \(such as Alpine, Ubuntu, and Container-optimized OS from Google\) if Linux security modules \(e.g., [AppArmor](https://en.wikipedia.org/wiki/AppArmor), [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux), or [KRSI](https://lwn.net/Articles/808048/)\) are enabled in the Linux Kernel. KubeArmor will use the appropriate LSMs to enforce the required policies.
 
-KubeArmor is designed for Kubernetes environments; thus, operators only need to define security policies and apply them into Kubernetes. Then, KubeArmor will automatically detect the changes in security policies from Kubernetes and enforce them to the corresponding containers without any human intervention.
+KubeArmor is designed for Kubernetes environments; thus, operators only need to define security policies and apply them to Kubernetes. Then, KubeArmor will automatically detect the changes in security policies from Kubernetes and enforce them to the corresponding containers without any human intervention.
 
 If there are any violations against security policies, KubeArmor immediately generates audit logs with container identities. If operators have any logging systems, it automatically sends audit logs to their systems as well.
 
-![Alt text](documentation/resources/kubearmor_overview.png "KubeArmor High Level Design")
+![KubeArmor High Level Design](documentation/resources/kubearmor_overview.png)
 
 ## Functionality Overview
 
@@ -42,7 +42,7 @@ KubeArmor provides the ability to monitor the life cycles of containers' process
 
 * Support network security enforcement among containers
 
-KubeArmor aims to protect containers themselves rather than interactions among containers. However, using KubeArmor a user can add policies which could apply policy settings at the level of network system calls \(e.g., bind\(\), listen\(\), accept\(\), and connect\(\)\), thus somewhat controlling interactions among containers.
+KubeArmor aims to protect containers themselves rather than interactions among containers. 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 somewhat controlling interactions among containers.
 
 ## Getting Started
 
@@ -62,7 +62,7 @@ If you want to make a contribution, please refer to the following documents too.
 
 * Slack
 
-  Please join [KubeArmor Slack channel](https://kubearmor.herokuapp.com) to communicate with KubeArmor developers and other users. We always welcome having a discussion about the problems that you face during the use of KubeArmor.
+  Please join the [KubeArmor Slack channel](https://kubearmor.herokuapp.com) to communicate with KubeArmor developers and other users. We always welcome having a discussion about the problems that you face during the use of KubeArmor.
 
 ## License
 

documentation/contribution/contribution_guide.md

@@ -6,19 +6,19 @@ If you want to make a contribution, please follow the steps below.
 
    First, fork this repository by clicking on the Fork button \(top right\).
 
-![Alt text](../resources/images/fork_button.png)
+   ![fork button](../resources/images/fork_button.png)
 
    Then, click your ID on the pop-up screen.
 
-![Alt text](../resources/images/fork_screen.png)
+   ![fork screen](../resources/images/fork_screen.png)
 
    This will create a copy of KubeArmor in your account.
 
-![Alt text](../resources/images/forked_repo.png)
+   ![fork repo](../resources/images/forked_repo.png)
 
 2. Clone the repository
 
-   Now, it is time to get the code in your machine. In your machine, please run the following command.
+   Now, it is time to get the code on your machine. In your machine, please run the following command.
 
    ```text
     $ git clone https://github.com/[your GitHub ID]/KubeArmor
@@ -48,7 +48,7 @@ If you want to make a contribution, please follow the steps below.
     (KubeArmor) $ git commit -m "Add a new feature by [your name]"
    ```
 
-   Please make sure that your changes are properly tested in your machine.
+   Please make sure that your changes are properly tested on your machine.
 
 5. Push changes to your forked repository
 
@@ -62,15 +62,15 @@ If you want to make a contribution, please follow the steps below.
 
    First, go to your repository on GitHub.
 
-![Alt text](../resources/images/commit_ahead.png)
+   ![commit ahead](../resources/images/commit_ahead.png)
 
    Then, click "Pull request" button.
 
-![Alt text](../resources/images/after_pull_request.png)
+   ![after pull request](../resources/images/after_pull_request.png)
 
    After checking your changes, click 'Create pull request'.
 
-![Alt text](../resources/images/open_pull_request.png)
+   ![open pull request](../resources/images/open_pull_request.png)
 
    A pull request should contain the details of all commits as specific as possible. Also, please make sure that you have "Fixes: \#\(issue number\)".
 

documentation/contribution/development_guide.md

@@ -15,9 +15,9 @@
      LSM - AppArmor
      ```
 
-     KubeArmor is designed for Kubernetes, which means that Kubernetes should be ready in your environment. If Kubernetes is not prepared yet, please refer to [Kubernetes installation guide](k8s_installation_guide.md). KubeArmor also requires Docker or Containerd since it internally uses their APIs. If you have other container platforms \(e.g., Podman\), please make an issue in this repository. While we are going to adopt other container platforms in KubeArmor, we may be able to adjust the priorities of our planned tasks on demand. KubeArmor requires LSMs to operate properly; thus, please make sure that your environment supports LSMs \(at least, AppArmor\).
+     KubeArmor is designed for Kubernetes, which means that Kubernetes should be ready in your environment. If Kubernetes is not prepared yet, please refer to [Kubernetes installation guide](k8s_installation_guide.md). KubeArmor also requires Docker or Containerd since it internally uses its APIs. If you have other container platforms \(e.g., Podman\), please make an issue in this repository. While we are going to adopt other container platforms in KubeArmor, we may be able to adjust the priorities of our planned tasks on demand. KubeArmor requires LSMs to operate properly; thus, please make sure that your environment supports LSMs \(at least, AppArmor\).
 
-     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 KubeArmor integrates with Linux-kernel native primitives such as LSMs.
+     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 KubeArmor integrates with Linux-kernel native primitives such as LSMs.
 
      * \(Optional\) MicroK8s Setup
 
@@ -28,7 +28,7 @@
        (microk8s) $ ./install_microk8s.sh
        ```
 
-   * Environmetal Setup
+   * Environmental Setup
 
      In order to install all dependencies, please run the following command.
 
@@ -87,7 +87,7 @@
 
 ## Code Directories
 
-Here, we briefly give you the overview of KubeArmor's directories.
+Here, we briefly give you an overview of KubeArmor's directories.
 
 * Source code for KubeArmor \(/KubeArmor\)
 
@@ -112,7 +112,7 @@ Here, we briefly give you the overview of KubeArmor's directories.
   protobuf/     - Protocol buffer
   ```
 
-* Source code for KubeArmor's custom resource defintion \(CRD\)
+* Source code for KubeArmor's custom resource definition \(CRD\)
 
   ```text
   pkg/k8s/      - CRD Code generated by Kube-Builder

documentation/contribution/k8s_installation_guide.md

@@ -2,7 +2,7 @@
 
 * Requirements
 
-  You can install Docker and Kubernetes in any Ubuntu platforms.
+  You can install Docker and Kubernetes on any Ubuntu platform.
 
 * Prerequisites
 

documentation/contribution/technical_roadmap.md

@@ -1,6 +1,6 @@
 # Technical Roadmap
 
-Here, we briefly share a plan for next releases \(e.g., including features, specs, and platforms\).
+Here, we briefly share a plan for the next releases \(e.g., including features, specs, and platforms\).
 
 * Current Release
 

documentation/getting-started/consideration_in_policy_action.md

@@ -6,4 +6,6 @@ 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.
+After that, let us say that the operator also wants 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.
+
+![Action Conflict](../resources/policy_action_conflict.png)

documentation/getting-started/deployment_guide.md

@@ -13,6 +13,8 @@
 
    KubeArmor currently supports self-managed Kubernetes and Google Kubernetes Engine \(GKE\). It will support Amazon Elastic Kubernetes Service \(EKS\) and Azure Kubernetes Service \(AKS\) later.
 
+   According to your environment, you can choose one of the following.
+
    * Deploy KubeArmor in self-managed Kubernetes \(with Docker\)
 
      ```text

documentation/getting-started/security_policy_examples.md

@@ -219,7 +219,7 @@ Here, we demonstrate how to define security policies using our example microserv
 
     * Explanation: We want to block sending ICMP packets from the containers with the 'ubuntu-5' label while allowing packets for the other protocols \(e.g., TCP and UDP\). For this, we use 'matchProtocols' to define the protocol \(i.e., ICMP\) that we want to block.
 
-    * Verification: After applying this policy, please get into the container with the 'ubuntu-5' label and run 'curl www.accuknox.com'. This will work fine. Then, please run 'ping 8.8.8.8'. You will see 'permission denied' since the 'ping' command internally uese the ICMP protocol.
+    * Verification: After applying this policy, please get into the container with the 'ubuntu-5' label and run 'curl www.accuknox.com'. This will work fine. Then, please run 'ping 8.8.8.8'. You will see 'permission denied' since the 'ping' command internally uses the ICMP protocol.
 
 * Capabilities Restriction
 
@@ -243,6 +243,6 @@ Here, we demonstrate how to define security policies using our example microserv
         Block
     ```
 
-    * Explanation: We want to block any network operations using raw sockets from the containers with the 'ubuntu-2' label, meaning that containers cannot send non-TCP/UDP packets \(e.g., ICMP echo request or reply\) to other containers. To achieve this, we use matchCapabilities and specify the 'CAP\_NET\_RAW' capability to block raw socket creations inside the containers. Here, since we use stream and datagram sockets to TCP and UDP packets respectively, we can still send those packets to others.
+    * Explanation: We want to block any network operations using raw sockets from the containers with the 'ubuntu-2' label, meaning that containers cannot send non-TCP/UDP packets \(e.g., ICMP echo request or reply\) to other containers. To achieve this, we use matchCapabilities and specify the 'CAP\_NET\_RAW' capability to block raw socket creations inside the containers. Here, since we use the stream and datagram sockets to TCP and UDP packets respectively, we can still send those packets to others.
 
     * Verification: After applying this policy, please get into the container with the 'ubuntu-1' label and run 'curl www.accuknox.com'. This will work fine. Then, please run 'ping 8.8.8.8'. You will see 'operation not permitted' since the 'ping' command internally requires a raw socket to send ICMP packets.

documentation/getting-started/security_policy_specification.md

@@ -118,7 +118,7 @@ Now, we will briefly explain how to define a security policy.
 
 * Process
 
-  In the process section, there are three types of matches: matchPaths, matchDirectories, and matchPatterns. You can define specific executables using matchPaths or all executables in specific directories using matchDirectories. In the case of matchPatterns, advanced operators may be able to determine particular patterns for executables by using regular expressions. However, the coverage of regular expressions is highly dependent on AppArmor \([Policy Core Reference](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference)\). Thus, we generally do not recommend to use this match.
+  In the process section, there are three types of matches: matchPaths, matchDirectories, and matchPatterns. You can define specific executables using matchPaths or all executables in specific directories using matchDirectories. In the case of matchPatterns, advanced operators may be able to determine particular patterns for executables by using regular expressions. However, the coverage of regular expressions is highly dependent on AppArmor \([Policy Core Reference](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference)\). Thus, we generally do not recommend using this match.
 
   ```text
     process:
@@ -231,7 +231,7 @@ Now, we will briefly explain how to define a security policy.
 
 * Action
 
-  The action could be Audit, Allow, or Block, and security policies would be handled in a blacklist manner or a whitelist manner according to the action. Thus, you need to define the action carefully. You can refer to [Consideration in Policy Action](consideration_in_policy_action.md) for more details. In the case of the Audit action, we can use this action for policy verification before applying a security policy with the Block action.
+  The action could be Audit, Allow, or Block. Security policies would be handled in a blacklist manner or a whitelist manner according to the action. Thus, you need to define the action carefully. You can refer to [Consideration in Policy Action](consideration_in_policy_action.md) for more details. In the case of the Audit action, we can use this action for policy verification before applying a security policy with the Block action.
 
   When we use the Allow action, we do not get any logs for objects and operations allowed to access and conduct. Hence, if we want to get logs for such allowed accesses, we can use the AllowWithAudit action instead of the Allow action.