Renamed to httpproxies

src/main/resources/lessons/httpproxies/documentation/0overview.adoc

@@ -0,0 +1,34 @@
+==== What's an HTTP Proxy
+
+A proxy is some forwarder application that connects your HTTP client to backend resources.
+HTTP clients can be browsers or applications like curl, SOAP UI, Postman, etc.
+Usually, these proxies are used for routing and getting internet access when there is no direct connection to the internet from the client itself.
+HTTP proxies are therefore also ideal when you are testing your application.
+You can always use the proxy log records to see what was actually sent from client to server.
+So you can check the request and response headers and the XML, JSON, or other payloads.
+
+HTTP Proxies receive requests from a client and relay them.
+They also typically record them.
+They act as a man-in-the-middle.
+It even works fine with or without HTTPS as long as your client or browser trusts the certificate of the HTTP Proxy.
+
+{nbsp} +
+
+==== ZAP Proxy Capabilities
+
+With ZAP, you can record traffic, inspect traffic, modify requests and responses from and to your browser, and get reports on a range of known vulnerabilities that ZAP detects through the inspection of the traffic.
+The passive and active reporting on security issues is usually used in Continuous Delivery pipelines that use a GUI-less ZAP.
+Here we will use ZAP interactively and mainly to see and modify requests to find vulnerabilities and solve assignments.
+ZAP has a graphical user interface but now also has a HUD Heads-On-Display, which uses a web socket connection between the browser, and the ZAP proxy.
+
+{nbsp} +
+
+==== Next pages
+
+You can go through all lesson pages or click on these links to skip some pages.
+
+* link:start.mvc#lesson/HttpProxies.lesson/1[Configuring] OWASP ZAP and browser
+* link:start.mvc#lesson/HttpProxies.lesson/5[Filtering] requests with ZAP
+* link:start.mvc#lesson/HttpProxies.lesson/6[A proxy assignment] with ZAP
+* link:start.mvc#lesson/HttpProxies.lesson/7[Replaying requests] with ZAP
+* link:start.mvc#lesson/HttpProxies.lesson/8[Replaying requests] with Burp

src/main/resources/lessons/httpproxies/documentation/10burp.adoc

@@ -0,0 +1,38 @@
+=== Burp Proxy
+
+Another proxy you can use is Burp. One of the exercises in WebGoat can only be resolved with Burp and not yet with OWAP ZAP.
+You can only configure Burp manually. Please follow the steps described link:start.mvc#lesson/HttpProxies.lesson/8[here] first.
+You can download the Burp community edition as a https://portswigger.net/burp/communitydownload[plain jar file,window=_blank]
+
+[source]
+----
+java -jar burpsuite_community_v2.1.04.jar
+----
+
+Choose `temporary project`, followed by `use burp defaults.`
+
+Go to the proxy options and change it to use port 8090
+
+image::images/burpproxy.png[Burp proxy options,style="lesson-image"]
+
+On this page, you can also export the Burp certificate and import it into your browser. Similar to the instructions in previous pages.
+
+Go to the proxy intercept page and click on the toggle so that intercept is switched off. (By default nd in the picture below, it is switched on)
+
+image::images/burpintercept.png[Burp intercept,style="lesson-image"]
+
+Then start a browser connected to the proxy and start using WebGoat.
+Now adjust the intercept request setting by extending the rule on what not to intercept:
+
+image::images/burpfilterclient.png[Burp client request filter,style="lesson-image"]
+
+Use e.g.: (\^mvc$|^txt$|\^woff$|^lesson$|\^gif$|^jpg$|\^png$|^css$|\^js$|^ico$)
+Then enable the intercept by clicking on the earlier mentioned toggle.
+
+An intercept will look like:
+
+image::images/burpintercepted.png[Burp client request filter,style="lesson-image"]
+
+Finally, you can look at the history and add filters for the history and replay requests from this screen:
+
+image::images/burpfilter.png[Burp history,style="lesson-image"]

src/main/resources/lessons/httpproxies/documentation/1proxysetupsteps.adoc

