> User Documentation Home

User Handbook
Tutorials
Resources
⇑ Managing Jenkins
Index

Script Console

Jenkins features a Groovy script console which allows one to run arbitrary Groovy scripts within the Jenkins controller runtime or in the runtime on agents.

It is very important to understand all of the following points because it affects the integrity of your Jenkins installation. The Jenkins Script Console:

  • Access is controlled by the RunScripts permission. If any authorization strategy allows this permission to be granted to users other than Admins, then extreme care should be taken not to allow non-admins to use this.

  • Is a web-based Groovy shell into the Jenkins runtime. Groovy is a very powerful language which offers the ability to do practically anything Java can do including:

    • Create sub-processes and execute arbitrary commands on the Jenkins controller and agents.

    • It can even read files in which the Jenkins controller has access to on the host (like /etc/passwd)

    • Decrypt credentials configured within Jenkins.

  • Offers no administrative controls to stop a User (or Admin) once they are able to execute the Script Console from affecting all parts of the Jenkins infrastructure. Granting a normal Jenkins user Script Console Access is essentially the same as giving them Administrator rights within Jenkins.

  • Can configure any Jenkins setting. It can disable security, reconfigure security, even open a backdoor on the host operating system completely outside of the Jenkins process. Due to the mission critical importance many organizations place on Jenkins in their infrastructure this point is especially important because it would allow an attacker to move laterally within infrastructure with little effort.

  • Is so powerful because it was originally intended as a debugging interface for Jenkins developers but has since grown into an interface used by Jenkins Admins to configure Jenkins and debug Jenkins runtime issues.

Because of the power offered by the Jenkins Script Console, Jenkins and its agents should never be run as the root user (on Linux) or system administrator on any other flavor of OS. Videos linked in this page demonstrate and discuss security warnings.

Be sure to secure your Jenkins instance

Multiple contexts

The Jenkins Script Console can run either on the controller or any configured agents.

Running Script Console on the controller

This feature can be accessed from "Manage Jenkins" > "Script Console".  Or by visiting the sub-URL /script on your Jenkins instance.

Running Script Console on agents

Visit "Manage Jenkins" > "Manage Nodes".  Select any node to view the status page.  In the menu on the left, a menu item is available to open a "Script Console" on that specific agent.

Run scripts from controller Script Console on agents

It’s also possible to run scripts from the controller Script Console on individual agents.  The following script is an example running a script on agents from the controller Script Console.

Script executes code on agent from Master Script Console

import hudson.util.RemotingDiagnostics
import jenkins.model.Jenkins

String agentName = 'your agent name'
//groovy script you want executed on an agent
groovy_script = '''
println System.getenv("PATH")
println "uname -a".execute().text
'''.trim()

String result
Jenkins.instance.slaves.find { agent ->
    agent.name == agentName
}.with { agent ->
    result = RemotingDiagnostics.executeGroovy(groovy_script, agent.channel)
}
println result

Reading and writing files

Files can be read and written directly on the controller or agents via the controller Script Console.

Write a file to the Jenkins controller

new File('/tmp/file.txt').withWriter('UTF-8') { writer ->
    try {
        writer << 'hello world\n'
    } finally {
        writer.close()
    }
}

Reading a file from the Jenkins controller

new File('/tmp/file.txt').text

Write file to agent through agent channel

import hudson.FilePath
import hudson.remoting.Channel
import jenkins.model.Jenkins

String agentName = 'some-agent'
String filePath = '/tmp/file.txt'

Channel agentChannel = Jenkins.instance.slaves.find { agent ->
    agent.name == agentName
}.channel

new FilePath(agentChannel, filePath).write().with { os ->
    try {
        os << 'hello world\n'
    } finally {
        os.close()
    }
}

Read file from agent through agent channel

import hudson.FilePath
import hudson.remoting.Channel
import jenkins.model.Jenkins

import java.io.BufferedReader
import java.io.InputStreamReader
import java.nio.charset.StandardCharsets
import java.util.stream.Collectors

String agentName = 'some-agent'
String filePath = '/tmp/file.txt'

