Skip to content

Latest commit

 

History

History
142 lines (112 loc) · 6.36 KB

script-approval.adoc

File metadata and controls

142 lines (112 loc) · 6.36 KB
Raw
layout
section
Table of Contents

Jenkins, and a number of plugins, allow users to execute Groovy scripts in Jenkins. These scripting capabilities are provided by:

  • Script Console.

  • Jenkins Pipeline.

  • The plugin:email-ext[Extended Email plugin].

  • The plugin:groovy[Groovy plugin] - when using the "Execute system Groovy script" step.

  • The plugin:job-dsl[JobDSL plugin] as of version 1.60 and later.

To protect Jenkins from execution of malicious scripts, these plugins execute user-provided scripts in a Groovy Sandbox that limits what internal APIs are accessible. Administrators can then use the "In-process Script Approval" page, provided by the plugin:script-security[Script Security plugin], to manage which unsafe methods, if any, should be allowed in the Jenkins environment.

Entering the In-process Script Approval configuration

Getting Started

The plugin:script-security[Script Security plugin] is installed automatically by the Post-install Setup Wizard, although initially no additional scripts or operations are approved for use.

Important

Older versions of this plugin may not be safe to use. Please review the security warnings listed on plugin:script-security[the Script Security plugin page] in order to ensure that the plugin:script-security[Script Security plugin] is up to date.

Security for in-process scripting is provided by two different mechanisms: the Groovy Sandbox and Script Approval. The first, the Groovy Sandbox, is enabled by default for Jenkins Pipeline allowing user-supplied Scripted and Declarative Pipeline to execute without prior Administrator intervention. The second, Script Approval, allows Administrators to approve or deny unsandboxed scripts, or allow sandboxed scripts to execute additional methods.

For most instances, the combination of the Groovy Sandbox and the Script Security’s built-in list of approved method signatures, will be sufficient. It is strongly recommended that Administrators only deviate from these defaults if absolutely necessary.

Groovy Sandbox

To reduce manual interventions by Administrators, most scripts will run in a Groovy Sandbox by default, including all Jenkins Pipelines. The sandbox only allows a subset of Groovy’s methods deemed sufficiently safe for "untrusted" access to be executed without prior approval. Scripts using the Groovy Sandbox are all subject to the same restrictions, therefore a Pipeline authored by an Administrator is subject to the restrictions as one authorized by a non-administrative user.

When a script attempts to use features or methods unauthorized by the sandbox, a script is halted immediately, as shown below with Jenkins Pipeline

Sandbox method rejection
Figure 1. Unauthorized method signature rejected at runtime via Blue Ocean

The Pipeline above will not execute until an Administrator approves the method signature via the In-process Script Approval page.

In addition to adding approved method signatures, users may also disable the Groovy Sandbox entirely as shown below. Disabling the Groovy Sandbox requires that the entire script must be reviewed and manually approved by an administrator.

Creating a Scripted Pipeline and unchecking 'Use Groovy Sandbox'
Figure 2. Disabling the Groovy Sandbox for a Pipeline

Script Approval

Manual approval of entire scripts, or method signatures, by an administrator provides Administrators with additional flexibility to support more advanced usages of in-process scripting. When the Groovy Sandbox is disabled, or a method outside of the built-in list is invoked, the Script Security plugin will check the Administrator-managed list of approved scripts and methods.

For scripts which wish to execute outside of the Groovy Sandbox, the Administrator must approve the entire script in the In-process Script Approval page:

Approving an unsandboxed Scripted Pipeline
Figure 3. Approving an unsandboxed Scripted Pipeline

For scripts which use the Groovy Sandbox, but wish to execute an currently unapproved method signature will also be halted by Jenkins, and require an Administrator to approve the specific method signature before the script is allowed to execute:

Approving a new method signature
Figure 4. Approving a new method signature

Approve assuming permissions check

Script approval provides three options: Approve, Deny, and "Approve assuming permissions check." While the purpose of the first two are self-evident, the third requires some additional understanding of what internal data scripts are able to access and how permissions checks inside of Jenkins function.

Consider a script which accesses the method hudson.model.AbstractItem.getParent(), which by itself is harmless and will return an object containing either the folder or root item which contains the currently executing Pipeline or Job. Following that method invocation, executing hudson.model.ItemGroup.getItems(), which will list items in the folder or root item, requires the Job/Read permission.

This could mean that approving the hudson.model.ItemGroup.getItems() method signature would allow a script to bypass built-in permissions checks.

Instead, it is usually more desirable to click Approve assuming permissions check which will cause the Script Approval engine to allow the method signature assuming the user running the script has the permissions to execute the method, such as the Job/Read permission in this example.