Skip to end of metadata
Go to start of metadata
Allows Jenkins administrators to control what in-process scripts can be run by less-privileged users.

Plugin Information

View Script Security on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

User’s guide

(adapted from information on template security in CloudBees Jenkins Enterprise)

Various Jenkins plugins require that users define custom scripts, most commonly in the Groovy language, to customize Jenkins’s behavior. If everyone who writes these scripts is a Jenkins administrator—specifically if they have the Overall/RunScripts permission, used for example by the Script Console link—then they can write whatever scripts they like. These scripts may directly refer to internal Jenkins objects using the same API offered to plugins. Such users must be completely trusted, as they can do anything to Jenkins (even changing its security settings or running shell commands on the server).

However, if some script authors are “regular users” with only more limited permissions, such as Job/Configure, it is inappropriate to let them run arbitrary scripts. To support such a division of roles, the Script Security library plugin can be integrated into various feature plugins. It supports two related systems: script approval, and Groovy sandboxing.

Script Approval

The first, and simpler, security system is to allow any kind of script to be run, but only with an administrator’s approval. There is a globally maintained list of approved scripts which are judged to not perform any malicious actions.

When an administrator saves some kind of configuration (for example, a job), any scripts it contains are automatically added to the approved list. They are ready to run with no further intervention. (“Saving” usually means from the web UI, but could also mean uploading a new XML configuration via REST or CLI.)

When a non-administrator saves a template configuration, a check is done whether any contained scripts have been edited from an approved text. (More precisely, whether the requested content has ever been approved before.) If it has not been approved, a request for approval of this script is added to a queue. (A warning is also displayed in the configuration screen UI when the current text of a script is not currently approved.)

An administrator may now go to Manage Jenkins » In-process Script Approval where a list of scripts pending approval will be shown. Assuming nothing dangerous-looking is being requested, just click Approve to let the script be run henceforth.

If you try to run an unapproved script, it will simply fail, typically with a message explaining that it is pending approval. You may retry once the script has been approved. The details of this behavior may vary according to the feature plugin integrating this library.

Groovy Sandboxing

Waiting for an administrator to approve every change to a script, no matter how seemingly trivial, could be unacceptable in a team spread across timezones or during tight deadlines. As an alternative option, the Script Security system lets Groovy scripts be run without approval so long as they limit themselves to operations considered inherently safe. This limited execution environment is called a sandbox. (Currently no sandbox implementations are available for other languages, so all such scripts must be approved if configured by non-administrators.)

To switch to this mode, simply check the box Use Groovy Sandbox below the Groovy script’s entry field. Sandboxed scripts can be run immediately by anyone. (Even administrators, though the script is subject to the same restrictions regardless of who wrote it.) When the script is run, every method call, object construction, and field access is checked against a whitelist of approved operations. If an unapproved operation is attempted, the script is killed and the corresponding Jenkins feature cannot be used yet.

The Script Security plugin ships with a small default whitelist, and integrating plugins may add operations to that list (typically methods specific to that plugin).

But you are not limited to the default whitelist: every time a script fails before running an operation that is not yet whitelisted, that operation is automatically added to another approval queue. An administrator can go to the same page described above for approval of entire scripts, and see a list of pending operation approvals. If Approve is clicked next to the signature of an operation, it is immediately added to the whitelist and available for sandboxed scripts.

Most signatures be of the form method class.Name methodName arg1Type arg2Type…, indicating a Java method call with a specific “receiver” class (this), method name, and list of argument (or parameter) types. (The most general signature of an attempted method call will be offered for approval, even when the actual object it was to be called on was of a more specific type overriding that method.) You may also see staticMethod for static (class) methods, new for constructors, and field for field accesses (get or set).

Administrators in security-sensitive environments should carefully consider which operations to whitelist. Operations which change state of persisted objects (such as Jenkins jobs) should generally be denied. Most getSomething methods are harmless.

ACL-aware methods

Be aware however that even some “getter” methods are designed to check specific permissions (using an ACL: access control list), whereas scripts are often run by a system pseudo-user to whom all permissions are granted. So for example method hudson.model.AbstractItem getParent (which obtains the folder or Jenkins root containing a job) is in and of itself harmless, but the possible follow-up call method hudson.model.ItemGroup getItems (which lists jobs by name within a folder) checks Job/Read. This second call would be dangerous to whitelist unconditionally, since it would mean that a user who is granted Job/Create in a folder would be able to read at least some information from any jobs in that folder, even those which are supposed to be hidden according to a project-based authorization strategy; it would suffice to create a job in the folder which includes a Groovy script like this (details would vary according to the integrating plugin):

