Skip to content

Commit fe84b5f

Browse files
committed
[GR-54802] Review Security documentation.
PullRequest: graal/18621
2 parents 0543913 + ecb3a52 commit fe84b5f

File tree

3 files changed

+27
-25
lines changed

3 files changed

+27
-25
lines changed

docs/security/native-image.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ toc_group: security-guide
44
link_title: Security Considerations in Native Image
55
permalink: /security-guide/native-image/
66
---
7+
78
# Security Considerations in Native Image
89

910
The `native-image` builder generates a snapshot of an application after startup and bundles it in a binary executable.
@@ -109,5 +110,5 @@ Attempting to set a security manager will trigger a runtime error.
109110
## Related Documentation
110111

111112
- [Security Guide](security-guide.md)
112-
- [Polyglot Sandboxing](polyglot-sandbox.md)
113+
- [Sandboxing](polyglot-sandbox.md)
113114
- [Jipher JCE with Native Image](JipherJCE.md)

docs/security/polyglot-sandbox.md

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,20 @@
11
---
22
layout: docs
33
toc_group: security-guide
4-
link_title: Polyglot Sandboxing
5-
permalink: /security-guide/polyglot-sandbox/
6-
redirect_from: /reference-manual/embed-languages/sandbox-resource-limits/
4+
link_title: Sandboxing
5+
permalink: /security-guide/sandboxing/
6+
redirect_from:
7+
- /security-guide/polyglot-sandbox/
8+
- /reference-manual/embed-languages/sandbox-resource-limits/
79
---
810

9-
# Polyglot Sandboxing
11+
# Sandboxing
1012

