Improve the documentation

Solves: #37
Solves: #60
Reviewed-by: Luca Carettoni <luca@doyensec.com>
Sponsored-by: doyensec <https://doyensec.com/>

FAQ.md

@@ -0,0 +1,51 @@
+FAQ
+===
+
+Is Burp Suite Free/Community edition supported?
+-----------------------------------------------
+
+No, it is not. Burp Rest API exposes functionalities that are best suited for the Professional 
+version of Burp Suite. Even if it was possible to start _burp-rest-api_ using the Free version of Burp, this is no longer possible and the support won't be included in future releases.
+
+Whenever I run the gradle command I receive an error. What can be the the cause?
+----------------------------------------------------------------------------
+
+Often times, Gradle introduces incompatibility between major versions, therefore
+the recommended way of executing any Gradle build is by using the Gradle
+Wrapper (in short just “Wrapper”). The Wrapper is a script that invokes a
+declared version of Gradle, downloading it beforehand if necessary.
+
+See [Issue 37](https://github.com/vmware/burp-rest-api/issues/37).
+
+Is it possible to run burp-rest-api graphically in remote servers?
+------------------------------------------------------------------
+
+Yes, it is possible to run Burp in graphical environments in multiple
+configurations (X Forwarding, Full VNC, RDP, XPRA).
+
+For running a non persistent X Forwarding session on your OS you can follow this
+[guide](https://uisapp2.iu.edu/confluence-prd/pages/viewpage.action?pageId=280461906).
+
+See [Issue 60](https://github.com/vmware/burp-rest-api/issues/60).
+
+Is it possible to customize the binding address:port for Burp Proxy and/or burp-rest-api APIs?
+----------------------------------------------------------------------------------------------
+
+There are two binding ports in a standard burp-rest-api setup:
+- **burp-rest-api RPC mechanism**. Both IP address and port can be customized at runtime using command line arguments (namely _--server.address_ and _--server.port_)
+- **Burp Proxy Listener**. This is a Burp Suite configuration, and can be customized using a custom project option file.
+
+```
+        "request_listeners":[
+            {
+                "certificate_mode":"per_host",
+                "listen_mode":"192.168.1.1",
+                "listener_port":8080,
+                "running":true
+            }
+```
+
+Is Burp Suite v2 supported?
+----------------------------------------------------------------------------------------------
+
+Next generation Burp Suite v2 is a beta release at the time of writing this FAQ. While we will *try* to mantain support for both Burp Suite stable and beta, we cannot ensure full compability. For production, please stay on Burp Suite Professional stable branch.

LICENSE

@@ -1,4 +1,5 @@
 Copyright (c) 2016 VMware, Inc. All Rights Reserved.
+Copyright (c) 2018 Doyensec LLC. All Rights Reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
  following conditions are met: Redistributions of source code must retain the above copyright notice, this list of

README.md

@@ -4,105 +4,55 @@
 
 A REST/JSON API to the Burp Suite security tool.
 
-Upon successfully building the project, an executable JAR file is created with the Burp Suite Professional JAR bundled
- in it. When the JAR is launched, it provides a REST/JSON endpoint to access the Scanner, Spider, Proxy and other
- features of the Burp Suite Professional security tool.
-
-## Try it out
-
-### Prerequisites
-
-* Java 8
-* Gradle
-* Licensed Burp Suite Professional version 1.7.x or later from: <http://portswigger.net/burp/>
-
-
-### Build & Run
-
-1. [Download](https://portswigger.net/burp/download.html) the Professional edition of Burp Suite.
-2. Create a `lib` folder under the project directory and place the Burp Suite JAR file into it and rename it to "burpsuite_pro.jar".
-3. The project can be run either by running the Gradle Spring `bootRun` command or by directly launching the JAR
- created from building the project:
-
-```
-    gradlew bootRun
-```
-
-or
-
-```
-    # build the jar
-    gradlew clean build
-    # and run it
-    java -jar build/libs/burp-rest-api-*.jar --burp.jar=./lib/burpsuite_pro.jar 
-```
-The version number of the JAR should match the version number from `build.gradle` while generating the JAR.
+Since version 2.0.0 it is possible to run the burp-rest-api release jar,
+downloading it directly from the 
+[release channel](https://github.com/vmware/burp-rest-api/releases).
 
 ## Documentation
 
 ### Configuration
 
-By default, Burp is launched in headless mode with the Proxy running on port 8080/tcp (localhost only) and the REST endpoint running on 8090/tcp (localhost only).
+By default, Burp is launched in headless mode with the Proxy running on port 8080/tcp (**localhost only**) and the REST endpoint running on 8090/tcp (**localhost only**).
 
 To __run Burp in UI mode__ from the command line, use one of the following commands:
 
-With the `bootRun` command:
-```
-    gradlew bootRun -Djava.awt.headless=false --burp.jar=./lib/burpsuite_pro.jar
 ```
-or
-```
-    gradlew bootRun -Dheadless.mode=false --burp.jar=./lib/burpsuite_pro.jar
-```
-or with the `bootRun` command using the `-PappArgs` to pass args directly to burp suite :
-```
-    gradlew bootRun -PappArgs="['-Djava.awt.headless=false','--project-file=./test.burp']"
-```
-With the executable JAR:
-```
-    java -jar burp-rest-api-1.0.2.jar -Djava.awt.headless=false --burp.jar=./lib/burpsuite_pro.jar
+    java -jar burp-rest-api-2.0.0.jar -Djava.awt.headless=false --burp.jar=./lib/burpsuite_pro.jar
 ```
 or
 ```
-    java -jar burp-rest-api-1.0.2.jar --headless.mode=false --burp.jar=./lib/burpsuite_pro.jar
+    java -jar burp-rest-api-2.0.0.jar --headless.mode=false --burp.jar=./lib/burpsuite_pro.jar
 ```
 
 
 To __modify the server port__ on which the API is accessible, use one of the following commands:
 
-With the `bootRun` command:
 ```
-    gradlew bootRun -Dserver.port=8081 --burp.jar=./lib/burpsuite_pro.jar
+    java -jar burp-rest-api-2.0.0.jar --server.port=8081 --burp.jar=./lib/burpsuite_pro.jar
 ```
 or
 ```
-    gradlew bootRun -Dport=8081 --burp.jar=./lib/burpsuite_pro.jar
-```
-
-With the executable JAR:
-```
-    java -jar burp-rest-api-1.0.2.jar --server.port=8081 --burp.jar=./lib/burpsuite_pro.jar
-```
-or
-```
-    java -jar burp-rest-api-1.0.2.jar --port=8081 --burp.jar=./lib/burpsuite_pro.jar
+    java -jar burp-rest-api-2.0.0.jar --port=8081 --burp.jar=./lib/burpsuite_pro.jar
 ```
 
 You can also __modify the server address__, used for network address binding:
 
-With the `bootRun` command:
 ```
-    gradlew bootRun -Dserver.address=192.168.1.2
+    java -jar burp-rest-api-2.0.0.jar --server.address=192.168.1.2 --burp.jar=./lib/burpsuite_pro.jar
 ```
 or
 ```
-    gradlew bootRun -Daddress=192.168.1.2
+    java -jar burp-rest-api-2.0.0.jar --address=192.168.1.2 --burp.jar=./lib/burpsuite_pro.jar
 ```
 
 ### Command Line Arguments
 
 The following command line arguments are used only by the extension to configure the run mode and port number.
 
+`--burp.jar=<filaname.jar>` : Loads the Burp jar dinamically, and expose it through REST APIs. This flag is required.
+
+`--burp.ext=<filename.{jar,rb,py}` : Loads the given Burp extensions during application startup. This flag can be repeated.
+
 `--server.port=<port_number>` : The REST API endpoint is available at the given port number. `--port=<port_number>`
  works as short hand argument.
 
@@ -122,7 +72,7 @@ Command line arguments passed to the executable burp-rest-api JAR are forwarded
 `--config-file=<filename>` : Opens the project using the options contained in the selected project configuration file. To
  load multiple project configurations, this argument can be passed more than once with different values.
 
- `--user-config-file=<filename>` : Opens the project using the options contained in the selected user configuration file. To
+`--user-config-file=<filename>` : Opens the project using the options contained in the selected user configuration file. To
   load multiple user configurations, this argument can be passed more than once with different values.
 
 For more information on Projects, refer to the Burp Suite documentation
@@ -155,18 +105,55 @@ This project also comes with a client (_BurpClient.java_) written in Java for us
 ## Credits
 
 This project is originally inspired from [Resty-Burp](https://github.com/continuumsecurity/resty-burp
- "continuumsecurity/resty-burp: REST/JSON interface to Burp Suite") and is developed in partnership with [Doyensec](https://www.doyensec.com).
+ "continuumsecurity/resty-burp: REST/JSON interface to Burp Suite"), and is developed in partnership with [Doyensec LLC](https://doyensec.com/). <img src="https://www.doyensec.com/images/logo.png" width="300">
 
 ## Contributing
 
 The burp-rest-api project team welcomes contributions from the community. If you wish to contribute code and you have
  not signed our contributor license agreement (CLA), our bot will update the issue when you open a Pull Request. For
- any questions about the CLA process, please refer to our [FAQ](https://cla.vmware.com/faq). For more detailed
- information, refer to [CONTRIBUTING.md](CONTRIBUTING.md).
+ any questions about the CLA process, please refer to our [CLA FAQ](https://cla.vmware.com/faq). For more detailed
+ information, refer to [CONTRIBUTING.md](CONTRIBUTING.md) and [FAQ.md](FAQ.md).
+
+### Develop
+
+Upon successfully building the project, an executable JAR file is created.
+The Burp suite JAR can be loaded dinamically through the `--burp.jar=` argument.
+When the JAR is launched, it provides a REST/JSON endpoint to access the Scanner, Spider, Proxy and other
+ features of the Burp Suite Professional security tool.
+
+#### Prerequisites
+
+* Java 8
+* Gradle
+* Licensed Burp Suite Professional version 1.7.x or later from: <http://portswigger.net/burp/>
+
+
+#### Build & Run
+
+1. [Download](https://portswigger.net/burp/download.html) the Professional edition of Burp Suite.
+2. The project can be run either by running the Gradle Spring `bootRun` command or by directly launching the JAR
+ created from building the project:
+3. OPTIONAL: Create a `lib` folder under the project directory and place the Burp Suite JAR file into it and rename it to "burpsuite_pro.jar" in order to run the integration tests.
+
+```
+    ./gradlew bootRun --burp.jar=./lib/burpsuite_pro.jar
+```
+
+or
+
+```
+    # build the jar
+    ./gradlew clean build
+    # and run it
+    java -jar build/libs/burp-rest-api-2.0.0.jar --burp.jar=./lib/burpsuite_pro.jar 
+```
+The version number of the JAR should match the version number from `build.gradle` while generating the JAR.
+
 
 ## License
 
 Copyright (c) 2016 VMware, Inc. All Rights Reserved.
+Copyright (c) 2018 Doyensec LLC. All Rights Reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
  following conditions are met: Redistributions of source code must retain the above copyright notice, this list of