println("I sniffed ${thisjob.getParent().getItems()}!");

When run, the script output would display at least the names of supposedly secret projects. An administrator may instead click Approve assuming permission check for getItems; this will permit the call when run as an actual user (if the integrating plugin ever does so), while forbidding it when run as the system user (which is more typical). In this case, getItems is actually implemented to return only those jobs which the current user has access to, so if run in the former case (as a specific user), the description will show just those jobs they could see anyway. This more advanced button is shown only for method calls (and constructors), and should be used only where you know that Jenkins is doing a permission check.

Developer’s guide

Complete example integration

The easy way

For a typical Groovy integration, in which you offer the user the option of using either script approval or the sandbox, change your describable’s String-valued script field into a SecureGroovyScript field. In your constructor, before storing the value, call configuringWithKeyItem (if there could only be one such script per top-level item) or configuringWithNonKeyItem (if there might be several). The configuration form should use <f:property field="…"/> to pick up the script and sandbox configuration. When you want to run the script, just call evaluate.

(For compatibility with old data, pick a different field name and deprecate the original. Then you can define a readResolve method which sets the new field to a SecureGroovyScript with the sandbox off, calls configuring(ApprovalContext.create()) on it to notify the system that an unapproved script has been loaded, and unsets the old field.)

The hard way

To be used if you need more control than SecureGroovyScript offers:

Introduce a boolean sandbox field into your configuration.

When unset, you need to call ScriptApproval.configuring in the @DataBoundConstructor. Use ApprovalContext.withCurrentUser, and also withItemAsKey where applicable (when there is just one script per job); otherwise at least withItem where applicable, and/or withKey when you can uniquely identify this usage from the context (StaplerRequest.findAncestorObject is helpful here). This lets the system know a (possibly) new script has been configured by a particular person. You will also need a readResolve that calls configuring to notify the system when a configurable with script has been loaded from disk (and thus the configurer is unknown). Call ScriptApproval.using when the script is run, and catch UnapprovedUsageException if necessary. The descriptor should use form validation on the script field and call ScriptApproval.checking (generally your descriptor should already be doing at least a syntax check on this field).

When the sandbox field is set, you need merely set up the Groovy shell with GroovySandbox.createSecureCompilerConfiguration and then call GroovySandbox.run; be prepared to catch RejectedAccessException and call ScriptApproval.accessRejected.

Preapproved methods for the sandbox

To preapprove some particular method calls, simply annotate them with @Whitelisted if in your plugin; otherwise you can register (with @Extension) a ProxyWhitelist delegating to StaticWhitelist.from and loading a text file listing whitelisted methods.

Classpath for evaluating scripts

When constructing a GroovyShell to evaluate a script, or calling SecureGroovyScript.evaluate, you must pass a ClassLoader which represents the effective classpath for the script. You could use the loader of Jenkins core, or your plugin, or Jenkins.getInstance().getPluginManager().uberClassLoader.

Whatever you choose, do not allow an unprivileged user to add arbitrary classpath entries by making a URLClassLoader! This would make it trivial to bypass all security when using the sandbox. (A user need merely make this or another job archive a JAR containing some class with a static method marked @Whitelisted and doing whatever they like, then call the method from their script.) No attack has yet been demonstrated when using whole-script approval—a URLClassLoader with normal parent-first delegation would not permit trivial masking of innocent-looking APIs by compromised versionsbut it is likely that some clever use of META-INF/services/org.codehaus.groovy.transform.ASTTransformation or similar could cause an otherwise safe script to behave in an unexpected and unauthorized manner. JENKINS-22834 suggests a safe standard alternative.

Unit tests

When writing tests for plug-ins that use the Script Security Plugin you may encounter some errors in your tests.

  • If your tests call, direct or indirectly, the ScriptApproval.get() method, then your unit tests must use JenkinsRule so that Jenkins.getInstance() does not return null.
  • It is likely that tests that were working now start to fail if you are not using the sandbox. It occurs because they are being enqueued for approval. In case you need to execute scripts regardless of approvals, ScriptApproval.get().preapprove(script, GroovyLanguage.get()) will ensure that all configured scripts are approved.
  • Alternately, you can have your tests run scripts using the sandbox. In this case you may need to whitelist methods used by your tests---either generally for real users, or using a @TestExtension to have a whitelist just for tests.

Changelog

Version 1.48 (29 Oct 2018)

Version 1.47 (17 Oct 2018)

  • Add the following methods to the generic whitelist:
    • DefaultGroovyMethods#leftShift(Writer, Object)
    • Class#isInstance(Object)
    • Throwable#getCause()
    • Arrays#asList(Object[])
    • Matcher#group(String)
    • DefaultGroovyMethods#minus(List, Collection)
    • DefaultGroovyMethods#asBoolean(CharSequence)
    • Various methods in the java.time package
  • Thanks, open source contributors TobiX, haridsv, kevinkjt2000!

Version 1.46 (Sep 5, 2018)

  • JENKINS-53420 - Fix MissingPropertyException when executing Pipeline steps.

Version 1.45 (Sep 4, 2018)

  • JENKINS-50843 - Allow calling Closure elements of a Map as methods.
  • JENKINS-51332 - Whitelist Calendar constants for days of the week and months (such as MONDAY and APRIL).
  • JENKINS-50906 - Allow this.foo() for closure variables.
  • Downgrade logging level for message about slow class loading increase threshold from 250ms to 1s.
  • Add the following methods to the generic whitelist:
    • DefaultGroovyMethods#addAll(Collection, Object[])
    • DefaultGroovyMethods#asImmutable(Map)
    • DefaultGroovyMethods#flatten(List)
    • DefaultGroovyMethods#getAt(List, Range)
    • DefaultGroovyMethods#subMap(Map, Object[])
    • DefaultGroovyMethods#subMap(Map, Collection)

Version 1.44 (Apr 27, 2018)

  • Add DefaultGroovyMethods.toLong(String) to the generic whitelist.
  • JENKINS-50470 - fix handling of ArrayList.someField to behave as a spread operation.
  • JENKINS-46882 - Add new Exception(String) to generic whitelist.

Version 1.43 (Mar 28, 2018)

  • Add DefaultGroovyMethods.collate methods to the generic whitelist.
  • JENKINS-50380 - Stop going through checkedCast process for objects that can be assigned to the target class and just return them instead.
  • Add Collection#remove(int) and List#remove(int) to the generic whitelist.
  • Add DefaultGroovyMethods for sorttoSorteduniquemaxmin, and abs to the generic whitelist. Note that using these (other than abs) in Pipeline code will not work until JENKINS-44924 is resolved.
  • Slightly improved error messages replacing unclassified ... for cases where we couldn't find a method, field, constructor, etc matching the signature.

Version 1.42 (Mar 12, 2018)

  • JENKINS-45982 - Fix an issue with calling super for a CPS-transformed method.
  • JENKINS-49542 - add Map#isEmpty() to generic whitelist.
  • Add DefaultGroovyMethods.multiply(String,Number)DefaultGroovyMethods.with(Object,Closure)Object#hashCode()Objects.hash(Object[])DefaultGroovyMethods.first(...), and DefaultGroovyMethods.last(...) to generic whitelist.

Version 1.41 (Feb 8, 2018)

  • Major improvement: greatly reduce time required to check against static Whitelists
  • Major improvement: allow permission checks to multithread - elliminate lock contention with concurrent calls
  • Improve UX for clearing dangerous signatures JENKINS-22660
  • Add Integer.toString(int, int) to default whitelist
  • Add DefaultGroovyMethods toListString and toMapString to whitelist

Version 1.40 (Jan 10, 2018)

  • Block System.getNanoTime() to prevent Spectre/Meltdown exploits.
  • Add DefaultGroovyMethods#contains(Iterable,Object) to default whitelist.

Version 1.39 (Dec 12, 2017)

  • JENKINS-48501 - Fix NPE regression caused by fix for JENKINS-48364 and JENKINS-46213.

Version 1.38 (Dec 11, 2017)

  • JENKINS-46764 - Log useful message when scriptApproval.xml is malformed.
  • JENKINS-48364 - Treat null first vararg param properly.
  • JENKINS-46213 - Treat trailing array parameters as varargs when appropriate.

Version 1.37 (Dec 11, 2017)

Version 1.36 (Nov 29, 2017)

  • JENKINS-47159JENKINS-47893 - Fix two issues with varargs handling.
  • Add more collection methods to the whitelist.
  • Hide ScriptApproval link if there are no pending or approved signatures.
  • Introduced support for SystemCommandLanguage

