Groovy Sandbox and In process Script Approval

In this guide, you’ll learn how Jenkins enforces Groovy sandbox security and how to manage in-process script approvals. We cover default sandbox behavior, unapproved method handling, UI workflows, sandbox disabling, and best practices.

Default Sandbox Execution in Pipelines

By default, Jenkins runs pipeline Groovy code inside a restricted sandbox provided by the Script Security Plugin. This prevents unauthorized operations on the controller.

pipeline {
  agent any
  stages {
    stage('Topic-1') {
      steps {
        echo 'Groovy Sandbox'
      }
    }
    stage('Topic-2') {
      steps {
        echo 'In-process Script Approval'
      }
    }
  }
}

How the Groovy Sandbox Works

Jenkins checks every method call and field access against an approved allow list.
Unapproved calls halt the script with an exception.
Signatures awaiting approval appear under Manage Jenkins ▶ In-process Script Approval.

Demonstration: Unapproved Static Method

Attempting to call a method like Hudson.getInstance() triggers a failure because it’s not on the allow list:

pipeline {
  agent any
  stages {
    stage('Get Hudson Instance') {
      steps {
        script {
          def hudson = hudson.model.Hudson.getInstance()
          println "Hudson Instance: ${hudson}"
        }
      }
    }
  }
}

The build stops with an UnapprovedUsageException:

Started by user siddharth
org.jenkinsci.plugins.scriptsecurity.scripts.UnapprovedUsageException: script not yet approved for use
    at org.jenkinsci.plugins.scriptsecurity.scripts.ScriptApproval.using(ScriptApproval.java:695)
    …
Finished: FAILURE

No further stages execute until an administrator approves the signature.

In-Process Script Approval UI

When a script fails due to an unapproved signature, it’s listed in Manage Jenkins ▶ In-process Script Approval. Administrators can:

Action	Description
Approve	Add the signature globally, allowing all pipelines to use it immediately.
Deny	Block the signature permanently and prevent future attempts.
Approve assuming permission check	Allow only if the executing user has appropriate Jenkins permissions.

The image shows a Jenkins interface for in-process script approval, highlighting a security warning about approving a specific script signature. It includes a navigation menu and a process flow diagram at the bottom.

Once approved, any pipeline invoking the signature will succeed until it’s removed from the allow list.

Disabling the Sandbox in Pipeline Configuration

Unchecking Use Groovy Sandbox means only administrators can run the pipeline without further approvals.
Non-admins see a prompt indicating that a Jenkins administrator must authorize the script.
Administrators can approve scripts directly from the job’s configuration page.

Warning

Disabling the sandbox exposes your Jenkins controller to unverified code. Only disable if absolutely necessary and you fully trust all pipeline sources.

Best Practices for Groovy Sandbox

Prefer Scripted Pipelines when advanced Groovy features are required.
Keep the sandbox enabled to minimize security risks.
Approve only read-only methods (e.g., getters). Avoid allowlisting any operations that change persisted state (e.g., execute, setters).

The image outlines three best practices for Groovy Sandbox: using scripted pipelines, disabling the sandbox, and allowlisting getMethods.

Write and test your pipeline incrementally—each unapproved call surfaces in the Script Approval UI for review.

The image outlines best practices for Groovy Sandbox, including using scripted pipelines, disabling the sandbox, and allowing specific methods.

Most safe signatures start with get. Steer clear of methods that modify external systems or internal state.

The image outlines best practices for Groovy Sandbox, featuring three steps: using scripted pipelines, disabling the sandbox, and allowing specific methods.

References

Watch Video

Watch video content