8000 Adjust to actual behavior of endpoint filtering, add env var filtering · arangodb/docs@b598f4e · GitHub
[go: up one dir, main page]
Skip to content
This repository was archived by the owner on Dec 13, 2023. It is now read-only.

Commit b598f4e

Browse files
Simran-BSimran-B
committed
Adjust to actual behavior of endpoint filtering, add env var filtering
tcp:// and ssl:// are still supported but somehow buggy. Updated docs only describe http:// and https:// that can now be used thanks to arangodb/arangodb#11236 h2://, h2s://, srv:// and unix:// are supported as well but not left uncovered in the docs.
1 parent b129f40 commit b598f4e

File tree

1 file changed

+117
-70
lines changed

1 file changed

+117
-70
lines changed

‎3.7/security-security-options.md‎

Lines changed: 117 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,27 @@ ArangoDB will use.
6262
These patterns and how they are applied can be observed by enabling
6363
`--log.level SECURITY=debug` in the `arangod` or `arangosh` log output.
6464

65-
#### Combining patterns
65+
### Options for blacklisting and whitelisting
66+
67+
The following options are available for blacklisting and whitelisting access
68+
to dedicated functionality for application code:
69+
70+
- `--javascript.startup-options-[whitelist|blacklist]`:
71+
These options control which startup options will be exposed to JavaScript code.
72+
73+
- `--javascript.environment-variables-[whitelist|blacklist]`:
74+
These options control which environment variables will be exposed to
75+
JavaScript code.
76+
77+
- `--javascript.files-whitelist`:
78+
This option controls which filesystem paths can be accessed from JavaScript
79+
code. There is only a whitelist option for file access.
80+
81+
- `--javascript.endpoints-[whitelist|blacklist]`:
82+
These options control which endpoints can be used from within the
83+
`@arangodb/request` JavaScript module.
84+
85+
#### Startup option access
6686

6787
The security option to observe the behavior of the pattern matching most easily
6888
is the masquerading of the startup options:
@@ -81,7 +101,7 @@ These sets will resolve internally to the following regular expressions:
81101
--javascript.startup-options-blacklist = "^javascript\.|endpoint"
82102
```
83103

84-
Invoking an arangosh with these options will hide the blacklisted commandline
104+
Invoking arangosh with these options will hide the blacklisted commandline
85105
options from the output of:
86106

87107
```js
@@ -91,6 +111,57 @@ require('internal').options()
91111
… and an exception will be thrown when trying to access items that are masked
92112
in the same way as if they weren't there in first place.
93113

114+
#### Environment variable access
115+
116+
Access to environment variables can be restricted to hide sensitive information
117+
from JavaScript code, for example:
118+
119+
```
120+
--javascript.environment-variables-whitelist "^ARANGO_"
121+
--javascript.environment-variables-blacklist "PASSWORD"
122+
```
123+
124+
This will allow JavaScript code to only see environment variables that start
125+
with `ARANGO_` except if they contain `PASSWORD`. It excludes the variables
126+
`PATH` and `ARANGO_ROOT_PASSWORD` for instance.
127+
128+
Note that regular expression matching is case-sensitive. `PASSWORD` will not
129+
exclude environment variables that include `password`. You may use
130+
`[Pp][Aa][Ss][Ss][Ww][Oo][Rr][Dd]` for case-insensitive matching.
131+
132+
You can test the black/whitelisting in _arangosh_, here using the ArangoDB 3.7
133+
Docker image:
134+
135+
```
136+
docker run --rm -e ARANGO_ROOT_PASSWORD="secret" arangodb:3.7 arangosh --javascript.execute-string "print(process.env)"
137+
...
138+
{
139+
"ARANGO_PACKAGE" : "arangodb3_3.7.15-1_amd64.deb",
140+
"HOSTNAME" : "84fe29186eba",
141+
"SHLVL" : "1",
142+
"HOME" : "/root",
143+
"ARANGO_ROOT_PASSWORD" : "secret",
144+
"ARANGO_VERSION" : "3.7.15",
145+
"PATH" : "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
146+
"ARANGO_URL" : "https://download.arangodb.com/arangodb37/DEBIAN/amd64",
147+
"ARANGO_PACKAGE_URL" : "https://download.arangodb.com/arangodb37/DEBIAN/amd64/arangodb3_3.7.15-1_amd64.deb",
148+
"ARANGO_SIGNATURE_URL" : "https://download.arangodb.com/arangodb37/DEBIAN/amd64/arangodb3_3.7.15-1_amd64.deb.asc",
149+
"PWD" : "/",
150+
"GLIBCXX_FORCE_NEW" : "1",
151+
"ICU_DATA" : "/usr/share/arangodb3/"
152+
}
153+
154+
docker run --rm -e ARANGO_ROOT_PASSWORD="secret" arangodb:3.7 arangosh --javascript.execute-string "print(process.env)" --javascript.environment-variables-whitelist "^ARANGO_" --javascript.environment-variables-blacklist "PASSWORD"
155+
...
156+
[Object {
157+
"ARANGO_PACKAGE" : "arangodb3_3.7.15-1_amd64.deb",
158+
"ARANGO_VERSION" : "3.7.15",
159+
"ARANGO_URL" : "https://download.arangodb.com/arangodb37/DEBIAN/amd64",
160+
"ARANGO_PACKAGE_URL" : "https://download.arangodb.com/arangodb37/DEBIAN/amd64/arangodb3_3.7.15-1_amd64.deb",
161+
"ARANGO_SIGNATURE_URL" : "https://download.arangodb.com/arangodb37/DEBIAN/amd64/arangodb3_3.7.15-1_amd64.deb.asc"
162+
}]
163+
```
164+
94165
#### File access
95166

