Skip to content

Commit

Permalink
[GR-54802] Review Security documentation.
Browse files Browse the repository at this point in the history
PullRequest: graal/18621
  • Loading branch information
olyagpl committed Aug 28, 2024
2 parents 0543913 + ecb3a52 commit fe84b5f
Show file tree
Hide file tree
Showing 3 changed files with 27 additions and 25 deletions.
3 changes: 2 additions & 1 deletion docs/security/native-image.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ toc_group: security-guide
link_title: Security Considerations in Native Image
permalink: /security-guide/native-image/
---

# Security Considerations in Native Image

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

- [Security Guide](security-guide.md)
- [Polyglot Sandboxing](polyglot-sandbox.md)
- [Sandboxing](polyglot-sandbox.md)
- [Jipher JCE with Native Image](JipherJCE.md)
31 changes: 16 additions & 15 deletions docs/security/polyglot-sandbox.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
---
layout: docs
toc_group: security-guide
link_title: Polyglot Sandboxing
permalink: /security-guide/polyglot-sandbox/
redirect_from: /reference-manual/embed-languages/sandbox-resource-limits/
link_title: Sandboxing
permalink: /security-guide/sandboxing/
redirect_from:
- /security-guide/polyglot-sandbox/
- /reference-manual/embed-languages/sandbox-resource-limits/
---

# Polyglot Sandboxing
# Sandboxing

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).
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).
Configured with a [sandbox policy](#sandbox-policies), a security boundary between a host application and guest code can be established.
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.
Host code can also execute multiple mutually distrusting instances of guest code that will be protected from one another.
Used this way, polyglot sandboxing supports a multi-tenant scenario:
Used this way, sandboxing supports a multi-tenant scenario:

![Sandbox Security Boundary](sandbox_security_boundary.png)

Expand Down Expand Up @@ -100,7 +102,7 @@ try (Context context = Context.newBuilder("js")
}
```

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.
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.
Isolated versions of the languages can be downloaded from Maven using the following dependency:

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

The [embedding guide](../reference-manual/embed-languages/#polyglot-isolates) contains more details on using polyglot isolate dependencies.

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

### Untrusted Policy

Expand Down Expand Up @@ -162,7 +163,7 @@ Therefore the sandboxing policies already restrict host access in the CONSTRAINE
`HostAccess.CONSTRAINED` is the predefined host access policy for the CONSTRAINED sandbox policy.
To expose a host class method, it has to be annotated with `@HostAccess.Export`.
This annotation is not inherited.
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.
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.

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

## Sharing Execution Engines

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.
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.
When multiple context share an engine, all of them must have the same sandbox policy (the engine's sandbox policy).
Application developers may choose to share execution engines among execution contexts for performance reasons.
While the context holds the state of the executed code, the engine holds the code itself.
Expand All @@ -494,17 +495,17 @@ Source.newBuilder(…).cached(false).build()

## Compatibility and Limitations

Polyglot sandboxing is not available in GraalVM Community Edition.
Sandboxing is not available in GraalVM Community Edition.

Depending on the sandboxing policy, only a subset of Truffle languages, instruments, and options are available.
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).
Sandboxing is also not supported from within GraalVM's Node.js.

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

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

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

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

### Related Documentation

- [Polyglot Sandboxing](polyglot-sandbox.md)
- [Security Guide](security-guide.md)
- [Security Considerations in Native Image](native-image.md)
18 changes: 9 additions & 9 deletions docs/security/security-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ redirect_from:

# Security Guide

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.
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.
It assumes that readers are familiar with the GraalVM architecture.
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.

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

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

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

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

## Polyglot Languages
## Graal Languages

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

### Polyglot Sandboxing
### Sandboxing

Polyglot sandboxing can establish a security boundary between privileged host code and unprivileged guest code.
For further information please refer to the [Polyglot Sandboxing guide](polyglot-sandbox.md).
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).
For further information please refer to the [Sandboxing documentation](polyglot-sandbox.md).

### ScriptEngine Compatibility

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

## GraalVM Community Edition Downgrade

Polyglot sandboxing is not available in GraalVM Community Edition.
Sandboxing is not available in GraalVM Community Edition.
Managed execution of native code is not available with GraalVM Community Edition.

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

### Related Documentation

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

0 comments on commit fe84b5f

Please sign in to comment.