Scripting and security

You should never run Elasticsearch as the root user, as this would allow a script to access or do anything on your server, without limitations.

You should not expose Elasticsearch directly to users, but instead have a proxy application inbetween. If you do intend to expose Elasticsearch directly to your users, then you have to decide whether you trust them enough to run scripts on your box or not, and apply the appropriate safety measures.

The script.* settings allow for fine-grained control of which script languages (e.g groovy, painless) are allowed to run in which context ( e.g. search, aggs, update), and where the script source is allowed to come from (i.e. inline, stored, file).

For instance, the following setting enables stored update scripts for groovy:

script.engine.groovy.inline.update: true

Less fine-grained settings exist which allow you to enable or disable scripts for all sources, all languages, or all contexts. The following settings enable inline and stored scripts for all languages in all contexts:

script.inline: true
script.stored: true

Scripts may be enabled or disabled depending on their source: inline, stored in the cluster state, or from a file on each node in the cluster. Each of these settings takes one of these values:

The default values are the following:

script.inline: false
script.stored: false
script.file:   true

Scripting may also be enabled or disabled in different contexts in the Elasticsearch API. The supported contexts are:

Plugins can also define custom operations that they use scripts for instead of using the generic plugin category. Those operations can be referred to in the following form: ${pluginName}_${operation}.

The following example disables scripting for update and plugin operations, regardless of the script source or language. Scripts can still be executed from sandboxed languages as part of aggregations, search and plugins execution though, as the above defaults still get applied.

script.update: false
script.plugin: false

First, the high-level script settings described above are applied in order (context settings have precedence over source settings). Then, fine-grained settings which include the script language take precedence over any high-level settings.

Fine-grained settings have the form:

script.engine.{lang}.{source}.{context}: true|false

And

script.engine.{lang}.{inline|file|stored}: true|false

For example:

script.inline: false 
script.stored: false 
script.file:   false 

script.engine.groovy.inline:          true 
script.engine.groovy.stored.search:   true 
script.engine.groovy.stored.aggs:     true 

script.engine.mustache.stored.search: true 

Elasticsearch runs with the Java Security Manager enabled by default. The security policy in Elasticsearch locks down the permissions granted to each class to the bare minimum required to operate. The benefit of doing this is that it severely limits the attack vectors available to a hacker.

Restricting permissions is particularly important with scripting languages like Groovy and Javascript which are designed to do anything that can be done in Java itself, including writing to the file system, opening sockets to remote servers, etc.

Scripting languages are only allowed to load classes which appear in a hardcoded whitelist that can be found in org.elasticsearch.script.ClassPermission.

In a script, attempting to load a class that does not appear in the whitelist may result in a ClassNotFoundException, for instance this script:

GET _search
{
  "script_fields": {
    "the_hour": {
      "script": "use(java.math.BigInteger); new BigInteger(1)"
    }
  }
}

will return the following exception:

{
  "reason": {
    "type": "script_exception",
    "reason": "failed to run inline script [use(java.math.BigInteger); new BigInteger(1)] using lang [groovy]",
    "caused_by": {
      "type": "no_class_def_found_error",
      "reason": "java/math/BigInteger",
      "caused_by": {
        "type": "class_not_found_exception",
        "reason": "java.math.BigInteger"
      }
    }
  }
}

However, classloader issues may also result in more difficult to interpret exceptions. For instance, this script:

use(groovy.time.TimeCategory); new Date(123456789).format('HH')

Returns the following exception:

{
  "reason": {
    "type": "script_exception",
    "reason": "failed to run inline script [use(groovy.time.TimeCategory); new Date(123456789).format('HH')] using lang [groovy]",
    "caused_by": {
      "type": "missing_property_exception",
      "reason": "No such property: groovy for class: 8d45f5c1a07a1ab5dda953234863e283a7586240"
    }
  }
}

If you encounter issues with the Java Security Manager, you have two options for resolving these issues:

The safest and most secure long term solution is to change the code causing the security issue. We recognise that this may take time to do correctly and so we provide the following two alternatives.

The classloader whitelist can be customised by tweaking the local Java Security Policy either:

Permissions may be granted at the class, package, or global level. For instance:

grant {
    permission org.elasticsearch.script.ClassPermission "java.util.Base64"; // allow class
    permission org.elasticsearch.script.ClassPermission "java.util.*"; // allow package
    permission org.elasticsearch.script.ClassPermission "*"; // allow all (disables filtering basically)
};

Here is an example of how to enable the groovy.time.TimeCategory class:

grant {
    permission org.elasticsearch.script.ClassPermission "java.lang.Class";
    permission org.elasticsearch.script.ClassPermission "groovy.time.TimeCategory";
};

See http://docs.oracle.com/javase/7/docs/technotes/guides/security/PolicyFiles.html for more information.