[GR-71396] Permissions for packages/operations

docs/user/Embedding-Permissions.md

@@ -69,6 +69,53 @@ The Java backend's state is disconnected from the actual OS state:
   - Effective IDs
   - `follow_symlinks=False` unless the mode is only `F_OK`
 
+## Context Security Configuration
+
+When embedding GraalPy using the Polyglot API, you can configure security and access permissions through the `Context.Builder` class. 
+These settings control what system resources and host functionality your embedded Python code can access.
+
+This table shows the common security methods:
+
+| Method                                    | Description                                                                | Notes   |
+| ----------------------------------------- | -------------------------------------------------------------------------- | ------- |
+| `allowAllAccess(boolean)`                 | Grants unrestricted access to all host functionality and system resources. | **Security Risk:** Should only be used in trusted environments or for testing. When `true`, bypasses most security restrictions. When `false` (default), access is controlled by other specific permission methods. |
+| `allowHostAccess(HostAccess)`             | Controls access to Java host objects and classes.                          | Use `HostAccess.ALL` for unrestricted access or create custom policies. Default is `HostAccess.NONE` which blocks host access. |
+| `allowHostClassLookup(Predicate<String>)` | Controls which Java classes can be looked up by name from Python.          | Accepts a predicate function to filter allowed class names. More granular than `allowHostAccess` for class loading. |
+| `allowPolyglotAccess(boolean)`            | Controls access to other polyglot languages and their objects.             | Required for interop with other languages like JavaScript. Default is `false`. |
+| `allowIO(IOAccess)`                       | Controls file system and network access.                                   | Use `IOAccess.ALL` for full access, `IOAccess.NONE` to block all I/O. Can create custom policies for specific paths or protocols. |
+| `allowEnvironmentAccess(boolean)`         | Controls access to environment variables.                                  | Required for accessing `os.environ["PATH"]` and other environment variables. Default is `false`. |
+| `allowCreateProcess(boolean)`             | Controls whether Python code can create new processes.                     | Required for the `subprocess` module to work. Default is `false`. |
+| `allowCreateThread(boolean)`              | Controls whether Python code can create new threads.                       | Default is `false` for security. |
+| `allowNativeAccess(boolean)`              | Controls access to native libraries and system calls.                      | Required for Python packages with native extensions. Default is `false`. |
+
+### Secure Configuration Example
+
+This example shows how to configure a production-ready context with restricted permissions:
+
+```java
+Context context = Context.newBuilder("python")
+    .allowHostAccess(HostAccess.EXPLICIT)  // Only explicitly exported objects
+    .allowIO(IOAccess.newBuilder()         // Restrict to specific directory
+        .fileSystem(FileSystem.newDefaultFileSystem(Path.of("/safe/directory")))
+        .build())
+    .allowCreateThread(false)              // No thread creation
+    .allowNativeAccess(false)              // No native code
+    .build();
+```
+
+### Development Configuration Example
+
+For development and testing environments, you might use a more permissive configuration:
+
+```java
+Context context = Context.newBuilder("python")
+    .allowAllAccess(true)                         // Full access for development
+    .option("python.PosixModuleBackend", "java")  // Use sandboxed backend
+    .build();
+```
+
+> **Warning:** Using `allowAllAccess(true)` disables most security protections. Only use this in trusted environments or during development. For production deployments, configure specific permissions using the individual allow methods.
+
 ## Python Native Extensions
 
 Python native extensions run by default as native binaries with full access to the underlying system. This means they bypass the security controls described above.