Moving readme to markdown. various syntax fixes in docs

README.md

@@ -0,0 +1,34 @@
+![image](https://badge.waffle.io/Netflix/security_monkey.png?label=ready&title=Ready%20%0A%20:target:%20https://waffle.io/Netflix/security_monkey%0A%20:alt:%20'Stories%20in%20Ready')
+
+![image](https://badges.gitter.im/Join%20Chat.svg%0A%20:alt:%20Join%20the%20chat%20at%20https://gitter.im/Netflix/security_monkey%0A%20:target:%20https://gitter.im/Netflix/security_monkey?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+**develop branch**:
+
+![image](https://travis-ci.org/Netflix/security_monkey.svg?branch=develop%0A%20:target:%20https://travis-ci.org/Netflix/security_monkey)
+
+![image](https://coveralls.io/repos/github/Netflix/security_monkey/badge.svg?branch=develop%0A%20:target:%20https://coveralls.io/github/Netflix/security_monkey)
+
+**master branch**:
+
+![image](https://travis-ci.org/Netflix/security_monkey.svg?branch=master%0A%20:target:%20https://travis-ci.org/Netflix/security_monkey)
+
+![image](https://coveralls.io/repos/github/Netflix/security_monkey/badge.svg?branch=master%0A%20:target:%20https://coveralls.io/github/Netflix/security_monkey)
+
+Security Monkey
+===============
+
+![Security Monkey Logo 2017](docs/images/Security_Monkey.png "Security Monkey Logo 2017")
+
+Security Monkey monitors your [AWS and GCP accounts](https://medium.com/@Netflix_Techblog/netflix-security-monkey-on-google-cloud-platform-gcp-f221604c0cc7) for policy changes and alerts on insecure configurations.  It provides a single UI to browse and search through all of your accounts, regions, and cloud services.
+
+Security Monkey can be extended with [custom account types](plugins.md), custom watchers, custom auditors, and [custom alerters](docs/misc.md#custom-alerters).
+
+It works on CPython 2.7. It is known to work on Ubuntu Linux and OS X.
+
+Project resources
+-----------------
+
+- [Quickstart](docs/quickstart.md)
+- [Source code](https://github.com/netflix/security_monkey)
+- [Issue tracker](https://github.com/netflix/security_monkey/issues)
+

docs/contributing.md

@@ -13,7 +13,8 @@ Development Setup Ubuntu
 
 Please review the [Ubuntu Development Setup Instructions](dev_setup_ubuntu.md) to set up your Ubuntu installation for Security Monkey Development.
 
-Development Setup Windows ========================
+Development Setup Windows
+-------------------------
 
 Please review the [Windows Development Setup Instructions](dev_setup_windows.md) to set up Windows for Security Monkey development.
 

docs/dev_setup_osx.md

@@ -5,7 +5,7 @@ Please follow the instructions below for setting up the Security Monkey developm
 AWS Credentials
 ===============
 
-You will need to have the proper IAM Role configuration in place. See [Configuration](configuration.md) for more details. Additionally, you will need to have IAM keys available within your environment variables. There are many ways to accomplish this. Please see Amazon's documentation for additional details: <http://docs.aws.amazon.com/general/latest/gr/getting-aws-sec-creds.html>.
+You will need to have the proper IAM Role configuration in place. See [IAM Role Setup on AWS](iam_aws.md) for more details. Additionally, you will need to have IAM keys available within your environment variables. There are many ways to accomplish this. Please see Amazon's documentation for additional details: <http://docs.aws.amazon.com/general/latest/gr/getting-aws-sec-creds.html>.
 
 Additionally, see the boto documentation for more information: <http://boto.readthedocs.org/en/latest/boto_config_tut.html>
 
@@ -127,11 +127,17 @@ Pip will install all the dependencies into the current virtualenv. :
     # For OS X versions prior to El Capitan, run:
     python setup.py develop
 
-Init the Security Monkey DB ========================== Run Alembic/FlaskMigrate to create all the database tables. :
+Init the Security Monkey DB
+===========================
+
+Run Alembic/FlaskMigrate to create all the database tables. :
 
     python manage.py db upgrade
 
-Install and configure NGINX ========================== NGINX will be used to serve static content for Security Monkey. Use `brew` to install. :
+Install and configure NGINX
+===========================
+
+NGINX will be used to serve static content for Security Monkey. Use `brew` to install. :
 
     brew install nginx  
 
@@ -172,7 +178,7 @@ Next, you will create the `securitymonkey.conf` NGINX configuration file. Create
           proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
           proxy_redirect off;
           proxy_buffering off;
-          proxy_set_header        Host            $host;
+          proxy_set_header        Host            $http_host;
           proxy_set_header        X-Real-IP       $remote_addr;
           proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
       }
@@ -198,7 +204,10 @@ Create the `devlog/security_monkey.access.log` file. :
 
 NGINX can be started by running the `nginx` command in the Terminal. You will need to run `nginx` before moving on. This will also output any errors that are encountered when reading the configuration files.
 
-Launch and Configure the WebStorm Editor ========================== We prefer the WebStorm IDE for developing with Dart: <https://www.jetbrains.com/webstorm/>. Webstorm requires the JDK to be installed. If you don't already have Java and the JDK installed, please download it here: <http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html>.
+Launch and Configure the WebStorm Editor
+========================================
+
+We prefer the WebStorm IDE for developing with Dart: <https://www.jetbrains.com/webstorm/>. Webstorm requires the JDK to be installed. If you don't already have Java and the JDK installed, please download it here: <http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html>.
 
 In addition to WebStorm, you will also need to have the Dart SDK installed. Please download and install the Dart suite (SDK and Dartium) via Homebrew:
 
@@ -215,7 +224,10 @@ The Dart plugin needs to be configured to utilize the Dart SDK. To configure the
 
 -   As an example, for a typical Dart OS X installation (via `brew`), the Dart path will be at: `/usr/local/opt/dart/libexec`, and the Dartium path will be: `/usr/local/opt/dart/Chromium.app`
 
-Toggle-On Security Monkey Development Mode ========================== Once the Dart plugin is configured, you will need to alter a line of Dart code so that Security Monkey can be loaded in your development environment. You will need to edit the `dart/lib/util/constants.dart` file:
+Toggle-On Security Monkey Development Mode
+==========================================
+
+Once the Dart plugin is configured, you will need to alter a line of Dart code so that Security Monkey can be loaded in your development environment. You will need to edit the `dart/lib/util/constants.dart` file:
 
 -   Comment out the `API_HOST` variable under the `// Same Box` section, and uncomment the `API_HOST` variable under the `// LOCAL DEV` section.
 
@@ -240,11 +252,17 @@ This will add a user account that can be used later to login to the web ui:
 
 The first argument is the email address of the new user. The second parameter is the role and must be one of [anonymous, View, Comment, Justify, Admin].
 
-Start the Security Monkey API ========================== This starts the REST API that the Angular application will communicate with. :
+Start the Security Monkey API
+==============================
+
+This starts the REST API that the Angular application will communicate with. :
 
     python manage.py runserver
 
-Launch Dartium from within WebStorm ========================== From within the Security Monkey project in WebStorm, we will launch the UI (inside the Dartium app).
+Launch Dartium from within WebStorm
+===================================
+
+From within the Security Monkey project in WebStorm, we will launch the UI (inside the Dartium app).
 
 To do this, within the Project Viewer/Explorer, right-click on the `dart/web/ui.html` file, and select "Open in Browser" \> Dartium.
 
@@ -253,7 +271,10 @@ This will open the Dartium browser with the Security Monkey web UI.
 -   **Note:** If you get a `502: Bad Gateway`, try refreshing the page a few times.
 -   **Another Note:** If the page appears, and then quickly becomes a 404 -- this is normal. The site is attempting to redirect you to the login page. However, the path for the login page is going to be: `http://127.0.0.1:8080/login` instead of the WebStorm port. This is only present inside of the development environment -- not in production.
 
-Register a user in Security Monkey ========================== If you didn't create a user on the command line (as instructed earlier), you can create one with the web ui:
+Register a user in Security Monkey
+==================================
+
+If you didn't create a user on the command line (as instructed earlier), you can create one with the web ui:
 
 Chromium/Dartium will launch and will try to redirect to the login page. Per the note above, it should result in a 404. This is due to the browser redirecting you to the WebStorm port, and not the NGINX hosted port. This is normal in the development environment. Thus, clear your browser address bar, and navigate to: `http://127.0.0.1:8080/login` (Note: do not use `localhost`, use the localhost IP.)
 
@@ -269,7 +290,10 @@ Watch an AWS Account
 
 After you have registered a user, logged in, and re-opened Dartium from WebStorm, you should be at the main Security Monkey interface. Once here, click on Settings and on the *+* to add a new AWS account to sync.
 
-Manually Run the Account Watchers ========================== Run the watchers to put some data in the database. :
+Manually Run the Account Watchers
+=================================
+
+Run the watchers to put some data in the database. :
 
     cd ~/security_monkey/
     python manage.py run_change_reporter all

docs/dev_setup_ubuntu.md

@@ -5,7 +5,7 @@ Please follow the instructions below for setting up the Security Monkey developm
 AWS Credentials
 ===============
 
-You will need to have the proper IAM Role configuration in place. See [Configuration](configuration.md) for more details. Additionally, you will need to have IAM keys available within your environment variables. There are many ways to accomplish this. Please see Amazon's documentation for additional details: <http://docs.aws.amazon.com/general/latest/gr/getting-aws-sec-creds.html>.
+You will need to have the proper IAM Role configuration in place. See [IAM Role Setup on AWS](iam_aws.md) for more details. Additionally, you will need to have IAM keys available within your environment variables. There are many ways to accomplish this. Please see Amazon's documentation for additional details: <http://docs.aws.amazon.com/general/latest/gr/getting-aws-sec-creds.html>.
 
 Additionally, see the boto documentation for more information: <http://boto.readthedocs.org/en/latest/boto_config_tut.html>
 
@@ -75,7 +75,10 @@ Create a PostgreSQL database for security monkey and add a role. Set the timezon
     select now();
     \q
 
-Init the Security Monkey DB ========================== Run Alembic/FlaskMigrate to create all the database tables. :
+Init the Security Monkey DB
+==========================
+
+Run Alembic/FlaskMigrate to create all the database tables. :
 
     python manage.py db upgrade
 
@@ -138,7 +141,10 @@ Next, you will create the `securitymonkey.conf` NGINX configuration file. Create
 
 NGINX can be started by running the `sudo nginx` command in the console. You will need to run `sudo nginx` before moving on. This will also output any errors that are encountered when reading the configuration files.
 
-Launch and Configure the WebStorm Editor: ========================== We prefer the WebStorm IDE for developing with Dart: <https://www.jetbrains.com/webstorm/>. Webstorm requires the JDK to be installed. If you don't already have Java installed, then install it by running the commands: :
+Launch and Configure the WebStorm Editor:
+=========================================
+
+We prefer the WebStorm IDE for developing with Dart: <https://www.jetbrains.com/webstorm/>. Webstorm requires the JDK to be installed. If you don't already have Java installed, then install it by running the commands: :
 
     sudo apt-get install default-jre default-jdk
 
@@ -171,7 +177,10 @@ The Dart plugin needs to be configured to utilize the Dart SDK. To configure the
 
 -   As an example, for a typical Dart Ubuntu installation (via `apt-get`), the Dart path will be at: `/usr/lib/dart`, and the Dartium path (following the instructions above) will be: `/opt/Dartium/chrome`
 
-Toggle-On Security Monkey Development Mode ========================== Once the Dart plugin is configured, you will need to alter a line of Dart code so that Security Monkey can be loaded in your development environment. You will need to edit the `dart/lib/util/constants.dart` file:
+Toggle-On Security Monkey Development Mode
+==========================================
+
+Once the Dart plugin is configured, you will need to alter a line of Dart code so that Security Monkey can be loaded in your development environment. You will need to edit the `dart/lib/util/constants.dart` file:
 
 -   Comment out the `API_HOST` variable under the `// Same Box` section, and uncomment the `API_HOST` variable under the `// LOCAL DEV` section.
 
@@ -196,11 +205,17 @@ This will add a user account that can be used later to login to the web ui:
 
 The first argument is the email address of the new user. The second parameter is the role and must be one of [anonymous, View, Comment, Justify, Admin].
 
-Start the Security Monkey API ========================== This starts the REST API that the Angular application will communicate with. :
+Start the Security Monkey API
+=============================
+
+This starts the REST API that the Angular application will communicate with. :
 
     python manage.py runserver
 
-Launch Dartium from within WebStorm ========================== From within the Security Monkey project in WebStorm, we will launch the UI (inside the Dartium app).
+Launch Dartium from within WebStorm
+===================================
+
+From within the Security Monkey project in WebStorm, we will launch the UI (inside the Dartium app).
 
 To do this, within the Project Viewer/Explorer, right-click on the `dart/web/ui.html` file, and select "Open in Browser" \> Dartium.
 
@@ -209,7 +224,10 @@ This will open the Dartium browser with the Security Monkey web UI.
 -   **Note:** If you get a `502: Bad Gateway`, try refreshing the page a few times.
 -   **Another Note:** If the page appears, and then quickly becomes a 404 -- this is normal. The site is attempting to redirect you to the login page. However, the path for the login page is going to be: `http://127.0.0.1:8080/login` instead of the WebStorm port. This is only present inside of the development environment -- not in production.
 
-Register a user in Security Monkey ========================== Chromium/Dartium will launch and will try to redirect to the login page. Per the note above, it should result in a 404. This is due to the browser redirecting you to the WebStorm port, and not the NGINX hosted port. This is normal in the development environment. Thus, clear your browser address bar, and navigate to: `http://127.0.0.1:8080/login` (Note: do not use `localhost`, use the localhost IP.)
+Register a user in Security Monkey
+==================================
+
+Chromium/Dartium will launch and will try to redirect to the login page. Per the note above, it should result in a 404. This is due to the browser redirecting you to the WebStorm port, and not the NGINX hosted port. This is normal in the development environment. Thus, clear your browser address bar, and navigate to: `http://127.0.0.1:8080/login` (Note: do not use `localhost`, use the localhost IP.)
 
 Select the Register link (`http://127.0.0.1:8080/register`) to create an account.
 
@@ -223,7 +241,10 @@ Watch an AWS Account
 
 After you have registered a user, logged in, and re-opened Dartium from WebStorm, you should be at the main Security Monkey interface. Once here, click on Settings and on the *+* to add a new AWS account to sync.
 
-Manually Run the Account Watchers ========================== Run the watchers to put some data in the database. :
+Manually Run the Account Watchers
+=================================
+
+Run the watchers to put some data in the database. :
 
     cd ~/security_monkey/
     python manage.py run_change_reporter all

docs/dev_setup_windows.md

@@ -13,7 +13,7 @@ I'm pretty happy with development on Windows. Docker seems much easier to work w
 AWS Credentials
 ---------------
 
-You will need to have the proper IAM Role configuration in place. See [Configuration](configuration.md) for more details. Additionally, you will need to have IAM keys available within your environment variables. There are many ways to accomplish this. Please see Amazon's documentation for additional details: <http://docs.aws.amazon.com/general/latest/gr/getting-aws-sec-creds.html>.
+You will need to have the proper IAM Role configuration in place. See [IAM Role Setup on AWS](iam_aws.md) for more details. Additionally, you will need to have IAM keys available within your environment variables. There are many ways to accomplish this. Please see Amazon's documentation for additional details: <http://docs.aws.amazon.com/general/latest/gr/getting-aws-sec-creds.html>.
 
 Additionally, see the boto documentation for more information: <http://boto.readthedocs.org/en/latest/boto_config_tut.html>