Merge pull request #770 from mikegrima/docFixesAgain

More documentation fixes 📑
Netflix · Jul 24, 2017 · 45deeb0 · 45deeb0
2 parents cea8abe + 1c7a53c
commit 45deeb0
Show file tree

Hide file tree

Showing 8 changed files with 95 additions and 19 deletions.
diff --git a/docs/images/new_security_group.png b/docs/images/new_security_group.png
diff --git a/docs/images/rds_sg.png b/docs/images/rds_sg.png
diff --git a/docs/images/resized_ubuntu.png b/docs/images/resized_ubuntu.png
diff --git a/docs/images/securitygroup_details.png b/docs/images/securitygroup_details.png
diff --git a/docs/instance_launch_aws.md b/docs/instance_launch_aws.md
@@ -1,22 +1,34 @@
-Launch an AWS Instance
+Launch Security Monkey in AWS
 ======================
 
 Netflix monitors dozens AWS accounts easily on a single m3.large instance. For this guide, we will launch a m1.small.
 
-In the console, start the process to launch a new Ubuntu instance. The screenshot below shows EC2 classic, but you can also launch this in external VPC.:
+**Please Note: It is highly recommended that you operate Security Monkey on an instance with at least of 1.7GB of RAM. 
+You may encounter installation issues if you have less than 1.7GB of RAM. See [#580](https://github.com/Netflix/security_monkey/issues/580) for details.**
+
+
+Launch a new Instance:
+----------------------
+
+In the console, start the process to launch a new Ubuntu LTS instance:
 
 ![image](images/resized_ubuntu.png)
 
 Select an m1.small and select "Next: Configure Instance Details".
 
-**Note: Do not select "Review and Launch". We need to launch this instance in a specific role.**
+**Note: Do not select "Review and Launch". We need to launch this instance in a specific role and select security groups.**
 
 ![image](images/resized_select_ec2_instance.png)
 
-Under "IAM Role", select SecurityMonkeyInstanceProfile:
+Under "IAM Role", select `SecurityMonkeyInstanceProfile`:
 
 ![image](images/resized_launch_instance_with_role.png)
 
+Continue to `Step 6. Configure Security Group`. In here, select `Create a new security group`. Name the security group `securitymonkey`, and
+ingress in port `22` so you can SSH onto the instance when created, as well as port `443` so that you can access the web UI:
+
+![image](images/securitygroup_details.png)
+
 You may now launch the new instance. Please take note of the "Public DNS" entry. We will need that later when configuring security monkey.
 
 ![image](images/resized_launched_sm.png)

diff --git a/docs/postgres_aws.md b/docs/postgres_aws.md
@@ -1,18 +1,40 @@
 Postgres on AWS
 ===============
 
-Amazon can host your postgres database in their [RDS service](https://aws.amazon.com/rds/).  We recommend using AWS RDS or [GCP Cloud SQL](postgres_gcp.md) to productionalize your security_monkey deployment.
+Amazon can host your postgres database in their [RDS service](https://aws.amazon.com/rds/).  We recommend using AWS RDS or [GCP Cloud SQL](postgres_gcp.md) to productionalize your Security Monkey deployment.
 
-Create a Postgres RDS instance in the same region you intend to launch your security_monkey instance.
+You must create a Postgres RDS instance in the same region you intend to launch your Security Monkey instance.
+
+Create RDS Security Group
+-------------------------
+The first step is to create a security group for this RDS instance. Navigate to the AWS EC2 console's security group section.
+Please ensure that you are within the same region that Security Monkey is deployed in.
+
+Click `Create Security Group`:
+
+![Create new security group](images/new_security_group.png)
+
+Create a new security group named `securitymonkey-rds`, and add an ingress rule on TCP 5432 to permit the `securitymonkey` 
+(or whatever you named the security group that Security Monkey is launched with) security group access.
+
+![Sg details](images/rds_sg.png)
+
+
+Launch Postgres RDS Instance
+---------------------------
 
 ![Create RDS Instance](images/aws_rds.png "Create RDS Instance")
 
-The AWS supplied defaults should get you going.  You will need to use the hostname, dbname, username, password to create a SQLALCHEMY_DATABASE_URI for your config.
+The AWS supplied defaults should get you going. 
+Make sure that you launch the RDS instance with the `securitymonkey-rds` security group that we created above.
+
+You will need to use the hostname, dbname, username, password to create a `SQLALCHEMY_DATABASE_URI` for your config.
 
     SQLALCHEMY_DATABASE_URI = 'postgresql://securitymonkeyuser:securitymonkeypassword@hostname:5432/secmonkey'
 
 Advanced users may wish to supply a KMS key for encryption at rest.
 
+
 Next:
 -----
 

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -88,6 +88,16 @@ Releases are on the master branch and are updated about every three months. Blee
     pip install google-compute-engine  # Only required on GCP
     pip install cloudaux\[gcp\]
     python setup.py develop
+
+### 🚨⚠️🥁🎺 ULTRA SUPER IMPORTANT SPECIAL NOTE PLEASE READ THIS 🎺🥁⚠️🚨 ###
+
+In the commands above, a [Python virtual environment](http://python-guide-pt-br.readthedocs.io/en/latest/dev/virtualenvs/) is created.
+**ALL** Security Monkey commands from this point forward **MUST** be done from within the virtual environment. If following
+the instructions above, you can get back into the virtual environment by running the following commands:
+
+    cd /usr/local/src/security_monkey
+    source venv/bin/activate
+
 
 ### Compile (or Download) the web UI
 
@@ -137,27 +147,59 @@ Security Monkey uses Flask-Migrate (Alembic) to keep database tables up to date.
 Populate Security Monkey with Accounts
 --------------------------------------
 
-### Add Amazon Accounts
+### Add Amazon Accounts (AWS ONLY)
+
+If you don't use AWS, you can skip this section.
+
+Security Monkey has the ability to check which accounts are accessing your resources. This is helpful to
+detect if there is unknown cross-account access. In some cases, your items will be configured to permit
+Amazon owned accounts that provide specific AWS services, such as ELB access logging. Security Monkey is 
+equipped with a command to automatically add these accounts to the database, which will prevent Security Monkey
+from raising an "unknown cross-account access" issue on a given item.
 
-This will add Amazon owned AWS accounts to security monkey. :
+To add the "friendly" Amazon service accounts to Security Monkey, please run the command:
 
-    monkey amazon_accounts
+    monkey amazon_accounts    
 
 ### Add Your AWS/GCP Accounts
 
 You'll need to add at least one account before starting the scheduler. It's easiest to add them from the command line, but it can also be done through the web UI. :
 
     monkey add_account_aws
-    usage: manage.py add_account_aws [-h] -n NAME [--thirdparty] [--active]
-                                 [--notes NOTES] --id IDENTIFIER
-                                 [--update-existing]
-                                 [--canonical_id CANONICAL_ID]
-                                 [--s3_name S3_NAME] [--role_name ROLE_NAME]
+    usage: monkey add_account_aws [-h] -n NAME [--thirdparty] [--active]
+                                  [--notes NOTES] --id IDENTIFIER
+                                  [--update-existing]
+                                  [--canonical_id CANONICAL_ID]
+                                  [--s3_name S3_NAME] [--role_name ROLE_NAME]
 
     monkey add_account_gcp
-    usage: manage.py add_account_gcp [-h] -n NAME [--thirdparty] [--active]
-                                 [--notes NOTES] --id IDENTIFIER
-                                 [--update-existing] [--creds_file CREDS_FILE]
+    usage: monkey add_account_gcp [-h] -n NAME [--thirdparty] [--active]
+                                  [--notes NOTES] --id IDENTIFIER
+                                  [--update-existing] [--creds_file CREDS_FILE]
+
+For clarity: the `-n NAME` refers to the name that you want Security Monkey to use to associate with the account.
+A common example would be "test" for your testing AWS account or "prod" for your main production AWS account. These names are unique.
+
+The `--id IDENTIFIER` is the back-end cloud service identifier for a given provider. For AWS, it's the 12 digit account number, 
+and for GCP, it's the project ID.
+
+
+### AWS Only: S3 Canonical IDs
+
+If you are not using AWS, you can skip this section. If you are using AWS, you should run the command:
+
+    monkey fetch_aws_canonical_ids
+    usage: monkey fetch_aws_canonical_ids [-h] [--override OVERRIDE]
+
+    Adds S3 canonical IDs in for all AWS accounts in SM.
+
+    optional arguments:
+      -h, --help           show this help message and exit
+      --override OVERRIDE
+
+AWS S3 has an ACL system that makes use of Canonical IDs. This is documented [here](http://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html).
+These IDs are not easy to find, but are very important for Security Monkey to know if an S3 bucket has unknown cross-account access.
+The above command is a convenience to automatically find those Canonical IDs and associate them with your account. It is highly recommended that you run this command after you add an AWS account.
 
 ### Create the first user:
 

diff --git a/docs/userguide.md b/docs/userguide.md
@@ -15,7 +15,7 @@ After you have registered a new account and logged in, you need to add an accoun
 Adding an Account in the Web UI
 -------------------------------
 
-Here you will see a list of the accounts Security Monkey is monitoring. (It should be empty.)
+Here you will see a list of the accounts Security Monkey is monitoring.
 
 Click on the plus sign to create a new account: