0
# Security Configuration
1

2
Security configuration provides comprehensive access control and sandboxing for polyglot environments. It enables fine-grained control over host system access, cross-language interactions, resource consumption, and environment isolation.
3

4
## Capabilities
5

6
### Host Access Control
7

8
Configure access to host (Java) objects from guest languages.
9

10
```java { .api }
11
public final class HostAccess {
12
    public static final HostAccess ALL;
13
    public static final HostAccess EXPLICIT;
14
    public static final HostAccess NONE;
15
    public static final HostAccess SCOPED;
16
    public static HostAccess.Builder newBuilder();
17
    public static HostAccess.Builder newBuilder(HostAccess conf);
18
}
19

20
public static final class HostAccess.Builder {
21
    public HostAccess.Builder allowPublicAccess(boolean enabled);
22
    public HostAccess.Builder allowAllImplementations(boolean enabled);
23
    public HostAccess.Builder allowAllClassImplementations(boolean enabled);
24
    public HostAccess.Builder allowArrayAccess(boolean enabled);
25
    public HostAccess.Builder allowListAccess(boolean enabled);
26
    public HostAccess.Builder allowBufferAccess(boolean enabled);
27
    public HostAccess.Builder allowIterableAccess(boolean enabled);
28
    public HostAccess.Builder allowIteratorAccess(boolean enabled);
29
    public HostAccess.Builder allowMapAccess(boolean enabled);
30
    public HostAccess.Builder allowAccessAnnotatedBy(Class<? extends Annotation> annotation);
31
    public HostAccess.Builder allowImplementationsAnnotatedBy(Class<? extends Annotation> annotation);
32
    public HostAccess.Builder denyAccess(Class<?> clazz);
33
    public HostAccess.Builder allowAccess(Class<?> clazz);
34
    public HostAccess.Builder allowAccess(Method method);
35
    public HostAccess.Builder allowAccess(Field field);
36
    public HostAccess.Builder allowAccess(Constructor<?> constructor);
37
    public HostAccess.Builder targetTypeMapping(Class<?> sourceType, Class<?> targetType, Predicate<Object> accepts, Function<Object, Object> converter);
38
    public HostAccess build();
39
}
40
```
41

42
**Usage:**
43

44
```java
45
// Predefined configurations
46
Context allAccess = Context.newBuilder("js")
47
    .allowHostAccess(HostAccess.ALL)        // Allow all host access
48
    .build();
49

50
Context explicitAccess = Context.newBuilder("js")
51
    .allowHostAccess(HostAccess.EXPLICIT)   // Only @HostAccess.Export annotated
52
    .build();
53

54
Context noAccess = Context.newBuilder("js")
55
    .allowHostAccess(HostAccess.NONE)       // No host access
56
    .build();
57

58
Context scopedAccess = Context.newBuilder("js")
59
    .allowHostAccess(HostAccess.SCOPED)     // Scoped access
60
    .build();
61

62
// Custom configuration
63
HostAccess customAccess = HostAccess.newBuilder()
64
    .allowPublicAccess(true)
65
    .allowArrayAccess(true)
66
    .allowListAccess(true)
67
    .allowMapAccess(false)
68
    .allowAccess(MyPublicClass.class)
69
    .denyAccess(MySensitiveClass.class)
70
    .allowAccessAnnotatedBy(HostAccess.Export.class)
71
    .build();
72

73
Context customContext = Context.newBuilder("js")
74
    .allowHostAccess(customAccess)
75
    .build();
76
```
77

78
### Polyglot Access Control
79

80
Configure cross-language access between guest languages.
81

82
```java { .api }
83
public final class PolyglotAccess {
84
    public static final PolyglotAccess ALL;
85
    public static final PolyglotAccess NONE;
86
    public static PolyglotAccess.Builder newBuilder();
87
}
88

89
public static final class PolyglotAccess.Builder {
90
    public PolyglotAccess.Builder allowEval(String languageId, String... targetLanguageIds);
91
    public PolyglotAccess.Builder allowBindingsAccess(String languageId);
92
    public PolyglotAccess.Builder denyBindingsAccess(String languageId);
93
    public PolyglotAccess.Builder allowEvalBetween(String... languageIds);
94
    public PolyglotAccess build();
95
}
96
```
97