96167
In contrast to other areas, access to directories and files from JavaScript
@@ -131,65 +202,65 @@ The endpoint black/white listing limits access to external HTTP resources:
131202
--javascript.endpoints-whitelist "<regex>"
132203
```
133204

134-
Filtering is done against the protocol, hostname / IP address, and the port.
135-
It is not possible to restrict URL paths or other parts of a URL.
136-
137-
In contrast to the URLs specified in JavaScript code, the filters have
138-
to be specified in the ArangoDB endpoints notation for the startup options:
139-
140-
- `tcp://` instead of `http://`
141-
- `ssl://` instead of `https://`
142-
- If no protocol is specified, then it will match both (tcp/http and ssl/https).
205+
Filtering is done against the full request URL, including protocol, domain /
206+
IP address, port, and path.
143207

144208
{% hint 'security' %}
145209
Keep in mind that these startup options are treated as regular expressions.
146-
It is recommended to fully specify protocol, host and port and to use a
147-
leading `^` and trailing `$` to ensure that no other than the intended URLs
148-
are matched.
210+
Certain characters have special mean D0E4 ing that may require escaping and the
211+
expression only needs to match a substring by default. It is recommended to
212+
fully specify URLs and to use a leading `^` and potentially a trailing `$` to
213+
ensure that no other than the intended URLs are matched.
149214
{% endhint %}
150215

151216
Specifying `arangodb.org` will match:
152-
- `http://arangodb.org`
153-
- `https://arangodb.org`
154-
- `https://arangodb.org:12345`
155-
- `https://subdomain.arangodb.organic` **(!)**
156-
- `https://arangodb-org.evil.com` **(!)**
157-
- etc.
217+
- `http://arangodb.org`
218+
- `https://arangodb.org`
219+
- `https://arangodb.org:12345`
220+
- `https://subdomain.arangodb.organic` **(!)**
221+
- `https://arangodb-org.evil.domain` **(!)**
222+
- etc.
158223

159224
An unescaped `.` represents any character. For a literal dot use `\.`.
160225