@@ -0,0 +1,11 @@
+==== HTTP Proxy Setup
+
+Since this is an OWASP project, we'll be using OWASP ZAP.
+If you are comfortable using another proxy (e.g., Burp), you can skip this.
+Otherwise, this will show you how to set up ZAP as a proxy on your local host.
+
+* First download and install https://www.zaproxy.org/download/[ZAP] for your operating system
+* Start ZAP
+* Start the browser directly from ZAP
+
+

src/main/resources/lessons/httpproxies/documentation/3browsersetup.adoc

@@ -0,0 +1,29 @@
+==== Setting up browser
+
+If you use the latest ZAP version (>= 2.8.0), you only need to start ZAP and click the browser button to be able to proxy, see image below:
+
+{nbsp} +
+
+image::images/zap-browser-button.png[ZAP Start,style="lesson-image"]
+
+{nbsp} +
+
+In the browser type: http://localhost:8080/WebGoat, you should see WebGoat and the OWASP ZAP Heads On Display (if you use OWASP ZAP as the proxy):
+
+{nbsp} +
+
+image::images/loginscreen.png[Browser with HUD,style="lesson-image"]
+
+{nbsp} +
+
+You might notice that this is the Dutch login screen. The browser determines the language settings. For some pages, there will be some local translations. You can contribute to WebGoat and add more for your preferred language. You can disable the Heads On Display by clicking on the highlighted button. You can learn about the OWASP ZAP HUD on their website. For now, we recommend disabling it as it kind of blocks the menu items.
+
+You should see the following in OWASP ZAP on the history panel:
+
+{nbsp} +
+
+image::images/zap-history.png[ZAP History,style="lesson-image"]
+
+{nbsp} +
+
+On the next page, we will show how to filter these requests to see only relevant requests and configure the interceptor.

src/main/resources/lessons/httpproxies/documentation/5configurefilterandbreakpoints.adoc

@@ -0,0 +1,23 @@
+==== Filter requests in history panel
+
+In the main ZAP window, click on Filter; see the image below.
+
+image::images/zap-exclude.png[Exclude internal APIs from WebGoat,style="lesson-image"]
+
+{nbsp} +
+
+Then in the `URL Inc Regex` box type:
+
+[source]
+----
+.*WebGoat.*
+----
+
+And in the `URL Exc Regex` box type:
+
+[source]
+----
+.*lesson.*.mvc
+----
+
+Click 'Apply to close the window, and ZAP will now no longer show internal WebGoat requests.

src/main/resources/lessons/httpproxies/documentation/6assignment.adoc

@@ -0,0 +1,34 @@
+==== Configure a breakpoint filter
+
+Before we start diving into intercepting requests with ZAP, we need to exclude the internal requests from the WebGoat
+framework. Otherwise, ZAP will also stop at all the requests which are only necessary for the inner working of WebGoat.
+Basically, a breakpoint is configured that will intercept requests when the request header contains a POST. You can add other rules as long as the polling `.mvc` messages will be excluded. As this would be annoying.
+
+Set the breakpoint as follows:
+
+image::images/breakpoint.png[Set breakpoint,style="lesson-image"]
+
+{nbsp} +
+
+You can see your active breakpoints here. And if you click on the checkbox, you can temporarily deactivate them and enable them again when you are just about to intercept the request. *DO NOT use the green/red button anymore*
+
+image::images/breakpoint2.png[Active breakpoints,style="lesson-image"]
+
+{nbsp} +
+
+Once you are intercepting requests and a request is made, it should look something like this:
+
+image::images/proxy-intercept-details.png[ZAP history tab,style="lesson-image"]
+
+==== Intercept and modify a request
+
+Set up the intercept as noted above and then submit the form/request below by clicking the submit button. When your request is intercepted (hits the breakpoint),
+modify it as follows.
+
+* Change the Method to GET
+* Add a header 'x-request-intercepted:true'
+* Remove the request body and instead send 'changeMe' as a query string parameter and set the value to 'Requests are tampered easily' (without the single quotes)
+
+Then let the request continue through (by hitting the play button).
+
+NOTE: The two play buttons behave a little differently, but we'll let you tinker and figure that out for yourself.

