Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README to explicitly discourage use of this library from outside of Jenkins #63

Merged
merged 2 commits into from May 28, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
41 changes: 3 additions & 38 deletions README.md
@@ -1,43 +1,8 @@
groovy-sandbox
==============

Compile-time transformer to run Groovy code in a restrictive sandbox. Executes untrusted Groovy script safely.
**WARNING** This library is only maintained in the context of Jenkins, and should only be used as a dependency of Jenkins plugins such as [Script Security Plugin](https://plugins.jenkins.io/script-security) and [Pipeline: Groovy Plugin](https://plugins.jenkins.io/workflow-cps). It should be considered deprecated and unsafe for all other purposes.

[Documentation](http://groovy-sandbox.kohsuke.org/).
This library provides a compile-time transformer to run Groovy code in an environment in which most operations, such as method calls, are intercepted before being executed. Consumers of the library can hook into the interception to allow or deny specific operations.

#### Maven dependency
```xml
<dependency>
<groupId>org.kohsuke</groupId>
<artifactId>groovy-sandbox</artifactId>
<version>1.25</version>
</dependency>
```

Starting with version 1.20, this artifact is only published to the Jenkins Releases repository, not to Maven Central as was done previously. Here are the details for the Jenkins Releases repository:
```xml
<repository>
<id>jenkins-releases</id>
<name>Jenkins Releases</name>
<url>https://repo.jenkins-ci.org/releases/</url>
</repository>
```

#### Usage
A good example can be found [here](https://github.com/jenkinsci/groovy-sandbox/tree/master/src/test/groovy/org/kohsuke/groovy/sandbox/robot).
This is a simple test that always expects a `SecurityException`:

```groovy
class Test {
static class DenyAll extends GroovyValueFilter {
Object filter(Object o) { throw new SecurityException('Denied!') }
}
@Test(expected = SecurityException)
void testScript() {
final sh = new GroovyShell(new CompilerConfiguration()
.addCompilationCustomizers(new SandboxTransformer()))
new DenyAll().register()
sh.evaluate('println hi')
}
}
```
This library is **not secure** when used by itself. In particular, you must at least use an additional `CompilationCustomizer` along the lines of [RejectASTTransformsCustomizer](https://github.com/jenkinsci-cert/script-security-plugin/blob/c43e099f2f86425b32b0be492020313644062763/src/main/java/org/jenkinsci/plugins/scriptsecurity/sandbox/groovy/RejectASTTransformsCustomizer.java) to reject AST transformations that can bypass the sandbox, and you need to take special care to ensure untrusted scripts are both parsed and executed inside of the sandbox.
7 changes: 0 additions & 7 deletions pom.xml
Expand Up @@ -132,13 +132,6 @@
<tag>${scmTag}</tag>
</scm>

<distributionManagement>
<site>
<id>github-pages</id>
<url>gitsite:git@github.com/jenkinsci/${project.artifactId}.git</url>
</site>
</distributionManagement>

<reporting>
<plugins>
<plugin>
Expand Down
62 changes: 0 additions & 62 deletions src/site/markdown/index.md

This file was deleted.

26 changes: 0 additions & 26 deletions src/site/site.xml

This file was deleted.