Version 1.35 (Nov 2, 2017)

  • JENKINS-47758 -  New feature: plugins using the SecureGroovyScript.evaluate method are automatically protected against Groovy memory leaks (most plugins)
    • Notable plugin exceptions: email-ext, matrix-project, ontrack (may be covered by a later enhancement), job-dsl (needs a bespoke implementation) and splunk-devops plugins (can't cover - doesn't use enough script-security APIs)
    • Pipeline offered its own leak protection mechanism (this is based on that)
  • JENKINS-35294 - VarArgs support for enums
  • Whitelist map.get method, List, minus, padLeft/padRight (thanks to community contributions from Github users ryankilloryIgnition, and andrey-fomin !)
  • JENKINS-47666 - Add math.max and math.min to whitelist
  • JENKINS-44557 - Properly cast GString (Groovy dynamic/templated string) in varargs

Version 1.34 (September 5, 2017)

  • JENKINS-46391 - Properly handle ~/foo/ regexp declarations and some other Pattern methods.
  • JENKINS-46358 - Whitelist a number of StringGroovyMethods including replaceAllfindAll, and more.

Version 1.33 (August 16, 2017)

  • JENKINS-46088 Fix problems caused by double sandbox transformation of right-hand-side of declarations.
  • JENKINS-33468 Allow use of it implicit closure parameter.
  • JENKINS-45776 Better handling of scoping of closure local variables.
  • JENKINS-46191 Fix compilation of empty declarations, such as String foo;, in sandbox.

Version 1.32 (August 16, 2017)

  • Failed release due to repository permissions issues; replaced by 1.33.

Version 1.31 (August 7, 2017)

Version 1.30 (July 25, 2017)

Now requires Jenkins 2.7.x or later, i.e., versions of Jenkins running Groovy 2.x.

  • Some whitelist and blacklist additions.
  • JENKINS-42563 Handling super calls to methods.

  • Be explicit about classpath directory rejection reason.
  • JENKINS-45117 Apply specificity comparisons to constructors, not just methods.

  • JENKINS-37129 Throw a more helpful MissingMethodException rather than an “unclassified” error.

  • Cleanup of math operations.
  • JENKINS-34599 Allow final fields to be set.

  • JENKINS-45629 Field initializers could produce a NullPointerException during script transformation.

Version 1.29.1 (July 10, 2017)

Version 1.29 (Jun 15, 2017)

  • Whitelist additions, particularly for DefaultGroovyMethods.

Version 1.28 (Jun 05, 2017)

  • JENKINS-34741 Unclassified error when using Groovy struct constructors.

  • Default whitelist additions.

Version 1.27 (Feb 27, 2017)

  • JENKINS-41797 Race condition could corrupt internal whitelist metadata.
  • JENKINS-39159 File handle leak when using custom script classpath could lead to unwanted locks on Windows or NFS.
  • Default whitelist additions.

Version 1.26 (Feb 13, 2017)

  • Default whitelist additions.

Version 1.25 (Jan 03, 2017)

  • More whitelist and blacklist entries.
  • Display a warning about previously approved signatures which are now in the blacklist.

Version 1.24 (Oct 20, 2016)

  • JENKINS-38908 Improper handling of some varargs methods.
  • Various whitelist additions.

Version 1.23 (Sep 21, 2016)

Version 1.22 (Aug 15, 2016)

  • Introduce a class loader caching layer for the Groovy sandbox to work around core performance limitations such as JENKINS-23784.
  • JENKINS-37344 Default whitelist additions pertaining to collections.

Version 1.21 (Jul 11, 2016)

  • Default whitelist additions pertaining to build changelogs (JENKINS-30412).

Version 1.20 (Jun 20, 2016)

  • Various default whitelist additions.
  • JENKINS-34739 Support for varargs methods.
  • JENKINS-33023 enum initializer fixes.
  • Blacklisting RunWrapper.getRawBuild.

Version 1.19 (Apr 26, 2016)

  • JENKINS-24399 Prohibit class directories from being approved classpath entries.
  • JENKINS-33023 Support enum initializers.
  • Permit metaclass methods to be run.
  • Some miscellaneous whitelist and blacklist additions.

Version 1.18.1 (Apr 11, 2016)

  • Security release (CVE-2016-3102). advisory

Version 1.18 (Apr 04, 2016)

  • Groovy prefers a getter/setter to a field access, so act accordingly, particularly when suggesting signatures to approve.
  • JENKINS-27725 Various fixes to handling of GDK methods.
  • Some miscellaneous whitelist and blacklist additions.
  • JENKINS-26481 Supporting fix to GDK method handling necessary to support calls such as Object.each(Closure) from groovy-cps Pipeline.

Version 1.17 (Jan 25, 2016)

  • obj.prop should interpret boolean TheClass.isProp(), not just boolean TheClass.getProp().