src/main/resources/lessons/httpproxies/documentation/7resend.adoc

@@ -0,0 +1,30 @@
+==== Use the "Edit and resend" functionality in ZAP
+
+Instead of intercepting the request, there is also an option to resend the same request again within ZAP.
+It helps you solve an assignment because you do not have to switch to ZAP, enable the intercept button, go back to WebGoat and perform the request again from within the browser.
+
+Let's look at an example. We are going to use the e-mail example from the WebWolf introduction lesson. This lesson
+will generate a request for `/WebGoat/WebWolf/mail`, in the "History" window, select the URL you want to resend right click
+on the URL and select `Open/Resend with Request Editor`. You can also find the request in the left pane of ZAP as indicated
+with the red arrow in the image below:
+
+image::images/zap_edit_and_resend.png[Open/Resend with Request Editor,style="lesson-image"]
+
+{nbsp} +
+
+A new window will open, and here, you can modify the request, for example, change the e-mail address to someone else and send it again.
+In the response tab, you can inspect the response of the request. The response will show a solved message in some assignments, but sometimes you get a code/flag that you need to submit in WebGoat to complete the assignment. Always be on the
+lookout for a response. If you solved the assignment by making a request, WebGoat would automatically mark
+the lesson as solved.
+
+image::images/zap_edit_and_send.png[Open/Resend with Request Editor,style="lesson-image"]
+
+{nbsp} +
+
+++++
+<img class="lesson-image" src="images/zap_edit_and_response.png"/>
+++++
+
+image::images/zap_edit_and_response.png[Open/Resend response,style="lesson-image"]
+
+

src/main/resources/lessons/httpproxies/documentation/8httpsproxy.adoc

@@ -0,0 +1,27 @@
+== Proxy from ZAP to HTTPS
+
+The ZAP proxy can also be configured to proxy *HTTPS* requests. It will terminate the HTTPS connection in ZAP and then proxy it to the target using its keystore. You can even proxy to sites with mutual TLS. In that case, you configure OWASP ZAP with the keystore and key to use for the connection.
+
+Go to Tools/Options/Client Certificate to proxy to a mutual TLS HTTPS site.
+Go to Tools/Options/Connection if you want to set timeouts and want to force the use of TLSv1.2 e.g.
+
+
+=== Export the certificate
+
+Depending on the local tools installation, ZAP can start a browser directly with some adjusted options like network settings and certificate adjustments. However, you should do this step if you want to start your browser independently of ZAP. To be able to use the browser, the browser needs the certificate, which you can export here:
+
+image::images/rootca.png[ZAP root CA,style="lesson-image"]
+image::images/savecerts.png[ZAP save CA,style="lesson-image"]
+
+
+
+=== Import the OWASP ZAP root certificate
+
+. Go to your Firefox Preferences (Mac, Linux) or Options (Windows) from the menu.`
+. Search for _certificates_
+. Click _View certificates_
+. Import the ZAP root certificate that was saved (see the previous page)
+
+image::images/firefoxsettingscerts.png[Firefox Certificates,width="75%",style="lesson-image"]
+
+image::images/importcerts.png[Firefox Certificate import,width="75%",style="lesson-image"]

src/main/resources/lessons/httpproxies/documentation/9manual.adoc

@@ -0,0 +1,56 @@
+== Manually setting the proxy
+
+This section is only necessary if you want to use Burp or running the browser through ZAP is not working in both
+cases we need to do some extra configuration.
+In the latest release of Chrome and Firefox no longer proxy traffic from localhost by default.
+
+=== Option 1: Change settings of your browser
+
+- To proxy localhost (and related addresses) with newer Firefox versions (>= 67), the preference network. proxy.allow_hijacking_localhost (accessible through the about:config page) must be set to true.
+- To proxy localhost (and related addresses) with newer Chrome versions (>= 72) the command line argument --proxy-bypass-list=<-loopback> must be provided.
+
+=== Option 2: Use www.webgoat.local
+
+- Use the hostname of your machine instead of `localhost`. You can find or add a hostname in `/etc/hosts` on Linux and MacOSX and `C:\Windows\System32\drivers\etc` on Windows
+
+image::images/newlocalhost.png[Hosts file,style="lesson-image"]
+
+Then in your browser, use http://www.webgoat.local:8080/WebGoat as the address.
+
+=== Configure browser to use proxy
+
+To manually configure a proxy in the browser, follow one of the configurations below:
+
+==== Firefox Proxy Config
+
+. Go to your Firefox Preferences (Mac, Linux) or Options (Windows) from the menu.`
+. Select _Advanced_ on the left
+. Select _Network_ in the Advanced Pane
+. Click _Settings_
+. Select _Manual proxy configuration_
+.. input *127.0.0.1* as the proxy (or www.webgoat.local depending on the choice you made above)
+.. input *8090* as the port if running WebGoat locally, and you updated ZAP to 8090 (otherwise, use *8080*)
+.. check the _Use this proxy server for all protocols_ checkbox
+
+image::images/firefox-proxy-config.png[Firefox Proxy Config,510,634,style="lesson-image"]
+
+==== Chrome Proxy Config
+
+. Bring up Chrome's settings from the menu
+. In the _Search settings_ box, type in *proxy* and hit Enter/Return. This should bring up the Network heading with a _Change proxy settings_ button.
+. Click the _Change proxy settings_ button
+. Select the _proxies_ tab
+. Select Web Proxy (HTTP)
+. Input 127.0.0.1 (or www.webgoat.local depending on the choice you made) in the first box under _Web Proxy Server_ and your port # (8090 if running WebGoat locally, otherwise 8080) in the second box (to the right)
+. You may also want to clear the _Bypass proxy settings for these Hosts & Domains_ text input at the bottom but shouldn't need to
+
+
+image::images/chrome-manual-proxy.png[Chrome Proxy Config,700,447,style="lesson-image"]
+
+(Mac config image above)
+
+image::images/chrome-manual-proxy-win.png[Chrome Proxy, 394,346,style="lesson-image"]
+
+(Win config image above)
+
+

