Merge branch 'master' of github.com:aws-samples/aws-waf-workshop into rezabekf/patch-01

Author: rezabekf

docs/2-00-http-flood-config.png

@@ -40,4 +40,4 @@ Step by step instructions:
 * On the final page, check the box at the bottom allowing AWS CloudFormation to create IAM resources with custom names.
 * Click the orange "Create stack" button at the bottom-right of the page to deploy the stack into your account.
 
-# [Next step](step-2.md)
+# [Next step](step-1.md)

docs/2-01-athena-saved-queries.png

@@ -1,3 +1,52 @@
 # Step 1 - Getting Started with AWS WAF Security Automations Solution
 
-# [Next step](step-2.md)
+## 1.1 Associate the solution's AWS WAF Web ACL with your ALB
+
+After deploying the Web App, look at the [CloudFormation Exports](https://console.aws.amazon.com/cloudformation/home?#/exports). You should have a value called `site-url`. That is the address of the Application Load Balancer sitting on top of the Web App. Take note of that URL.
+
+Next, you need to associate the solution's AWS WAF Web ACL with your ALB. For that:
+* Go to the [AWS WAF console](https://console.aws.amazon.com/wafv2/home?#/webacls)
+* Check if the region drop-down filter (not the one on the top, the one in the page) is selected with your region as value. For instance, "EU (Ireland)"
+* Select the solution's WebACL - for instance "AWSWAFSecurityAutomations"
+* On the right panel, select the "Rules" tab
+* Scroll down to "AWS resources using this web ACL" section and click the "Add association" button
+* On the "Resource type" drop-down, select "Application load balancer"
+* On the "Resource" drop-down, select the ALB you've created
+* Finally, click the "Add" button.
+
+
+## 1.2 SQL Injection and XSS
+
+Access the `site-url` endpoint and include bad signatures to the requests. You can use, for example:
+
+* SQL Injection: `<your-endpoint>/?username=1'%20or%20'1'%20=%20'1&password=1'%20or%20'1'%20=%20'1'`
+* XSS: `<your-endpoint>/?<SCRIPT>alert(“Cookie”+document.cookie)</SCRIPT>`
+
+## 1.3 HTTP Flood (AWS Lambda log parser)
+
+To test HTTP Flood, you can simulate an WAF log file deliver event. For that:
+
+* Go to the CloudFormation stack's `Outputs` tab and search for the value defined for `WafLogBucket`
+* Go to S3, and upload [this file](files/waf-access-log-sample.gz) to the `WafLogBucket` bucket
+* Wait a few seconds (while the log parser function processes the new WAF log file)
+* Check if the file `<stack_name>-waf_log_out.json` was added to the `WafLogBucket` bucket
+* Go to [AWS WAF console](https://console.aws.amazon.com/wafv2/home?#/webacls) and check if `HTTP Flood` rule contains any IP listed
+
+## 1.4 Scanners & Probe (Amazon Athena log parser)
+
+To test Scanners & Probe, you can simulate a CloudWatch event running a query in a bucket that contains a sample access log file.
+For that:
+* Go to the S3 bucket that you set as Access Log Bucket. If you don't remember, go to stack's `Outputs` tab and search for the value defined for `AppAccessLogBucket`
+* Create a new folder and name it AWSLogs and upload [this file](files/alb-access-log-sample.gz) to it
+
+This file will be processed during the next scheduled *Scanner and Probe* scan. Rather than wait, we will run it on demand.
+
+* Go to the [AWS Lambda console](https://console.aws.amazon.com/lambda/home)
+* Open the `<stack_name>-LambdaLogParserFunction-<ID>` lambda function
+* Follow the link related the CloudWatch scheduled event
+* Copy the event data and create a Lambda test event with that information
+* Run the lambda function using the same event data used by the scheduled event
+* Wait a few seconds (while Athena processes the data, save the result back on S3 and the log parser function is called again to process the result file)
+* Go to [AWS WAF console](https://console.aws.amazon.com/wafv2/home?#/webacls) and check if `Scanners & Probes` rule contains any IP listed
+
+# [Next step](step-2.md)

docs/2-02-log-parser-cw-event.png

@@ -1,3 +1,81 @@
 # Step 2 - Customising and extending AWS WAF Security Automations Solution
 
-# [Next step](step-3.md)
+
+## 2.1.1 Customise HTTP Flood Protection (AWS Lambda Log Parser)
+
+The HTTP Flood log parser comes with some extensions points, they are:
+
+* Request Threshold: the maximum acceptable requests per five minutes per IP address.
+* Block Period: the period (in minutes) to block applicable IP addresses.
+* Ignored Suffixes: requests accessing this type of resource will not count to request threshold. By default, this list is empty.
+* URI List: use this to define a custom request threshold and block period for specifics URLs. By default, this list is empty.
+
+The goal now is to apply customizations and check how it affects the log parser behavior. 
+
+
+### 2.1.2 Customising the Parser
+
+* Go to the S3 bucket used for WAF Logs Bucket. To check it's name, go to stack's Outputs tab and search for the value defined for WafLogBucket;
+* Download the configuration file `<stack_name>-waf_log_conf.json`;
+* Make your changes (ex: change requestThreshold to 100);
+* Overwrite the configuration file on S3 bucket by uploading the new `<stack_name>-waf_log_conf.json` back to WAF Logs Bucket.
+
+Here is a sample of changed file:
+
+![http-flood-config](2-00-http-flood-config.png)
+
+
+### 2.1.3 Testing the new rules
+Let's test your HTTP flood protection. We will use [Apache AB](https://httpd.apache.org/docs/2.4/programs/ab.html).
+
+> ⚠️ **Warning**: Do not run the benchmarking tool from your local machine!
+
+We will use [Systems Manager Session Manager](https://console.aws.amazon.com/systems-manager/session-manager/start-session) to connect to the instance and run the `ab` benchmarking tool.
+
+Run against your endpoint 50,000 requests, with concurrency 100.
+```bash
+# Note the trailing slash
+ab -n 50000 -c 100 <your-endpoint>/
+```
+
+* After a couple of minutes (time necessary to ALB deliver the access logs to S3), go to AWS WAF console and check if HTTP Flood rule contains your EC2 instance IP listed.
+
+* Try to access <your-endpoint> from the instance you've sent the requests:
+```bash
+curl -s -o /dev/null -w "Return Code: %{http_code}\n" <your-endpoint>
+```
+
+## 2.2 Customising Scanners and Probes
+
+
+
+Now we will customise our Scanner and Probe rules. These use Amazon Athena.
+The solutions refer to the Athena by a saved query ID. As Athena don't allow you to change saved queries, the process to apply customizations to Athena query is by creating a new query and updating the Athena log parser event to use the new query ID.
+
+### 2.2.1
+* Navigate to the Amazon Athena console, select the Saved Queries tab;
+* Select the query you want to customize (ScannersProbesLogParser);
+
+![athena-saved-queries](2-01-athena-saved-queries.png)
+
+* Apply your changes (ex: change from `COUNT(*)>=50` to `COUNT(*)>=500`);
+* Save the new Athena Query and copy the new query ID.
+
+
+> NOTE: The query ID is part of the URL when you access the saved query (https://console.aws.amazon.com/athena/home?force#query/saved/**_query_id_**). Alternatively, you can use the `get-named-query CLI command`;
+
+
+* Navigate to LogParser events and select the corresponding event (ScannerProbe);
+
+![log-parser](2-02-log-parser-cw-event.png)
+
+* Edit the event data to point to the new Query ID copied above;
+
+![cw-event-rule](2-03-cw-event-output.png)
+
+Save the new event data;
+
+The Log Parser will now process logs using your new Athena Query.
+
+Done? Great work! Continue to the last challenge
+# [Next step](step-3.md)

docs/2-03-cw-event-output.png

@@ -1,7 +1,7 @@
 AWSTemplateFormatVersion: '2010-09-09'
 Description: Workshop about AWS WAF and WAF Security Automations Solution (uksb-1q1gt3g5d)
 Metadata:
-  Version: '0.2'
+  Version: '0.3'
   AWS::CloudFormation::Interface:
     ParameterGroups:
       - Label: