diff --git a/documentation/resources/images/after_pull_request.png b/.gitbook/assets/after_pull_request.png similarity index 100% rename from documentation/resources/images/after_pull_request.png rename to .gitbook/assets/after_pull_request.png diff --git a/documentation/resources/images/commit_ahead.png b/.gitbook/assets/commit_ahead.png similarity index 100% rename from documentation/resources/images/commit_ahead.png rename to .gitbook/assets/commit_ahead.png diff --git a/documentation/resources/images/fork_button.png b/.gitbook/assets/fork_button.png similarity index 100% rename from documentation/resources/images/fork_button.png rename to .gitbook/assets/fork_button.png diff --git a/documentation/resources/images/fork_screen.png b/.gitbook/assets/fork_screen.png similarity index 100% rename from documentation/resources/images/fork_screen.png rename to .gitbook/assets/fork_screen.png diff --git a/documentation/resources/images/forked_repo.png b/.gitbook/assets/forked_repo.png similarity index 100% rename from documentation/resources/images/forked_repo.png rename to .gitbook/assets/forked_repo.png diff --git a/documentation/resources/kubearmor_overview.png b/.gitbook/assets/kubearmor_overview.png similarity index 100% rename from documentation/resources/kubearmor_overview.png rename to .gitbook/assets/kubearmor_overview.png diff --git a/documentation/resources/logo.png b/.gitbook/assets/logo.png similarity index 100% rename from documentation/resources/logo.png rename to .gitbook/assets/logo.png diff --git a/documentation/resources/images/open_pull_request.png b/.gitbook/assets/open_pull_request.png similarity index 100% rename from documentation/resources/images/open_pull_request.png rename to .gitbook/assets/open_pull_request.png diff --git a/documentation/resources/policy_action_conflict.png b/.gitbook/assets/policy_action_conflict.png similarity index 100% rename from documentation/resources/policy_action_conflict.png rename to .gitbook/assets/policy_action_conflict.png diff --git a/README.md b/README.md index 79589afdef..b5458f807b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # KubeArmor -![KubeArmor Logo](documentation/resources/logo.png) +![KubeArmor Logo](.gitbook/assets/logo.png) ## Introduction to KubeArmor @@ -14,7 +14,7 @@ KubeArmor is designed for Kubernetes environments; thus, operators only need to 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. -![KubeArmor High Level Design](documentation/resources/kubearmor_overview.png) +![KubeArmor High Level Design](.gitbook/assets/kubearmor_overview.png) ## Functionality Overview @@ -48,15 +48,15 @@ KubeArmor aims to protect containers themselves rather than interactions among c Please take a look at the following documents. -1. [Deployment Guide](documentation/getting-started/deployment_guide.md) -2. [Security Policy Specification](documentation/getting-started/security_policy_specification.md) -3. [Security Policy Examples](documentation/getting-started/security_policy_examples.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) If you want to make a contribution, please refer to the following documents too. -1. [Contribution Guide](documentation/contribution/contribution_guide.md) -2. [Development Guide](documentation/contribution/development_guide.md) -3. [Technical Roadmap](documentation/contribution/technical_roadmap.md) +1. [Contribution Guide](contribution/contribution_guide.md) +2. [Development Guide](contribution/development_guide.md) +3. [Technical Roadmap](contribution/technical_roadmap.md) ## Community @@ -68,3 +68,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 index f3beacf90d..5cdf5fd887 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,29 +2,28 @@ * [KubeArmor](README.md) -## Documentation +## Getting Started -### Getting Started +* [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) -* [Deployment Guide](documentation/getting-started/deployment_guide.md) -* [Security Policy Specification](documentation/getting-started/security_policy_specification.md) -* [Security Policy Examples](documentation/getting-started/security_policy_examples.md) -* [Consideration in Policy Action](documentation/getting-started/consideration_in_policy_action.md) +## Contribution -### Contribution +* [Contribution Guide](contribution/contribution_guide.md) +* [Development Guide](contribution/development_guide.md) +* [Kubernetes Installation](contribution/k8s_installation_guide.md) +* [Technical Roadmap](contribution/technical_roadmap.md) -* [Contribution Guide](documentation/contribution/contribution_guide.md) -* [Development Guide](documentation/contribution/development_guide.md) -* [Kubernetes Installation](documentation/contribution/k8s_installation_guide.md) -* [Technical Roadmap](documentation/contribution/technical_roadmap.md) +## Reference -### Reference - -* [Supported Capability List](documentation/reference/supported_capability_list.md) -* [Supported Operation List](documentation/reference/supported_operation_list.md) +* [Supported Capability List](reference/supported_capability_list.md) +* [Supported Operation List](reference/supported_operation_list.md) ## Examples * [Multiubuntu](examples/multiubuntu.md) * [Sock-Shop](examples/sock-shop.md) * [Wordpress-MySQL](examples/wordpress-mysql.md) + diff --git a/documentation/contribution/contribution_guide.md b/contribution/contribution_guide.md similarity index 79% rename from documentation/contribution/contribution_guide.md rename to contribution/contribution_guide.md index 8cbd3aaaeb..02d663656c 100644 --- a/documentation/contribution/contribution_guide.md +++ b/contribution/contribution_guide.md @@ -6,15 +6,17 @@ If you want to make a contribution, please follow the steps below. First, fork this repository by clicking on the Fork button \(top right\). - ![fork button](../resources/images/fork_button.png) + ![fork button](../.gitbook/assets/fork_button.png) + Then, click your ID on the pop-up screen. - ![fork screen](../resources/images/fork_screen.png) + ![fork screen](../.gitbook/assets/fork_screen.png) + This will create a copy of KubeArmor in your account. - ![fork repo](../resources/images/forked_repo.png) + ![fork repo](../.gitbook/assets/forked_repo.png) 2. Clone the repository @@ -24,13 +26,13 @@ If you want to make a contribution, please follow the steps below. $ git clone https://github.com/[your GitHub ID]/KubeArmor ``` - Then, you will get the full code of KubeArmor in your machine. + Then, you will get the full code of KubeArmor in your machine. 3. Make changes First, go into the repository directory and make some changes. - Please refer to [development guide](development_guide.md) to set up your environment for KubeArmor contribution. + Please refer to [development guide](development_guide.md) to set up your environment for KubeArmor contribution. 4. Commit the changes @@ -48,7 +50,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 on your machine. + Please make sure that your changes are properly tested on your machine. 5. Push changes to your forked repository @@ -62,18 +64,24 @@ If you want to make a contribution, please follow the steps below. First, go to your repository on GitHub. - ![commit ahead](../resources/images/commit_ahead.png) + ![commit ahead](../.gitbook/assets/commit_ahead.png) + Then, click "Pull request" button. - ![after pull request](../resources/images/after_pull_request.png) + ![after pull request](../.gitbook/assets/after_pull_request.png) + After checking your changes, click 'Create pull request'. - ![open pull request](../resources/images/open_pull_request.png) + ![open pull request](../.gitbook/assets/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\)". - A pull request should contain the details of all commits as specific as possible. Also, please make sure that you have "Fixes: \#\(issue number\)". Finally, click the "Create pull request" button. + The changes would be merged post a review by the respective module owners. Once the changes are merged, you will get a notification, and the corresponding issue will be closed. + diff --git a/documentation/contribution/development_guide.md b/contribution/development_guide.md similarity index 97% rename from documentation/contribution/development_guide.md rename to contribution/development_guide.md index 99568c9c6f..8d6c761136 100644 --- a/documentation/contribution/development_guide.md +++ b/contribution/development_guide.md @@ -3,7 +3,6 @@ ## Development 1. Self-managed Kubernetes - * Requirements Here is the list of minimum requirements for self-managed Kubernetes. @@ -17,7 +16,9 @@ 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 @@ -39,10 +40,8 @@ [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. - + 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 @@ -130,3 +129,4 @@ Here, we briefly give you an overview of KubeArmor's directories. examples/ - Example microservices for testing tests/ - Automated test framework for KubeArmor ``` + diff --git a/documentation/contribution/k8s_installation_guide.md b/contribution/k8s_installation_guide.md similarity index 88% rename from documentation/contribution/k8s_installation_guide.md rename to contribution/k8s_installation_guide.md index d768458ca8..14065b5b20 100644 --- a/documentation/contribution/k8s_installation_guide.md +++ b/contribution/k8s_installation_guide.md @@ -2,7 +2,7 @@ * Requirements - You can install Docker and Kubernetes on any Ubuntu platform. + You can install Docker and Kubernetes on any Ubuntu platform. * Prerequisites @@ -40,11 +40,12 @@ (k8s) $ ./initialize_kubernetes.sh [ weave | calico | cilium ] master ``` - Please make sure that you need to put "master" at the above command end if you have only a single machine. + Please make sure that you need to put "master" at the above command end if you have only a single machine. * Kubernetes Installation \(multiple machines\) - If you use multiple machines to set up a multi-node environment, Please run the following command. + If you use multiple machines to set up a multi-node environment, Please run the following commands. + * Master Node @@ -54,10 +55,11 @@ (k8s) $ ./initialize_kubernetes.sh [ flannel | weave | calico | cilium ] (master) ``` - Here, the master node will only serve Kubernetes services since you do not put "master" at the above command end. However, if you also want to use the master node to deploy containers, you can put "master" at the above command end. + Here, the master node will only serve Kubernetes services since you do not put "master" at the above command end. However, if you also want to use the master node to deploy containers, you can put "master" at the above command end. * Worker Node ```text $ sudo kubeadm ... (the command that you get from the master node) ``` + diff --git a/documentation/contribution/technical_roadmap.md b/contribution/technical_roadmap.md similarity index 91% rename from documentation/contribution/technical_roadmap.md rename to contribution/technical_roadmap.md index 5171b0b615..6187500896 100644 --- a/documentation/contribution/technical_roadmap.md +++ b/contribution/technical_roadmap.md @@ -3,19 +3,12 @@ Here, we briefly share a plan for the next releases \(e.g., including features, specs, and platforms\). * 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 @@ -35,17 +28,11 @@ Here, we briefly share a plan for the next releases \(e.g., including features, Log file gRPC ``` - * 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: @@ -75,17 +62,11 @@ Here, we briefly share a plan for the next releases \(e.g., including features, ```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: @@ -99,3 +80,4 @@ Here, we briefly share a plan for the next releases \(e.g., including features, ```text Integration with network security solutions (e.g., Cilium) ``` + diff --git a/examples/multiubuntu.md b/examples/multiubuntu.md index 9e69d1eb27..a3b295b6d0 100644 --- a/examples/multiubuntu.md +++ b/examples/multiubuntu.md @@ -58,3 +58,4 @@ $ kubectl -n multiubuntu exec -it {pod name for ubuntu 5} -- bash ```text $ kubectl -n kube-system exec -it {KubeArmor in the node where ubuntu 5 is located} -- tail /tmp/kubearmor.log ``` + diff --git a/examples/sock-shop.md b/examples/sock-shop.md index 44fd9ff8b6..db64845609 100644 --- 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 index b7feb69dbd..eb5b631f8b 100644 --- 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/documentation/getting-started/consideration_in_policy_action.md b/getting-started/consideration_in_policy_action.md similarity index 96% rename from documentation/getting-started/consideration_in_policy_action.md rename to getting-started/consideration_in_policy_action.md index e5df2224d3..1c9783aa86 100644 --- a/documentation/getting-started/consideration_in_policy_action.md +++ b/getting-started/consideration_in_policy_action.md @@ -8,4 +8,5 @@ Here, we introduce an example of how security policies are handled differently. 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) +![Action Conflict](../.gitbook/assets/policy_action_conflict.png) + diff --git a/documentation/getting-started/deployment_guide.md b/getting-started/deployment_guide.md similarity index 98% rename from documentation/getting-started/deployment_guide.md rename to getting-started/deployment_guide.md index 71e5bfd10a..dcfdf70de0 100644 --- a/documentation/getting-started/deployment_guide.md +++ b/getting-started/deployment_guide.md @@ -11,9 +11,11 @@ 2. Deploy KubeArmor in your Kubernetes environment - 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. + 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. - According to your environment, you can choose one of the following. * Deploy KubeArmor in self-managed Kubernetes \(with Docker\) @@ -54,3 +56,4 @@ ```text Coming soon ``` + diff --git a/documentation/getting-started/security_policy_examples.md b/getting-started/security_policy_examples.md similarity index 98% rename from documentation/getting-started/security_policy_examples.md rename to getting-started/security_policy_examples.md index 307380ea1a..41d9395b66 100644 --- a/documentation/getting-started/security_policy_examples.md +++ b/getting-started/security_policy_examples.md @@ -3,7 +3,6 @@ Here, we demonstrate how to define security policies using our example microservice \(multiubuntu\). * Process Execution Restriction - * Block a specific executable \([ksp-group-1-proc-path-block.yaml](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-group-1-proc-path-block.yaml)\) ```text @@ -25,8 +24,7 @@ Here, we demonstrate how to define security policies using our example microserv ``` * Explanation: The purpose of this policy is to block the execution of '/bin/sleep' in the containers with the 'group-1' label. For this, we define the 'group-1' label in selector -> matchLabels and the specific path \('/bin/sleep'\) in process -> matchPaths. Also, we put 'Block' as the action of this policy. - - * Verification: After applying this policy, please get into one of the containers with the 'group-1' \(using "kubectl -n multiubuntu exec -it ubuntu-X-deployment-... -- bash"\) and run '/bin/sleep'. You will see that /bin/sleep is blocked. + * Verification: After applying this policy, please get into one of the containers with the 'group-1' \(using "kubectl -n multiubuntu exec -it ubuntu-X-deployment-... -- bash"\) and run '/bin/sleep'. You will see that /bin/sleep is blocked. * Block all executables in a specific directory \([ksp-ubuntu-1-proc-dir-block.yaml](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-ubuntu-1-proc-dir-block.yaml)\) @@ -49,8 +47,7 @@ Here, we demonstrate how to define security policies using our example microserv ``` * Explanation: The purpose of this policy is to block all executables in the '/sbin' directory. Since we want to block all executables rather than a specific executable, we use matchDirectories to specify the executables in the '/sbin' directory at once. - - * Verification: After applying this policy, please get into the container with the 'ubuntu-1' label and run '/sbin/route' to see if this command is allowed \(this command will be blocked\). + * Verification: After applying this policy, please get into the container with the 'ubuntu-1' label and run '/sbin/route' to see if this command is allowed \(this command will be blocked\). * Block all executables in a specific directory and its subdirectories \([ksp-ubuntu-2-proc-dir-recursive-block.yaml](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-ubuntu-2-proc-dir-recursive-block.yaml)\) @@ -74,8 +71,7 @@ Here, we demonstrate how to define security policies using our example microserv ``` * Explanation: As the extension of the previous policy, we want to block all executables in the '/usr' directory and its subdirectories \(e.g., '/usr/bin', '/usr/sbin', and '/usr/local/bin'\). Thus, we add 'recursive: true' to extend the scope of the policy. - - * Verification: After applying this policy, please get into the container with the 'ubuntu-2' label and run '/usr/bin/env' or '/usr/bin/whoami'. You will see that those commands are blocked. + * Verification: After applying this policy, please get into the container with the 'ubuntu-2' label and run '/usr/bin/env' or '/usr/bin/whoami'. You will see that those commands are blocked. * Allow specific executables only \([ksp-ubuntu-3-proc-dir-allow.yaml](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-ubuntu-3-proc-dir-allow.yaml)\) @@ -102,8 +98,7 @@ Here, we demonstrate how to define security policies using our example microserv ``` * Explanation: Unlike the previous policies, we want the container with the 'ubuntu-3' label only to execute specific executables. To achieve this goal, we first define the scope of this policy using matchDirectories \(you can also use matchPaths\). Then, we define the 'Allow' action instead of the 'Block' action. - - * Verification: In this policy, we allow some files \(i.e., /credentials/\*\) for verification. After applying this policy, please get into the container with the 'ubuntu-3' label and run 'cd /credentials', 'ls', and 'cat /credentials/password'. You will see that all of the binaries in /bin work well. Now, please simply run 'awk' or 'diff'. Then, those commands will be blocked since they are in /usr/bin. + * Verification: In this policy, we allow some files \(i.e., /credentials/\*\) for verification. After applying this policy, please get into the container with the 'ubuntu-3' label and run 'cd /credentials', 'ls', and 'cat /credentials/password'. You will see that all of the binaries in /bin work well. Now, please simply run 'awk' or 'diff'. Then, those commands will be blocked since they are in /usr/bin. * Allow a specific executable to be launched by its owner only \([ksp-ubuntu-3-proc-path-owner-only.yaml](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-ubuntu-3-proc-path-owner-only.yaml)\) @@ -136,11 +131,8 @@ Here, we demonstrate how to define security policies using our example microserv ``` * Explanation: This policy aims to allow a specific user \(i.e., user1\) only to launch its own executable \(i.e., hello\), which means that we do not want for the root user to even launch /home/user1/hello. For this, we define a security policy similar to the above ones, but we specifically add 'ownerOnly: true'. - - * Verification: For verification, we allow /bin/su and some files used by /bin/su to change users \(from 'root' to 'user1'\) in the policy. After applying this policy, please get into the container with the 'ubuntu-3' label and run '/home/user1/hello' first. This command will be blocked even though you are the 'root' user. Then, please run 'su - user1'. Now, you are the 'user1' user. Please run '/home/user1/hello' again. You will see that it works now. - + * Verification: For verification, we allow /bin/su and some files used by /bin/su to change users \(from 'root' to 'user1'\) in the policy. After applying this policy, please get into the container with the 'ubuntu-3' label and run '/home/user1/hello' first. This command will be blocked even though you are the 'root' user. Then, please run 'su - user1'. Now, you are the 'user1' user. Please run '/home/user1/hello' again. You will see that it works now. * File Access Restriction - * Allow accessing specific files only \([ksp-ubuntu-4-file-path-readonly-allow.yaml](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-ubuntu-4-file-path-readonly-allow.yaml)\) ```text @@ -167,8 +159,7 @@ Here, we demonstrate how to define security policies using our example microserv ``` * Explanation: The purpose of this policy is to allow the container with the 'ubuntu-4' label to access '/secret.txt' and '/credentials/password' only. We also want the container to read '/credentials/password' only \(the write operation is blocked\) while allowing the container to read and write '/secret.txt'. - - * Verification: For testing, we allow binaries in /bin. After applying this policy, please get into the container with the 'ubuntu-4' label and run 'cat /secret.txt' and 'cat /credentials/password'. You can see the contents in those files. Now, please run 'echo \"test\" >> /secret.txt'. This command will work fine. Please run 'echo \"test\" >> /credentials/password'. You will see that the write operation will be blocked. + * Verification: For testing, we allow binaries in /bin. After applying this policy, please get into the container with the 'ubuntu-4' label and run 'cat /secret.txt' and 'cat /credentials/password'. You can see the contents in those files. Now, please run 'echo \"test\" >> /secret.txt'. This command will work fine. Please run 'echo \"test\" >> /credentials/password'. You will see that the write operation will be blocked. * Block all file accesses in a specific directory and its subdirectories \([ksp-ubuntu-5-file-dir-recursive-block.yaml](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-ubuntu-5-file-dir-recursive-block.yaml)\) @@ -192,11 +183,8 @@ Here, we demonstrate how to define security policies using our example microserv ``` * Explanation: In this policy, we do not want the container with the 'ubuntu-5' label to access any files in the '/credentials' directory and subdirectories. Thus, we use 'matchDirectories' and 'recursive: true' to define all files in the '/credentials' directory and its subdirectories. - - * Verification: After applying this policy, please get into the container with the 'ubuntu-5' label and run 'cat /secret.txt'. You will see the contents of /secret.txt. Then, please run 'cat /credentials/password'. This command will be blocked due to the security policy. - + * Verification: After applying this policy, please get into the container with the 'ubuntu-5' label and run 'cat /secret.txt'. You will see the contents of /secret.txt. Then, please run 'cat /credentials/password'. This command will be blocked due to the security policy. * Network Operation Restriction - * Block ICMP packets \([ksp-ubuntu-5-net-icmp-block](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-ubuntu-5-net-icmp-block.yaml)\) ```text @@ -218,11 +206,8 @@ 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 uses 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 - * Block Raw Sockets \(i.e., non-TCP/UDP packets\) \([ksp-ubuntu-1-cap-net-raw-block.yaml](https://github.com/accuknox/KubeArmor/tree/master/examples/multiubuntu/security-policies/ksp-ubuntu-1-cap-net-raw-block.yaml)\) ```text @@ -244,5 +229,5 @@ Here, we demonstrate how to define security policies using our example microserv ``` * 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. + diff --git a/documentation/getting-started/security_policy_specification.md b/getting-started/security_policy_specification.md similarity index 95% rename from documentation/getting-started/security_policy_specification.md rename to getting-started/security_policy_specification.md index 5e8862038a..a3c33aeef7 100644 --- a/documentation/getting-started/security_policy_specification.md +++ b/getting-started/security_policy_specification.md @@ -154,9 +154,7 @@ Now, we will briefly explain how to define a security policy. * fromSource - If a path or a directory is specified in fromSource, the executable of the path or the executables in the directory will be allowed/blocked to execute the executables defined with matchPaths or matchDirectories. - - For better understanding, let us say that an operator defines a policy as follows. Then, /bin/bash will be only allowed to execute /bin/sleep. Otherwise, the execution of /bin/sleep will be blocked. + If a path or a directory is specified in fromSource, the executable of the path or those in the directory will be allowed/blocked to execute the executables defined with matchPaths or matchDirectories. For better understanding, let us say that an operator defines a policy as follows. Then, /bin/bash will be only allowed to execute /bin/sleep. Otherwise, the execution of /bin/sleep will be blocked. ```text process: @@ -199,7 +197,7 @@ Now, we will briefly explain how to define a security policy. * readOnly \(static action: allow to read only; otherwise block all\) - If this is enabled, the read operation will be only allowed, and any other operations \(e.g., write\) will be blocked. + If this is enabled, the read operation will be only allowed, and any other operations \(e.g., write\) will be blocked. * Network @@ -233,8 +231,10 @@ Now, we will briefly explain how to define a security policy. 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. ```text action: [Audit|Allow|Block|AllowWithAudit|BlockWithAudit] ``` + diff --git a/documentation/reference/supported_capability_list.md b/reference/supported_capability_list.md similarity index 99% rename from documentation/reference/supported_capability_list.md rename to reference/supported_capability_list.md index fef25f11c0..e8e52b09c3 100644 --- a/documentation/reference/supported_capability_list.md +++ b/reference/supported_capability_list.md @@ -38,3 +38,4 @@ setfcap mac_override mac_admin ``` + diff --git a/documentation/reference/supported_operation_list.md b/reference/supported_operation_list.md similarity index 98% rename from documentation/reference/supported_operation_list.md rename to reference/supported_operation_list.md index 476888ecae..10b5d65ffc 100644 --- a/documentation/reference/supported_operation_list.md +++ b/reference/supported_operation_list.md @@ -5,3 +5,4 @@ The operations that are currently supported are: ```text TBF ``` +