From 3f3626c11a04736181dac8e9b0962b34338cb2de Mon Sep 17 00:00:00 2001 From: epriestley Date: Mon, 12 Oct 2015 17:54:11 -0700 Subject: [PATCH] Write some documentation about Drydock security and repository automation Summary: Ref T182. Ref T9519. Some of what this describes doesn't exist yet, but should soon. Test Plan: Read documentation. Reviewers: chad Reviewed By: chad Maniphest Tasks: T182, T9519 Differential Revision: https://secure.phabricator.com/D14258 --- src/docs/user/userguide/drydock.diviner | 9 + .../drydock_repository_automation.diviner | 39 ++++ .../user/userguide/drydock_security.diviner | 209 ++++++++++++++++++ 3 files changed, 257 insertions(+) create mode 100644 src/docs/user/userguide/drydock_repository_automation.diviner create mode 100644 src/docs/user/userguide/drydock_security.diviner diff --git a/src/docs/user/userguide/drydock.diviner b/src/docs/user/userguide/drydock.diviner index a03346f1cb..49b1f1df9e 100644 --- a/src/docs/user/userguide/drydock.diviner +++ b/src/docs/user/userguide/drydock.diviner @@ -58,3 +58,12 @@ a corresponding resource by either finding a suitable unused resource or creating a new resource. When work completes, the resource is returned to the resource pool or destroyed. +Next Steps +========== + +Continue by: + + - understanding Drydock security concerns with + @{article:Drydock User Guide: Security}; or + - allowing Phabricator to write to repositories with + @{article:Drydock User Guide: Repository Automation}. diff --git a/src/docs/user/userguide/drydock_repository_automation.diviner b/src/docs/user/userguide/drydock_repository_automation.diviner new file mode 100644 index 0000000000..a16e8d33e9 --- /dev/null +++ b/src/docs/user/userguide/drydock_repository_automation.diviner @@ -0,0 +1,39 @@ +@title Drydock User Guide: Repository Automation +@group userguide + +Configuring repository automation so Phabricator can push commits. + + +Overview +======== + +IMPORTANT: This feature is very new and most of the capabilities described +in this document are not yet available. This feature as a whole is a prototype. + +By configuring Drydock and Diffusion appropriately, you can enable **Repository +Automation** for a repository. Once automation is set up, Phabricator will be +able to make changes to the repository. + + +Security +======== + +Configuring repository automation amounts to telling Phabricator where it +should perform working copy operations (like merges, cherry-picks and pushes) +when doing writes. + +Depending on how stringent you are about change control, you may want to +make sure these processes are isolated and can not be tampered with. If you +run tests and automation on the same hardware, tests may be able to interfere +with automation. You can read more about this in +@{article:Drydock User Guide: Security}. + + +Next Steps +========== + +Continue by: + + - understanding Drydock security concerns with + @{article:Drydock User Guide: Security}; or + - returning to the @{article:Drydock User Guide}. diff --git a/src/docs/user/userguide/drydock_security.diviner b/src/docs/user/userguide/drydock_security.diviner new file mode 100644 index 0000000000..f12586ab35 --- /dev/null +++ b/src/docs/user/userguide/drydock_security.diviner @@ -0,0 +1,209 @@ +@title Drydock User Guide: Security +@group userguide + +Understanding security concerns in Drydock. + +Overview +======== + +Different applications use Drydock for different things, and some of the things +they do with Drydock require different levels of trust and access. It is +important to configure Drydock properly so that less trusted code can't do +anything you aren't comfortable with. + +For example, running unit tests on Drydock normally involves running relatively +untrusted code (it often has a single author and has not yet been reviewed) +that needs very few capabilities (generally, it only needs to be able to report +results back to Phabricator). In contrast, automating merge requests on Drydock +involves running trusted code that needs more access (it must be able to write +to repositories). + +Drydock allows resources to be shared and reused, so it's possible to configure +Drydock in a way that gives untrusted code a lot of access by accident. + +One way Drydock makes allocations faster is by sharing, reusing, and recycling +resources. When an application asks Drydock for a working copy, it will try to +satisfy the request by cleaning up a suitable existing working copy if it can, +instead of building a new one. This is faster, but it means that tasks have +some ability to interact or interfere with each other. + +Similarly, Drydock may allocate multiple leases on the same host at the same +time, running as the same user. This is generally simpler to configure and less +wasteful than fully isolating leases, but means that they can interact. + +Depending on your organization, environment and use cases, you might not want +this, and it may be important that different use cases are unable to interfere +with each other. For example, you might want to prevent unit tests from writing +to repositories. + +**Drydock does not guarantee that resources are isolated by default**. When +resources are more isolated, they are usually also harder to configure and +slower to allocate. Because most installs will want to find a balance between +isolation and complexity/performance, Drydock does not make assumptions about +either isolation or performance having absolute priority. + +You'll usually want to isolate things just enough that nothing bad can happen. +Fortunately, this is straightforward. This document describes how to make sure +you have enough isolation so that nothing you're uncomfortable with can occur. + + +Choosing an Isolation Policy +============================ + +This section provides some reasonable examples of ways you might approach +configuring Drydock. + +| Isolation | Suitable For | Description +|-----------|-----|------- +| Zero | Development | Everything on one host. +| Low | Small Installs | Use a dedicated Drydock host. +| High | Most Installs | **Recommended**. Use low-trust and high-trust pools. +| Custom | Special Requirements | Use multiple pools. +| Absolute | Special Requirements | Completely isolate all resources. + +**Zero Isolation**: Run Drydock operations on the same host that Phabricator +runs on. This is only suitable for developing or testing Phabricator. Any +Drydock operation can potentially compromise Phabricator. It is intentionally +difficult to configure Drydock to operate in this mode. Running Drydock +operations on the Phabricator host is strongly discouraged. + +**Low Isolation**: Designate a separate Drydock host and run Drydock +operations on it. This is suitable for small installs and provides a reasonable +level of isolation. However, it will allow unit tests (which often run +lower-trust code) to interfere with repository automation operations. + +**High Isolation**: Designate two Drydock host pools and run low-trust +operations (like builds) on one pool and high-trust operations (like repository +automation) on a separate pool. This provides a good balance between isolation +and performance, although tests can still potentially interfere with the +execution of unrelated tests. + +**Custom Isolation**: You can continue adding pools to refine the resource +isolation model. For example, you may have higher-trust and lower-trust +repositories or do builds on a mid-trust tier which runs only reviewed code. + +**Absolute Isolation**: Configure blueprints to completely initialize and +destroy hosts or containers on every request, and limit all resources to one +simultaneous lease. This will completely isolate every operation, but come at +a high performance and complexity cost. + +NOTE: It is not currently possible to configure Drydock in an absolute +isolation mode. + +It is usually reasonable to choose one of these approaches as a starting point +and then adjust it to fit your requirements. You can also evolve your use of +Drydock over time as your needs change. + + +Threat Scenarios +================ + +This section will help you understand the threats to a Drydock environment. +Not all threats will be concerning to all installs, and you can choose an +approach which defuses only the threats you care about. + +Attackers have three primary targets: + + - capturing hosts; + - compromising Phabricator; and + - compromising the integrity of other Drydock processes. + +**Attacks against hosts** are the least sophisticated. In this scenario, an +attacker wants to run a program like a Bitcoin miner or botnet client on +hardware that they aren't paying for or which can't be traced to them. They +write a "unit test" or which launches this software, then send a revision +containing this "unit test" for review. If Phabricator is configured to +automatically run tests on new revisions, it may execute automatically and give +the attacker access to computing resources they did not previously control and +which can not easily be traced back to them. + +This is usually only a meaningful threat for open source installs, because +there is a high probability of eventual detection and the value of these +resources is small, so employees will generally not have an incentive to +attempt this sort of attack. The easiest way to prevent this attack is to +prevent untrusted, anonymous contributors from running tests. For example, +create a "Trusted Contributors" project and only run tests if a revision author +is a member of the project. + +**Attacks against Phabricator** are more sophisticated. In this scenario, an +attacker tries to compromise Phabricator itself (for example, to make themselves +an administrator or gain access to an administrator account). + +This is made possible if Drydock is running on the same host as Phabricator or +runs on a privileged subnet with access to resources like Phabricator database +hosts. Most installs should be concerned about this attack. + +The best way to defuse this attack is to run Drydock processes on a separate +host which is not on a privileged subnet. For example, use a +`build.mycompany.com` host or pool for Drydock processes, separate from your +`phabricator.mycompany.com` host or pool. + +Even if the host is not privileged, many Drydock processes have some level of +privilege (enabling them to clone repositories, or report test results back to +Phabricator). Be aware that tests can hijack credentials they are run with, +and potentialy hijack credentials given to other processes on the same hosts. +You should use credentials with a minimum set of privileges and assume all +processes on a host have the highest level of access that any process on the +host has. + +**Attacks against Drydock** are the most sophisticated. In this scenario, an +attacker uses one Drydock process to compromise a different process: for +example, a unit test which tampers with a merge or injects code into a build. +This might allow an attacker to make changes to a repository or binary without +going through review or triggering other rules which would normally detect the +change. + +These attackers could also make failing tests appear to pass, or break tests or +builds, but these attacks are generally less interesting than tampering with +a repository or binary. + +This is a complex attack which you may not have to worry about unless you have +a high degree of process and control in your change pipeline. If users can push +changes directly to repositories, this often represents a faster and easier way +to achieve the same tampering. + +The best way to defuse this attack is to prevent high-trust (repository +automation) processes from running on the same hosts as low-trust (unit test) +processes. For example, use an `automation.mycompany.com` host or pool for +repository automation, and a `build.mycompany.com` host or pool for tests. + + +Applying an Isolation Policy +============================ + +Designing a security and isolation policy for Drydock can take some thought, +but applying it is straightforward. Applications which want to use Drydock must +explicitly list which blueprints they are allowed to use, and they must be +approved to use them in Drydock. By default, nothing can do anything, which is +very safe and secure. + +To get builds or automation running on a host, specify the host blueprint as a +usable blueprint in the build step or repository configuration. This creates a +new authorization request in Drydock which must be approved before things can +move forward. + +Until the authorization is approved, the process can not use the blueprint to +create any resources, nor can it use resources previously created by the +blueprint. + +You can review and approve requests from the blueprint detail view in Drydock: +find the request and click {nav Approve Authorization}. You can also revoke +approval at any time from this screen which will prevent the object from +continuing to use the blueprint (but note that this does not release any +existing leases). + +Once the authorization request is approved, the build or automation process +should be able to run if everything else is configured properly. + +Note that authorizations are transitive: if a build step is authorized to use +blueprint A, and blueprint A is authorized to use blueprint B, the build step +may indirectly operate on resources created by blueprint B. This should +normally be consistent with expectations. + + +Next Steps +========== + +Continue by: + + - returning to the @{article:Drydock User Guide}.