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
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.
14
+
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
15
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.
16
+
- Defining the outer structure of a pipeline to help prevent malicious code infiltration.
17
+
- Automatically including steps to do tasks such as credential scanning.
18
+
- 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.
27
25
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.
26
+
- 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.
29
27
30
28
```yaml
31
29
steps:
@@ -53,7 +51,7 @@ steps:
53
51
- ${{ step }}
54
52
```
55
53
56
-
The following pipeline code extends the *template.yml* template.
54
+
The following example pipeline extends the *template.yml* template.
57
55
58
56
```yaml
59
57
# azure-pipelines.yml
@@ -77,32 +75,30 @@ extends:
77
75
78
76
## Pipeline security features
79
77
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.
78
+
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.
81
79
82
80
### Step targets
83
81
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.
85
-
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.
82
+
You can restrict specified steps to run in a container rather than on the host. Steps in containers can't access the agent's host, so they can't modify agent configuration or leave malicious code for later execution.
87
83
88
-
The following example pipeline runs a step on the agent host before running a step inside a container.
84
+
For example, you can prevent open network access from within a container, so user steps can't retrieve packages from unauthorized sources or upload code and secrets to external locations. The following example pipeline demonstrates running a step on the agent host before running a step inside a container.
89
85
90
86
```yaml
91
87
resources:
92
88
containers:
93
89
- container: builder
94
90
image: mysecurebuildcontainer:latest
95
91
steps:
96
-
- script: echo This step runs on the agent host, and it could use Docker commands to tear down or limit the container's network
97
-
- script: echo This step runs inside the builder container
92
+
- script: echo This step runs on the agent host, so could use commands to tear down or limit the host network
93
+
- script: echo This step runs inside the builder container, which limits network access
98
94
target: builder
99
95
```
100
96
101
97
### Type-safe parameters
102
98
103
99
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
100
105
-
In the following example template, the parameters restrict the available pipeline pool options by enumerating specific choices instead of allowing freeform strings.
101
+
In the following example template, the parameters restrict the available pipeline pool options by enumerating specific choices instead of allowing any string.
106
102
107
103
```yaml
108
104
# template.yml
@@ -120,7 +116,7 @@ steps:
120
116
- script: echo Hello world
121
117
```
122
118
123
-
When it extends the template, the pipeline must specify one of the available pool choices.
119
+
To extend the template, the pipeline must specify one of the available pool choices.
124
120
125
121
```yaml
126
122
# azure-pipelines.yml
@@ -134,9 +130,9 @@ extends:
134
130
135
131
### Agent logging command restrictions
136
132
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.
133
+
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.
138
134
139
-
In the following example, the `target` property instructs the agent not to allow publishing artifacts, so the task fails.
135
+
In the following example, the `target` property instructs the agent not to allow publishing artifacts, so the artifact publishing task fails.
140
136
141
137
```yaml
142
138
- task: PublishBuildArtifacts@1
@@ -146,11 +142,13 @@ In the following example, the `target` property instructs the agent not to allow
146
142
commands: restricted
147
143
```
148
144
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.
145
+
#### Variables in logging commands
146
+
147
+
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 as environment variables to subsequent tasks and compromise the agent host.
150
148
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.
149
+
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.
152
150
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.
151
+
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 called `BadVar`.
154
152
155
153
```yaml
156
154
- task: PowerShell@2
@@ -184,7 +182,7 @@ jobs:
184
182
185
183
Azure Pipelines templates have the flexibility to iterate over and modify YAML syntax. By using iteration, you can enforce specific YAML security features.
186
184
187
-
A template can also rewrite user steps, allowing only approved tasks to run. For example, you can prevent inline script execution.
185
+
A template can also rewrite user steps, allowing only approved tasks to run. For example, the template can prevent inline script execution.
188
186
189
187
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`.
190
188
@@ -214,7 +212,7 @@ steps:
214
212
displayName: 'Disabled by template: ${{ step.displayName }}'
215
213
```
216
214
217
-
In the following pipeline that extends this template, the script steps are stripped out and not run.
215
+
In the following example pipeline that extends the preceding template, the script steps are stripped out and not run.
218
216
219
217
```yaml
220
218
# azure-pipelines.yml
@@ -268,7 +266,7 @@ You can configure [approvals and checks](../process/approvals.md) for your agent
268
266
<a name="set-required-templates"></a>
269
267
### Required templates
270
268
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.
269
+
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.
272
270
273
271
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.
0 commit comments