Merge pull request #20 from cloudmitigator/docs_refactor

Minor: Make docs sound for time being

about/about.rst

@@ -1,4 +1,53 @@
 What is Reflex?
 ==================================
 
-Reflex is a collection of open source tools and modules that allow you to enforce security best practices in your cloud environment. Reflex works by deploying resources which monitor your environment, and automatically fixes resources that are configured in an insecure manner. Best of all, Reflex is event driven, so problems are fixed as they happen. No manual intervention required.
+Reflex is a tool that enables organizations to enforce security best practices in their cloud environment. Reflex works by deploying resources which monitor your environment, and automatically detect or fix resources that are configured in an insecure manner. Best of all, Reflex is event driven, so problems are identified as they happen. No manual intervention or synchronized polling required.
+
+Reflex Architecture
+-----------------------
+Reflex leverages the **CloudWatch Events** resource as the main source of active account monitoring within AWS. Our architecture uses this as the foundational message source forwarding to an **SQS Queue** target that will then be ingested by a custom **Lambda Function**. Once the logic in that message is evaluated by the Lambda function and the event is found to be non compliant, an alert will be sent out via a central **SNS Topic** to subscribed parties. If the specific rule allows for remediation
+functionality, the remediation will take place and results of remediation will be included in the alert. 
+
+.. image:: reflex-architecture.png 
+ :width: 800pt
+
+How Much Does Reflex Cost
+----------------------------
+Reflex itself is open source, and the Reflex tool is free to use. *However*, Reflex works by deploying resources in your AWS account, and there is a cost to deploying and running those resources.
+
+**Any costs incurred while running Reflex are your responsibility.** Make sure you understand how Reflex works and are comfortable incurring any associated costs before you deploy resources.
+
+
+Typical Monthly Cost
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Your cost to run Reflex will depend on a variety of factors, particularly the number of Reflex rules you deploy and how often activity occurs in your AWS account. Our experience has been that running these kinds of rules, even in large AWS environments, is inexpensive. The largest AWS users (ie large enterprises with dozens or hundreds of active developers) typically spend no more than $5 per rule per month. The average user, with only a few developers, should expect to spend a few cents per rule per month. And if you qualify for AWS' free tier, it is likely that there will be little to no cost at all.
+
+The following information outlines the resources Reflex deploys, and should give you a starting point for estimating the cost of running Reflex in your AWS account.
+
+
+CloudWatch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Reflex utilizes CloudWatch Event Rules to monitor events in your environment and trigger rules. Event Rules are free. Reflex also utilizes CloudWatch Logs, which have ingestion and archive costs if you choose to use those features. In most cases the cost of Logs should be free.
+
+For more information see `AWS' CloudWatch Pricing Documentation <https://aws.amazon.com/cloudwatch/pricing/>`_.
+
+
+SQS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The first million requests with SQS each month are free (if you qualify for the free tier), so for most users there should be no cost for SQS. If you do not qualify for the free tier, SQS costs $0.40 per million requests, so the cost for SQS should be negligible in most environments.
+
+For more information see `AWS' SQS Pricing Documentation <https://aws.amazon.com/sqs/pricing/>`_.
+
+
+Lambda
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Lambda compute costs are the main cost associated with running Reflex. As these costs are dependent on which rules you use in your environment, it can be hard to predict what these will be. However even for large organizations it shouldn't be more than a few dollars per rule per month.
+
+For more information see `AWS' Lambda Pricing Documentation <https://aws.amazon.com/sqs/pricing/>`_.
+
+
+SNS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+By default Reflex will create SNS Topics and publish messages to them to notify you of what is happening in your environment. SNS offers one thousand free email publishes per month, with a cost of $2.00 per 100,000 after that. For small organizations the cost of SNS should be low or nothing, but as always it depends on your environment and deployed rules.
+
+For more information see `AWS' SNS Pricing Documentation <https://aws.amazon.com/sns/pricing/>`_.

conf.py

@@ -48,6 +48,10 @@
 # a list of builtin themes.
 #
 html_theme = 'alabaster'