11-
GraalVM allows a host application written in a JVM-based language to execute guest code written in Javascript via the [Polyglot Embedding API](../reference-manual/embedding/embed-languages.md).
13+
GraalVM allows a host application written in a JVM-based language to execute guest code written in Javascript via the [Polyglot API](../reference-manual/embedding/embed-languages.md).
1214
Configured with a [sandbox policy](#sandbox-policies), a security boundary between a host application and guest code can be established.
1315
For example, host code can execute untrusted guest code using the [UNTRUSTED](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/SandboxPolicy.html#UNTRUSTED) policy.
1416
Host code can also execute multiple mutually distrusting instances of guest code that will be protected from one another.
15-
Used this way, polyglot sandboxing supports a multi-tenant scenario:
17+
Used this way, sandboxing supports a multi-tenant scenario:
1618

1719
![Sandbox Security Boundary](sandbox_security_boundary.png)
1820

@@ -100,7 +102,7 @@ try (Context context = Context.newBuilder("js")
100102
}
101103
```
102104

103-
Since Polyglot version 23.1, the isolated and untrusted policy also requires isolated images of the languages to be specified on the class or module path.
105+
Since Polyglot API version 23.1, the isolated and untrusted policy also requires isolated images of the languages to be specified on the class or module path.
104106
Isolated versions of the languages can be downloaded from Maven using the following dependency:
105107

106108
```xml
@@ -112,8 +114,7 @@ Isolated versions of the languages can be downloaded from Maven using the follow
112114
</dependency>
113115
```
114116

115-
The [embedding guide](../reference-manual/embed-languages/#polyglot-isolates) contains more details on using polyglot isolate dependencies.
116-
117+
The [Embedding Languages guide](../reference-manual/embed-languages/#polyglot-isolates) contains more details on using polyglot isolate dependencies.
117118

118119
### Untrusted Policy
119120

@@ -162,7 +163,7 @@ Therefore the sandboxing policies already restrict host access in the CONSTRAINE
162163
`HostAccess.CONSTRAINED` is the predefined host access policy for the CONSTRAINED sandbox policy.
163164
To expose a host class method, it has to be annotated with `@HostAccess.Export`.
164165
This annotation is not inherited.
165-
Service providers such as [polyglot file system](https://www.graalvm.org/sdk/javadoc/index.html?org/graalvm/polyglot/io/FileSystem.html) implementations or output stream recipients for standard output and error stream redirections are exposed to guest code invocations.
166+
Service providers such as [Polyglot API FileSystem](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/io/FileSystem.html) implementations or output stream recipients for standard output and error stream redirections are exposed to guest code invocations.
166167

167168
Guest code can also implement a Java interface that has been annotated with `@Implementable`.
168169
Host code using such an interface directly interacts with guest code.
@@ -483,7 +484,7 @@ A speculative execution barrier is placed at each target of a conditional branch
483484

484485
## Sharing Execution Engines
485486

486-
Guest code of different trust domains has to be separated at the Polylgot engine level, that is, only guest code of the same trust domain should share an engine.
487+
Guest code of different trust domains has to be separated at the polyglot engine level, that is, only guest code of the same trust domain should share an engine.
487488
When multiple context share an engine, all of them must have the same sandbox policy (the engine's sandbox policy).
488489
Application developers may choose to share execution engines among execution contexts for performance reasons.
489490
While the context holds the state of the executed code, the engine holds the code itself.
@@ -494,17 +495,17 @@ Source.newBuilder(…).cached(false).build()
494495

495496
## Compatibility and Limitations
496497

497-
Polyglot sandboxing is not available in GraalVM Community Edition.
498+
Sandboxing is not available in GraalVM Community Edition.
498499

499500
Depending on the sandboxing policy, only a subset of Truffle languages, instruments, and options are available.
500501
In particular, sandboxing is currently only supported for the runtime's [default version](https://github.com/oracle/graaljs/blob/master/docs/user/JavaScriptCompatibility.md) of ECMAScript (ECMAScript 2022).
501502
Sandboxing is also not supported from within GraalVM's Node.js.
502503

503-
Polyglot sandboxing is not compatible with modifications to the VM setup via (for example) system properties that change the behavior of the VM.
504+
Sandboxing is not compatible with modifications to the VM setup via (for example) system properties that change the behavior of the VM.
504505

505506
The sandboxing policy is subject to incompatible changes across major GraalVM releases to maintain a secure-by-default posture.
506507

507-
Polyglot sandboxing cannot protect against vulnerabilities in its operating environment, such as vulnerabilities in the operating system or the underlying hardware.
508+
Sandboxing cannot protect against vulnerabilities in its operating environment, such as vulnerabilities in the operating system or the underlying hardware.
508509
We recommend to adopt the appropriate external isolation primitives to protect against corresponding risks.
509510

510511
## Differentiation with Java Security Manager
@@ -531,5 +532,5 @@ We ask that you do not contact project contributors directly or through other ch
531532

532533
### Related Documentation
533534

534-
- [Polyglot Sandboxing](polyglot-sandbox.md)
535+
- [Security Guide](security-guide.md)
535536
- [Security Considerations in Native Image](native-image.md)

docs/security/security-guide.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ redirect_from:
99

1010
# Security Guide
1111

12-
This security guide provides developers and embedders with information on the security model and features of GraalVM for developers and embedders who seek to build a secure application on top of it.
12+
This security guide provides information on the security model and features of GraalVM for developers and embedders who seek to build a secure application on top of it.
1313
It assumes that readers are familiar with the GraalVM architecture.
1414
This guide does not replace but rather supplements the Java security documentation such as the [Secure Coding Guidelines for Java SE](https://www.oracle.com/java/technologies/javase/seccodeguide.html) with aspects unique to GraalVM.
1515

@@ -25,20 +25,20 @@ They may further open network sockets to allow debug clients to connect.
2525

2626
Experimental features in GraalVM are not for production use and may have security limitations not covered in the Security Guide.
2727

28-
GraalVM enables execution of untrusted code in an appropriately configured polyglot execution context (see [Polyglot Sandboxing](polyglot-sandbox.md)).
28+
GraalVM enables execution of untrusted code in an appropriately configured polyglot execution context (see [Sandboxing](polyglot-sandbox.md)).
2929

3030
We appreciate reports of bugs that break the security model via the process
3131
outlined in the [Reporting Vulnerabilities guide](https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html).
3232

33-
## Polyglot Languages
33+
## Graal Languages
3434

35-
For every Polyglot language shipped with GraalVM, a launcher, for example, an interactive shell, is provided.
35+
Every language runtime, generally available with a GraalVM release, provides a launcher, for example, an interactive shell.
3636
These launchers behave in the same way and come with the same security guarantees as their "original" counterparts.
3737

38-
### Polyglot Sandboxing
38+
### Sandboxing
3939

40-
Polyglot sandboxing can establish a security boundary between privileged host code and unprivileged guest code.
41-
For further information please refer to the [Polyglot Sandboxing guide](polyglot-sandbox.md).
40+
Sandboxing can establish a security boundary between privileged host code and unprivileged guest code, facilitated through the [Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html).
41+
For further information please refer to the [Sandboxing documentation](polyglot-sandbox.md).
4242

4343
### ScriptEngine Compatibility
4444

@@ -74,13 +74,13 @@ GraalVM does not support untrusted code execution in Java.
7474

7575
## GraalVM Community Edition Downgrade
7676

77-
Polyglot sandboxing is not available in GraalVM Community Edition.
77+
Sandboxing is not available in GraalVM Community Edition.
7878
Managed execution of native code is not available with GraalVM Community Edition.
7979

8080
When downgrading to GraalVM Community Edition, native code execution is only possible with the `allowNativeAccess` privilege.
8181
This also applies to languages implemented with Truffle that allow for native code extensions, such as Python and Ruby.
8282

8383
### Related Documentation
8484

85-
- [Polyglot Sandboxing](polyglot-sandbox.md)
85+
- [Sandboxing](polyglot-sandbox.md)
8686
- [Security Considerations in Native Image](native-image.md)

0 commit comments

Comments
 (0)