Merge pull request #521 from psiinon/api-file-xfer

API File Transfer help

Author: kingthorin

addOns/help/src/main/javahelp/contents/start/features/api.html

@@ -28,6 +28,41 @@ <H1>API</H1>
 Future versions of ZAP will increase the functionality available via the APi.
 </p>
 
+<H2><a name="filexfer">File Transfer</a></H2>
+
+Many API endpoints allow you to load or save files to and from the file system.
+<p>
+The core API also supports uploading and downloading files, but this is disabled by default as a security measure.
+If an attacker is able to access the ZAP API then with this feature enabled they would be able to upload their own script to 
+ZAP and then run it. ZAP scripts run with the same permissions as ZAP and so this is full remote code execution access.
+<p>
+To enable file transfer you will need to have an API key set and to enable it via the 
+<a href="../../ui/dialogs/options/api.html#filexferenabled">Options API screen</a>.
+You can also enable file transfers via the command line as explained in the help for that screen.
+<p>
+With file transfer enabled you will be able to upload text files to the 
+<a href="../../ui/dialogs/options/api.html#xferdir">Transfer Directory</a> using the 'fileUpload' 'other' endpoint
+and download them from there using the 'fileDownload' 'other' endpoint.
+You can specify subdirectories (e.g. "subdir/myfile") but any attempt to upload or download a file to or from another directory 
+(e.g. using "../../") will be rejected.
+The 'fileUpload' endpoint only accepts POST requests and you should use an encoding of either "multipart/form-data" or "application/x-www-form-urlencoded". 
+The web UI allows you to select and upload local files.
+<p>
+Curl example for uploading a file:
+<pre>
+curl \
+    -F fileContents=@/full/path/to/file/to/be/uploaded \
+    -F apikey=your-api-key \
+    -F fileName=destination-filename \
+    http://localhost:8080/OTHER/core/other/fileUpload/
+</pre>
+<p>
+To download a file generated by another API endpoint you will need to specify a file name/path starting with "${XFER}".
+For example you could export a context to "${XFER}/contexts/my.context" and then download it by specifying "contexts/my.context".
+<p>
+To upload a file to another API endpoint you need to do the reverse - first upload it, e.g. to "plans/myplan.yaml", and 
+then import it via the path "${XFER}/plans/myplan.yaml".
+
 
 <H2>See also</H2>
 <table>

addOns/help/src/main/javahelp/contents/ui/dialogs/options/api.html

@@ -24,6 +24,22 @@ <H3>Secure Only</H3>
 
 If enabled then the API will only be available via HTTPS. Otherwise it will be available via both HTTP and HTTPS.<br/>
 
+<H3><a name="filexferenabled">File Transfer Enabled</a></H3>
+
+If enabled then files can be transfered to and from ZAP via the API.
+This option is only available if the API key is <i>not</i> disabled.
+For more details see <a href="../../../start/features/api.html#filexfer">File Transfer</a>.
+<p>
+You can also enable this option via the command line using the parameter: <code>-config api.filexfer=true</code>
+
+<H3><a name="xferdir">Transfer Directory</a></H3>
+
+The directory used to transfer files to and from ZAP via the API.
+This option is only available if the API key is <i>not</i> disabled.
+For more details see <a href="../../../start/features/api.html#filexfer">File Transfer</a>.
+<p>
+You can also set the Transfer Directory via the command line using: <code>-config api.xferdir=/full/path/to/dir</code>
+
 <H3>API Key</H3>
 
 A key that must be specified on all API 'actions' and some 'other' operations.<br/>