98
**Usage:**
99

100
```java
101
// Allow all cross-language access
102
Context allPolyglot = Context.newBuilder("js", "python")
103
    .allowPolyglotAccess(PolyglotAccess.ALL)
104
    .build();
105

106
// Deny all cross-language access
107
Context noPolyglot = Context.newBuilder("js", "python")
108
    .allowPolyglotAccess(PolyglotAccess.NONE)
109
    .build();
110

111
// Custom polyglot access
112
PolyglotAccess customPolyglot = PolyglotAccess.newBuilder()
113
    .allowEval("js", "python")              // JS can eval Python
114
    .allowBindingsAccess("js")              // JS can access bindings
115
    .denyBindingsAccess("python")           // Python cannot access bindings
116
    .allowEvalBetween("js", "python", "R")  // Mutual eval between languages
117
    .build();
118

119
Context customContext = Context.newBuilder("js", "python", "R")
120
    .allowPolyglotAccess(customPolyglot)
121
    .build();
122
```
123

124
### I/O Access Control
125

126
Configure file system, network, and process access.
127

128
```java { .api }
129
public final class IOAccess {
130
    public static final IOAccess ALL;
131
    public static final IOAccess NONE;
132
    public static IOAccess.Builder newBuilder();
133
}
134

135
public static final class IOAccess.Builder {
136
    public IOAccess.Builder allowHostFileAccess(boolean enabled);
137
    public IOAccess.Builder allowHostSocketAccess(boolean enabled);
138
    public IOAccess.Builder fileSystem(FileSystem fileSystem);
139
    public IOAccess.Builder processHandler(ProcessHandler processHandler);
140
    public IOAccess build();
141
}
142
```
143

144
**Usage:**
145

146
```java
147
// Allow all I/O
148
Context allIO = Context.newBuilder("js")
149
    .allowIO(IOAccess.ALL)
150
    .build();
151

152
// Deny all I/O
153
Context noIO = Context.newBuilder("js")
154
    .allowIO(IOAccess.NONE)
155
    .build();
156

157
// Custom I/O access
158
FileSystem restrictedFS = new RestrictedFileSystem("/safe/directory");
159
ProcessHandler restrictedProc = new RestrictedProcessHandler();
160

161
IOAccess customIO = IOAccess.newBuilder()
162
    .allowHostFileAccess(false)          // No direct file access
163
    .allowHostSocketAccess(false)        // No socket access
164
    .fileSystem(restrictedFS)            // Custom file system
165
    .processHandler(restrictedProc)      // Custom process handler
166
    .build();
167

168
Context customContext = Context.newBuilder("js")
169
    .allowIO(customIO)
170
    .build();
171
```
172

173
### Sandbox Policies
174

175
Apply predefined security policies for different trust levels.
176

177
```java { .api }
178
public enum SandboxPolicy {
179
    TRUSTED,     // No restrictions
180
    CONSTRAINED, // Limited restrictions
181
    ISOLATED,    // Strong restrictions
182
    UNTRUSTED    // Maximum restrictions
183
}
184
```
185

186
**Usage:**
187

188
```java
189
// Trusted environment (no restrictions)
190
Context trusted = Context.newBuilder("js")
191
    .sandbox(SandboxPolicy.TRUSTED)
192
    .build();
193

194
// Constrained environment
195
Context constrained = Context.newBuilder("js")
196
    .sandbox(SandboxPolicy.CONSTRAINED)
197
    .build();
198

199
// Isolated environment
200
Context isolated = Context.newBuilder("js")
201
    .sandbox(SandboxPolicy.ISOLATED)
202
    .build();
203

204
// Untrusted environment (maximum restrictions)
205
Context untrusted = Context.newBuilder("js")
206
    .sandbox(SandboxPolicy.UNTRUSTED)
207
    .build();
208
```
209

210
### Resource Limits
211

212
Control resource consumption and execution limits.
213

214
```java { .api }
215
public final class ResourceLimits {
216
    public static ResourceLimits.Builder newBuilder();
217
}
218

219
public static final class ResourceLimits.Builder {
220
    public ResourceLimits.Builder statementLimit(long limit, Predicate<Source> sourceFilter);
221
    public ResourceLimits.Builder onLimit(Consumer<ResourceLimitEvent> onLimit);
222
    public ResourceLimits build();
223
}
224

225
public final class ResourceLimitEvent {
226
    public String getLimit();
227
    public Context getContext();
228
}
229
```
230

