11.1. Securing extensions

This section describes how to ensure the security of custom-written additions in Neo4j.

Neo4j can be extended by writing custom code which can be invoked directly from Cypher, as described in Java Reference → Procedures and functions. This section describes how to ensure the security of these additions.

11.1.1. Sandboxing

Neo4j provides sandboxing to ensure that procedures do not inadvertently use insecure APIs. For example, when writing custom code it is possible to access Neo4j APIs that are not publicly supported, and these internal APIs are subject to change, without notice. Additionally, their use comes with the risk of performing insecure actions. The sandboxing functionality limits the use of extensions to publicly supported APIs, which exclusively contain safe operations, or contain security checks.

The configuration setting dbms.security.procedures.unrestricted provides the possibility to circumvent the sandboxing functionality by defining a comma-separated list of procedures and/or user-defined functions that are allowed full access to the database. The list may contain fully-qualified procedure names, and partial names with the wildcard *.

Any attempt to load an extension which contains an unsupported API, which has not been marked as allowed in dbms.security.procedures.unrestricted, will result in a warning in the security log. The warning will point out that the extension does not have access to the components it is trying to load. Additionally, a mocked procedure will be loaded with the procedure’s name. Calling the mocked procedure will result in an error, saying that the procedure failed to load due to needing more permissions.

Example 11.1. Sandboxing

In this example we assume that the procedure my.extensions.example, as well as some procedures in the my.procedures library, make use of unsupported APIs. In order to allow the running of these procedures we configure the setting as shown below.

# Example sandboxing

11.1.2. White listing

White listing can be used to allow loading only a few extensions from a larger library.

The configuration setting dbms.security.procedures.whitelist is used to name certain procedures that should be available from a library. It defines a comma-separated list of procedures that are to be loaded. The list may contain both fully-qualified procedure names, and partial names with the wildcard *.

Example 11.2. White listing

In this example we wish to allow the use of the method apoc.load.json as well as all the methods under apoc.coll. We do not want to make available any additional extensions from the apoc library, other than the ones matching these criteria.

# Example white listing

There are a few things that should be noted about dbms.security.procedures.whitelist:

  • If using this setting, no extensions other than those listed will be loaded. In particular, if it is set to the empty string, no extensions will be loaded.
  • The default of the setting is *. This means that if you do not explicitly give it a value (or no value), all libraries in the plugins directory will be loaded.
  • If the extensions pointed out by this parameter are programmed to access internal APIs, they also have to be explicitly allowed, as described in Section 11.1.1, “Sandboxing”.