Version 1.16 (Jan 19, 2016)

  • Many more default whitelist entries, including standard Groovy operators and GDK methods.
  • JENKINS-30432 Warn about dangerous signatures.
  • JENKINS-31234 Groovy allows Singleton.instance as an alias for Singleton.getInstance(); handled.
  • JENKINS-31701 Misclassification of a method taking long and being passed an int.

Version 1.15 (Aug 20, 2015)

  • Added a number of new default whitelist entries.
  • Properly classify pseudofields of a Map.
  • JENKINS-29541 Methods on a GString may really be called on a String.
  • Corrected classification of methods ambiguous between GroovyDefaultMethods and invokeMethod.
  • JENKINS-28586 Corrected handling of receivers inside a Closure.
  • JENKINS-28154 Fixing handling of Groovy operators.

Version 1.14 (Apr 22, 2015)

  • Better error message when you mistype a method name on a Groovy class.
  • Default to using sandbox mode when the current user is not an administrator.

Version 1.13 (Feb 02, 2015)

  • Testability fix only.

Version 1.12 (Dec 04, 2014)

  • JENKINS-25914 Support for special whitelist of env in Workflow plugins.
  • Whitelisting Collection.contains.

Version 1.11 (Dec 03, 2014)

  • Handling some more Groovy constructs, such as the =~ operator, and GDK methods like Iterable.join(String).

Version 1.10 (Nov 14, 2014)

Version 1.9 (Nov 4, 2014)

  • Code can escape sandbox if there are multiple copies of groovy-sandbox.jar in Jenkins (JENKINS-25348)

Version 1.8 (Oct 29, 2014)

  • groovy-sandbox 1.8 has a few fixes.

Version 1.7 (Oct 13, 2014)

Version 1.6 (Oct 2, 2014)

  • Handle GroovyObject.invokeMethod(String,Object) correctly during call site selecction.

Version 1.5 (Aug 19, 2014)

Version 1.4 (Jun 08, 2014)

  • Do not bother enforcing whole-script approval when Jenkins is unsecured anyway.
  • Some changes to make writing acceptance tests easier.

Version 1.3 (May 13, 2014)

  • Fixing some regressions from 1.2.

Version 1.2 (May 13, 2014)

  • Updated Groovy sandbox library for better language coverage.

Version 1.1 (May 06, 2014)

  • Making it possible to use Groovy functions with def syntax.
  • Added GroovySandbox.run to stop whitelists from being consulted on methods defined in the script itself.

Version 1.0 (Apr 15, 2014)

  • String concatenation fix in sandbox.
  • Preapprove the empty script.
  • Support for static fields in sandbox.
  • Changed package of AbstractWhitelist.

Version 1.0 beta 6 (Mar 31, 2014)

  • Added SecureGroovyScript convenience class.

Version 1.0 beta 5 (Mar 13, 2014)

  • Fixed various bugs in the Groovy sandbox.
  • Added AbstractWhitelist.

Version 1.0 beta 4 (Mar 12, 2014)

  • Refactored Whitelist to support GString and more

Version 1.0 beta 3 (Mar 01, 2014)

  • Reverted GString fix for now

Version 1.0 beta 2 (Feb 28, 2014)

  • @Whitelisted
  • initialization bug fix
  • Groovy GString fix

Version 1.0 beta 1 (Feb 28, 2014)

  • Initial version.

6 Comments

  1. C H

    How do I unapprove something I approved by mistake, without clearing all approvals? Thanks!

    1. Did you have an answer? Because I am looking for such an option too.

  2. To run a System Groovy script from a file, it took over 20 different method and static new etc sandbox approvals (and an equal number of job failures)!

    I am the Jenkins administrator and according to the documentation it seems that I should be able to approve the entire script. I guess this does not happen as the script is not saved in the job configuration but is run from an external file.

    Is there a better way to structure such scripts to make them easier to execute given the Script Security restrictions?

    Perhaps an approved script repository, something along the lines of the Managed Scripts Plugin?

  3. Only StaticWhitelist supports blacklisting with no way of writing our own plugin implementation to blacklist method calls which match our own criterias. As a Jenkins administrator, for security I want to restrict any one to use classes like hudson.model.* and jenkins.model.* and any other classes that have access to the Jenkins.getInstance(), but I cannot do it, even after extending the plugin with provided extension points. Also, for every addition in my blacklist file. I have to restart the Jenkins instance.

    1. Sry to mention, but one cannot event blacklist the content by their own as the file is only loaded from the plugin resources. 

      If as an administrator I want to blacklist any access, I cannot do that. 

      1. Vishal Meghani If you want to request an improvement or feature, please open an appropriate JIRA - we do not accept feature requests in the form of Wiki comments.