231
**Usage:**
232

233
```java
234
// Statement execution limit
235
ResourceLimits limits = ResourceLimits.newBuilder()
236
    .statementLimit(10000, source -> !source.isInternal())
237
    .onLimit(event -> {
238
        System.out.println("Resource limit exceeded: " + event.getLimit());
239
        // Handle limit exceeded
240
    })
241
    .build();
242

243
Context limitedContext = Context.newBuilder("js")
244
    .resourceLimits(limits)
245
    .build();
246

247
try {
248
    // This will hit the statement limit
249
    limitedContext.eval("js", "while(true) { /* infinite loop */ }");
250
} catch (PolyglotException e) {
251
    if (e.isResourceExhausted()) {
252
        System.out.println("Resource limit reached");
253
    }
254
}
255
```
256

257
### Environment Access Control
258

259
Control access to environment variables and system properties.
260

261
```java { .api }
262
public final class EnvironmentAccess {
263
    public static final EnvironmentAccess INHERIT;
264
    public static final EnvironmentAccess NONE;
265
    public static EnvironmentAccess.Builder newBuilder();
266
}
267

268
public static final class EnvironmentAccess.Builder {
269
    public EnvironmentAccess.Builder inheritSystemProperties(boolean enabled);
270
    public EnvironmentAccess.Builder inheritEnvironmentVariables(boolean enabled);
271
    public EnvironmentAccess build();
272
}
273
```
274

275
**Usage:**
276

277
```java
278
// Inherit all environment
279
Context inheritEnv = Context.newBuilder("js")
280
    .allowEnvironmentAccess(EnvironmentAccess.INHERIT)
281
    .build();
282

283
// No environment access
284
Context noEnv = Context.newBuilder("js")
285
    .allowEnvironmentAccess(EnvironmentAccess.NONE)
286
    .build();
287

288
// Custom environment access
289
EnvironmentAccess customEnv = EnvironmentAccess.newBuilder()
290
    .inheritSystemProperties(false)
291
    .inheritEnvironmentVariables(true)
292
    .build();
293

294
Context customContext = Context.newBuilder("js")
295
    .allowEnvironmentAccess(customEnv)
296
    .build();
297
```
298

299
## Advanced Security Patterns
300

301
### Layered Security
302

303
Combine multiple security mechanisms for defense in depth:
304

305
```java
306
Context secureContext = Context.newBuilder("js")
307
    .sandbox(SandboxPolicy.ISOLATED)
308
    .allowHostAccess(HostAccess.EXPLICIT)
309
    .allowPolyglotAccess(PolyglotAccess.NONE)
310
    .allowIO(IOAccess.NONE)
311
    .allowEnvironmentAccess(EnvironmentAccess.NONE)
312
    .allowCreateThread(false)
313
    .allowNativeAccess(false)
314
    .resourceLimits(ResourceLimits.newBuilder()
315
        .statementLimit(100000, null)
316
        .build())
317
    .build();
318
```
319

320
### Custom Host Access
321

322
Create fine-grained host access controls:
323

324
```java
325
@HostAccess.Export
326
public class SafeAPI {
327
    @HostAccess.Export
328
    public String processData(String data) {
329
        // Safe data processing
330
        return data.toUpperCase();
331
    }
332
    
333
    // This method is not exported (no annotation)
334
    private void sensitiveOperation() {
335
        // Not accessible from guest languages
336
    }
337
}
338

339
HostAccess restrictedAccess = HostAccess.newBuilder()
340
    .allowAccessAnnotatedBy(HostAccess.Export.class)
341
    .allowAccess(String.class)
342
    .allowAccess(Integer.class)
343
    .denyAccess(System.class)
344
    .denyAccess(Runtime.class)
345
    .build();
346

347
Context restrictedContext = Context.newBuilder("js")
348
    .allowHostAccess(restrictedAccess)
349
    .build();
350

351
restrictedContext.getBindings("js").putMember("api", new SafeAPI());
352
restrictedContext.eval("js", "api.processData('hello')"); // Works
353
// restrictedContext.eval("js", "api.sensitiveOperation()"); // Fails
354
```
355

