Miscellaneous API Usage Recommendations

View the index of available developer guides

Starting Programs

Other programs should generally be invoked using a Launcher instance bound to the appropriate agent through its channel. Directly using Runtime#exec and similar Java APIs is usually a bug and can in some cases constitute a security vulnerability: While users with the permissions to configure and run jobs may be able to invoke arbitrary tools on those agents, they should not be able to run programs on the Jenkins controller.

Most Jenkins instances archive artifacts on the Jenkins controller file system, so even possible constraints, such as for the command to exist on the controller’s file system, or not taking any arguments, is trivially bypassed.

Dealing with SSL/TLS Connection Issues

Plugins that integrate with external services may encounter problems establishing connections via HTTPS due to various SSL/TLS issues. An easy way to prevent issues due to misconfigurations is to override the hostname verifier (to not perform hostname validation) and/or trust manager (to accept all certificates).

This is a very unsafe behavior and must never be the default in plugins distributed by the Jenkins project. Ignoring SSL/TLS errors is only permitted if the following constraints are both followed:

  1. Ignoring SSL/TLS errors is limited to the specific connections opened by the plugin. Plugins should never cause SSL/TLS errors to be ignored for the entire Jenkins instance. As a consequence, APIs like HttpsURLConnection#setDefaultHostnameVerifier or HttpsURLConnection#setDefaultSSLSocketFactory must not be called by plugins. The only exceptions to this rule are dedicated plugins with only this purpose, like skip-certificate-check.

  2. Ignoring SSL/TLS problems for specific connections (e.g. HttpsURLConnection#setHostnameVerifier or HttpsURLConnection#setSSLSocketFactory) is allowed, but users need to opt in to this behavior. By default, SSL/TLS problems must not be ignored.

Ideally, users have fine-grained control over which connections should ignore errors. For example, if a plugin allows integrating with a set of several different remote services, ignoring SSL/TLS errors should be a per-service option, rather than a single global option.

Processing XML, JSON, or YAML

Plugin developers need to be careful when working with user-provided content. This can take many forms, but common data formats are XML, JSON, and YAML, and are provided through potentially untrusted sources.

If you’re implementing form validation for a build step whose configuration is provided as XML, or a post-build step that processes a file in the workspace, be sure to treat the contents as not fully trusted.

XML

Be sure to review the OWASP Cheat Sheet for XML External Entity prevention. All content should be treated as untrusted except in very specific circumstances.

When using jackson-databind, make sure to depend on 2.10.x or newer, and only use the "safe" replacement APIs to prevent deserialization vulnerabilities: Use activateDefaultTyping instead of enableDefaultTyping. See the documentation on polymorphic deserialization.

X-Stream is bundled with Jenkins. Jenkins plugins generally should not use it directly, but only through XStream2.

YAML

When processing YAML, be sure to look into the parser library’s security documentation. It needs to be configured to prevent the instantiation of arbitrary types.

When using SnakeYAML, make sure to never use the parameterless new Yaml() constructor, but to pass a SafeConstructor as argument (or otherwise restrict what can be deserialized). Additionally, use at least version 1.26 to get denial-of-service protection ("billion laughs"). Consider depending on the SnakeYAML API Plugin instead of bundling SnakeYAML with your plugin.

Groovy Scripting

Many Jenkins plugins allow the use of Groovy to extend their capabilites. For example, the Email Extension Plugin allows executing a script to determine whether an email should be sent.

All such functionality, if available to users without Overall/Administer, must integrate with Script Security Plugin.