Javadocs
diff --git a/juneau-doc/docs/Topics/20.Security.html b/juneau-doc/docs/Topics/20.Security.html
new file mode 100644
index 0000000..214f1da
--- /dev/null
+++ b/juneau-doc/docs/Topics/20.Security.html
@@ -0,0 +1,24 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+Security Best-Practices
+
+<p>
+ Security is always an ongoing concern in any library.
+ If you discover any security vulnerabilities in this code, please refer to the instructions found here:
+</p>
+<ul class='spaced-list'>
+ <li class='extlink'>{@doc http://www.apache.org/security SECURITY}
+</ul>
diff --git a/juneau-doc/docs/Topics/20.Security/01.juneau-marshall.html b/juneau-doc/docs/Topics/20.Security/01.juneau-marshall.html
new file mode 100644
index 0000000..6644cda
--- /dev/null
+++ b/juneau-doc/docs/Topics/20.Security/01.juneau-marshall.html
@@ -0,0 +1,89 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+juneau-marshall
+
+<h5 class='topic'>Demarshalling vulnerabilities</h5>
+<p>
+ One common security vulnerability is the ability to create arbitrary Java object instances through crafted
+ user input. For example, support for constructing POJOs based on an input attribute defining a
+ fully-qualified class name like <js>"{class:'com.foo.MyBean',...}"</js>
+</p>
+<p>
+ Fortunately, Juneau does not support an open-ended <js>"class</js> attribute.
+ As a rule, it should not be possible to create arbitrary POJOs by any of the parsers.
+ The demarshalled object types are inferred via reflection of the class objects passed in through the parser
+ method (e.g. <c>JsonParser.<jsf>DEFAULT</jsf>.parse(input, MyBean.<jk>class</jk>)</c>).
+ As long as the <c>Class</c> object passed into this method is not constructed from user-generated input,
+ it should be free from demarshalling vulnerabilities.
+</p>
+<p>
+ The following example shows a potential vector that circumvents the restriction above:
+</p>
+<p class='bpcode w800'>
+ <jc>// Don't do this!</jc>
+ Class c = Class.<jsf>forName</jsf>(someUserInputString);
+ JsonParser.<jsf>DEFAULT</jsf>.parse(input, c); <jc>// Oops! Security hole!</jc>
+</p>
+<p>
+ Juneau does support something similar to a <js>"class"</js> attribute that allows you to define the
+ POJO type at runtime.
+ This is the <js>"type"</js> attribute.
+ The difference is that it's not possible to specify fully-qualified class names in <js>"type"</js> attributes,
+ and instead can only specify type keys defined through bean dictionaries.
+ Instead of serializing the fully-qualified class names in the output, we instead serialize type
+ names that represent those POJO types.
+ i.e. instead of <js>"class='com.foo.MyBean'"</js>, we instead serialize <js>"type='MyBeanIdentifier'"</js>.
+ Since bean types are defined at compile time, it's impossible to instantiate arbitrary POJOs.
+</p>
+<p>
+ POJO types of generalized input are also inferred through swaps.
+ Again, since the POJO types are hardcoded at compile time, these should not be subject to demarshalling
+ vulnerabilities. However, it is possible to circumvent this through your swap implementation as shown
+ below:
+</p>
+<p class='bpcode w800'>
+ <jc>// Don't do this!</jc>
+ <jk>public class</jk> MyInsecureSwap <jk>extends</jk> PojoSwap<ObjectMap,Object> {
+ <jk>public</jk> Object swap(BeanSession session, ObjectMap input) <jk>throws</jk> Exception {
+ <jc>// Security hole!</jc>
+ <jk>return</jk> Class.<jsf>forName</jsf>(input.getString(<js>"class"</js>)).newInstance();
+ }
+ }
+</p>
+<p>
+ Note that the {@link oaj.jso.JsoParser}, a thin layer of the Juneau Parser API written on
+ top of plain-old Java Object Serialization which itself is vulnerable to demarshalling issues.
+ Due to this, the JSO parser is not included in any of the default REST servlet implementations.
+ Be especially careful when using this parser, particularly if you want to use it for handing
+ <c>application/x-java-serialized-object</c> input through REST servlets.
+</p>
+<p>
+ All other parsers (JSON, URL-Encoding, MessagePack, etc...) work the same way in determining POJO types, so
+ should be safe from demarshalling vulnerabilities.
+</p>
+
+<h5 class='topic'>Dependent libraries</h5>
+<p>
+ When accessing security vulnerabilities of any library, dependent libraries must also be taken into account:
+</p>
+<ul>
+ <li>The JSON, HTML, MsgPack, URL-Encoding, and UON parsers are written from scratch and do not rely on
+ any other parsing technologies.
+ <li>The XML and HTML parsers uses the built-in Java StAX parser.
+ This *should* be free from vulnerabilities.
+ <li>The RDF parsers rely on Apache Jena 2.7.1.
+ As of <c>7.0.1</c>, no known security vulnerabilities exist that affect Juneau at this time.
+</ul>
diff --git a/juneau-doc/docs/Topics/20.Security/02.juneau-svl.html b/juneau-doc/docs/Topics/20.Security/02.juneau-svl.html
new file mode 100644
index 0000000..4a833f3
--- /dev/null
+++ b/juneau-doc/docs/Topics/20.Security/02.juneau-svl.html
@@ -0,0 +1,61 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+juneau-svl
+
+<p>
+ Care must be used when defining new {@link oaj.svl.Var Vars} using the SVL API since mistakes
+ could potentially expose system properties, environment variables, or even file system files.
+</p>
+<p>
+ For recap, the SVL support allows you to embed variables of the form <js>"$X{key}"</js> inside strings that
+ get resolved to other strings. The resolved strings themselves can also contain variables that also
+ get recursively resolved.
+</p>
+<p>
+ An example of a potential security hole is shown below that could potentially expose any file on a file
+ system through a REST request:
+</p>
+<p class='bpcode w800'>
+ <jk>public</jk> String doUnsafeGet(RestRequest req) {
+ <jc>// Security hole!</jc>
+ <jk>return</jk> req.getVarResolver().resolve(<js>"$RQ{foo}"</js>);
+ }
+</p>
+<p>
+ This code is simply echoing the value of the <c>foo</c> query parameter.
+ Now say for example that a bad actor passes in the query string <js>"foo=$F{/some/file/on/file/system}"</js>.
+ The <c>$F</c> variable allows you to resolve the contents of files using SVL, and is provided
+ by default using the built-in variable resolver returned by the <c>RestRequest</c> object.
+ You've potentially just exposed the contents of that file through your REST interface.
+</p>
+<p>
+ In reality, the above security hole does not exist because of the following restrictions:
+</p>
+<ul class='spaced-list'>
+ <li>
+ <c>Vars</c> have two methods {@link oaj.svl.Var#allowNested()} and
+ {@link oaj.svl.Var#allowRecurse()} that can be overridden to prevent recursive processing
+ of string variables. These are both <jk>false</jk> for the <c>$R</c> variable, so the <c>$F</c>
+ variable in the result will never get processed and instead be treated as plain text.
+ <li>
+ The <c>$F</c> variable only allows you to retrieve files within the JVM starting directory.
+</ul>
+<p>
+ Even though the built-in Juneau variables are safe, special care is needed when defining your own custom
+ variables. If your variable resolves user input in any way, it's HIGHLY recommended that you override the
+ {@link oaj.svl.Var#allowNested()} and {@link oaj.svl.Var#allowRecurse()}
+ methods to prevent recursive handling of variables.
+</p>
diff --git a/juneau-doc/docs/Topics/20.Security/03.juneau-rest-server.html b/juneau-doc/docs/Topics/20.Security/03.juneau-rest-server.html
new file mode 100644
index 0000000..2d15a79
--- /dev/null
+++ b/juneau-doc/docs/Topics/20.Security/03.juneau-rest-server.html
@@ -0,0 +1,28 @@
+<!--
+/***************************************************************************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ ***************************************************************************************************************************/
+ -->
+
+juneau-rest-server
+
+<p>
+ Denial of service attacks can be alleviated through the {@link oajr.annotation.Rest#maxInput() maxInput()}
+ setting. Arbitrarily-large input will trigger an exception before causing out-of-memory errors.
+ The default value for this setting is 100MB.
+</p>
+<p>
+ Since the parsers do not use intermediate DOMs and instead parse directly into Java objects,
+ deeply nested data structures will almost always trigger stack overflow errors long before memory consumption
+ becomes an issue. However, this is NOT true of the RDF parsers that use an intermediate DOM. If parsing
+ RDF, you may want to consider lowering the max-input value above.
+</p>
