@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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
+257
+9
src/docs/user/userguide/drydock.diviner
+9
src/docs/user/userguide/drydock.diviner
···
58
58
creating a new resource. When work completes, the resource is returned to the
59
59
resource pool or destroyed.
60
60
61
+
Next Steps
62
+
==========
63
+
64
+
Continue by:
65
+
66
+
- understanding Drydock security concerns with
67
+
@{article:Drydock User Guide: Security}; or
68
+
- allowing Phabricator to write to repositories with
69
+
@{article:Drydock User Guide: Repository Automation}.
+39
src/docs/user/userguide/drydock_repository_automation.diviner
+39
src/docs/user/userguide/drydock_repository_automation.diviner
···
1
+
@title Drydock User Guide: Repository Automation
2
+
@group userguide
3
+
4
+
Configuring repository automation so Phabricator can push commits.
5
+
6
+
7
+
Overview
8
+
========
9
+
10
+
IMPORTANT: This feature is very new and most of the capabilities described
11
+
in this document are not yet available. This feature as a whole is a prototype.
12
+
13
+
By configuring Drydock and Diffusion appropriately, you can enable **Repository
14
+
Automation** for a repository. Once automation is set up, Phabricator will be
15
+
able to make changes to the repository.
16
+
17
+
18
+
Security
19
+
========
20
+
21
+
Configuring repository automation amounts to telling Phabricator where it
22
+
should perform working copy operations (like merges, cherry-picks and pushes)
23
+
when doing writes.
24
+
25
+
Depending on how stringent you are about change control, you may want to
26
+
make sure these processes are isolated and can not be tampered with. If you
27
+
run tests and automation on the same hardware, tests may be able to interfere
28
+
with automation. You can read more about this in
29
+
@{article:Drydock User Guide: Security}.
30
+
31
+
32
+
Next Steps
33
+
==========
34
+
35
+
Continue by:
36
+
37
+
- understanding Drydock security concerns with
38
+
@{article:Drydock User Guide: Security}; or
39
+
- returning to the @{article:Drydock User Guide}.
+209
src/docs/user/userguide/drydock_security.diviner
+209
src/docs/user/userguide/drydock_security.diviner
···
1
+
@title Drydock User Guide: Security
2
+
@group userguide
3
+
4
+
Understanding security concerns in Drydock.
5
+
6
+
Overview
7
+
========
8
+
9
+
Different applications use Drydock for different things, and some of the things
10
+
they do with Drydock require different levels of trust and access. It is
11
+
important to configure Drydock properly so that less trusted code can't do
12
+
anything you aren't comfortable with.
13
+
14
+
For example, running unit tests on Drydock normally involves running relatively
15
+
untrusted code (it often has a single author and has not yet been reviewed)
16
+
that needs very few capabilities (generally, it only needs to be able to report
17
+
results back to Phabricator). In contrast, automating merge requests on Drydock
18
+
involves running trusted code that needs more access (it must be able to write
19
+
to repositories).
20
+
21
+
Drydock allows resources to be shared and reused, so it's possible to configure
22
+
Drydock in a way that gives untrusted code a lot of access by accident.
23
+
24
+
One way Drydock makes allocations faster is by sharing, reusing, and recycling
25
+
resources. When an application asks Drydock for a working copy, it will try to
26
+
satisfy the request by cleaning up a suitable existing working copy if it can,
27
+
instead of building a new one. This is faster, but it means that tasks have
28
+
some ability to interact or interfere with each other.
29
+
30
+
Similarly, Drydock may allocate multiple leases on the same host at the same
31
+
time, running as the same user. This is generally simpler to configure and less
32
+
wasteful than fully isolating leases, but means that they can interact.
33
+
34
+
Depending on your organization, environment and use cases, you might not want
35
+
this, and it may be important that different use cases are unable to interfere
36
+
with each other. For example, you might want to prevent unit tests from writing
37
+
to repositories.
38
+
39
+
**Drydock does not guarantee that resources are isolated by default**. When
40
+
resources are more isolated, they are usually also harder to configure and
41
+
slower to allocate. Because most installs will want to find a balance between
42
+
isolation and complexity/performance, Drydock does not make assumptions about
43
+
either isolation or performance having absolute priority.
44
+
45
+
You'll usually want to isolate things just enough that nothing bad can happen.
46
+
Fortunately, this is straightforward. This document describes how to make sure
47
+
you have enough isolation so that nothing you're uncomfortable with can occur.
48
+
49
+
50
+
Choosing an Isolation Policy
51
+
============================
52
+
53
+
This section provides some reasonable examples of ways you might approach
54
+
configuring Drydock.
55
+
56
+
| Isolation | Suitable For | Description
57
+
|-----------|-----|-------
58
+
| Zero | Development | Everything on one host.
59
+
| Low | Small Installs | Use a dedicated Drydock host.
60
+
| High | Most Installs | **Recommended**. Use low-trust and high-trust pools.
61
+
| Custom | Special Requirements | Use multiple pools.
62
+
| Absolute | Special Requirements | Completely isolate all resources.
63
+
64
+
**Zero Isolation**: Run Drydock operations on the same host that Phabricator
65
+
runs on. This is only suitable for developing or testing Phabricator. Any
66
+
Drydock operation can potentially compromise Phabricator. It is intentionally
67
+
difficult to configure Drydock to operate in this mode. Running Drydock
68
+
operations on the Phabricator host is strongly discouraged.
69
+
70
+
**Low Isolation**: Designate a separate Drydock host and run Drydock
71
+
operations on it. This is suitable for small installs and provides a reasonable
72
+
level of isolation. However, it will allow unit tests (which often run
73
+
lower-trust code) to interfere with repository automation operations.
74
+
75
+
**High Isolation**: Designate two Drydock host pools and run low-trust
76
+
operations (like builds) on one pool and high-trust operations (like repository
77
+
automation) on a separate pool. This provides a good balance between isolation
78
+
and performance, although tests can still potentially interfere with the
79
+
execution of unrelated tests.
80
+
81
+
**Custom Isolation**: You can continue adding pools to refine the resource
82
+
isolation model. For example, you may have higher-trust and lower-trust
83
+
repositories or do builds on a mid-trust tier which runs only reviewed code.
84
+
85
+
**Absolute Isolation**: Configure blueprints to completely initialize and
86
+
destroy hosts or containers on every request, and limit all resources to one
87
+
simultaneous lease. This will completely isolate every operation, but come at
88
+
a high performance and complexity cost.
89
+
90
+
NOTE: It is not currently possible to configure Drydock in an absolute
91
+
isolation mode.
92
+
93
+
It is usually reasonable to choose one of these approaches as a starting point
94
+
and then adjust it to fit your requirements. You can also evolve your use of
95
+
Drydock over time as your needs change.
96
+
97
+
98
+
Threat Scenarios
99
+
================
100
+
101
+
This section will help you understand the threats to a Drydock environment.
102
+
Not all threats will be concerning to all installs, and you can choose an
103
+
approach which defuses only the threats you care about.
104
+
105
+
Attackers have three primary targets:
106
+
107
+
- capturing hosts;
108
+
- compromising Phabricator; and
109
+
- compromising the integrity of other Drydock processes.
110
+
111
+
**Attacks against hosts** are the least sophisticated. In this scenario, an
112
+
attacker wants to run a program like a Bitcoin miner or botnet client on
113
+
hardware that they aren't paying for or which can't be traced to them. They
114
+
write a "unit test" or which launches this software, then send a revision
115
+
containing this "unit test" for review. If Phabricator is configured to
116
+
automatically run tests on new revisions, it may execute automatically and give
117
+
the attacker access to computing resources they did not previously control and
118
+
which can not easily be traced back to them.
119
+
120
+
This is usually only a meaningful threat for open source installs, because
121
+
there is a high probability of eventual detection and the value of these
122
+
resources is small, so employees will generally not have an incentive to
123
+
attempt this sort of attack. The easiest way to prevent this attack is to
124
+
prevent untrusted, anonymous contributors from running tests. For example,
125
+
create a "Trusted Contributors" project and only run tests if a revision author
126
+
is a member of the project.
127
+
128
+
**Attacks against Phabricator** are more sophisticated. In this scenario, an
129
+
attacker tries to compromise Phabricator itself (for example, to make themselves
130
+
an administrator or gain access to an administrator account).
131
+
132
+
This is made possible if Drydock is running on the same host as Phabricator or
133
+
runs on a privileged subnet with access to resources like Phabricator database
134
+
hosts. Most installs should be concerned about this attack.
135
+
136
+
The best way to defuse this attack is to run Drydock processes on a separate
137
+
host which is not on a privileged subnet. For example, use a
138
+
`build.mycompany.com` host or pool for Drydock processes, separate from your
139
+
`phabricator.mycompany.com` host or pool.
140
+
141
+
Even if the host is not privileged, many Drydock processes have some level of
142
+
privilege (enabling them to clone repositories, or report test results back to
143
+
Phabricator). Be aware that tests can hijack credentials they are run with,
144
+
and potentialy hijack credentials given to other processes on the same hosts.
145
+
You should use credentials with a minimum set of privileges and assume all
146
+
processes on a host have the highest level of access that any process on the
147
+
host has.
148
+
149
+
**Attacks against Drydock** are the most sophisticated. In this scenario, an
150
+
attacker uses one Drydock process to compromise a different process: for
151
+
example, a unit test which tampers with a merge or injects code into a build.
152
+
This might allow an attacker to make changes to a repository or binary without
153
+
going through review or triggering other rules which would normally detect the
154
+
change.
155
+
156
+
These attackers could also make failing tests appear to pass, or break tests or
157
+
builds, but these attacks are generally less interesting than tampering with
158
+
a repository or binary.
159
+
160
+
This is a complex attack which you may not have to worry about unless you have
161
+
a high degree of process and control in your change pipeline. If users can push
162
+
changes directly to repositories, this often represents a faster and easier way
163
+
to achieve the same tampering.
164
+
165
+
The best way to defuse this attack is to prevent high-trust (repository
166
+
automation) processes from running on the same hosts as low-trust (unit test)
167
+
processes. For example, use an `automation.mycompany.com` host or pool for
168
+
repository automation, and a `build.mycompany.com` host or pool for tests.
169
+
170
+
171
+
Applying an Isolation Policy
172
+
============================
173
+
174
+
Designing a security and isolation policy for Drydock can take some thought,
175
+
but applying it is straightforward. Applications which want to use Drydock must
176
+
explicitly list which blueprints they are allowed to use, and they must be
177
+
approved to use them in Drydock. By default, nothing can do anything, which is
178
+
very safe and secure.
179
+
180
+
To get builds or automation running on a host, specify the host blueprint as a
181
+
usable blueprint in the build step or repository configuration. This creates a
182
+
new authorization request in Drydock which must be approved before things can
183
+
move forward.
184
+
185
+
Until the authorization is approved, the process can not use the blueprint to
186
+
create any resources, nor can it use resources previously created by the
187
+
blueprint.
188
+
189
+
You can review and approve requests from the blueprint detail view in Drydock:
190
+
find the request and click {nav Approve Authorization}. You can also revoke
191
+
approval at any time from this screen which will prevent the object from
192
+
continuing to use the blueprint (but note that this does not release any
193
+
existing leases).
194
+
195
+
Once the authorization request is approved, the build or automation process
196
+
should be able to run if everything else is configured properly.
197
+
198
+
Note that authorizations are transitive: if a build step is authorized to use
199
+
blueprint A, and blueprint A is authorized to use blueprint B, the build step
200
+
may indirectly operate on resources created by blueprint B. This should
201
+
normally be consistent with expectations.
202
+
203
+
204
+
Next Steps
205
+
==========
206
+
207
+
Continue by:
208
+
209
+
- returning to the @{article:Drydock User Guide}.