Package org.jenkinsci.plugins.scriptsecurity.scripts

Class ScriptApproval

java.lang.Object

hudson.model.Descriptor<GlobalConfiguration>

jenkins.model.GlobalConfiguration

org.jenkinsci.plugins.scriptsecurity.scripts.ScriptApproval

All Implemented Interfaces:

ExtensionPoint, Action, Describable<GlobalConfiguration>, ModelObject, RootAction, Saveable, OnMaster

@Symbol("scriptApproval")
@Extension
public final class ScriptApproval
extends GlobalConfiguration
implements RootAction

Manages approved scripts.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ScriptApproval.ApprovedClasspathEntry	Approved classpath entry.
static final class	ScriptApproval.ApprovedWhitelist
static class	ScriptApproval.FormValidationPageDecorator
static final class	ScriptApproval.PendingClasspathEntry	A classpath entry requiring approval by an administrator.
static final class	ScriptApproval.PendingScript
static final class	ScriptApproval.PendingSignature
static class	ScriptApproval.PendingThing

Nested classes/interfaces inherited from class hudson.model.Descriptor

Descriptor.FormException, Descriptor.PropertyType, Descriptor.Self

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field	Description
static boolean	ADMIN_AUTO_APPROVAL_ENABLED	SECURITY-2450: Since 1172.v35f6a_0b_8207e, unmodified, unsandboxed scripts are no longer automatically approved when administrators submit job configuration forms.
static boolean	ALLOW_ADMIN_APPROVAL_ENABLED	SECURITY-3103: Since 1265.va_fb_290b_4b_d34, administrators saving jobs (e.g., when copying existing jobs with unapproved scripts) will no longer result in unapproved scripts in those configurations being approved.

Fields inherited from class hudson.model.Descriptor

clazz

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Constructor	Description
ScriptApproval()

Method Summary

Modifier and Type	Method	Description
RejectedAccessException	accessRejected(RejectedAccessException x, ApprovalContext context)	Deprecated. Unnecessary if using GroovySandbox.enter().
String[][]	aclApproveSignature(String signature)
net.sf.json.JSON	approveClasspathEntry(String hash)
void	approveScript(String hash)
String[][]	approveSignature(String signature)
FormValidation	checking(String script, Language language)	Deprecated. Use checking(String, Language, boolean) instead
FormValidation	checking(String script, Language language, boolean willBeApproved)	To be used from form validation, in a doCheckFieldName method.
FormValidation	checking(ClasspathEntry entry)	Like checking(String, Language, boolean) but for classpath entries.
net.sf.json.JSON	clearApprovedClasspathEntries()
void	clearApprovedScripts()
String[][]	clearApprovedSignatures()
String[][]	clearDangerousApprovedSignatures()
void	clearDeprecatedApprovedScripts()	Clears approvedScriptHashes from all entries not matching DEFAULT_HASHER.
String	configuring(String script, Language language, ApprovalContext context)	Deprecated. Use configuring(String, Language, ApprovalContext, boolean) instead
String	configuring(String script, Language language, ApprovalContext context, boolean approveIfAdmin)	Used when someone is configuring a script.
void	configuring(ClasspathEntry entry, ApprovalContext context)	Called when configuring a classpath entry.
void	convertDeprecatedApprovedClasspathEntries()	Schedules a Thread task that rehashes/converts all approved classpath entries that are hashed not using DEFAULT_HASHER.
int	countDeprecatedApprovedClasspathHashes()
int	countDeprecatedApprovedScriptHashes()
net.sf.json.JSON	denyApprovedClasspathEntry(String hash)
net.sf.json.JSON	denyClasspathEntry(String hash)
void	denyScript(String hash)
void	denySignature(String signature)
void	doApproveScriptHash(String hash)
static ScriptApproval	get()	Gets the singleton instance.
String[]	getAclApprovedSignatures()
List<ScriptApproval.ApprovedClasspathEntry>	getApprovedClasspathEntries()
String[]	getApprovedScriptHashes()
String[]	getApprovedSignatures()
GlobalConfigurationCategory	getCategory()
net.sf.json.JSON	getClasspathRenderInfo()
protected XmlFile	getConfigFile()
String[]	getDangerousApprovedSignatures()
String	getIconFileName()
List<ScriptApproval.PendingClasspathEntry>	getPendingClasspathEntries()
Set<ScriptApproval.PendingScript>	getPendingScripts()
Set<ScriptApproval.PendingSignature>	getPendingSignatures()
String	getSpinnerIconClassName()
String	getUrlName()
boolean	hasDeprecatedApprovedClasspathHashes()
boolean	hasDeprecatedApprovedScriptHashes()
boolean	isConvertingDeprecatedApprovedClasspathEntries()	Checks if convertDeprecatedApprovedClasspathEntriesThread is active.
boolean	isForceSandbox()	Flag indicating whether the current system is blocking non sandbox operations for non Admin users.
boolean	isForceSandboxForCurrentUser()	Logic to indicate if the flag isForceSandbox() applies for the current user.
boolean	isScriptApproved(String script, Language language)
void	load()
static void	maybeRegister(RejectedAccessException x)
static void	popRegistrationCallback()
String	preapprove(String script, Language language)	Unconditionally approve a script.
void	preapproveAll()	Unconditionally approves all pending scripts.
static void	pushRegistrationCallback(Consumer<RejectedAccessException> callback)
void	setApprovedScriptHashes(String[] scriptHashes)
void	setApprovedSignatures(String[] signatures)
void	setForceSandbox(boolean forceSandbox)
static <T> boolean	shouldHideSandbox(T instance, Predicate<T> isSandbox)	All sandbox checkboxes in the system should confirm their visibility based on this flag. It depends on the current sandbox value in the affected instance and isForceSandboxForCurrentUser()
String	using(String script, Language language)	Called when a script is about to be used (evaluated).
void	using(ClasspathEntry entry)	Asserts that a classpath entry is approved.
static void	validateSandbox(boolean sandbox)	All describable containing the Sandbox flag should invoke this method before saving. It will confirm if the current user can persist the information in case the sandbox flag is disabled.

