[GR-54802] Review Security documentation.

PullRequest: graal/18621

Author: olyagpl

docs/security/native-image.md

@@ -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.
@@ -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)

docs/security/polyglot-sandbox.md

@@ -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)
 
@@ -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
@@ -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
 
@@ -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.
@@ -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.
@@ -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
@@ -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)

docs/security/security-guide.md

@@ -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.
 
@@ -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
 
@@ -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)