Jenkins pipelines allow users to execute Groovy code to automate builds, deployments, and infrastructure operations. Because this code may come from repositories or contributors who do not have administrative access to the Jenkins controller, Jenkins must enforce a strict execution security model.
The Script Security Model protects the Jenkins platform by restricting what pipeline code can do, preventing malicious or unsafe operations from compromising the system.
This article explains:
- Why Jenkins restricts Groovy execution
- How the Groovy Sandbox works
- When sandbox execution is used
- The In-Process Script Approval mechanism
- Why plugins like Active Choices require approval
- Best practices for secure pipeline design
1. Why Jenkins Needs Script Security
A Jenkins pipeline can execute powerful operations such as:
- running shell commands
- cloning repositories
- accessing credentials
- modifying files
- interacting with cloud APIs
Without restrictions, a malicious pipeline could:
- access sensitive credentials
- delete files on the Jenkins controller
- execute arbitrary system commands
- exfiltrate secrets from the environment
Since pipelines are often defined by developers and stored in Git repositories, Jenkins cannot assume that every script is trusted.
To mitigate these risks, Jenkins uses the Script Security Plugin, which implements a sandboxed Groovy runtime.
2. The Two Execution Modes in Jenkins
Groovy code in Jenkins can run in two different modes.
| Mode | Description |
|---|---|
| Groovy Sandbox | Restricted execution environment |
| Non-Sandbox Execution | Full Groovy execution requiring administrator approval |
The sandbox is the default execution mode for most Jenkins pipelines.
3. When the Groovy Sandbox Is Used
In most modern Jenkins setups, the user does not explicitly choose whether the sandbox is used.
Jenkinsfile Pipelines
When a pipeline is defined using a Jenkinsfile from a Git repository:
Pipeline script from SCM
the pipeline runs automatically inside the Groovy Sandbox.
Example Jenkinsfile:
pipeline {
agent any
stages {
stage("Example") {
steps {
echo "Hello Jenkins"
}
}
}
}
Because Jenkinsfiles may be modified by developers through Git commits, Jenkins treats them as untrusted code and enforces sandbox restrictions automatically.
Pipeline Script Defined in the Jenkins UI
When a pipeline script is written directly in the Jenkins UI, Jenkins exposes a checkbox:
Use Groovy Sandbox
If this option is enabled, the script runs inside the sandbox.
If disabled, the script runs with full Groovy access but requires administrator approval before execution.
Active Choice Parameters
Some plugins execute Groovy scripts outside the normal pipeline runtime.
For example:
CascadeChoiceParameter
ActiveChoiceParameter
These parameters use a GroovyScript object that includes a sandbox configuration:
script: [
$class: 'GroovyScript',
script: 'return ["dev","stage","prod"]',
sandbox: false
]
When sandbox execution is disabled, Jenkins requires administrator approval before running the script.
Shared Libraries
Shared libraries behave differently depending on how they are configured.
| Library Type | Sandbox |
|---|---|
| Trusted library | No sandbox restrictions |
| Untrusted library | Sandbox enforced |
Trusted libraries are usually configured globally by Jenkins administrators and are considered part of the Jenkins platform itself.
4. How the Groovy Sandbox Works
The Jenkins Groovy Sandbox intercepts every method call performed by a pipeline script.
When a method is invoked, Jenkins verifies it against a whitelist of approved operations.
For each call Jenkins checks:
- Is the class allowed?
- Is the method allowed?
- Is the operation safe?
If the call is not approved, Jenkins blocks execution.
Example:
new File("/etc/passwd").text
This operation would be rejected because direct filesystem access is not allowed in the sandbox.
5. The Role of the Script Security Plugin
The Script Security Plugin enforces the sandbox and manages approvals.
It performs several functions:
- intercepting Groovy method calls
- validating calls against a whitelist
- managing approval of unsafe operations
- preventing unauthorized access to Jenkins internals
Internally, the plugin uses Groovy AST transformations to instrument scripts and enforce security rules.
This means that before the script executes, Jenkins modifies the Groovy code to ensure every operation is validated.
6. In-Process Script Approval
When a pipeline attempts to execute an operation that is not on the whitelist, Jenkins blocks the execution and records the request.
Administrators can review and approve these operations via:
Manage Jenkins -> In-Process Script Approval
Instead of approving entire scripts, Jenkins approves individual method signatures.
Examples:
method java.lang.String execute
new java.io.File
staticMethod java.lang.System getenv
Once approved, the operation can be used in pipelines.
7. Why Active Choice Parameters Require Approval
Plugins such as Active Choices execute Groovy scripts dynamically when Jenkins renders the job parameter interface.
Example script:
def items = [
"kubernetes",
"vault",
"gitlab"
]
return items
Since these scripts execute outside the pipeline runtime and may interact with Jenkins objects or external systems, Jenkins treats them as potentially unsafe.
Therefore they often require administrator approval before they can run.
8. Pipeline DSL vs Groovy Execution
Jenkins pipelines combine two different execution models.
Jenkins Pipeline DSL
These commands are provided by Jenkins plugins:
stage
steps
sh
checkout
withCredentials
archiveArtifacts
These operations are considered safe because they run through controlled plugin APIs.
Groovy Runtime
Groovy code allows:
- variables
- loops
- conditionals
- maps
- functions
Example:
def services = ["api","worker"]
services.each {
echo it
}
Groovy operations are subject to sandbox restrictions.
9. Important Security Detail: Shell Commands
A common misconception is that the sandbox prevents all dangerous operations.
In reality, the sandbox protects Groovy execution, not shell commands.
For example:
sh "rm -rf /tmp/test"
The sh step is allowed because it is a Jenkins plugin step.
The command itself executes on the agent node, not inside the sandbox.
This means the sandbox protects Jenkins internals but does not restrict what a build can do on an agent.
10. Script Security and Credentials
Sensitive data such as credentials must be accessed using dedicated pipeline steps.
Example:
withCredentials([usernamePassword(
credentialsId: 'git-creds',
usernameVariable: 'USER',
passwordVariable: 'PASS'
)]) {
sh "git clone https://${USER}:${PASS}@repo"
}
The withCredentials step ensures that:
- secrets are masked in logs
- credentials are scoped to the block
- sensitive values are not exposed outside the step
11. Common Script Security Errors
Users frequently encounter errors caused by sandbox restrictions.
Example:
Scripts not permitted to use method java.lang.String execute
This indicates that the pipeline attempted to call a method that is not on the sandbox whitelist.
Resolution requires administrator approval or rewriting the pipeline using approved steps.
12. Best Practices for Secure Pipelines
To work effectively within the Script Security Model, follow these practices.
Prefer Jenkins pipeline steps
Use built-in steps such as:
sh
checkout
git
archiveArtifacts
withCredentials
instead of invoking low-level system APIs.
Move complex logic into shared libraries
Trusted shared libraries can bypass sandbox restrictions and provide reusable functionality.
Avoid direct filesystem manipulation
Instead of using Groovy file APIs, prefer Jenkins workspace operations.
Review script approvals carefully
Administrators should ensure that approved methods do not introduce security risks.
13. Summary
The Jenkins Script Security Model protects Jenkins infrastructure from unsafe pipeline code by enforcing strict control over Groovy execution.
Key elements of the model include:
- the Groovy Sandbox, which restricts method calls
- the Script Security Plugin, which intercepts operations
- the In-Process Script Approval system, which allows administrators to review unsafe operations
- controlled access to credentials and pipeline steps
Understanding how the sandbox works is essential for designing secure Jenkins pipelines, especially when using dynamic parameters, shared libraries, or advanced Groovy logic.
A well-designed pipeline architecture respects these constraints while still providing powerful automation capabilities.