Methods inherited from class jenkins.model.GlobalConfiguration

all, configure, getDescriptor, getGlobalConfigPage

Methods inherited from class hudson.model.Descriptor

addHelpFileRedirect, bindJSON, calcAutoCompleteSettings, calcFillSettings, configure, doHelp, find, find, findByDescribableClassName, findById, getCheckMethod, getCheckUrl, getConfigPage, getCurrentDescriptorByNameUrl, getDescriptorFullUrl, getDescriptorUrl, getDisplayName, getGlobalPropertyType, getHelpFile, getHelpFile, getHelpFile, getId, getJsonSafeClassName, getKlass, getPlugin, getPossibleViewNames, getPropertyType, getPropertyType, getPropertyTypeOrDie, getRequiredGlobalConfigPagePermission, getT, getViewPage, isInstance, isSubTypeOf, newInstance, newInstance, newInstancesFromHeteroList, newInstancesFromHeteroList, save, self, toArray, toList, toMap

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface hudson.model.Action

getDisplayName

Field Details

ADMIN_AUTO_APPROVAL_ENABLED

public static boolean ADMIN_AUTO_APPROVAL_ENABLED

SECURITY-2450: Since 1172.v35f6a_0b_8207e, unmodified, unsandboxed scripts are no longer automatically approved when administrators submit job configuration forms.

This flag restores the previous behavior when set to true.

See Also:

• 1172.v35f6a_0b_8207e changelog

ALLOW_ADMIN_APPROVAL_ENABLED

public static boolean ALLOW_ADMIN_APPROVAL_ENABLED

SECURITY-3103: Since 1265.va_fb_290b_4b_d34, administrators saving jobs (e.g., when copying existing jobs with unapproved scripts) will no longer result in unapproved scripts in those configurations being approved.

This flag restores the previous behavior when set to true.

See Also:

• 1265.va_fb_290b_4b_d34 changelog

Constructor Details

ScriptApproval

@DataBoundConstructor
public ScriptApproval()

Method Details

getConfigFile

protected XmlFile getConfigFile()

Overrides:

getConfigFile in class Descriptor<GlobalConfiguration>

getCategory

@NonNull
public GlobalConfigurationCategory getCategory()

Overrides:

getCategory in class Descriptor<GlobalConfiguration>

get

@NonNull
public static ScriptApproval get()

Gets the singleton instance.

isScriptApproved

public boolean isScriptApproved(@NonNull
 String script,
 @NonNull
 Language language)

load

public void load()

Overrides:

load in class Descriptor<GlobalConfiguration>

hasDeprecatedApprovedScriptHashes

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean hasDeprecatedApprovedScriptHashes()

countDeprecatedApprovedScriptHashes

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public int countDeprecatedApprovedScriptHashes()

countDeprecatedApprovedClasspathHashes

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public int countDeprecatedApprovedClasspathHashes()

hasDeprecatedApprovedClasspathHashes

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean hasDeprecatedApprovedClasspathHashes()

configuring

public String configuring(@NonNull
 String script,
 @NonNull
 Language language,
 @NonNull
 ApprovalContext context,
 boolean approveIfAdmin)