src/main/resources/lessons/httpproxies/html/HttpProxies.html

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+
+<html xmlns:th="http://www.thymeleaf.org">
+
+    <div class="lesson-page-wrapper">
+        <div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/0overview.adoc"></div>
+    </div>
+
+    <div class="lesson-page-wrapper">
+		<div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/1proxysetupsteps.adoc"></div>
+	</div>
+
+    <div class="lesson-page-wrapper">
+		<div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/3browsersetup.adoc"></div>
+	</div>
+
+    <div class="lesson-page-wrapper">
+        <div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/5configurefilterandbreakpoints.adoc"></div>
+    </div>
+
+    <div class="lesson-page-wrapper">
+        <div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/6assignment.adoc"></div>
+        <div class="attack-container">
+            <div class="assignment-success"><i class="fa fa-2 fa-check hidden" aria-hidden="true"></i></div>
+            <form class="attack-form" accept-charset="UNKNOWN" name="intercept-request"
+                  method="POST"
+                  action="/WebGoat/HttpProxies/intercept-request">
+
+                <input type="text" value="doesn't matter really" name="changeMe" />
+                <input type="submit" value="Submit" />
+
+            </form>
+            <div class="attack-feedback"></div>
+            <div class="attack-output"></div>
+        </div>
+    </div>
+
+    <div class="lesson-page-wrapper">
+        <div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/7resend.adoc"></div>
+    </div>
+    <div class="lesson-page-wrapper">
+        <div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/8httpsproxy.adoc"></div>
+    </div>
+    <div class="lesson-page-wrapper">
+        <div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/9manual.adoc"></div>
+    </div>
+    <div class="lesson-page-wrapper">
+        <div class="adoc-content" th:replace="doc:lessons/httpproxies/documentation/10burp.adoc"></div>
+    </div>
+</html>

src/main/resources/lessons/httpproxies/i18n/WebGoatLabels.properties

@@ -0,0 +1,4 @@
+2.http-proxies.title=HTTP Proxies
+
+http-proxies.intercept.success=Well done, you tampered the request as expected
+http-proxies.intercept.failure=Please try again. Make sure to make all the changes. And case sensitivity may matter ... or not, you never know!