Capabilities
SurrealDB is secure by default and is suitable for all database use cases. It offers powerful features like scripting, functions or network access from within your SurrealQL queries. To aid flexibility, SurrealDB doesn't enable any of these features by default and lets the administrator enable them as needed per use case.
When a query wants to use a feature that is not enabled, SurrealDB will reject it.
Rejected Query> RETURN http::get("www.surrealdb.com");
There was a problem with the database: Function 'http::get' is not allowed to be executed
Capabilities list
List of options for allowing capabilities:
| Option | Description | Default | |
|---|---|---|---|
--allow-scripting | Allow execution of embedded scripting functions | False | |
--allow-guests | Allow non-authenticated users to execute queries when authentication is enabled | False | |
--allow-funcs [<target>,...] | Allow execution of all functions. Optionally, you can provide a comma-separated list of function names to allow | None | |
--allow-net [<target>,...] | Allow all outbound network access. Optionally, you can provide a comma-separated list of targets to allow | None | |
-A, --allow-all | Allow all capabilities above | False | |
List of options for denying capabilities:
| Option | Description | Default | |
|---|---|---|---|
--deny-scripting | Deny execution of embedded scripting functions | False | |
--deny-guests | Deny non-authenticated users to execute queries when authentication is enabled | False | |
--deny-funcs [<target>,...] | Deny execution of all functions. Optionally, you can provide a comma-separated list of function names to allow | None | |
--deny-net [<target>,...] | Deny all outbound network access. Optionally, you can provide a comma-separated list of targets to allow | None | |
-D, --deny-all | Deny all capabilities above | False | |
Denied capabilities will override any allowed capability that matches.
Guest access
Guest access is used when you want to expose certain parts of a database to non-authenticated users. It's useful when you want to serve datasets publicly and still require authentication for the rest of the system.
Even when this capability is allowed, a guest user can only execute functions or data operations like SELECT, CREATE, etc, and only if the PERMISSIONS clause for the resource being used in the query allows it.
// Prepare tables with custom PERMISSIONS
test/test> DEFINE TABLE protected PERMISSIONS NONE;
test/test> DEFINE TABLE public PERMISSIONS FULL;
// When guest access is allowed
$ surreal start --allow-guests
test/test> CREATE public;
[{ id: public:uy0qzy31v4xox8vivrd4 }]
test/test> SELECT * FROM public;
[{ id: public:uy0qzy31v4xox8vivrd4 }]
test/test> CREATE protected;
[]
test/test> SELECT * FROM protected;
[]
// When guest access is denied
$ surreal start --deny-guests
test/test> CREATE public;
There was a problem with the database: There was a problem with the database: IAM error: Not enough permissions to perform this action
test/test> SELECT * FROM public;
There was a problem with the database: There was a problem with the database: IAM error: Not enough permissions to perform this action
test/test> CREATE protected;
There was a problem with the database: There was a problem with the database: IAM error: Not enough permissions to perform this action
test/test> SELECT * FROM protected;
There was a problem with the database: There was a problem with the database: IAM error: Not enough permissions to perform this action
Functions
SurrealDB offers built-in functions to perform common operations like string manipulation, math, etc. Users can also define their own functions with custom logic.
In certain environments, you may not want users to use specific functions (i.e. http::*) or execute any custom function at all. You can use the allow/deny lists to configure what functions are allowed and what functions are denied.
// Allow all functions except the http family and crypto::md5()
surreal start --allow-funcs --deny-funcs "http","crypto::md5"
// Allow certain custom functions only (all custom functions start with "fn::")
surreal start --allow-funcs "fn::shared_fn"
Network
SurrealDB offers http functions that can access external network endpoints.
If you want to allow or deny access to certain network target, you can configure the network options accordingly. Here are some examples:
// Deny network access to localhost and private IPv4 ranges
$ surreal start --allow-net --deny-net "127.0.0.1","localhost","10.0.0.0/8","192.168.0.0/16","172.16.0.0/12"
// Allow access to an internal system but only to port 443
$ surreal start --allow-net internal.example.com:433
// Allow access to some private networks but not to others
$ surreal start --allow-net 10.0.0.0/16 --deny-net 10.10.0.0/24