+html_theme_options = {
+ 'logo': 'reflex-logo.png',
+ 'logo_name': True
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

index.rst

@@ -1,21 +1,17 @@
-.. Reflex documentation master file, created by
- sphinx-quickstart on Wed Feb 5 15:30:01 2020.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
+Reflex: Event Driven Security Automation
+=========================================
 
-Welcome to Reflex's documentation!
-==================================
+Welcome to the documentation for the reflex event driven security auomation framework.
 
 .. toctree::
  :maxdepth: 2
  :caption: Contents:
 
  about/about
- about/why-reflex
- about/cost
  usage/installation
  usage/quickstart
  usage/cli
+ usage/infrastructure
 
 Search the Docs
 ==================================

usage/cli.rst

@@ -1,11 +1,7 @@
 ==================================
-Using the Cli
+Reflex CLI
 ==================================
 
-Requirements
-----------------------------------
-If you haven't yet installed the Reflex CLI, refer to :doc:`/usage/installation`
-
 Usage
 ----------------------------------
 In order to get a list of commands and options type:
@@ -14,7 +10,7 @@ In order to get a list of commands and options type:
  reflex
 
 Available Commands
-----------------------------------
+^^^^^^^^^^^^^^^^^^^
 **init:**
 
  ::
@@ -49,7 +45,7 @@ Available Commands
 - Will walk you through the steps of creating a reflex rule. Creates the directory and all the necessary files to create a rule. Documents which areas need manual intervention in order to make the rule work.
 
 Options
-----------------------------------
+^^^^^^^^^^^
 
 **--version**
 
@@ -67,4 +63,49 @@ Options
 
 - Show all available commands and options.
 
+Reflex Config File: reflex.yaml
+----------------------------------
+The generated asset of ``reflex init`` is a config file which is by default named ``reflex.yaml``. Below is a reference for the format of that file:
+
+.. code-block:: yaml
+
+ ---
+ cli_version: '1.0'
+
+
+ engine_version: v1.0.0
+
+
+ globals:
+ default_email: administrator@example.com
+
+
+ backend:
+ s3:
+ - bucket: example-backend-bucket
+ - key: reflex-state
+
+
+ providers:
+ - aws:
+ region: us-east-1
+
 
+ rules:
+ aws:
+ - enforce-s3-encryption:
+ configuration:
+ - mode: detect
+ version: v0.4.2
+ - detect-deactivate-mfa:
+ version: v0.3.3
+ - detect-root-user-activity:
+ version: v0.2.4
+ - enforce-no-public-ami:
+ configuration:
+ - mode: detect
+ version: v0.3.2
+ - custom-reflex-rule-repository-name:
+ configuration:
+ - github_org: github_username
+ version: v0.0.2

usage/installation.rst

@@ -1,4 +1,47 @@
 Installing Reflex
 ==================================
 
+Dependencies
+----------------
+To deploy the reflex infrastructure, you will need to use terraform and have an AWS account deploy to. 
+
+Install Python
+^^^^^^^^^^^^^^^^^^^^^^^^
+If using the CLI, you will need to `install python. <https://www.python.org/downloads/>`_
+
+Install Terraform
+^^^^^^^^^^^^^^^^^^^^^^^^
+Reflex uses Terraform under the hood, so you'll need to `install that as well. <https://learn.hashicorp.com/terraform/getting-started/install.html>`_
+
+
+Set Up AWS Provider
+^^^^^^^^^^^^^^^^^^^^^^^^
+If you're already launching Terraform with an AWS provider setup, continue using that provider confirguration, otherwise, continue using roles or credentials as:
+
+Reflex currently only supports AWS, so you'll need to setup AWS credentials or a role for Terraform to utilize. For instructions on setting up your credentials see `the AWS documentation. <https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html>`_
+
+CLI Installation
+-------------------------
 To get started with Reflex, install the Reflex CLI: ``pip install reflex-cli``
+
+Terraform Module Integration
+----------------------------------
+If you'd like to use our reflex terraform modules independently, simply reference them properly as a `git source`__.
+
+.. __: https://www.terraform.io/docs/modules/sources.html#generic-git-repository
+
+
+As an example of this, the following is the output of a built module using the reflex CLI's ``reflex build`` command:
+
+.. code-block:: hcl
+
+ module "reflex-aws-enforce-s3-encryption" {
+ source = "git::https://github.com/cloudmitigator/reflex-aws-enforce-s3-encryption.git?ref=v0.4.2"
+ sns_topic_arn = module.central-sns-topic.arn
+ reflex_kms_key_id = module.reflex-kms-key.key_id
+ mode = ""
+ }
+
+For information about the terraform modules, check out the relevant rule or engine repository in our `Github organization`__.
+
+.. __: https://www.github.com/cloudmitigator/

usage/quickstart.rst

@@ -1,4 +1,4 @@
-Reflex Quickstart
+Reflex CLI Quickstart
 ==================================
 
 Getting started with Reflex is easy, and can be done in as little as 10 minutes.
@@ -9,19 +9,6 @@ Install the Reflex CLI
 If you haven't yet installed the Reflex CLI, refer to :doc:`/usage/installation`
 
 
-Install Terraform
-----------------------------------
-Reflex uses Terraform under the hood, so you'll need to `install that as well. <https://learn.hashicorp.com/terraform/getting-started/install.html>`_
-
-
-Set Up AWS Provider
-----------------------------------
-If you're already launching Terraform with an AWS provider setup, continue using that provider confirguration, otherwise, continue using roles or credentials as:
-
-
-Reflex currently only supports AWS, so you'll need to setup AWS credentials or a role for Terraform to utilize. For instructions on setting up your credentials see `the AWS documentation. <https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html>`_
-
-
 Generating a Reflex Configuration
 ----------------------------------
 Now that everything is installed and configured we can get started using Reflex. The first step is to create a Reflex configuration file, which tells Reflex which measures you want to enforce in your environment. The Reflex CLI makes this easy with the ``init`` command.
@@ -35,17 +22,17 @@ Generating Terraform Modules
 ----------------------------------
 Once you've created a ``reflex.yaml`` configuration file, you're ready to generate Terraform modules. Run ``reflex build`` to generate your Terraform modules. This will output a Terraform file for each measure you have specified in your configuration. These files will be created in a new ``reflex_out`` directory by default, but this is configurable with the ``-o`` option.
 
+Deploy With Terraform
+------------------------
 
 Run Terraform Init
-----------------------------------
+^^^^^^^^^^^^^^^^^^^^^
 Once you've generated your Terraform files, you're ready to start deploying your resources. First run ``terraform init`` from your ``reflex_out`` directory (or whatever you decided to name it). This will download all the required modules and perform all steps necessary to deploy your resources.
 
-
 Run Terraform Plan (Optional)
-----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Once you've generated your Terraform files and run ``terraform init`` you're ready to deploy your resources. If you want to see what resources will be deployed before you go ahead, you can run ``terraform plan`` to get a list of what resources will be added to your environment. Each measure will create multiple resources, so don't be alarmed that the number of resources being created is much larger than the number of measures you selected.
 
-
 Run Terraform Apply
-----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 If you are ready to move forward and actually deploy your resources, go ahead and run ``terraform apply``, and Terraform will start deploying resources to your environment. As soon as it finishes running, your resources a deployed and you're done!