feat(docs): add new docs and readme (#1529)

Co-authored-by: sergargar <sergio@verica.io>
Co-authored-by: n4ch04 <nachor1992@gmail.com>

docs/tutorials/aws/organizations.md

@@ -0,0 +1,49 @@
+# AWS Organizations
+## Get AWS Account details from your AWS Organization:
+
+Prowler allows you to get additional information of the scanned account in CSV and JSON outputs. When scanning a single account you get the Account ID as part of the output.
+
+If you have AWS Organizations Prowler can get your account details like Account Name, Email, ARN, Organization ID and Tags and you will have them next to every finding in the CSV and JSON outputs.
+
+- In order to do that you can use the option `-O`/`--organizations-role <organizations_role_arn>`. See the following sample command:
+
+```
+prowler aws -O arn:aws:iam::<management_organizations_account_id>:role/<role_name>
+```
+> Make sure the role in your AWS Organizatiosn management account has the permissions `organizations:ListAccounts*` and `organizations:ListTagsForResource`.
+
+- In that command Prowler will scan the account and getting the account details from the AWS Organizations management account assuming a role and creating two reports with those details in JSON and CSV.
+
+In the JSON output below (redacted) you can see tags coded in base64 to prevent breaking CSV or JSON due to its format:
+
+```json
+  "Account Email": "my-prod-account@domain.com",
+  "Account Name": "my-prod-account",
+  "Account ARN": "arn:aws:organizations::222222222222:account/o-abcde1234/111111111111",
+  "Account Organization": "o-abcde1234",
+  "Account tags": "\"eyJUYWdzIjpasf0=\""
+```
+
+The additional fields in CSV header output are as follow:
+
+```csv
+ACCOUNT_DETAILS_EMAIL,ACCOUNT_DETAILS_NAME,ACCOUNT_DETAILS_ARN,ACCOUNT_DETAILS_ORG,ACCOUNT_DETAILS_TAGS
+```
+
+## Assume Role and across all accounts in AWS Organizations or just a list of accounts:
+
+If you want to run Prowler across all accounts of AWS Organizations you can do this:
+
+- First get a list of accounts that are not suspended:
+
+```
+ACCOUNTS_IN_ORGS=$(aws organizations list-accounts --query Accounts[?Status==`ACTIVE`].Id --output text)
+```
+
+- Then run Prowler to assume a role (same in all members) per each account, in this example it is just running one particular check:
+
+```
+for accountId in $ACCOUNTS_IN_ORGS; do prowler aws -O arn:aws:iam::<management_organizations_account_id>:role/<role_name>; done
+```
+
+- Using the same for loop it can be scanned a list of accounts with a variable like `ACCOUNTS_LIST='11111111111 2222222222 333333333'`

docs/tutorials/aws/role-assumption.md

@@ -0,0 +1,24 @@
+# AWS Assume Role
+
+Prowler uses the AWS SDK (Boto3) underneath so it uses the same authentication methods.
+
+However, there are few ways to run Prowler against multiple accounts using IAM Assume Role feature depending on each use case:
+
+1. You can just set up your custom profile inside `~/.aws/config` with all needed information about the role to assume then call it with `prowler aws -p/--profile your-custom-profile`.
+
+2. You can use `-R`/`--role <role_arn>` and Prowler will get those temporary credentials using `aws sts assume-role`, set them up as environment variables and run against that given account.
+```sh
+prowler aws -R arn:aws:iam::<account_id>:role/<role_name>
+```
+- Optionally, the session duration (in seconds, by deafult 3600) and the external ID of this role assumption can be defined:
+
+```sh
+prowler aws -T/--session-duration <seconds> -I/--external-id <external_id> -R arn:aws:iam::<account_id>:role/<role_name>
+```
+
+>To create a role to assume in multiple accounts easier either as CFN Stack or StackSet, look at [this CloudFormation template](iam/create_role_to_assume_cfn.yaml) and adapt it.
+
+
+> _NOTE 1 about Session Duration_: Depending on the mount of checks you run and the size of your infrastructure, Prowler may require more than 1 hour to finish. Use option `-T <seconds>` to allow up to 12h (43200 seconds). To allow more than 1h you need to modify _"Maximum CLI/API session duration"_ for that particular role, read more [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session).
+
+> _NOTE 2 about Session Duration_: Bear in mind that if you are using roles assumed by role chaining there is a hard limit of 1 hour so consider not using role chaining if possible, read more about that, in foot note 1 below the table [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html).

docs/tutorials/aws/securityhub.md

@@ -0,0 +1,38 @@
+# Security Hub Integration
+
+Prowler supports natively and as **official integration** sending findings to [AWS Security Hub](https://aws.amazon.com/security-hub). This integration allows Prowler to import its findings to AWS Security Hub.
+
+With Security Hub, you now have a single place that aggregates, organizes, and prioritizes your security alerts, or findings, from multiple AWS services, such as Amazon GuardDuty, Amazon Inspector, Amazon Macie, AWS Identity and Access Management (IAM) Access Analyzer, and AWS Firewall Manager, as well as from AWS Partner solutions and from Prowler for free.
+
+Before sending findings to Prowler, you will need to perform next steps:
+
+1. Since Security Hub is a region based service, enable it in the region or regions you require. Use the AWS Management Console or using the AWS CLI with this command if you have enough permissions:
+    - `aws securityhub enable-security-hub --region <region>`.
+2. Enable Prowler as partner integration integration. Use the AWS Management Console or using the AWS CLI with this command if you have enough permissions:
+    - `aws securityhub enable-import-findings-for-product --region <region> --product-arn arn:aws:securityhub:<region>::product/prowler/prowler` (change region also inside the ARN).
+    - Using the AWS Management Console:
+     ![Screenshot 2020-10-29 at 10 26 02 PM](https://user-images.githubusercontent.com/3985464/97634660-5ade3400-1a36-11eb-9a92-4a45cc98c158.png)
+3. Allow Prowler to import its findings to AWS Security Hub by adding the policy below to the role or user running Prowler:
+    - [iam/prowler-security-hub.json](iam/prowler-security-hub.json)
+
+Once it is enabled, it is as simple as running the command below (for all regions):
+
+```sh
+./prowler aws -S
+```
+
+or for only one filtered region like eu-west-1:
+
+```sh
+./prowler -S -f eu-west-1
+```
+
+> **Note 1**: It is recommended to send only fails to Security Hub and that is possible adding `-q` to the command.
+
+> **Note 2**: Since Prowler perform checks to all regions by defauls you may need to filter by region when runing Security Hub integration, as shown in the example above. Remember to enable Security Hub in the region or regions you need by calling `aws securityhub enable-security-hub --region <region>` and run Prowler with the option `-f <region>` (if no region is used it will try to push findings in all regions hubs).
+
+> **Note 3** to have updated findings in Security Hub you have to run Prowler periodically. Once a day or every certain amount of hours.
+
+Once you run findings for first time you will be able to see Prowler findings in Findings section:
+
+![Screenshot 2020-10-29 at 10 29 05 PM](https://user-images.githubusercontent.com/3985464/97634676-66c9f600-1a36-11eb-9341-70feb06f6331.png)