356
### Runtime Security Monitoring
357

358
Monitor and respond to security events:
359

360
```java
361
ResourceLimits monitoredLimits = ResourceLimits.newBuilder()
362
    .statementLimit(50000, null)
363
    .onLimit(event -> {
364
        // Log security event
365
        logger.warn("Resource limit exceeded in context: " + event.getContext());
366
        
367
        // Take corrective action
368
        event.getContext().interrupt(Duration.ofSeconds(1));
369
    })
370
    .build();
371

372
Context monitoredContext = Context.newBuilder("js")
373
    .resourceLimits(monitoredLimits)
374
    .build();
375
```
376

377
### Secure Configuration Templates
378

379
Create reusable security configurations:
380

381
```java
382
public class SecurityConfigurations {
383
    public static Context.Builder webSandbox() {
384
        return Context.newBuilder()
385
            .sandbox(SandboxPolicy.ISOLATED)
386
            .allowHostAccess(HostAccess.EXPLICIT)
387
            .allowPolyglotAccess(PolyglotAccess.NONE)
388
            .allowIO(IOAccess.NONE)
389
            .allowEnvironmentAccess(EnvironmentAccess.NONE)
390
            .allowCreateThread(false);
391
    }
392
    
393
    public static Context.Builder trustedScript() {
394
        return Context.newBuilder()
395
            .sandbox(SandboxPolicy.CONSTRAINED)
396
            .allowHostAccess(HostAccess.ALL)
397
            .allowPolyglotAccess(PolyglotAccess.ALL)
398
            .allowIO(IOAccess.ALL);
399
    }
400
    
401
    public static Context.Builder dataProcessing() {
402
        return Context.newBuilder()
403
            .sandbox(SandboxPolicy.CONSTRAINED)
404
            .allowHostAccess(HostAccess.newBuilder()
405
                .allowPublicAccess(true)
406
                .allowArrayAccess(true)
407
                .allowListAccess(true)
408
                .denyAccess(System.class)
409
                .build())
410
            .allowIO(IOAccess.newBuilder()
411
                .allowHostFileAccess(true)
412
                .allowHostSocketAccess(false)
413
                .build());
414
    }
415
}
416

417
// Usage
418
Context webContext = SecurityConfigurations.webSandbox()
419
    .languages("js")
420
    .build();
421

422
Context scriptContext = SecurityConfigurations.trustedScript()
423
    .languages("js", "python")
424
    .build();
425
```
426

427
## Security Best Practices
428

429
1. **Principle of Least Privilege**: Start with the most restrictive settings and only add permissions as needed
430
2. **Defense in Depth**: Use multiple security layers (sandbox policy + specific restrictions)
431
3. **Explicit Access**: Use `HostAccess.EXPLICIT` with annotations rather than `HostAccess.ALL`
432
4. **Resource Limits**: Always set appropriate resource limits for untrusted code
433
5. **Monitoring**: Implement logging and monitoring for security events
434
6. **Regular Updates**: Keep GraalVM updated for latest security fixes
435
7. **Testing**: Thoroughly test security configurations with malicious inputs
436

437
## Common Security Configurations
438

439
```java
440
// Web application sandbox (untrusted user scripts)
441
Context webSandbox = Context.newBuilder("js")
442
    .sandbox(SandboxPolicy.UNTRUSTED)
443
    .build();
444

445
// Microservice (trusted internal scripts)
446
Context microservice = Context.newBuilder("js", "python")
447
    .sandbox(SandboxPolicy.CONSTRAINED)
448
    .allowHostAccess(HostAccess.EXPLICIT)
449
    .build();
450

451
// Development environment (full access)
452
Context development = Context.newBuilder()
453
    .allowAllAccess(true)
454
    .build();
455

456
// CI/CD pipeline (controlled access)
457
Context cicd = Context.newBuilder("js")
458
    .sandbox(SandboxPolicy.ISOLATED)
459
    .allowIO(IOAccess.newBuilder()
460
        .allowHostFileAccess(true)
461
        .allowHostSocketAccess(false)
462
        .build())
463
    .build();
464
```