Used when someone is configuring a script. Typically you would call this from a DataBoundConstructor. It should also be called from a readResolve method (which may then simply return this), so that administrators can for example POST to config.xml and have their scripts be considered approved.

If the script has already been approved, this does nothing. Otherwise, if this user has the Jenkins.ADMINISTER permission (and is not ACL.SYSTEM2) and a corresponding flag is set to true, or Jenkins is running without security, it is added to the approved list. Otherwise, it is added to the pending list.

Parameters:

script - the text of a possibly novel script

language - the language in which it is written

context - any additional information about how where or by whom this is being configured

approveIfAdmin - indicates whether script should be approved if current user has admin permissions

Returns:

script, for convenience

configuring

@Deprecated
public String configuring(@NonNull
 String script,
 @NonNull
 Language language,
 @NonNull
 ApprovalContext context)

Deprecated.

Use configuring(String, Language, ApprovalContext, boolean) instead

using

public String using(@NonNull
 String script,
 @NonNull
 Language language)
             throws UnapprovedUsageException

Called when a script is about to be used (evaluated).

Parameters:

script - a possibly unapproved script

language - the language in which it is written

Returns:

script, for convenience

Throws:

UnapprovedUsageException - in case it has not yet been approved

configuring

public void configuring(@NonNull
 ClasspathEntry entry,
 @NonNull
 ApprovalContext context)

Called when configuring a classpath entry. Usage is similar to configuring(String, Language, ApprovalContext, boolean).

Parameters:

entry - entry to be configured

context - any additional information

Throws:

IllegalStateException - Jenkins instance is not ready

checking

public FormValidation checking(@NonNull
 ClasspathEntry entry)

Like checking(String, Language, boolean) but for classpath entries. However, this method does not actually check whether the classpath entry is approved, because it would have to connect to the URL and download the contents, which may be unsafe if this is called via a web method by an unprivileged user (This is automatic if use ClasspathEntry as a configuration element.)

Parameters:

entry - the classpath entry to verify

Returns:

whether it will be approved

Throws:

IllegalStateException - Jenkins instance is not ready

using

public void using(@NonNull
 ClasspathEntry entry)
           throws IOException,
UnapprovedClasspathException

Asserts that a classpath entry is approved. Also records it as a pending entry if not approved.

Parameters:

entry - a classpath entry

Throws:

IOException - when failed to the entry is inaccessible

UnapprovedClasspathException - when the entry is not approved

checking

public FormValidation checking(@NonNull
 String script,
 @NonNull
 Language language,
 boolean willBeApproved)

To be used from form validation, in a doCheckFieldName method.

Parameters:

script - a possibly unapproved script

language - the language in which it is written

willBeApproved - whether script is going to be approved after configuration is saved

Returns:

a warning indicating that admin approval will be needed in case current user does not have Jenkins.ADMINISTER permission; a warning indicating that script is not yet approved if user has such permission and willBeApproved is false; a message indicating that script will be approved if user has such permission and willBeApproved is true; nothing if script is empty; a corresponding message if script is approved

doApproveScriptHash

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@POST
public void doApproveScriptHash(@QueryParameter(required=true)
 String hash)
                         throws IOException

Throws:

IOException

checking

@Deprecated
public FormValidation checking(@NonNull
 String script,
 @NonNull
 Language language)

Deprecated.

Use checking(String, Language, boolean) instead

preapprove

public String preapprove(@NonNull
 String script,
 @NonNull
 Language language)

Unconditionally approve a script. Does no access checks and does not automatically save changes to disk. Useful mainly for testing.

Parameters:

script - the text of a possibly novel script

language - the language in which it is written

Returns:

script, for convenience

preapproveAll

public void preapproveAll()

Unconditionally approves all pending scripts. Does no access checks and does not automatically save changes to disk. Useful mainly for testing in combination with @LocalData.

accessRejected

@Deprecated
public RejectedAccessException accessRejected(@NonNull
 RejectedAccessException x,
 @NonNull
 ApprovalContext context)

Deprecated.

Unnecessary if using GroovySandbox.enter().

To be called when a sandbox rejects access for a script not using manual approval. The signature of the failing method (if known) will be added to the pending list.

Parameters:

x - an exception with the details

context - any additional information about where or by whom this script was run

Returns:

x, for convenience in rethrowing

maybeRegister

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static void maybeRegister(@NonNull
 RejectedAccessException x)

pushRegistrationCallback

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static void pushRegistrationCallback(Consumer<RejectedAccessException> callback)

popRegistrationCallback

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static void popRegistrationCallback()

setApprovedSignatures

