org.jenkinsci.plugins.scriptsecurity.scripts

Class ScriptApproval

java.lang.Object

org.jenkinsci.plugins.scriptsecurity.scripts.ScriptApproval

All Implemented Interfaces:

hudson.ExtensionPoint, hudson.model.Action, hudson.model.ModelObject, hudson.model.RootAction, hudson.model.Saveable

@Extension
public class ScriptApproval
extends Object
implements hudson.model.RootAction, hudson.model.Saveable

Manages approved scripts.

Nested Class Summary

Nested Classes

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

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

hudson.ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Constructor and Description
ScriptApproval()

Method Summary

Modifier and Type	Method and Description
RejectedAccessException	accessRejected(RejectedAccessException x, ApprovalContext context) To be called when a sandbox rejects access for a script not using manual approval.
String[][]	aclApproveSignature(String signature)
net.sf.json.JSON	approveClasspathEntry(String hash)
void	approveScript(String hash)
String[][]	approveSignature(String signature)
hudson.util.FormValidation	checking(ClasspathEntry entry) Like checking(String, Language) but for classpath entries.
hudson.util.FormValidation	checking(String script, Language language) To be used from form validation, in a doCheckFieldName method.
net.sf.json.JSON	clearApprovedClasspathEntries()
void	clearApprovedScripts()
String[][]	clearApprovedSignatures()
void	configuring(ClasspathEntry entry, ApprovalContext context) Called when configuring a classpath entry.
String	configuring(String script, Language language, ApprovalContext context) Used when someone is configuring a script.
net.sf.json.JSON	denyApprovedClasspathEntry(String hash)
net.sf.json.JSON	denyClasspathEntry(String hash)
void	denyScript(String hash)
void	denySignature(String signature)
static ScriptApproval	get() Gets the singleton instance.
String[]	getAclApprovedSignatures()
List<ScriptApproval.ApprovedClasspathEntry>	getApprovedClasspathEntries()
String[]	getApprovedSignatures()
net.sf.json.JSON	getClasspathRenderInfo()
String[]	getDangerousApprovedSignatures()
String	getDisplayName()
String	getIconFileName()
List<ScriptApproval.PendingClasspathEntry>	getPendingClasspathEntries()
Set<ScriptApproval.PendingScript>	getPendingScripts()
Set<ScriptApproval.PendingSignature>	getPendingSignatures()
String	getUrlName()
String	preapprove(String script, Language language) Unconditionally approve a script.
void	preapproveAll() Unconditionally approves all pending scripts.
void	save()
void	using(ClasspathEntry entry) Asserts that a classpath entry is approved.
String	using(String script, Language language) Called when a script is about to be used (evaluated).

Methods inherited from class java.lang.Object

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

Constructor Detail

ScriptApproval

public ScriptApproval()

Method Detail

get

@Nonnull
public static ScriptApproval get()

Gets the singleton instance.

configuring

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

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.RUN_SCRIPTS permission (and is not ACL.SYSTEM), 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

Returns:

script, for convenience

Throws:

IllegalStateException - Jenkins instance is not ready

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).

Parameters:

entry - entry to be configured

context - any additional information

Throws:

IllegalStateException - Jenkins instance is not ready

checking

public hudson.util.FormValidation checking(@Nonnull
                                           ClasspathEntry entry)

Like checking(String, Language) but for classpath entries. (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 hudson.util.FormValidation checking(@Nonnull
                                           String script,
                                           @Nonnull
                                           Language language)

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

Parameters:

script - a possibly unapproved script

language - the language in which it is written

Returns:

a warning in case the script is not yet approved and this user lacks Jenkins.RUN_SCRIPTS, else FormValidation.ok()

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

public RejectedAccessException accessRejected(@Nonnull
                                              RejectedAccessException x,
                                              @Nonnull
                                              ApprovalContext context)

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

getApprovedSignatures

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

getDangerousApprovedSignatures

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

getAclApprovedSignatures

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

getIconFileName

public String getIconFileName()

Specified by:

getIconFileName in interface hudson.model.Action

getDisplayName

public String getDisplayName()

Specified by:

getDisplayName in interface hudson.model.Action

Specified by:

getDisplayName in interface hudson.model.ModelObject

getUrlName

public String getUrlName()

Specified by:

getUrlName in interface hudson.model.Action

save

public void save()
          throws IOException

Specified by:

save in interface hudson.model.Saveable

Throws:

IOException

getPendingScripts

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

approveScript

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

Throws:

IOException

denyScript

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

Throws:

IOException

clearApprovedScripts

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

Throws:

IOException

getPendingSignatures

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

approveSignature

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

Throws:

IOException

aclApproveSignature

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

Throws:

IOException

denySignature

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

Throws:

IOException

clearApprovedSignatures

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

Throws:

IOException

getApprovedClasspathEntries

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

getPendingClasspathEntries

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

getClasspathRenderInfo

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

approveClasspathEntry

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

Throws:

IOException

denyClasspathEntry

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

Throws:

IOException

denyApprovedClasspathEntry

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

Throws:

IOException

clearApprovedClasspathEntries

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

Throws:

IOException