161-
Specifying `tcp://arangodb\.org` will match:
162-
- `http://arangodb.org`
163-
- `http://arangodb.org:12345`
164-
- `http://arangodb.organic` **(!)**
165-
- etc.
226+
Specifying `http://arangodb\.org` will match:
227+
- `http://arangodb.org`
228+
- `http://arangodb.org:12345`
229+
- `http://arangodb.organic` **(!)**
230+
- `http://arangodb.org.evil.domain` **(!)**
231+
- etc.
232+
233+
Specifying `^http://arangodb\.org$` will only match `http://arangodb.org`.
234+
Despite port 80 being the default HTTP port, this will not match
235+
`http://arangodb.org:80` with an explicitly stated port. Conversely, specifying
236+
`^http://arangodb\.org:80$` will match `http://arangodb.org:80` with an explicit
237+
port in the request URL but not `http://arangodb.org` with the port left out.
238+
To allow both, you can make the port optional like `^http://arangodb\.org(:80)?$`.
239+
However, the trailing `$` demands that the URL has no path. This means
240+
`http://arangodb.org/folder/file.html` and even `http://arangodb.org/` will not
241+
match. You can specify `^http://arangodb\.org(:80)?/` to allow any path (but
242+
the trailing slash will be needed in the request URL).
243+
244+
Specifying `^https?://arangodb\.org(:80|:443)?(/|$)` will match:
245+
- `http://arangodb.org`
246+
- `http://arangodb.org/`
247+
- `http://arangodb.org/folder/file.html`
248+
- `http://arangodb.org:80`
249+
- `http://arangodb.org:80/`
250+
- `http://arangodb.org:80/folder/file.html`
251+
- `https://arangodb.org:443`
252+
- `https://arangodb.org:443/`
253+
- `https://arangodb.org:443/folder/file.html`
254+
- etc.
166255

167-
Specifying `^tcp://arangodb\.org:80$` will match:
168-
- `http://arangodb.org`
169-
- `http://arangodb.org:80`
170-
171-
Note that `^tcp://arangodb\.org$` will not match anything, because the port
172-
(here: `:80`) is added internally after `.org` but the expression demands that
173-
the address must not have a port (`\.org$`).
174-
175-
Specifying `^ssl://arangodb\.org:443$` will match:
176-
- `https://arangodb.org`
177-
- `https://arangodb.org:443`
178-
179-
Specifying `^(tcp|ssl)://arangodb.org:(80|443)$` will match:
180-
- `http://arangodb.org`
181-
- `http://arangodb.org:80`
182-
- `http://arangodb.org:443`
183-
- `https://arangodb.org`
184-
- `https://arangodb.org:80`
185-
- `https://arangodb.org:443`
186256

187257
You can test the black/whitelisting in _arangosh_:
188258

189259
```
190-
arangosh --javascript.endpoints-whitelist "^ssl://arangodb\.org:443$"
260+
arangosh --javascript.endpoints-whitelist "^https://arangodb\.org(:443)?/"
191261
127.0.0.1:8529@_system> require('internal').download('http://arangodb.org/file.zip')
192-
JavaScript exception: ArangoError 11: not allowed to connect to this endpoint
262+
JavaScript exception: ArangoError 11: not allowed to connect to this URL: http://arangodb.org/file.zip
263+
...
193264
194265
127.0.0.1:8529@_system> require('internal').download('https://arangodb.org/file.zip')
195266
<request permitted by whitelist>
@@ -205,30 +276,6 @@ Examples are:
205276
wrapped in double quotes (`"^http…"`).
206277
{% endhint %}
207278

208-
### Options for blacklisting and whitelisting
209-
210-
The following options are available for blacklisting and whitelisting access
211-
to dedicated functionality for application code:
212-
213-
- `--javascript.startup-options-[whitelist|blacklist]`:
214-
These options control which startup options will be exposed to JavaScript code,
215-
following above rules for blacklists and whitelists.
216-
217-
- `--javascript.environment-variables-[whitelist|blacklist]`:
218-
These options control which environment variables will be exposed to JavaScript
219-
code, following above rules for blacklists and whitelists.
220-
221-
- `--javascript.endpoints-[whitelist|blacklist]`:
222-
These options control which endpoints can be used from within the `@arangodb/request`
223-
JavaScript module.
224-
Endpoint values are passed into the filter in a normalized format starting
225-
with either of the prefixes `tcp://`, `ssl://`, `unix://` or `srv://`.
226-
Note that for HTTP/SSL-based endpoints the port number will be included too,
227-
and that the endpoint can be specified either as an IP address or host name
228-
from application code.
229-
230-
- `--javascript.files-whitelist`:
231-
This option controls which filesystem paths can be accessed from JavaScript code.
232279

233280
### Additional JavaScript security options
234281

0 commit comments

Comments
 (0)
0