You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This article describes how templates can streamline security for Azure Pipelines. Templates can define the outer structure of your pipeline and help prevent malicious code infiltration. Templates can also automatically include steps to do tasks such as credential scanning. If multiple pipelines within your team or organization share the same structure, consider using templates.
14
+
If multiple pipelines within your team or organization share the same structure, consider using [templates](../process/templates.md). This article describes how templates can streamline security for Azure Pipelines.
15
15
16
-
[Checks on protected resources](resources.md) form the fundamental security framework for Azure Pipelines. These checks apply regardless of pipeline structure, stages, and jobs. You can use templates to help enforce these checks.
16
+
Pipeline templates can:
17
+
18
+
- Define the outer structure of your pipeline to help prevent malicious code infiltration.
19
+
- Automatically include steps to do tasks such as credential scanning.
20
+
- Help enforce [checks on protected resources](resources.md). These checks form the fundamental security framework for Azure Pipelines and apply to all pipeline structures, stages, and jobs.
Azure Pipelines provides *includes* and *extends* templates.
23
27
24
-
-Includes templates include the template's code directly in the outer file that references it, similar to `#include` in C++. The following example pipeline inserts the *include-npm-steps.yml* template into the `steps` section.
28
+
-An `includes`templates includes the template's code directly in the outer file that references the template, similar to `#include` in C++. The following example pipeline inserts the *include-npm-steps.yml* template into the `steps` section.
25
29
26
30
```yaml
27
31
steps:
28
32
- template: templates/include-npm-steps.yml
29
33
```
30
34
31
-
- Extends templates define the outer structure of the pipeline and offer specific points for targeted customizations. In the context of C++, `extends` templates resemble inheritance.
35
+
- An `extends` template defines the outer structure of the pipeline and offers specific points for targeted customizations. In the context of C++, `extends` templates resemble inheritance.
32
36
33
-
When you use `extends` templates, you can also use `includes` in both the template and the final pipeline to do common configuration pieces. For a complete reference, see the [Template usage reference](../process/templates.md).
37
+
When you use `extends` templates, you can also use `includes` to do common configuration pieces in both the template and the final pipeline. For more information, see [Use YAML templates in pipelines for reusable and secure processes](../process/templates.md).
34
38
35
39
<a name="use-extends-templates"></a>
36
-
## Extends templates
40
+
### Extends templates
37
41
38
-
For the most secure pipelines, start by using extends templates. These templates define the outer structure of the pipeline and prevent malicious code from infiltrating the pipeline.
42
+
For the most secure pipelines, start by using `extends` templates. These templates define the outer structure of the pipeline and help prevent malicious code infiltration.
39
43
40
-
For example, the following template file is named *template.yml*.
44
+
The following example shows a template file named *template.yml*.
41
45
42
46
```yaml
43
47
parameters:
@@ -49,7 +53,7 @@ steps:
49
53
- ${{ step }}
50
54
```
51
55
52
-
The following pipeline extends the *template.yml* template.
56
+
The following pipeline code extends the *template.yml* template.
53
57
54
58
```yaml
55
59
# azure-pipelines.yml
@@ -69,19 +73,19 @@ extends:
69
73
```
70
74
71
75
>[!TIP]
72
-
>When you set up `extends` templates, consider anchoring them to a particular Git branch or tag so if there are breaking changes, existing pipelines aren't affected. The preceding example uses this feature.
76
+
>When you set up `extends` templates, consider anchoring them to a particular Git branch or tag so any breaking changes don't affect existing pipelines. The preceding example uses this feature.
73
77
74
-
## YAML pipeline security features
78
+
## Pipeline security features
75
79
76
-
The YAML pipeline syntax includes several built-in protections. Extends template can enforce their use. To enhance pipeline security, you can implement any of the following restrictions.
80
+
The YAML pipeline syntax includes several built-in protections. `Extends` template can enforce their use to enhance pipeline security. You can implement any of the following restrictions.
77
81
78
82
### Step targets
79
83
80
84
You can restrict certain steps to run in a container rather than on the host. Steps in containers don't have access to the agent's host, preventing these steps from modifying agent configuration or leaving malicious code for later execution.
81
85
82
-
For example, consider limiting network access. Without open network access, user steps can't retrieve packages from unauthorized sources or upload code and secrets to external network locations.
86
+
For example, you can limit network access. Without open network access, user steps can't retrieve packages from unauthorized sources or upload code and secrets to external network locations.
83
87
84
-
The following example pipeline runs steps on the agent host before running steps inside a container.
88
+
The following example pipeline runs a step on the agent host before running a step inside a container.
85
89
86
90
```yaml
87
91
resources:
@@ -94,13 +98,45 @@ steps:
94
98
target: builder
95
99
```
96
100
101
+
### Type-safe parameters
102
+
103
+
Before a pipeline runs, templates and their parameters transform into constants. [Template parameters](../process/template-parameters.md) can enhance type safety for input parameters.
104
+
105
+
In the following example template, the parameters restrict the available pipeline pool options by enumerating specific choices instead of allowing freeform strings.
106
+
107
+
```yaml
108
+
# template.yml
109
+
parameters:
110
+
- name: userpool
111
+
type: string
112
+
default: Azure Pipelines
113
+
values:
114
+
- Azure Pipelines
115
+
- private-pool-1
116
+
- private-pool-2
117
+
118
+
pool: ${{ parameters.userpool }}
119
+
steps:
120
+
- script: echo Hello world
121
+
```
122
+
123
+
When it extends the template, the pipeline must specify one of the available pool choices.
124
+
125
+
```yaml
126
+
# azure-pipelines.yml
127
+
extends:
128
+
template: template.yml
129
+
parameters:
130
+
userpool: private-pool-1
131
+
```
132
+
97
133
::: moniker range=">=azure-devops-2022"
98
134
99
135
### Agent logging command restrictions
100
136
101
-
You can restrict the services the Azure Pipelines agent provides to user steps. User steps request services by using *logging commands*, which are specially formatted strings printed to standard output. In restricted mode, most of the agent's services, such as uploading artifacts and attaching test results, are unavailable.
137
+
User steps request services by using *logging commands*, which are specially formatted strings printed to standard output. You can restrict the services that the Azure Pipelines agent provides to user steps. In restricted mode, most of the agent's services, such as uploading artifacts and attaching test results, are unavailable.
102
138
103
-
The following example task fails because its `target` property instructs the agent not to allow publishing artifacts.
139
+
In the following example, the `target` property instructs the agent not to allow publishing artifacts, so the task fails.
104
140
105
141
```yaml
106
142
- task: PublishBuildArtifacts@1
@@ -110,11 +146,11 @@ The following example task fails because its `target` property instructs the age
110
146
commands: restricted
111
147
```
112
148
113
-
In `restricted` mode, the `setvariable` command remains permissible, so caution is necessary because pipeline variables are exported as environment variables to subsequent tasks. If tasks output user-provided data, such as open issues retrieved via a REST API, they might be vulnerable to injection attacks. Malicious user content could set environment variables that might be exploited to compromise the agent host.
149
+
The `setvariable` command remains permissible in `restricted` mode, and pipeline variables can be exported as environment variables to subsequent tasks. If tasks output user-provided data, such as open issues retrieved via a REST API, they might be vulnerable to injection attacks. Malicious user content could set environment variables that might be exploited to compromise the agent host.
114
150
115
-
To mitigate this risk, pipeline authors can explicitly declare which variables are settable by using the `setvariable` logging command. When you specify an empty list, all variable setting is disallowed.
151
+
To mitigate this risk, you can explicitly declare which variables are settable by using the `setvariable` logging command. If you specify an empty list, all variable setting is disallowed.
116
152
117
-
The following example task fails because the task is only allowed to set the `expectedVar` variable or a variable prefixed with `ok`.
153
+
The following example restricts the `settableVariables` to `expectedVar` or a variable prefixed with `ok`. The task fails because it attempts to set a different variable.
118
154
119
155
```yaml
120
156
- task: PowerShell@2
@@ -131,7 +167,7 @@ The following example task fails because the task is only allowed to set the `ex
131
167
132
168
### Conditional stage or job execution
133
169
134
-
You can restrict stages and jobs to run only under specific conditions. In the following example, the condition ensures that restricted code builds only for the main branch.
170
+
You can restrict stages and jobs to run only under specific conditions. The following exampleensures that restricted code builds only for the `main` branch.
135
171
136
172
```yaml
137
173
jobs:
@@ -150,7 +186,7 @@ Azure Pipelines templates have the flexibility to iterate over and modify YAML s
150
186
151
187
A template can also rewrite user steps, allowing only approved tasks to run. For example, you can prevent inline script execution.
152
188
153
-
The following example template prevents the step types `bash`, `powershell`, `pwsh`, and `script` from running. For complete lockdown of ad-hoc scripts, you could also block `BatchScript` and `ShellScript`.
189
+
The following example template prevents the script step types `bash`, `powershell`, `pwsh`, and `script` from running. For complete lockdown of scripts, you could also block `BatchScript` and `ShellScript`.
154
190
155
191
```yaml
156
192
# template.yml
@@ -187,57 +223,24 @@ extends:
187
223
parameters:
188
224
usersteps:
189
225
- task: MyTask@1
190
-
- script: echo This step will be stripped out and not run!
191
-
- bash: echo This step will be stripped out and not run!
192
-
- powershell: echo "This step will be stripped out and not run!"
193
-
- pwsh: echo "This step will be stripped out and not run!"
194
-
- script: echo This step will be stripped out and not run!
226
+
- script: echo This step is stripped out and not run
227
+
- bash: echo This step is stripped out and not run
228
+
- powershell: echo "This step is stripped out and not run"
229
+
- pwsh: echo "This step is stripped out and not run"
230
+
- script: echo This step is stripped out and not run
195
231
- task: CmdLine@2
196
-
displayName: Test - Will be stripped out
232
+
displayName: Test - stripped out
197
233
inputs:
198
-
script: echo This step will be stripped out and not run!
234
+
script: echo This step is stripped out and not run
199
235
- task: MyOtherTask@2
200
236
```
201
237
202
238
:::moniker-end
203
239
204
-
### Type-safe parameters
205
-
206
-
Before a pipeline runs, templates and their parameters are transformed into constants. [Template parameters](../process/template-parameters.md) can enhance type safety for input parameters.
207
-
208
-
In the following example template, the parameters restrict the available pipeline pool options by providing an enumeration of specific choices instead of allowing freeform strings.
209
-
210
-
```yaml
211
-
# template.yml
212
-
parameters:
213
-
- name: userpool
214
-
type: string
215
-
default: Azure Pipelines
216
-
values:
217
-
- Azure Pipelines
218
-
- private-pool-1
219
-
- private-pool-2
220
-
221
-
pool: ${{ parameters.userpool }}
222
-
steps:
223
-
- script: # ... removed for clarity
224
-
```
225
-
226
-
When the pipeline extends the template, it has to specify one of the available pool choices.
227
-
228
-
```yaml
229
-
# azure-pipelines.yml
230
-
extends:
231
-
template: template.yml
232
-
parameters:
233
-
userpool: private-pool-1
234
-
```
235
-
236
240
::: moniker range=">=azure-devops"
237
-
238
241
### Template steps
239
242
240
-
A template can automatically include steps in a pipeline. These steps can do tasks such as credential scanning or static code checks. The following template inserts steps before and after the user steps in every job.
243
+
A template can automatically include steps in a pipeline, for example to do credential scanning or static code checks. The following template inserts steps before and after the user steps in every job.
241
244
242
245
```yaml
243
246
parameters:
@@ -258,12 +261,14 @@ jobs:
258
261
259
262
## Template enforcement
260
263
261
-
Templates are a valuable security mechanism, but their effectiveness relies on enforcement. The key control points for enforcing template usage are [protected resources](resources.md). You can configure approvals and checks for your agent pool or other protected resources such as repositories. For an example, see [Add a repository resource check](../process/repository-resource.md#add-a-repository-resource-check).
264
+
The effectiveness of templates as a security mechanism relies on enforcement. The key control points for enforcing template usage are [protected resources](resources.md).
265
+
266
+
You can configure [approvals and checks](../process/approvals.md) for your agent pool or other protected resources such as repositories. For an example, see [Add a repository resource check](../process/repository-resource.md#add-a-repository-resource-check).
262
267
263
268
<a name="set-required-templates"></a>
264
269
### Required templates
265
270
266
-
To enforce the use of a specific template, configure the [required template check](../process/approvals.md#required-template) for a resource. This check applies only when the pipeline extends from a template.
271
+
To enforce the use of a specific template, configure the [required template](../process/approvals.md#required-template) check for a resource. This check applies only when the pipeline extends from a template.
267
272
268
273
When you view the pipeline job, you can monitor the check's status. If the pipeline doesn't extend from the required template, the check fails. The run stops and notifies you of the failed check.
269
274
@@ -273,7 +278,7 @@ When you use the required template, the check passes.
273
278
274
279
:::image type="content" source="../process/media/approval-pass.png" alt-text="Screenshot showing a passed approval check.":::
275
280
276
-
The following *params.yml* template must be referenced in any pipeline that extends it.
281
+
For example, the following *params.yml* template must be referenced in any pipeline that extends it.
0 commit comments