diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d4e7dc7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +_book/ + diff --git a/000 - Introduction.md b/000 - Introduction.md index bb99707..1c02794 100644 --- a/000 - Introduction.md +++ b/000 - Introduction.md @@ -10,7 +10,7 @@ This document is helping you to secure your containerized environment and keep i There are often misunderstandings of what the security impacts - negative or positive - are supposed to be when using Docker. -Docker as any other containerization technology doesn't solve application security problems. It doesn't help doing input validation and it doesn't provide protecting against SQL injection. For application security risks OWASP provides a lot of other useful documents, starting from the OWASP Top 10 over the [https://www.owasp.org/index.php/OWASP_Proactive_Controls OWASP Proactive Controls] to the [https://www.owasp.org/index.php/Category:OWASP_Application_Security_Verification_Standard_Project OWASP Application Security Verification standard] -- just to name a few. +Docker as any other containerization technology doesn't solve application security problems. It doesn't help doing input validation and it doesn't provide protecting against SQL injection. For application security risks OWASP provides a lot of other useful documents, starting from the OWASP Top 10 over the [OWASP Proactive Controls](https://www.owasp.org/index.php/OWASP_Proactive_Controls) to the [OWASP Application Security Verification standard]([https://www.owasp.org/index.php/Category:OWASP_Application_Security_Verification_Standard_Project) -- just to name a few. Container Security is mostly about system and network security and a secure architectural design. @@ -22,7 +22,7 @@ Looking at it from the perspective of the classical world, especially in system Apart from these technical areas there are two non-technical points: -* Docker with its 5 years is a relatively new technology. Subtracting the time for maturing and adoption the time span is even shorter. Every new technology needs time until the knowledge of the technology and their best practices becomes common knowledge. +* Docker is not a new technology anymore but subtracting the time for maturing and adoption, its time span is shorter. Every technology needs time until the knowledge of the technology and their best practices becomes common knowledge. * While container solutions might offer benefits for the developer, the technology is not simple from the security perspective. Not being simple is what makes security more difficult, a.k.a. the _KISS principle_ -- keep it simple and stupid. This is what this document is trying to help you with: It provides you with the knowledge to avoid common pitfalls in the system and network area and it tries to get a handle on the complexity. @@ -31,4 +31,12 @@ This is what this document is trying to help you with: It provides you with the In order to achieve this, this document first does an analysis of the threats caused by the technology. This is the basis for the ten points to follow. +Each of those ten points has paragraphs in the following order: + * introduction, + * outline of threat scenarios, + * recommendation how to prevent the aforementioned threats, + * technical hint how to identify whether you might a problem here + * and eventually lists references (split in commercial and non-commercial ones) + +It is mostly agnostic to any orchestration framework or any other specific product (OS, programming language). diff --git a/001 - Threats.md b/001 - Threats.md index b8d2163..6cc2d40 100644 --- a/001 - Threats.md +++ b/001 - Threats.md @@ -5,6 +5,9 @@ The classical approach how to secure an environment is looking at it from the at Those vectors will help you to define what needs to be protected. With this definition one can put security controls in place to provide a baseline protection and beyond. This is what the ten controls in the following chapters are about. +The following image gives an overview of threats in docker. +![threat-overview](assets/threats.png) + ### Threat 1: Container Escape (System) @@ -35,17 +38,17 @@ This again has the same first vector as the one mentioned before. With his shell ### Threat 6: Resource Starvation The underlying vector is due to a security condition from another container -running on the same host. The security condition could be either to the +running on the same host. The security condition could be due to the fact that the other container is eating up resources which could be CPU cycles, RAM, network or disk-I/O. It could also be that the container has a host file system mounted which the -attacker has been filling up which causes problem on the host which in turn +attacker has been filling up which causes problems on the host which in turn affects other containers. ### Threat 7: Host compromise -Whereas the previous threat the attacker managed indirectly over the host to affect +Whereas in the previous threat the attacker managed indirectly over the host to affect another / other containers, here the attacker has compromised the host -- either through another container or through the network. @@ -56,7 +59,7 @@ The CD pipeline could involve several hops where the mini operating system image been passed from one step to the next until it reaches the deployment. Every hop is a potential attack surface for the attacker. If an attacker manages -to get foot into one step and there's no integrity check whether what will be +to get a foothold into one step and there's no integrity check whether what will be deployed is what should be deployed there is the threat that on behalf of the attacker images with his malicious payloads are being deployed. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fe12c13 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,27 @@ + +## Contributions / participation + +is always welcome! + +Note please the following: + +* One PR per feature or bug fix or improvement. Please do not mix issues. +* Document your PR in the commit message +* To lower the bar: For a few points being not yet complete we have dev branches like D06_dev, D07_dev. If your input is important but not complete or needs more or less polishing or amendments before being merged to main those branches are the ones you should issue use your PRs against. +* If your PR is a WIP, please mark it accordingly. Remove that when you think you're done. + +## Document Structure + +For an amendment or if you want to fill in blanks for one of the ten points please follow the document structure: + + * Introduction + * Examples of threat scenarios + * Recommendation how to prevent the aforementioned threats + * Technical hints how to identify whether you might have a problem here + * References (split in commercial and non-commercial ones) + +Try to be as non-specific with respect to orchestration frameworks or any other product (OS, programming language). + + +For questions just open an issue. + diff --git a/D00 - Overview.md b/D00 - Overview.md index 3129c04..df18892 100644 --- a/D00 - Overview.md +++ b/D00 - Overview.md @@ -2,15 +2,15 @@ | Title | Description | | -- | -- | -| D01 - Secure User Mapping | Often the main security advantage of Docker is neglected: The application within the container runs with administrative privileges: root. This violates the least privilege principle and gives an attacker better chances further extending his activities if he manages to break out of the application into the container. From the host perspective the application should never run as root. | -| D02 - Patch Management Strategy | The host, the containment technology, the orchestration solution and the minimal operating system images in the container will have security bugs. Once publicly known it is vital for your security posture to address the bugs. For all domains mentioned you need to decide when you apply regular and emergency patches. | -| D03 - Network Separation and Firewalling | You properly need to design your network upfront. Management interfaces from the orchestration tool as well as network services are crucial and need to be protected on a network level. Also make sure that all other network based microservices are only exposed to the legitimate consumer of this microservice and not to the whole network. | +| D01 - Secure User Mapping | Most often the application within the container runs with the default administrative privileges: root. This violates the least privilege principle and gives an attacker better chances further extending his activities if he manages to break out of the application into the container. From the host perspective the application should never run as root. | +| D02 - Patch Management Strategy | The host, the containment technology, the orchestration solution and the minimal operating system images in the container will have security bugs. Once publicly known it is vital for your security posture to address those bugs in a timely fashion. For all those components mentioned you need to decide when you apply regular and emergency patches before you put those into production. | +| D03 - Network Segmentation and Firewalling | You properly need to design your network upfront. Management interfaces from the orchestration tool and especially network services from the host are crucial and need to be protected on a network level. Also make sure that all other network based microservices are only exposed to the legitimate consumer of this microservice and not to the whole network. | | D04 - Secure Defaults and Hardening | Depending on your choice of host and container operating system and orchestration tool you have to take care that no unneeded components are installed or started. Also all needed components need to be properly configured and locked down. | -| D05 - Maintain Security Contexts | Mixing production containers on one host with other stages of undefined or less secure containers may open a backdoor to your production. Also mixing e.g. frontend with backend services on one host may have a negative security impact. | -| D06 - Protect Secrets | Authentication and authorization of a microservice against a peer or a third party requires secrets to be provided. Also for an attacker those secrets potentially provide access to your data. Any passwords, tokens, private keys or certificates need to be protected as good as possible. | -| D07 - Resource Protection | As all containers share the same physical CPU, disks, memory and networks those physical resources need to be protected so that a single container running out of control -- deliberately or not -- doesn't affect any other container's resources. | -| D08 - Container Image Integrity and Origin | The minimal operating system in the container runs your code and needs to be fully trustworthy, starting from the origin up until the deployment. You need to make sure that all transfers as well as the images at rest are secure. | -| D09 - Follow Immutable Paradigm | Often container images don't need to write into their filesystem or a mounted filesystem, once set up and deployed. In those cases you have a extra security benefit if you start the containers in read-only mode. | -| D10 - Logging | For your container image, orchestration tool and host you need to log all security relevant events on a system and API level. All logs should be remote, they should contain a common timestamp and they should be tamper proof. Your application should also provide remote logging, not into the container. +| D05 - Maintain Security Contexts | Mixing production containers on one host with other stages of undefined or less secure containers may open a backdoor to your production. Also mixing e.g. frontend with backend services on one host may have negative security impacts. | +| D06 - Protect Secrets | Authentication and authorization of a microservice against a peer or a third party requires secrets to be provided. For an attacker those secrets potentially enable him to access more of your data or services. Thus any passwords, tokens, private keys or certificates need to be protected as good as possible. | +| D07 - Resource Protection | As all containers share the same physical CPU, disks, memory and networks. Those physical resources need to be protected so that a single container running out of control -- deliberately or not -- doesn't affect any other container's resources. | +| D08 - Container Image Integrity and Origin | The minimal operating system in the container runs your code and needs to be trustworthy, starting from the origin up until the deployment. You need to make sure that all transfers and images at rest haven't been tampered with. | +| D09 - Follow Immutable Paradigm | Often container images don't need to write into their filesystem or a mounted filesystem, once set up and deployed. In those cases you have an extra security benefit if you start the containers in read-only mode. | +| D10 - Logging | For your container image, orchestration tool and host you need to log all security relevant events on a system and API level. All logs should be remote, they should contain a common timestamp and they should be tamper proof. Your application should also provide remote logging. diff --git a/D01 - Secure User Mapping.md b/D01 - Secure User Mapping.md index af8c444..ff720db 100644 --- a/D01 - Secure User Mapping.md +++ b/D01 - Secure User Mapping.md @@ -3,24 +3,30 @@ ## Threat Scenarios -The threat is here that a microservice is being offered to run under `root` in the container. If the service contains a weakness the attacker has full privileges within the container. While there's still some default protection left (Linux capabilities, either AppArmor or SELinux profiles) it removes one layer of protection. This extra layer broadens the attack surface. It also violates the least privilege principle [1] and from the OWASP perspective an insecure default. +The threat is here that a microservice is being offered to run under `root` in the container. If the service contains a weakness the attacker has full privileges within the container. While there's still some default protection left (Linux capabilities, either AppArmor or SELinux profiles) it removes one layer of protection. This extra layer broadens the attack surface. It also violates the least privilege principle [1] and from the OWASP perspective is an insecure default. -It should be noted that it is very dangerous for the host and all containers on this host to run a privileged container (`--privileged`) as it removes almost every restriction. Root in a container can access e.g. block devices, the /proc and /sys file system on the host and with a little work it can also load modules on the host [2]. +For privileged containers (`--privileged`) a breakout from the microservice into the container is almost comparable to run without any container. Privileged containers endanger your whole host and all other containers. ## How Do I prevent? -It is important to run your microservice with the least privilege possible. The good thing is that containers are unprivileged, unless you have configured them explicitly differently (e.g. `docker run --privileged`). However running your microservice under a different user as root requires configuration. You need to configure your mini distribution of your container to both contain a user (and maybe a group) and your service needs to make use of this user and group. +It is important to run your microservice with the least privilege possible. + +First of all: Never use the `--privileged` flag. It gives all so-called capabilities (see D04) to the container and it can access host devices (`/dev`) including disks, and also has access to the `/sys` and `/proc` filesystem. And with a little work the container can even load kernel modules on the host [2]. The good thing is that containers are per default unprivileged. You would have to configure them explicitly to run privileged. + +However still running your microservice under a different user as root requires configuration. You need to configure your mini distribution of your container to both contain a user (and maybe a group) and your service needs to make use of this user and group. Basically there are two choices. -In a simple container scenario if you build your container you have to add `RUN useradd ` or `RUN adduser ` with the appropriate parameters -- respectively the same applies for group IDs. Then, before you start the microservice, the `USER ` [3] switches to this user. Please note that a standard web server wants to use a port like 80 or 443. Configuring a user doesn't let you bind the server on any port below 1024. There's no need at all to bind to a low port for any service. You need to configure a higher port and map this port accordingly with the expose command [4]. Your mileage may vary if you're using an orchestration tool. +In a simple container scenario if you build your container you have to add `RUN useradd ` or `RUN adduser ` with the appropriate parameters -- respectively the same applies for group IDs. Then, before you start the microservice, the `USER ` [3] switches to this user. Please note that a standard web server wants to use a port like 80 or 443. Configuring a user doesn't let you bind the server on any port below 1024. There's no need at all to bind to a low port for any service. You should then configure a higher port and map this port accordingly with the expose command [4]. If a binary needs root for other reasons you can grant them the capabitlity only using `setcap` instead of full root privileges [5]. -The second choice would be using Linux *user namespaces*. Namespaces are a general means to provide to a container a different (faked) view of Linux kernel resources. There are different resources available like User, Network, PID, IPC, see `namespaces(7)`. In the case of *user namespaces* a container could be provided with a his view of a standard root user whereas the host kernel maps this to a different user ID. More, see [5], `cgroup_namespaces(7)` and `user_namespaces(7)`. +The second choice would be using Linux *user namespaces*. Namespaces are a general means to provide to a container a different (faked) view of Linux kernel resources. There are different resources available like User, Network, PID, IPC, see `namespaces(7)`. In the case of *user namespaces* a container could be provided with a relative perspective of a standard root user whereas the host kernel maps this to a different user ID. More, see [6], `cgroup_namespaces(7)` and `user_namespaces(7)`. -The catch using namespaces is that you can only run one namespace at a time. If you run user namespacing you e.g. can't use network namespacing on the same host [6]. Also, all your containers on a host will be defaulted to it, unless you explicitly configure this differently per container. +User namespace does come with some limitations [7]. If you run user namespacing you e.g. can't share network/pid namespace with the host `--pid=host` or `--network=host`. Also, all your containers on a host will be defaulted to it, unless you explicitly configure this differently per container. +In any case use user IDs which haven't been taken yet. If you e.g. run a service in a container which maps outside the container to a `systemd` user, this is not necessarily better. +Your mileage may vary if you're using an orchestration tool. In an orchestrated environment make sure that you have a proper pod security policy. ## How can I find out? @@ -40,9 +46,7 @@ Have a look in the process list of the host, or use `docker top` or `docker insp #### User namespaces -The files `/etc/subuid` and `/etc/subgid` do the uid mapping for all containers. If they don't exist and `/var/lib/docker/` doesn't contain -any other entries owned by `root:root` you're not using any uid remapping. On the other hand if those files exist and there are files in that directory you still need to check whether your docker daemon was started with `--userns-remap` or the config file `/etc/docker/daemon.json` was used. - +The files `/etc/subuid` and `/etc/subgid` do the UID mapping for all containers. If they don't exist and `/var/lib/docker/` doesn't contain any other entries owned by `root:root` you're not using any UID remapping. On the other hand if those files exist and there are files in that directory you still need to check whether your docker daemon was started with `--userns-remap` or the config file `/etc/docker/daemon.json` was used. @@ -50,8 +54,9 @@ any other entries owned by `root:root` you're not using any uid remapping. On th * [1] [OWASP: Security by Design Principles](https://www.owasp.org/index.php/Security_by_Design_Principles#Principle_of_Least_privilege) * [3] [Docker Docs: USER command](https://docs.docker.com/engine/reference/builder/#user) * [4] [Docker Docs: EXPOSE command](https://docs.docker.com/engine/reference/builder/#expose) -* [5] [Docker Docs: Isolate containers with a user namespace](https://docs.docker.com/engine/security/userns-remap/) -* [6] [Docker Docs: User namespace known limitations](https://docs.docker.com/engine/security/userns-remap/#user-namespace-known-restrictions) +* [5] Rasene's blog: https://raesene.github.io/blog/2017/07/23/network-tools-in-nonroot-docker-images/ +* [6] [Docker Docs: Isolate containers with a user namespace](https://docs.docker.com/engine/security/userns-remap/) +* [7] [Docker Docs: User namespace known limitations](https://docs.docker.com/engine/security/userns-remap/#user-namespace-known-restrictions) ### Commercial diff --git a/D02 - Patch Management Strategy.md b/D02 - Patch Management Strategy.md index a995b4d..bfb9f58 100644 --- a/D02 - Patch Management Strategy.md +++ b/D02 - Patch Management Strategy.md @@ -1,16 +1,22 @@ # D02 - Patch Management Strategy -Please note that by patch management strategy (patch management plan or policy, or security SLA are used synonymous) in the following paragraphs the scope is not primarily a technical one: It's necessary to agree and have an approval _when_ certain patches will be applied. Often this strategy would be a task of an Information Security Officer. But not having an ISO is no excuse for not having a patch management strategy. +Not patching the infrastructure in a timely fashion is still the most frequent security problem in the IT industry which proved Viruses like WannaCry or NotPetya. Most software defects from "off the shelf software" are well known for some time before exploits are written and used. Sometimes not even a sophisticated exploit is needed. All you need to do is patching those known vulnerabilities soon enough. + +This is similar to OWASP Top 10's "Known Vulnerabilities" [1]. + +It's necessary to agree and have a policy or at least a common understanding _when_ certain patches will be applied. Often this strategy would be a task of an Information Security Officer, an ISO or CISO. Not having an (C)ISO is no excuse for not having a patch management strategy. Please note that by the term patch management strategy in this paragraph the scope intended is not primarily a technical one. Synonymous terms for patch management strategy are patch management policy or plan, or security SLA. ## Threat Scenarios -The worst thing which can happen to your container environment is that either the host(s) are compromised or the orchestration tool. The first would enable the attacker to control all the containers running on the host, the second will enable the attacker to control all containers on _all_ hosts which the software is managing. +The worst thing which can happen to your container environment is that either the host(s) are compromised or the orchestration tool. The first would enable the attacker to control all the containers running on the host, the second will enable the attacker to control all containers on _all_ hosts which the software is managing. + +The most severe threats to the host are kernel exploits from within a container through abuse of Linux sys(tem)calls which lead to root access [2]. Also the orchestration software has interfaces whose defaults were weak and have shown numerous problems in the past [3],[4]. -The most important threats are kernel exploits from within a container through abuse of Linux sys(tem )calls which lead to root access. Also the orchestration software has interfaces which either maybe not be locked down [1] and have shown numerous problems in the past. e.g. like etcd [], kubelet [] and dashboard []. +While threats from the Linux kernel can be partly mitigated by constraining syscalls further (see D4) and network access restrictions (D3) can be applied to reduce the network vector for the orchestration, it is important to keep in mind that you can't mitigate future security problems, like from remaining syscalls, other than by patching. The likelihood of such an incident might be small, however the impact is huge, thus resulting in a high risk. -While threats from the Linux kernel can be partly mitigated by constraining syscalls further (see D4) and network access restrictions (D3) can be applied to reduce the network vector for the orchestration it is important to keep in mind that risk is equal likelihood times damage. Which means also if you minimized the likelihood through partly mitigation or network access, the damage and thus the risk is very high. Patches make sure that the software is always as secure as provided from the vendor. +Patching timely makes sure that your software you are using for your infrastructure is always secure and you avoid known vulnerabilities. -Another threat arises from any Linux services on the host. Also if the host configuration is reasonable secured (see D3 and D4) e.g. a vulnerable `sshd` poses a threat to your host too. If the services is not secured via network and configuration, the risk is higher. +Another threat arises from any Linux services on the host. Also if the host configuration is reasonably secured (see D3 and D4) e.g. a vulnerable `sshd` poses a threat to your host too. If the services are not secured via network and configuration, the risk is higher. You should also keep an eye on the support life time of each "ops" component used. If e.g. the host OS or orchestration software has run out of support, you likely won't be able to address security issues. @@ -18,11 +24,9 @@ You should also keep an eye on the support life time of each "ops" component use ### Different Patch Domains -In general not patching in a timely fashion is the most frequent problem in the IT industry. Most software defects from "off the shelf software" are well known before exploits are written and used. Sometimes not even a sophisticated exploit is needed. +Maintaining your infrastructure software is not as straightforward though as there are four different "patch domains": -Same applies for your container environment. It is not as straight foward though as there are four different "patch domains": - -* Images: the container operating distribution +* Images: the container distribution * Container software: Docker * Orchestration software (Kubernetes, Mesos, OpenShift, ...) * Host: operating system @@ -31,38 +35,57 @@ While the first domain of patching seems easy at the first glance updating the C Have a migration plan for EOL support for each domain mentioned. -### Suggestion when to patch what +### When to patch what? + +In short: patch often and if possible automated. -Depending on the patch domains mentioned above there are different approaches how patching can be achieved. Important is to have a patch strategy for each component. Your patch strategy should handle _regular_ and _emergency_ patches. +Depending on the patch domains mentioned above there are different approaches how proper patching can be achieved. Important is to have a patch strategy for each component. Your patch strategy should handle _regular_ and _emergency_ patches. You also need to be prepared for testing patches and rollback procedures. -If you aren't in an environment which has change or patch policies or processes recommended is the following (also if you are it's recommended to review them whether it needs to be re-adjusted for you container environment): +If you aren't in an environment which has change or patch policies or processes, the following is recommended (test procedures omitted for simplicity): -* Define a time span in which outstanding patches will be applied on a _regular basis_. This can be different for each patch domain but it doesn't have to. Differences may arise due to different threat scenarios: An exposed container or API from your orchestration software which you need to expose has a higher threat level. -* Execute patch cycles and monitor them for success and failures. +* Define a time span in which pending patches will be applied on a _regular basis_. This process should be automated. +* This can be different for each patch domain -- as the risk might be different -- but it doesn't have to. It may differ due to different risks: An exposed container, an API from your orchestration software or a severe kernel bug are a higher risk than container, the DB backend or a piece of middleware. +* Execute patch cycles and monitor them for success and failures, see below. * For critical patches to your environment where the time span between the regular patches is too large for an attacker you need to define a policy for emergency patches which need to be followed in such a case. You also need a team which tracks critical vulnerabilities and patches, e.g. through vendor announcements or through security mailing lists. Emergency patches are normally applied within days or about a week. -Keep in mind that some patches require a restart of their service, a new deployment (container image) or even a reboot (host) to become effective. If this won't be done your patching otherwise can be as effective as not to patch. Those technical details which come after applying patches need to be defined in the the patch plan too. +Keep in mind that some patches require a restart of their service, a new deployment (container image) or even a reboot (host) to become effective. If this won't be done, your patching otherwise could be as effective as just not to patch. Technical details when to restart a service, a host or initiate a new deployment need to be defined in the patch plan too. +It helps a lot if you have planned for redundancy, so that e.g. a new deployment of a container or a reboot of a host won't affect your services. ## How can I find out? -Depending on your role there are different approaches. If you are external or not involved you can just ask what the plan is for the different patch domains and have the plans explained. This can be supplemented by having a look at the systems. +Depending on your role there are different approaches. If you are external or not involved you can just ask what the plan is for the different patch domains and have the plans explained. This can be supplemented by having a look at the systems. Also keep an eye on the continuity management. + +### Manual Without doing deep researches you can gather good indicators on the host like * `uptime` -* When were last patches applied (`rpm --qa --last`, `yum check-update`, `zypper lu` or check `/var/log/dpkg.log*`, `echo n | apt-get upgrade`) +* When were last patches applied (`rpm --qa --last`, `tail -f /var/log/dpkg.log`). Which patches are pending? (RHEL/CentOS: `echo n | yum check-update`, Suse/SLES: `zypper list-patches --severity important -g security`, Debian/Ubuntu: `echo n | apt-get upgrade`). * `ls -lrt /boot/vmlinu*` vs. `uname -a` * Have a look at the runtime of processes (`top` --> column `TIME+`) including e.g. `dockerd`, `docker-containerd*` and `kube*` processes * Deleted files: `lsof +L1` -If your role is internal within the organization and you need to be sure that both patch management strategies exist and are being properly executed. Depending where you start with your policy recommended is [n-1]. [n]. +If your role is internal within the organization, you need to be sure that a patch management plan exists and is being properly executed. Depending where you start with your policy recommended is [5]. +### Automated + +For the host: patch often! Every Linux vendor nowadays supports automated patching. For monitoring patches there are external tools available for authenticated vulnerability scans like OpenVAS [6]. But also all Linux operation systems provide builtin means notifying you for outstanding security patches. + +The general idea for container images is though to deploy often and only freshly build containers. Scanning also here should never be used as a reactive measure but rather to verify that your patching works. For your container images there are a variety of solutions available [7]. Both use feed data on the CVEs available. + +In any case it's also recommended to make use of plugins for your monitoring software notifying you of pending patches. ## References +* [1] OWASP's Top 10 2017, A9: [Using Components with Known Vulnerabilities](https://www.owasp.org/index.php/Top_10-2017_A9-Using_Components_with_Known_Vulnerabilities) +* [3]: Weak default of etcd in CoreOS 2.1: [The security footgun in etcd](https://gcollazo.com/the-security-footgun-in-etcd) +* [4]: cvedetails on [Kubernetes](https://www.cvedetails.com/vulnerability-list/vendor_id-15867/product_id-34016/Kubernetes-Kubernetes.html), [Rancher](https://www.cvedetails.com/vulnerability-list/vendor_id-19744/product_id-53073/Rancher-Rancher.html) +* [5] [OpenVAS](http://openvas.org/index.html). + ### Commercial -* [1] [Lacework: Containers at Risk](https://www.lacework.com/containers-at-risk-a-review-of-21000-cloud-environments/) -* [n-1] TBD: ~~Good source (1) for patch management, lightweighted (not ITIL, nor ISO 2700x)~~ -* [n] TBD: ~~Another good source (2) for patch management~~ +* [2] Blog of Aquasec: [Dirty COW Vulnerability: Impact on Containers](https://blog.aquasec.com/dirty-cow-vulnerability-impact-on-containers) + +* [5] TBD: ~~Good source (1) for patch management, light-weighted (not ITIL, nor ISO 2700x)~~ +* [6] TBD: ~~what all needs to be listed here?~~ diff --git a/D03 - Network Segmentation and Firewalling.md b/D03 - Network Segmentation and Firewalling.md new file mode 100644 index 0000000..3468bad --- /dev/null +++ b/D03 - Network Segmentation and Firewalling.md @@ -0,0 +1,69 @@ +# D03 - Network Segmentation and Firewalling + +In the old world one had a secured DMZ (demilitarized zone) managed by an infrastructure or network team which made sure that only the frontend server's service was reachable from the internet. And on the other side this server was able to talk securely to the middleware and backend - and to nothing else. Management interfaces from a serial console or a baseband management controller were put to a dedicated management LAN with strict access controls. + +This is basically what network engineers call network segmentation and firewalling. That should be basically your idea when planning a network for your microservices. + +## Threat Scenarios + +The container world changed also the networking. Without precautions the network where your containers are deployed within is not necessarily divided into segments with strict firewall/routing rules. In a worst case it maybe even flat and any microservice is basically able to talk to all other microservices, including interfaces of the management backplane - your orchestration tool or e.g. the host's services. + +The paradigm having one microservice per container makes matters from the network security standpoint not easier, as some microservices need to talk to each other while others, from a security point of view, should definitely not. + +__Asking for the biggest trouble is exposing your management interfaces of your orchestration tool in the internet__. There have been researches for it [1] and a couple of surprising discoveries [2]. Please note that also if it is being protected by a login, it means only one step for an attacker getting control over your whole environment. + + +Threats: + +* Internet exposed management frontends/APIs from orchestration tool 1) +* LAN/DMZ exposed management frontends/APIs from orchestration tool 1) +* Access to the host's services from a microservice +* LAN/DMZ unnecessarily exposed microservices in the LAN from same application ( token,) +* LAN/DMZ unnecessarily exposed classical services (NFS/Samba, CI/CD appliance, DBs) +* No 100% network separation between tenants as they share the same network + +Except the first scenario: The threats are that an attacker got access to the local network (LAN/DMZ), e.g. though your compromised frontend service (internet) and moves from there around in this network. + + +## How Do I prevent? + +In a nutshell: Have a multilayer network defense like in the old world and allow only a white-list based communication. Expose to any networks only the ports you need. This includes especially management and host services. + +Do proper network planning upfront: + +* Choose the right network driver for your environment +* Segment your DMZ appropriately +* Multiple tenants should not share the same network +* Define necessary communication +* Protect management frontends/APIs. Never ever expose them in the internet. If you really, really need to, only allow the trusted IPs necessary. +* Also don't expose them in the DMZ. This is your management backplane. It needs strict white-list based network protection +* Protect the host services in the same manner. +* In an orchestrated environment make sure that you have + * first a proper ingress network and routing policy + * secondly a proper egress network policy (restrict downloads from the internet as much as possible) + * then decide for which container intercommunication is needed and may posed a threat + + +## How can I find out? + +First you should check whether any of the orchestration tool's management interfaces is exposed in the internet. Scan yourself from a random internet IP [3] to make sure this isn't the case. If your environment is volatile it also can't hurt to do regular scanning from the outside to make sure that never happens. Or at least when it happens, you will get notified and can take immediate action. + +Secondly you should view this from an attacker perspective: If that one has gotten complete control over a container, what can he/she do? Make sure that from the container he can't reach a) the orchestration management interfaces b) anything else which could be of value for him (e.g. file servers in the LAN or any other container he doesn't need to "speak" to). A poor man's solution is exec into the container and use netcat/nc to check. Another option is a manually crafted docker container containing nmap. + +The prerequisite is to understand the network. If you didn't build the network yourself in nowadays orchestration environments that is often not easy. Either you ask somebody who set this up or you need to get a picture yourself. There's not a straightforward method. You should understand first what the external and internal network interfaces from the host are and in which network they are `ip a / tp ro` is your friend. The same or similar you can do for your containers, either by exec'ing those commands in the container or by just listing that from the host like `for n in $(docker network ls --format="{{.ID}}"); do docker inspect $n; done`. + +You probably want to scan from different networks. The first choice is from the same LAN as from the host. On the host targeting the containers might be a good idea (e.g.`nmap -sTV -p1-65535 $(docker inspect $(docker ps -q) --format '{{.NetworkSettings.IPAddress}}')`. Repeating the same from a container might be also a good idea to check what is in reach of an attacker. + + + +## References + + * [3] _The_ tool for network scanning and discovery is [nmap](https://nmap.org). + +### Commercial: + * [1] [Containers at Risk](https://www.lacework.com/containers-at-risk-a-review-of-21000-cloud-environments/) + * [2] RedLock: [Lessons from the Cryptojacking Attack at Tesla](https://redlock.io/blog/cryptojacking-tesla), Arstechnica: Tesla cloud resources are [hacked to run cryptocurrency-mining malware](https://arstechnica.com/information-technology/2018/02/tesla-cloud-resources-are-hacked-to-run-cryptocurrency-mining-malware/). + +---- + +1) That can be ones which require credentials or even not. Examples for both: etcd, dashboards, kubelet, ... diff --git a/D03 - Network Separation and Firewalling.md b/D03 - Network Separation and Firewalling.md deleted file mode 100644 index 568c424..0000000 --- a/D03 - Network Separation and Firewalling.md +++ /dev/null @@ -1,54 +0,0 @@ -# D03 - Network Separation and Firewalling - -In the old world one had a secured DMZ managed by an infrastructure or network team which made sure that the frontend server's service was in a locked down fashion reachable from the internet and e.g. can talk securely to the middleware and backend -- and to nothing else. Management interfaces from a serial console or a baseband management controller were put to a dedicated LAN with strict access controls. - -This should be bascially your starting point when planning a network for your microservices. - -## Threat Scenarios - -The container world changed the networking. The network is not necessarily divided into zones with strict firewall/routing rules. Without precautions it maybe even flat and every microservice is basically able to talk to all microservices, including interfaces of the management backplane - your orchestration tool or e.g. the host's services. - -The paradigm having one microservice per containers makes matters not easier, as some microservices need to talk to each other while others should definitely not from the security standpoint. - -Threats: - -* Internet exposed management frontends/APIs from orchestration tool 1) -* LAN/DMZ exposed management frontends/APIs from orchestration tool 1) -* LAN/DMZ unnecessarily exposed microservices in the LAN from same application ( token,) -* LAN/DMZ unnecessarily exposed classical services (NFS/Samba, CI/CD appliance, DBs) -* No 100% network separation between tenants as they share the same network -* Access to host network from a microservice - -Except the first scenario: The threats are that an attacker got access to the local network (LAN/DMZ), e.g. though your compromised frontend service (internet) and moves from there around in this network. - - -## How Do I prevent? - -In one line: Have a mulitlayer network defense like in the old world and allow only a white-list based communication. - -Do proper network planning: - -* Choose the right network driver for your environment -* Segment your DMZ appropriately -* Muliple tenants should not share the same network -* Define necessary communication -* Protect management frontends/APIs. Never ever expose them in the internet. -* Also don't expose them in the DMZ. This is your management backplane. It needs strict white-list based network protection -* Protect the host via white-list - - -## How can I find out? - -If the network is segmented and not flat it is quite a task. Network information is best to request beforehand. - -Just reading the output from host-based firewalls like `iptables -t nat -L -nv` and `iptables -L -nv` becomes a tedious task. _The_ tool for network scanning and discovery is nmap [1]. If the network is not flat you probably want to scan from different source IPs. That could be hosts and/or a specially crafted docker container containing nmap. Depending on the capabilities preconfigured and whether TCP connect scans suffice you maybe need to allow nmap in a container to send raw packets (`cap_net_raw`). - - -## References - -[1] [https://nmap.org/](https://nmap.org) - - ----- - -1) That can be ones which require credentials or even not. Examples for both: etcd, dashboards, kubelet, ... \ No newline at end of file diff --git a/D04 - Secure Defaults and Hardening.md b/D04 - Secure Defaults and Hardening.md index cb085a3..02a0995 100644 --- a/D04 - Secure Defaults and Hardening.md +++ b/D04 - Secure Defaults and Hardening.md @@ -1,46 +1,76 @@ # D04 - Secure Defaults and Hardening -While D03 - Network Separation and Firewalling for sure provides at least can an extra layer of protection for any network based services on the e.g. host, the orchestration tool and other places: it doesn't address the root cause. It mitigates the symptom. Best practice though is not to start any service which is not needed. And those services which are needed need to be locked down properly. +While *D03 - Network Segmentation and Firewalling* aims for providing a layer of protection for any network based services on the host and the containers and the orchestration tool: it doesn't address the root cause. It mitigates often just the symptom. If there's a network service started which is not needed at all you should rather not start it in the first place. And if the service started is needed you should lock it down properly. ## Threat Scenarios Basically there are three "domains" where services can be attacked: * Interfaces from the orchestration tool. Typically: dashboard, etcd, API -* Interfaces from the Host. Typically: RPC services, OpenSSHD, avahi, systemd-services +* Interfaces from the Host. Typically: RPC services, OpenSSHD, avahi, network based systemd-services * Interfaces within the container, either from the microservice (e.g. spring-boot) or from the distribution. ## How Do I prevent? +### Orchestration / Host + For your orchestration tool it is crucial to know what service is running and whether it is protected properly or has a weak default configuration. -For your host the first step is picking the right distribution. E.g. -- a standard Ubuntu system is a standard Ubuntu system. There might be other distributions more specialised on hosting containers. Then install a minimal distribution. Desktop applications, compiler environments or any server applications have no business here. They all add an attack surface. Think of a minimal bare metal system. When you pick an OS for the host, -find out the support time left (EOL). +For your host the first step is picking the right distribution: A standard Ubuntu system is a standard Ubuntu system. There are distributions specialized on hosting containers, you should rather consider this. In any case install a minimal distribution -- think of a minimal bare metal system. And if you rather opted for a standard distribution: Desktop applications, compiler environments or any server applications have no business here. They all add an attack surface to a crucial system in your environment. -Also for the container, best practise is: do no install unnecessary packages [1]. Alpine Linux has a smaller footprint and has per default less binaries on board. +Support lifetime is another topic: When you pick an OS for the host, find out the EOL date. -In general you need to make sure you know what services are offered from each component in your LAN. Then you need to decided what do with each: +In general you need to make sure you know what services are offered from each component in your LAN. Then you need to decide what do with each: * Can it be stopped/disabled without affecting the operation? * Can it be started only on the localhost interface or any other network interface? -* Is proper authentication needed for this service? +* Is authentication configured for this service? * Can a tcpwrapper (host) or any other config option narrow down the access to this service? -* Are there any known design flaws? Did you review the documention in terms of security? +* Are there any known design flaws? Did you review the documentation in terms of security? -For services which cannot be turned off, reconfigured or hardended: This is where the network based protection (D03) should at least provide one layer of defense. +For services which cannot be turned off, reconfigured or hardened: This is where the network based protection (D03) should at least provide one layer of defense. -Also: If your host OS hiccups because of AppArmor or SELinux rules, do not switch those technologies off. Find the root causes in the system log file and relax those rule only. +Also: If your host OS hiccups because of AppArmor or SELinux rules, never switch those additional protections off. Find the root causes in the system log file with the tools provided and relax those rule only. +### Container -## How can I find out? +Also for the containers, best practice is: do no install unnecessary packages [1]. Alpine Linux has a smaller footprint and has per default less binaries on board. It still comes with a set of binaries like `wget` and `netcat` (provided by busybox) though. In a case of an application breakout into the container those binaries could help an attacker "phoning home" and retrieven some tool. If you want to put the bar higher you should look into "distroless" [2] images. + +There are a couple of further options you should look into. What can affect the security of the host kernel are defective syscalls. In a worst case this can lead to a privilege escalation from a container as a user to root on the host. So-called capabilities are a superset from the syscalls. + +Here are some defenses: + +* Disable SUID/SGID bits (`--security-opt no-new-privileges`): even if you run as a user, SUID binaries could elevate privileges. Or use `--cap-drop=setuid --cap-drop=setgid` when applying the following. +* Drop more capabilities (`--cap-drop`): Docker restricts the so-called capabilities of a container from 38 (see `/usr/include/linux/capability.h`) to 14 (see ``man 7 capabilities`` and [3]). Likely you can drop a few like `net_bind_service`, `net_raw` and more, see [4]. `pscap` is your tool on the host to list capabilities. Never use `--cap-add=all`. +* If you need finer grained controls than the capabilities can provide you can control each of the >300 syscalls with seccomp with a profile in JSON (`--security-opt seccomp=mysecure.json`), see [5]. About 44 syscalls are already disabled by default. Do not use `unconfined` or `apparmor=unconfined` here. + +Best practise is to settle which of the above you chose. Better do not mix capabilities setting and seccomp profiles. -* System: Log into it with administrative privileges and see what's running using `netstat -tulp` or `lsof -i -Pn| grep -v ESTABLISHED`. This won't return the network sockets from the containers though. -* Container: Please note that `docker inspect` returns deliberately exposed ports only. #FIXME# `nmap -sTU -p1-65535 $(docker inspect $(docker ps -q) --format '{{.NetworkSettings.IPAddress}}')` -* As in D03 scanning the network would be another one option, albeit probably not as effective. +## How can I find out? + +* Special attention is needed for your orchestration tool. There have been unprotected interfaces by (bad) design [6], [7]-[9]. +* You can always scan the system from the same network to see what is exposed in this LAN. D03 describes how to do that. +* Better is to look onto the system. + * Host: Log in with administrative privileges and see what's running using `netstat -tulpn | grep -v ESTABLISHED` or `lsof -i -Pn| grep -v ESTABLISHED`. This won't return the network sockets from the containers though. + * In a container you can use those commands as well - if `netstat` or `lsof` is supplied by the image. +* Any services might also be protected by the host-based firewall. What rules will be applied via default varies from host OS to host OS. As just reading the output from `iptables -t nat -L -nv` and `iptables -L -nv` becomes in larger container environments quickly a tedious task. Thus here it's a good idea to also scan the LAN. ## References -[1] [Docker Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +* [1] Docker's [Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +* [2] Google's FLOSS project [distroless](https://github.com/GoogleContainerTools/distroless) +* [3] Docker Documentation: [Runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) +* [5] [Docker Documentation, Seccomp security profiles for Docker](https://docs.docker.com/engine/security/seccomp/) +* [6] Weak default of etcd in CoreOS 2.1: [The security footgun in etcd](https://gcollazo.com/the-security-footgun-in-etcd) +* [7] Kubernetes documentation: [Controlling access to the Kubelet](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/#controlling-access-to-the-kubelet): _Kubelets expose HTTPS endpoints which grant powerful control over the node and containers. By default Kubelets allow unauthenticated access to this API. Production clusters should enable Kubelet authentication and authorization._ +* [8] Github: ["Exploit"](https://github.com/kayrus/kubelet-exploit) for the API in [7]. +* [9] Medium: [Analysis of a Kubernetes hack — Backdooring through kubelet](https://medium.com/handy-tech/analysis-of-a-kubernetes-hack-backdooring-through-kubelet-823be5c3d67c). Incident because of an open API, see [7]. + +### Commercial + +* [4] RedHat Blog: Secure your Container: [One weird trick](https://www.redhat.com/en/blog/secure-your-containers-one-weird-trick) + + diff --git a/D05 - Maintain Security Contexts.md b/D05 - Maintain Security Contexts.md index 27cd079..88b6b4e 100644 --- a/D05 - Maintain Security Contexts.md +++ b/D05 - Maintain Security Contexts.md @@ -1,12 +1,43 @@ # D05 - Maintain Security Contexts +To have the investment into the powerful hardware pay off, it might sound +appropriate to put as many containers as possible directly on one single host. + +From the security standpoint this is often questionable as different containers +may have different security contexts and also different security statuses. + +A backend container and a frontend container on the same host might be one concern as they have different information security values. A bigger issue is mixing production e.g. with a test or development environment. Production systems need to be available and development containers might contain code which isn't necessarily as secure. One shouldn't affect the other. + +The highest consideration should be put into multi tenant environments. ## Threat Scenarios +* A student from the university has a part time job at a company. He just learned PHP programming and deploys his work into the CD chain of a company. The company +has limited resources and bought only a very few big iron hosts which serve all containers. The environment has rapidly and historically grown so that nobody had the resources to split production from test environment or the playground area. Unfortunately the student's application contains a remote execution vulnerability which internet scanning bots find and within a fingersnap exploit. That means it broke out from the application and ended up in the container. Through this vulnerability the attacker goes shopping in the network and accessed either an insecured etcd or http(s) interface of the orchestration tool. Or he downloads an exploit as there's a similar vulnerability as Dirty COW [1] which grants him immediate root access to the big iron machine - including all containers. + +This is a slightly exaggerated scenario. One can exchange the student from the university with an in-house developer who just did one mistake which is obvious looking at the application from the outside but was not visible to him. + +One can also change the company to a different one providing a container service. And the developer to a client of the CaaS (Container as a Service) company. If one client of the CaaS provider does a similar mistake as the student, as a worst case scenario it could affect the whole CaaS environment's availability, confidentiality and integrity. + + ## How Do I prevent? +Also if some of the threat scenarios might appear deliberately exaggerated, you should have gotten the picture: + +As a general rule of thumb it's not recommended to mix containers with different security statuses or contexts. + +* Put production containers on a separate host system and be careful who has the privilege deploying to this host. There should be no other containers allowed on this host. +* Looking at the information security value of your data you should also consider separating containers according to their contexts. Databases, middleware, authentication services, frontend and master components (cluster’s control plane of e.g. Kubernetes) shouldn't be on the same host. +* VMs (Virtual Machines) can be used in general to separate different security contexts from each other, like production and test. This is the minimum requirement when you are short in physical hardware and need to run different tenants on one hardware. + ## How can I find out? -## References +As an external auditor it's the best to get the system's architecture explained. +In addition by logging in to the bare metal system you can check whether there are processes running which look like a VM process (e.g. `qemu-system-x86_64`) or docker processes only. QEMU processes or `virsh list --all` gives at least a hint that the virtualization KVM is running. What's inside those VMs is best to analyze when you log into the VMs. KVM/libvirt including QEMU is one of the virtualization technologies under Linux using its own kernel. There's also VirtualBox, VMWare and Xen. +In any case it's important to find out whether the separation of the systems reflect their security contexts. + + +## References +[1] Dirty COW, [vulnerability and exploit](https://dirtycow.ninja/) from 2016 diff --git a/D07 - Resource Protection.md b/D07 - Resource Protection.md index 2d4b547..dea1380 100644 --- a/D07 - Resource Protection.md +++ b/D07 - Resource Protection.md @@ -1,12 +1,31 @@ # D07 - Resource Protection - ## Threat Scenarios +Depending on the host OS there's no restriction at all for a container in terms of CPU, memory -- or network and disk I/O. The threat is that either due to a software failure or due to a deliberate cause by an attacker one of those resources runs short which affects physical resources of the underlying host and all other containers. + +Also if a container has been contained by default security measures imposed by e.g. docker it still shares physical resources with other containers and the host, i.e. mostly CPU and memory. So if other containers use those resources extensively, there won't be much left for your container. + +The network is also a shared medium and most likely when data is being read or written, it is the same resource. + +For the memory it is important to understand that there's a so called OOM [1] killer in the host's Linux kernel. The OOM killer kicks in when the kernel is short of memory. Then it starts - using some algorithms [2] - to "free" memory so that the host and kernel itself can still survive. The processes being killed are not necessarily the ones to blame for the extensive memory consumption (OOM score see [3]) and often the host's RAM is oversubscribed [3]. + + ## How Do I prevent? +The best is first for containers to impose reasonable upper limits in terms of memory and CPU. By reaching those limits the container won't be able to allocate more memory or consume more CPU. + +For memory there are two main variables for setting a hard limit ``-memory`` and ``--memory-swap``. Soft limits can exceed the value specified. They would be set with ``--memory-reservation``. For a more complete description see the docker documentation [4]. To protect processes in the container you can also set ``--oom-kill-disable``. The container daemons have a lower OOM score and won't normally be killed). + ## How can I find out? -## References +* Configured: ``docker inspect`` +* Live: ``docker stats``, including what's configure +* Details memory: ``/sys/fs/cgroup/memory/docker/$CONTAINERID/* +## References +* [1] OOM stands for Out of Memory Management +* [2] https://www.kernel.org/doc/gorman/html/understand/understand016.html +* [3] https://lwn.net/Articles/317814/ +* [4] https://docs.docker.com/config/containers/resource_constraints/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..640c5f6 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,17 @@ +FROM node:12.11.1-slim + +RUN apt-get update && \ + apt-get install -y git calibre && \ + apt-get clean && \ + mkdir /build && \ + chown node:node /build && chmod 0750 /build + +# Install custom gitbook version + +WORKDIR /build +USER root +ENV PUPPETEER_SKIP_DOWNLOAD=true +RUN apt-get install -y pandoc texlive-latex-base texlive-fonts-recommended texlive-extra-utils texlive-latex-extra +COPY entrypoint.sh . +# RUN git clone "https://github.com/simonhaenisch/md-to-pdf" && cd md-to-pdf && npm link + diff --git a/README.md b/README.md index 7d78729..7dabbe8 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,92 @@ -# Docker Security +Docker Security +=============== This is the OWASP Docker Top 10. It's a work in progress. ## About this document -This document describes the most important 10 security bullet points for building a secure containerized environment. You can use it as a specification sheet if you start from scratch, alternatively handing it to a contractor who will do this for you. +This document describes the most important 10 security bullet points for +building a secure containerized environment. You can use it as a specification +sheet if you start from scratch, alternatively handing it to a contractor who +will do this for you. -It can also be used to audit or secure an existing installation but especially here you should start thinking about security very early. Best is in the design phase. Later on it becomes either difficult to change some decisions you made or they becomes costly, in terms of money or time. +It can also be used to audit or secure an existing installation but especially +here you should start thinking about security very early. Best is in the design +phase. Later on it becomes either difficult to change some decisions you made or +they become costly, in terms of money or time. ### Name -Albeit the document's name resembles the OWASP Top 10 it's quite different. First, it is not about risks which are based on data collected as the OWASP Top 10. Secondly the 10 bullet points here resemble either architectural bullet points or proactive controls. +Albeit the document's name resembles the OWASP Top 10 it's quite different. +First, it is not about risks which are based on data collected as the OWASP Top +10. Secondly the 10 bullet points here resemble (proactive) controls. ### For whom is this? -This guide is for developers, auditors, architects, system and networking engineers. As indicated above you can also use this guide for external contractors to add formal technical requirements to your contract. The information security officer should have some interest too to meet baseline security requirements and beyond. +This guide is for developers, auditors, architects, system and networking +engineers. As indicated above you can also use this guide for external +contractors to add formal technical requirements to your contract. The +information security officer should have some interest too to meet baseline +security requirements and beyond. -These 10 bullet points are mostly (see below this paragraph) about system and network security and also system and network architecture. As a developer you don't have to be an expert in those -- that's what this guide is for. But as indicated above best is to start thinking about those points early. Please do not just start building it. +These 10 bullet points are mostly (see below this paragraph) about system and +network security and system and network architecture. As a developer you don't +have to be an expert in those -- that's what this guide is for. But as indicated +above best is to start thinking about and addressing those points early. Please +do not just start building it. -One of the bullet point should not be misunderstood: Patch management is not a techincal point. It's a management process. Lat but not least for technical or information security management who has not been much worried about containerization this document also provides insights about the risks involve. +One of the bullet points should not be misunderstood: Patch management is not a +technical point. It's a management process. Last but not least for technical or +information security management who has not been much worried about +containerization this document also provides insights about the risks involved. ### Structure of this document -Security in Docker environments seemed often to be misunderstood. It was/is a highly disputed matter what the threats are supposed to be. So before diving into the Docker Top 10 bullet points, the threads need to be modeled which is happening upfront in the document. It not only helps understanding the security impacts but also gives you the ability to prioritize your task. +Security in Docker environments seemed often to be misunderstood. It was`/`is a +highly disputed matter what the threats are supposed to be. So before diving +into the Docker Top 10 bullet points, the threats need to be modeled which is +happening upfront in this document. It not only helps to understand any security +impacts but also gives you the ability to prioritize your tasks. +### Contribution + +Please see CONTRIBUTING.md. To ease contributions to the the open points please +file your PRs against the corresponding dev branches (D06_dev, D07_dev, ...). + + +### How to Build PDF version + +You can build yourself a PDF version as long as you have Docker and docker-compose +installed. + +``` +docker-compose run --rm build +``` + +It's not frequently updated in this repository as it otherwise clogs this repo. ## FAQ ### Why not "Container Security" -Albeit the name of this project carries the word "Docker", it also can be used with little abstraction for other containment solutions. Docker is as of now the most popular one, so the in-depth details are focusing for now on Docker. This could change later. +Albeit the name of this project carries the word "Docker", it also can be used +with little abstraction for other containment solutions. Docker is as of now the +most popular one, so the in-depth details are focusing for now on Docker. This +could change later. ### A single container? -If you run more than 3 containers on a server you probably have an orchestration solution to manage them. _Specific_ security pitfalls of such a tool are currently beyond the scope of this document. That does not mean that this guide is just concerning one or a few containers managed manually -- on the contrary. It means only that we're looking at the containers including their networking and their host systems in such an orchestrated environment and not on special pitfalls of e.g. _Kubernetes_, _Swarm_, _Mesos_ or _OpenShift_. +If you run more than 3 containers on a server you probably have an orchestration +solution to manage them. _Specific_ security pitfalls of such a tool are +currently beyond the scope of this document. That does not mean that this guide +is just concerning one or a few containers managed manually -- on the contrary. +It means only that we're looking at the containers including their networking +and their host systems in such an orchestrated environment and not on special +pitfalls of e.g. _Kubernetes_, _Swarm_, _Rancher_ or _OKD/OpenShift_. ### Why ten? -To be honest for us humans the number 10 sounds catchy and while putting it all together those 10 were considered to be the most important ones. +To be honest for us humans the number 10 sounds catchy and while putting it all +together those 10 were considered to be the most important ones. + + diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..dd1a82a --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,18 @@ +Summary +======= + +* [Introduction](000 - Introduction.md) +* [Threats](001 - Threats.md) +* [Overview](D00 - Overview.md) +* [D01 - Secure User Mapping](D01 - Secure User Mapping.md) +* [D02 - Patch Management Stategy](D02 - Patch Management Strategy.md) +* [D03 - Network Segmentation and Firewalling](D03 - Network Segmentation and Firewalling.md) +* [D04 - Secure Defaults and Hardening](D04 - Secure Defaults and Hardening.md) +* [D05 - Maintain Securty Contexts](D05 - Maintain Security Contexts.md) +* [D06 - Protect Secrets](D06 - Protect Secrets.md) +* [D07 - Resource Protection](D07 - Resource Protection.md) +* [D08 - Container Image Integrity and Origin](D08 - Container Image Integrity and Origin.md) +* [D09 - Follow Immutable Paradigm](D09 - Follow Immutable Paradigm.md) +* [D10 - Logging](D10 - Logging.md) +* [What's Next?](E11 - What's Next?.md) + diff --git a/assets/LICENSE-FRONT-WASP.txt b/assets/LICENSE-FRONT-WASP.txt new file mode 100644 index 0000000..766f233 --- /dev/null +++ b/assets/LICENSE-FRONT-WASP.txt @@ -0,0 +1,405 @@ +The yellow jacket wasp image was obtained from Wikipedia, from an image by Fir0002/Flagstaffotos + +https://en.wikipedia.org/wiki/Yellowjacket#/media/File:European_wasp_white_bg.jpg + +Here is the license for that image (and that image only): + +https://www.gnu.org/licenses/old-licenses/fdl-1.2.html + + GNU Free Documentation License + Version 1.2, November 2002 + + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The "Document", below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as "you". You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section "Entitled XYZ" means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as "Acknowledgements", +"Dedications", "Endorsements", or "History".) To "Preserve the Title" +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. +O. Preserve any Warranty Disclaimers. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +https://www.gnu.org/licenses/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. \ No newline at end of file diff --git a/assets/cover.xcf b/assets/cover.xcf new file mode 100644 index 0000000..1bec33e Binary files /dev/null and b/assets/cover.xcf differ diff --git a/assets/front-wasp.png b/assets/front-wasp.png new file mode 100644 index 0000000..5a163dd Binary files /dev/null and b/assets/front-wasp.png differ diff --git a/assets/threats.png b/assets/threats.png new file mode 100644 index 0000000..857aeab Binary files /dev/null and b/assets/threats.png differ diff --git a/book.json b/book.json new file mode 100644 index 0000000..627a1a1 --- /dev/null +++ b/book.json @@ -0,0 +1,15 @@ +{ + "structure": { + "readme": "000 - Introduction.md" + }, + "title": "OWASP Docker Top 10", + "description": "The Ten Most Important Aspects To Build a Secure Containerized Environment", + "language": "en_US", + "gitbook": "3.2.3", + "pdf": { + "fontFamily": "sans-serif", + "chapterMark": "pagebreak", + "pageBreaksBefore": "//*[name()='pagebreak']" + } +} + diff --git a/cover.jpg b/cover.jpg new file mode 100644 index 0000000..da6fb1e Binary files /dev/null and b/cover.jpg differ diff --git a/cover_small.jpg b/cover_small.jpg new file mode 100644 index 0000000..499d9b9 Binary files /dev/null and b/cover_small.jpg differ diff --git a/dist/owasp-docker-security.pdf b/dist/owasp-docker-security.pdf new file mode 100644 index 0000000..ea6fa97 Binary files /dev/null and b/dist/owasp-docker-security.pdf differ diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..190fe15 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,9 @@ +version: "3.6" +services: + build: + build: . + image: dockersecbuilder:latest + entrypoint: /build/entrypoint.sh + volumes: + - .:/build + diff --git a/entrypoint.sh b/entrypoint.sh new file mode 100644 index 0000000..d40f978 --- /dev/null +++ b/entrypoint.sh @@ -0,0 +1,13 @@ +#!/bin/bash +VAR="" + +for f in *.md; do + [[ -f $f ]] || continue + VAR+="'${f}' " + cat "$f" >> './dist/combined-guide.md' +done + +IFS=$'\n' +echo "Combining Files" $VAR +pandoc ./dist/combined-guide.md -o ./dist/owasp-docker-security.pdf +# cat './dist/combined-guide.md' | md-to-pdf > ./dist/owasp-docker-security.pdf \ No newline at end of file