Updates documentation to match functionality

docs/src/pages/about.rst

@@ -18,10 +18,10 @@ the only data store.
 How It Works
 =============
 
-SnowAlert queries Snowflake data on a regular schedule. We provide a Docker container so you can deploy it anywhere: on a server in the closet, with AWS Fargate, or even on your laptop.
+SnowAlert queries Snowflake data on a regular schedule. We provide a Docker container and orchestration templates, so that you can deploy it anywhere: on your laptop or on a server, or orchestrated with AWS Fargate or Google Kubernetes.
 
 The queries that drive the alerts are all defined as views that get stored in Snowflake; if you can write SQL, you can write queries for SnowAlert. We also provide some prebuilt packs of queries to help you get started and to serve as a model for what informative alerts should look like.
 
-Alerts are generated when queries match data in your warehouse, and they are saved to Snowflake as well. We use a Python script to create incident tickets from alerts but the same code can be extended to message or page your incident responders.
+Alerts are generated when Query Rules match Data in your database and are saved into Snowflake. There, they are de-duplicated, passed through Suppression Rules for sorting into expected and unexpected behavior, correlated by action or object, and dispatched to Handlers (e.g. Slack, Jira) for review by users or analysts, who then circle back to correct Data (e.g. update vulnerable software) or refine the Rules (e.g. whitelist access of a certaint type) that power SnowAlert.
 
 SnowAlert can also manage Violations, which are like alerts that require a less immediate response: a server not following best practices, a user without MFA enabled, and so on. These gets stored in a table similar to alerts, but are intended to be visualized with a tool like Sigma or Looker for ease of processing.

docs/src/pages/k8s.rst

@@ -18,7 +18,7 @@ suitable for your environment.
 
 Quickstart
 ==========
-To use the included manifests (warninig, they will deploy into the default
+To use the included manifests (warning, they will deploy into the default
 namespace). Modify the sa-secrets.yaml file with base64 encoded values that are
 the result of the non-KMS install process (i.e. the values contained within the
 envs file).
@@ -29,7 +29,7 @@ Assuming you have kubectl configured and pointing to your cluster you can execut
 
 .. code::
 
-    $ kubectl apply -f manifests 
+    $ kubectl apply -f manifests
 
 from within the /infra/k8s/ directory.
 

docs/src/pages/manage.rst

@@ -10,31 +10,31 @@ Query Rules
 
 Before creating new alerts, take a look at the alert configuration file ``packs/snowflake_query_pack.sql`` to see examples of useful Queries.
 
-Note that each Query Rule defines a set set of columns, of which some are static, e.g. ``'Medium' AS severity`` and ``'SnowAlert' AS detector``, while others are based on the data queries, such as ``user_name AS actor`` and ``start_time AS event_time``. Together, these define alerts that are saved in the `SNOWALERT.RESULTS` schema in your Snowflake account.
+Note that each Query Rule defines a set set of columns, of which some are static, e.g. ``'Medium' AS severity`` and ``'SnowAlert' AS detector``, while others are based on the data queries, such as ``user_name AS actor`` and ``start_time AS event_time``. Together, these define alerts that are saved in the ``results`` schema in your Snowflake account.
 
 
 Creating New Alert Queries
 ==========================
 
-Since a Query Rule is a view over data in Snowflake, they can be managed by writing SQL statements to create those views and grant the SnowAlert role `SELECT` privileges on them. Those statements can be saved in a .sql file and either pasted into the SnowFlake worksheet UI or executed via snowsql. A single .sql file can contain multiple rules.
+Since a Query Rule is a view over data in Snowflake, they can be managed by writing SQL statements to create those views and grant the SnowAlert role ``SELECT`` privileges on them. Those statements can be saved in a .sql file and either pasted into the SnowFlake worksheet UI or executed via snowsql. A single .sql file can contain multiple rules.
 
 
 Viewing Alert Results
 =====================
 
 When alert queries return data from your warehouse, the results will be added to the alerts table in your SnowAlert database. You can select them in the database to confirm that they are being generated as expected.
 
-If you've configured the alert handler to notify you on alerts, e.g. through JIRA, you can expect to see those notifications as soon as the container finishes executing all three Python scripts.
+If you've configured the alert handlers to notify you on alerts, e.g. through Jira, you can expect to see those notifications as soon as the Dispatch step is done.
 
 
 Adding Suppressions
 ===================
 
-SnowAlert supports suppression queries to prevent false positives from creating alerts. Suppression queries are configured similarly to alert queries, within .sql files in the alerts/suppressions folder. Suppressions are best targeted for specific queries, with a suppression for, e.g. ``AWS_ACCESS_DENIED_ALERT_QUERY``, being called ``AWS_ACCESS_DENIED_ALERT_SUPPRESSION``.
+SnowAlert supports Suppression Queries to prevent known behavior from being dispatched for review. Suppression Queries are configured similarly to Alert Queries, but end with ``_ALERT_SUPPRESSION``. Suppressions can suppress Alerts from multiple Queries or from a specific query, with a suppression for, e.g. ``AWS_ACCESS_DENIED_ALERT_QUERY``, being called ``AWS_ACCESS_DENIED_ALERT_SUPPRESSION``.
 
-Suppressions are views over the Alerts table, just like how queries are views over data, and can be managed in the same way as queries: by writing .sql files with statements to create the view and make the appropriate grants.
+Suppressions are views over the Alerts table, like Queries are views over data, and so can be managed in the same way: by writing .sql files with statements to create the view and make the appropriate grants.
 
-When the suppression function runs, it marks new alerts as suppressed or not. Only alerts that have been assessed by the suppression function are then processed by the alert handler.
+When the suppression step runs, it marks Alerts as suppressed or not. Alerts that have been through the suppression step and were not suppressed are then dispatched to handlers (e.g. Jira, Slack) by the Alert Dispatcher.
 
 
 SnowAlert Query Packs
@@ -44,7 +44,7 @@ SnowAlert is shipped with some sample queries, categorized by the type of monito
 
 To enable a query pack, copy the query pack file from packs/ into the Snowflake Worksheet UI and run the SQL statements to create the appropriate views and enable the appropriate grants.
 
-The current query packs and the queries are documented below:
+The current query packs and queries are documented below:
 
 - Snowflake Query Pack
 

docs/src/pages/start.rst

@@ -14,7 +14,7 @@ which configures your database, and
 
 .. code::
 
-    docker run -it --env-file snowalert-{account}.envs snowsec/snowalert ./run all
+    docker run -it --env-file snowalert-{account}.envs snowsec/snowalert ./run
 
 which runs the SnowAlert functions.