@DataBoundSetter
public void setApprovedSignatures(String[] signatures)
                           throws IOException

Throws:

IOException

getApprovedSignatures

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public String[] getApprovedSignatures()

getDangerousApprovedSignatures

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public String[] getDangerousApprovedSignatures()

getAclApprovedSignatures

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public String[] getAclApprovedSignatures()

setApprovedScriptHashes

@DataBoundSetter
public void setApprovedScriptHashes(String[] scriptHashes)
                             throws IOException

Throws:

IOException

setForceSandbox

@DataBoundSetter
public void setForceSandbox(boolean forceSandbox)

isForceSandbox

public boolean isForceSandbox()

Flag indicating whether the current system is blocking non sandbox operations for non Admin users.

isForceSandboxForCurrentUser

public boolean isForceSandboxForCurrentUser()

Logic to indicate if the flag isForceSandbox() applies for the current user.
It does not apply for admin users.

getApprovedScriptHashes

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public String[] getApprovedScriptHashes()

getIconFileName

public String getIconFileName()

Specified by:

getIconFileName in interface Action

getUrlName

public String getUrlName()

Specified by:

getUrlName in interface Action

getPendingScripts

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public Set<ScriptApproval.PendingScript> getPendingScripts()

approveScript

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public void approveScript(String hash)
                   throws IOException

Throws:

IOException

denyScript

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public void denyScript(String hash)
                throws IOException

Throws:

IOException

clearApprovedScripts

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public void clearApprovedScripts()
                          throws IOException

Throws:

IOException

clearDeprecatedApprovedScripts

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public void clearDeprecatedApprovedScripts()
                                    throws IOException

Clears approvedScriptHashes from all entries not matching DEFAULT_HASHER.

Throws:

IOException - if so when saving to disk.

getSpinnerIconClassName

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public String getSpinnerIconClassName()

convertDeprecatedApprovedClasspathEntries

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public void convertDeprecatedApprovedClasspathEntries()

Schedules a Thread task that rehashes/converts all approved classpath entries that are hashed not using DEFAULT_HASHER.

isConvertingDeprecatedApprovedClasspathEntries

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean isConvertingDeprecatedApprovedClasspathEntries()

Checks if convertDeprecatedApprovedClasspathEntriesThread is active.

Returns:

true if so.

getPendingSignatures

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public Set<ScriptApproval.PendingSignature> getPendingSignatures()

approveSignature

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public String[][] approveSignature(String signature)
                            throws IOException

Throws:

IOException

aclApproveSignature

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public String[][] aclApproveSignature(String signature)
                               throws IOException

Throws:

IOException

denySignature

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public void denySignature(String signature)
                   throws IOException

Throws:

IOException

clearApprovedSignatures

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public String[][] clearApprovedSignatures()
                                   throws IOException

Throws:

IOException

clearDangerousApprovedSignatures

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public String[][] clearDangerousApprovedSignatures()
                                            throws IOException

Throws:

IOException

getApprovedClasspathEntries

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public List<ScriptApproval.ApprovedClasspathEntry> getApprovedClasspathEntries()

getPendingClasspathEntries

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public List<ScriptApproval.PendingClasspathEntry> getPendingClasspathEntries()

getClasspathRenderInfo

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public net.sf.json.JSON getClasspathRenderInfo()

approveClasspathEntry

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public net.sf.json.JSON approveClasspathEntry(String hash)
                                       throws IOException

Throws:

IOException

denyClasspathEntry

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public net.sf.json.JSON denyClasspathEntry(String hash)
                                    throws IOException

Throws:

IOException

denyApprovedClasspathEntry

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public net.sf.json.JSON denyApprovedClasspathEntry(String hash)
                                            throws IOException

Throws:

IOException

clearApprovedClasspathEntries

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
@JavaScriptMethod
public net.sf.json.JSON clearApprovedClasspathEntries()
                                               throws IOException

Throws:

IOException

shouldHideSandbox

public static <T> boolean shouldHideSandbox(@CheckForNull
 T instance,
 Predicate<T> isSandbox)

All sandbox checkboxes in the system should confirm their visibility based on this flag.
It depends on the current sandbox value in the affected instance and isForceSandboxForCurrentUser()

Parameters:

isSandbox - method handle in the instance class confirming the sandbox current value for the instance.

validateSandbox

public static void validateSandbox(boolean sandbox)
                            throws Descriptor.FormException

All describable containing the Sandbox flag should invoke this method before saving.
It will confirm if the current user can persist the information in case the sandbox flag is disabled. It depends on isForceSandboxForCurrentUser() In case the current user can't save it will raise a new Descriptor.FormException

Throws:

Descriptor.FormException