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
Copy file name to clipboardExpand all lines: docs/pipelines/security/templates.md
+83-77Lines changed: 83 additions & 77 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,43 +1,46 @@
1
1
---
2
-
title: Use templates for security
3
-
description: Learn about using template features to improve pipeline security.
2
+
title: Templates for security
3
+
description: Learn about using template features to help improve pipeline security.
4
4
ms.assetid: 73d26125-e3ab-4e18-9bcd-387fb21d3568
5
-
ms.date: 07/18/2024
5
+
ms.date: 09/12/2025
6
6
ms.topic: conceptual
7
7
monikerRange: '>= azure-devops-2020'
8
+
#customer intent: As an Azure DevOps user, I want to understand how pipeline templates can help increase security, so I can use templates to do security tasks and help prevent malicious code infiltration and execution.
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.
15
+
Azure Pipelines[templates](../process/templates.md) let you define reusable content, logic, and parameters in YAML pipelines. This article describes how templates can help enhance pipeline security by:
15
16
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.
17
+
- Defining the outer structure of a pipeline to help prevent malicious code infiltration.
18
+
- Automatically including steps to do tasks such as credential scanning.
19
+
- Helping enforce [checks on protected resources](resources.md), which form the fundamental security framework for Azure Pipelines and apply to all pipeline structures and components.
Azure Pipelines provides *includes* and *extends* templates.
23
26
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.
27
+
-An `includes` template 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
28
26
29
```yaml
27
30
steps:
28
31
- template: templates/include-npm-steps.yml
29
32
```
30
33
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.
34
+
- 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
35
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).
36
+
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
37
35
38
<a name="use-extends-templates"></a>
36
-
## Extends templates
39
+
### Extends templates
37
40
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.
41
+
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
42
40
-
For example, the following template file is named *template.yml*.
43
+
The following example shows a template file named *template.yml*.
41
44
42
45
```yaml
43
46
parameters:
@@ -49,7 +52,7 @@ steps:
49
52
- ${{ step }}
50
53
```
51
54
52
-
The following pipeline extends the *template.yml* template.
55
+
The following example pipeline extends the *template.yml* template.
53
56
54
57
```yaml
55
58
# azure-pipelines.yml
@@ -69,38 +72,70 @@ extends:
69
72
```
70
73
71
74
>[!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.
75
+
>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
76
74
-
## YAML pipeline security features
77
+
## Pipeline security features
75
78
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.
79
+
YAML pipeline syntax includes several built-in protections. `Extends` templates can enforce their use to enhance pipeline security. You can implement any of the following restrictions.
77
80
78
81
### Step targets
79
82
80
-
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.
83
+
You can restrict specified steps to run in a container rather than on the host. Steps in containers can't access the agent host, so they can't modify agent configuration or leave malicious code for later execution.
81
84
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.
85
+
For example, you can run user steps in a container to prevent them from accessing the network, so they can't retrieve packages from unauthorized sources or upload code and secrets to external locations.
83
86
84
-
The following example pipeline runs steps on the agent host before running steps inside a container.
87
+
The following example pipeline runs a step on the agent host that could potentially alter the host network, followed by a step inside a container that limits network access.
85
88
86
89
```yaml
87
90
resources:
88
91
containers:
89
92
- container: builder
90
93
image: mysecurebuildcontainer:latest
91
94
steps:
92
-
- script: echo This step runs on the agent host, and it could use Docker commands to tear down or limit the container's network
95
+
- script: echo This step runs on the agent host
93
96
- script: echo This step runs inside the builder container
94
97
target: builder
95
98
```
96
99
100
+
### Type-safe parameters
101
+
102
+
Before a pipeline runs, templates and their parameters transform into constants. [Template parameters](../process/template-parameters.md) can enhance type safety for input parameters.
103
+
104
+
In the following example template, the parameters restrict the available pipeline pool options by enumerating specific choices instead of allowing any string.
105
+
106
+
```yaml
107
+
# template.yml
108
+
parameters:
109
+
- name: userpool
110
+
type: string
111
+
default: Azure Pipelines
112
+
values:
113
+
- Azure Pipelines
114
+
- private-pool-1
115
+
- private-pool-2
116
+
117
+
pool: ${{ parameters.userpool }}
118
+
steps:
119
+
- script: echo Hello world
120
+
```
121
+
122
+
To extend the template, the pipeline must specify one of the available pool choices.
123
+
124
+
```yaml
125
+
# azure-pipelines.yml
126
+
extends:
127
+
template: template.yml
128
+
parameters:
129
+
userpool: private-pool-1
130
+
```
131
+
97
132
::: moniker range=">=azure-devops-2022"
98
133
99
134
### Agent logging command restrictions
100
135
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.
136
+
User steps request services by using *logging commands*, which are specially formatted strings printed to standard output. You can restrict the services that logging commands provide for user steps. In `restricted` mode, most agent services such as uploading artifacts and attaching test results are unavailable for logging commands.
102
137
103
-
The following example task fails because its `target` property instructs the agent not to allow publishing artifacts.
138
+
In the following example, the `target` property instructs the agent to restrict publishing artifacts, so the artifact publishing task fails.
104
139
105
140
```yaml
106
141
- task: PublishBuildArtifacts@1
@@ -110,11 +145,13 @@ The following example task fails because its `target` property instructs the age
110
145
commands: restricted
111
146
```
112
147
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.
148
+
#### Variables in logging commands
149
+
150
+
The `setvariable` command remains permissible in `restricted` mode, so tasks that output user-provided data, such as open issues retrieved via a REST API, might be vulnerable to injection attacks. Malicious user content could set variables that export to subsequent tasks as environment variables and could compromise the agent host.
114
151
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.
152
+
To mitigate this risk, you can explicitly declare the variables that are settable by using the `setvariable` logging command. If you specify an empty list in `settableVariables`, all variable setting is disallowed.
116
153
117
-
The following example task fails because the task is only allowed to set the `expectedVar` variable or a variable prefixed with `ok`.
154
+
The following example restricts the `settableVariables` to `expectedVar` and any variable prefixed with `ok`. The task fails because it attempts to set a different variable called `BadVar`.
118
155
119
156
```yaml
120
157
- task: PowerShell@2
@@ -131,7 +168,7 @@ The following example task fails because the task is only allowed to set the `ex
131
168
132
169
### Conditional stage or job execution
133
170
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.
171
+
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
172
136
173
```yaml
137
174
jobs:
@@ -148,9 +185,9 @@ jobs:
148
185
149
186
Azure Pipelines templates have the flexibility to iterate over and modify YAML syntax. By using iteration, you can enforce specific YAML security features.
150
187
151
-
A template can also rewrite user steps, allowing only approved tasks to run. For example, you can prevent inline script execution.
188
+
A template can also rewrite user steps, allowing only approved tasks to run. For example, the template can prevent inline script execution.
152
189
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`.
190
+
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
191
155
192
```yaml
156
193
# template.yml
@@ -178,7 +215,7 @@ steps:
178
215
displayName: 'Disabled by template: ${{ step.displayName }}'
179
216
```
180
217
181
-
In the following pipeline that extends this template, the script steps are stripped out and not run.
218
+
In the following example pipeline that extends the preceding template, the script steps are stripped out and not run.
182
219
183
220
```yaml
184
221
# azure-pipelines.yml
@@ -187,57 +224,24 @@ extends:
187
224
parameters:
188
225
usersteps:
189
226
- 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!
227
+
- script: echo This step is stripped out and not run
228
+
- bash: echo This step is stripped out and not run
229
+
- powershell: echo "This step is stripped out and not run"
230
+
- pwsh: echo "This step is stripped out and not run"
231
+
- script: echo This step is stripped out and not run
195
232
- task: CmdLine@2
196
-
displayName: Test - Will be stripped out
233
+
displayName: Test - stripped out
197
234
inputs:
198
-
script: echo This step will be stripped out and not run!
235
+
script: echo This step is stripped out and not run
199
236
- task: MyOtherTask@2
200
237
```
201
238
202
239
:::moniker-end
203
240
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
241
::: moniker range=">=azure-devops"
237
-
238
242
### Template steps
239
243
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.
244
+
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
245
242
246
```yaml
243
247
parameters:
@@ -258,22 +262,24 @@ jobs:
258
262
259
263
## Template enforcement
260
264
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).
265
+
The effectiveness of templates as a security mechanism relies on enforcement. The key control points for enforcing template usage are [protected resources](resources.md).
266
+
267
+
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
268
263
269
<a name="set-required-templates"></a>
264
270
### Required templates
265
271
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.
272
+
To enforce the use of a specific template, configure the [required template](../process/approvals.md#required-template) check on the service connection for a resource. This check applies only when the pipeline extends from a template.
267
273
268
-
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.
274
+
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.
269
275
270
276
:::image type="content" source="../process/media/approval-fail.png" alt-text="Screenshot showing a failed approval check.":::
271
277
272
278
When you use the required template, the check passes.
273
279
274
280
:::image type="content" source="../process/media/approval-pass.png" alt-text="Screenshot showing a passed approval check.":::
275
281
276
-
The following *params.yml* template must be referenced in any pipeline that extends it.
282
+
For example, the following *params.yml* template must be referenced in any pipeline that extends it.
277
283
278
284
```yaml
279
285
# params.yml
@@ -295,7 +301,7 @@ steps:
295
301
- script: echo ${{ parameters.image }}
296
302
```
297
303
298
-
The following example pipeline extends the *params.yml* template and requires it for approval. To demonstrate a pipeline failure, comment out the reference to *params.yml*.
304
+
The following example pipeline extends the *params.yml* template and requires it for approval. To demonstrate a pipeline failure, comment out the `extends` reference to *params.yml*.
0 commit comments