Channel agentChannel = Jenkins.instance.slaves.find { agent ->
    agent.name == agentName
}.channel

String fileContents = ''
new FilePath(agentChannel, filePath).read().with { is ->
    try {
        fileContents = new BufferedReader(
            new InputStreamReader(is, StandardCharsets.UTF_8))
                .lines()
                .collect(Collectors.joining("\n"))
    } finally {
        is.close()
    }
}

// print contents of the file from the agent
println '==='
println(fileContents)
println '==='

Remote access

A Jenkins Admin can execute groovy scripts remotely by sending an HTTP POST request to /script/ url or /scriptText/.

curl example via bash

curl -d "script=<your_script_here>" https://jenkins/script
# or to get output as a plain text result (no HTML)
curl -d "script=<your_script_here>" https://jenkins/scriptText

Also, Jenkins CLI offers the possibility to execute groovy scripts remotely using groovy command or execute groovy interactively via groovysh. However, once again curl can be used to execute groovy scripts by making use of bash command substitution. In the following example somescript.groovy is a groovy script in the current working directory.

Curl submitting groovy file via bash

curl --data-urlencode "script=$(< ./somescript.groovy)" https://jenkins/scriptText

If security is configured in Jenkins, then curl can be provided options to authenticate using the curl --user option.

Curl submitting groovy file providing username and api token via bash

curl --user 'username:api-token' --data-urlencode \
  "script=$(< ./somescript.groovy)" https://jenkins/scriptText

Here is the equivalent command using python, not curl.

Python submitting groovy file providing username and api token

with open('somescript.groovy', 'r') as fd:
    data = fd.read()
r = requests.post('https://jenkins/scriptText', auth=('username', 'api-token'), data={'script': data})

Shortcut key on script console to submit

You can submit a script without mouse. Jenkins has a shortcut key which enables to submit with keyboard.

  • Windows / Linux: Ctrl + Enter

  • Mac: Command + Enter

Video Tutorials and additional learning materials

Here are some recorded videos on the Jenkins Script Console:

To expand your ability to write scripts in the script console, the following references are recommended:

Example Groovy scripts

Out of date scripts

Due to the nature of Groovy scripts accessing Jenkins source code directly, Script Console scripts are easily out of date from the Jenkins source code. It is possible to run a script and get exceptions because public methods and interfaces in Jenkins core or Jenkins plugins have changed. Keep this in mind when trying out examples. Jenkins is easily started from a local development machine via the following command:

Starting a local copy of Jenkins

export JENKINS_HOME="./my_jenkins_home"
java -jar jenkins.war

Use CTRL+C to stop Jenkins. It is not recommended to try Script Console examples in a production Jenkins instance.

The following repositories offer solid examples of Groovy scripts for Jenkins.

Browse all Scriptler Plugin Groovy Scripts and please share your scripts with the Scriptler Plugin.

Plugins enabling Groovy usage

  • Config File Provider Plugin Adds the ability to provide configuration files (i.e., settings.xml for maven, XML, groovy, custom files, etc.) loaded through the Jenkins UI which will be copied to the job’s workspace.

  • Global Post Script Plugin — Execute a global configured groovy script after each build of each job managed by the Jenkins. This is typical for cases when you need to do something based on a shared set of parameters, such as triggering downstream jobs managed by the same Jenkins or remote ones based on the parameters been passed to the parameterized jobs.

  • Groovy plugin

  • Groovy Postbuild Plugin — This plugin executes a groovy script in the Jenkins JVM. Typically, the script checks some conditions and changes accordingly the build result, puts badges next to the build in the build history and/or displays information on the build summary page.

  • Groovy Remote Control Plugin — This plugin provides Groovy Remote Control's receiver, and allows to control external application from Jenkins.

  • Matrix Groovy Execution Strategy Plugin — A plugin to decide the execution order and valid combinations of matrix projects.

  • Pipeline Classpath Step Plugin Pipeline DSL step to add path to the groovy classpath

  • Scriptler Plugin — Scriptler allows you to store/edit groovy scripts and execute it on any of the nodes…​ no need to copy/paste groovy code anymore.

⇑ Managing Jenkins
Index

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.