docs: updated Logging, Environment Variables, Setup and Deployment do…

…cs. (#524)

* rearranging setup docs

* docs: updated logging docs, added new log envvars

* docs: a few more changes to setup, log docs.

docs/_build/html/_sources/admin-guide/admin-guide.rst.txt

@@ -56,6 +56,13 @@ Users can be Unregistered from STIG Manager, which will delete STIGMan's informa
       :title: User Grants Administration
 
 
+User Properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Last Claims
+
+
 ------------------------------
 
 STIG and SCAP Benchmarks Admin Panel

docs/_build/html/_sources/installation-and-setup/authentication.rst.txt

@@ -4,8 +4,7 @@
 Authentication and Identity
 ########################################
 
-
-The API requires an OAuth2 JSON Web Token (JWT) that conforms to the OpenID Connect specification to determine client and user access.  The STIG Manager OSS Project suggests the use of the Authorization Code Flow with Proof Key for Code Exchange (PKCE)​ flavor of OAuth 2.0​.
+The API requires an OAuth2 JSON Web Token (JWT) that conforms to the OpenID Connect specification to determine client and user access. The STIG Manager OSS Project suggests the use of the **Authorization Code Flow with Proof Key for Code Exchange** (PKCE)​ flavor of OAuth 2.0​.
 
 STIG Manager OSS has been tested to work with Keycloak and Okta as OIDC providers.  It is expected to work with other OIDC providers if they can be configured to provide a token that meets the requirements specified below. Please create an Issue with details on our GitHub project if you experience issues with other providers.
 

docs/_build/html/_sources/installation-and-setup/environment-variables.rst.txt

@@ -127,6 +127,12 @@ STIG Manager is configured via its Environment Variables:
    * - STIGMAN_JWT_USERNAME_CLAIM
      - **Default** ``preferred_username`` The access token claim whose value is the user's username
      - API, Client
+   * - STIGMAN_LOG_LEVEL
+     - **Default** ``3`` Controls the granularity of the generated log output, from 1 to 4. Each level is inclusive of the ones before it. Level 1 will log only errors, level 2 includes warnings, level 3 includes status and transaction logs, and level 4 includes debug-level logs. 
+     - API
+   * - STIGMAN_LOG_MODE
+     - **Default** ``combined`` Controls whether the logs will create one "combined" log entry for http requests that includes both the request and response information; or two separate log entries, one for the request and one for the response, that can be correlated via a generated Request GUID in each entry. 
+     - API          
    * - STIGMAN_OIDC_PROXY_HOST
      - **No default** The ``Host:`` header value to be used by the CORS proxy for outbound requests. Some OIDC providers return configuration metadata with endpoint URLs having this value as their base.
      - API, Client

docs/_build/html/_sources/installation-and-setup/index.rst.txt

@@ -1,7 +1,7 @@
 
 .. _installation-and-setup-index:
 
-Install, Setup, and Run
+Setup and Deployment
 ===============================
 
 .. meta::

docs/_build/html/_sources/installation-and-setup/installation-and-setup.rst.txt

@@ -4,17 +4,27 @@
 STIG Manager OSS Setup and Technical Information
 ########################################################## 
 
-The STIG Manager open-source project provides an API and Web Client which are designed for deployment in a containerized service that is part of a fully orchestrated STIG Manager application. A STIG Manager application includes at least two other mandatory services:
+The STIG Manager open-source project provides an API and Web Client. The project is ideal for deployment as containerized service components that are part of a fully orchestrated individual or enterprise STIG Manager web application, but can also be run from source code in a Node.js runtime environment. 
 
-#. An OpenID Connect (OIDC) Provider
-#. A MySQL database
+Several deployment approaches are described in this document:
+
+- :ref:`Deploy our sample Docker Compose orchestration<deploy-docker-compose>`
+- :ref:`Deploy with Individual Containers <deploy-container>`
+- :ref:`Deploy from Source Code in Node.js runtime environment <deploy-from-source>`
+
+A STIG Manager deployment requires at least two other mandatory services, which are freely available but must be provided and configured by the those deploying the STIG Manager instance:
+  - An OpenID Connect (OIDC) Provider
+  - A MySQL database
+
+A sample orchestration, which includes the STIGMan API, Web Client, a Keycloak container, and a MySQL container, is available on our Docker Hub page. Follow the `Quick Start Orchestration instructions on Docker Hub. <https://hub.docker.com/r/nuwcdivnpt/stig-manager>`_
 
 The STIG Manager application is often deployed at the enterprise level with orchestration platforms such as Kubernetes or OpenShift. However, containerization allows STIG Manager deployments to be readily scaled up or down and it can be orchestrated on a single laptop with tools such as docker-compose.
 
 .. note::
   Containerized deployments of STIG manager are highly recommended because they offer improved security, scalability, portability, and maintenance. If absolutely necessary, it is possible to deploy the STIG Manager API in legacy environments from source code, but this is not recommended for secure deployments and is not fully documented. 
 
 
+
 Common Components 
 =================
 
@@ -24,64 +34,54 @@ Common Components
   :title: Component Diagram
 
 
+
 -------------------------------
 
+The required and optional components of a STIG Manager OSS deployment:
 
-API (Always Required)
------------------------------------
+**API** (Always Required)
+  A RESTful API implemented on the current LTS version of Node.js and the Express web application framework. Exposes 1 HTTP port. Built as a stateless container service.
+**Web Client** (Recommended for Interactive Access)
+  A Single Page Application (SPA) using the ExtJS 3.4 JavaScript framework. The Web Client is often enabled as static content from the API container which does not require a separate container.
+**OIDC Provider**  (Always Required)
+  An authentication service that manages user accounts and issues OAuth2 JWT tokens to the Web Client which authorize access to the API. We routinely test using Red Hat Keycloak and fully support Keycloak as an OIDC Provider of choice. More limited testing has been done using authentication services from Okta and Azure AD.
+**MySQL Database**  (Always Required)
+  A stateful data storage capability that supports mutual TLS authentication and secure data at rest. We support MySQL 8.0.14 and above.
 
-A RESTful API implemented on the current LTS version of Node.js and the Express web application framework. Exposes 1 HTTP port. Built as a stateless container service.
+-------------------------------
 
-Web Client (Recommended for Interactive Access)
--------------------------------------------------------------------------------
 
-A Single Page Application (SPA) using the ExtJS 3.4 JavaScript framework. The Web Client is often enabled as static content from the API container which does not require a separate container.
+Deployment Scenarios
+===============================================
 
-OIDC Provider (Always Required)
-------------------------------------------------
 
-An authentication service that manages user accounts and issues OAuth2 JWT tokens to the Web Client which authorize access to the API. We routinely test using Red Hat Keycloak and fully support Keycloak as an OIDC Provider of choice. More limited testing has been done using authentication services from Okta and Azure AD.
+.. _deploy-docker-compose:
 
-MySQL Database (Always Required)
+Quick Start Orchestration with Docker Compose
 -------------------------------------------------
 
-A stateful data storage capability that supports mutual TLS authentication and secure data at rest. We support MySQL 8.0.14 and above.
-
-Reverse Proxy (Recommended)
---------------------------------------------------------------
-
-An endpoint management capability that can provide mutual TLS authentication, including DoD Common Access Card (CAC), and TLS encryption for the API, Web Client, and OIDC Provider (if required).
-
-Log Collector (Recommended)
---------------------------------------------------------------
-
-A centralized logging capability that collects log records from all orchestration components. Most orchestration platforms provide some form of log collection.
-
-Log Analysis (Recommended)
-------------------------------------------------------
-
-A centralized log aggregation, analysis and reporting capability. Examples include Splunk, Solar Winds Security Event Manager, Elasticsearch, etc.
-
-
-Deployment Scenarios for Product Evaluation
-===============================================
-
+Requirements
+~~~~~~~~~~~~~~
 
-Quick Start Orchestration with Docker Compose
--------------------------------------------------
+- `Docker <https://www.docker.com/get-started>`_
 
 To quickly establish a demonstration instance of STIG Manager, follow the `Quick Start Orchestration instructions on Docker Hub. <https://hub.docker.com/r/nuwcdivnpt/stig-manager>`_
 
 
-Container Deployment with Docker Desktop
+.. _deploy-container:
+
+Container Deployment with Docker
 -------------------------------------------------
 
-Using the STIG Manager container image is the recommended way to deploy the app. These instructions specify a Docker Desktop deployment, but the app will run just as well in a Kubernetes or other orchestration environment. Using this deployment approach satisfies the application's NodeJS requirement.
+Using the STIG Manager container image is the recommended way to deploy the app. These instructions specify a Docker deployment, but the app will run just as well in a Kubernetes or other orchestration environment. Using this deployment approach satisfies the application's NodeJS requirement.
 
 Requirements
 ~~~~~~~~~~~~~~
 
-`Docker <https://www.docker.com/get-started>`_
+- `Docker <https://www.docker.com/get-started>`_
+- :ref:`OIDC Authentication Provider <keycloak>`
+- :ref:`mySQL`
+
 
 Procedure
 ~~~~~~~~~~~~~~~~~~~~~
@@ -95,11 +95,11 @@ Procedure
    *Make note of the address and ports these servers are using (as well as any other values that differ from the defaults). Set the appropriate* :ref:`Environment Variables` *to these values so STIG Manager will be able to reach them*
 
 #. Pull the latest image from Docker Hub. This command will grab the image based on the Iron Bank NodeJS hardened image:  ``docker pull nuwcdivnpt/stig-manager:latest-ironbank``
-#. Run the STIG Manager image. Specify Environment Variables if the defaults in the :ref:`Environment Variables` reference do not work for your environment. Set the Environment Variables using ``-e <Variable Name>=<value>`` parameters. A sample docker run command, exposing port 54000, and creating a container named "stig-manager" is shown here:
+#. Run the STIG Manager image using the ``docker run`` command. Specify Environment Variables if the defaults in the :ref:`Environment Variables` reference do not work for your environment. Set the Environment Variables using ``-e <Variable Name>=<value>`` parameters. A sample docker run command, exposing port 54000, and creating a container named "stig-manager" is shown here:
 
    .. code-block:: bash
 
-      docker run --name stig-manager \
+      docker run --name stig-manager -d \
       -p 54000:54000 \
       -e STIGMAN_DB_HOST=<DATABASE_IP> \
       -e STIGMAN_DB_PORT=<DATABASE_PORT> \
@@ -118,18 +118,20 @@ Procedure
       [START] Client is available at /
 
 
-
+.. _deploy-from-source:
 
 Deployment from Source Code
 -------------------------------
 
-STIG Manager can be deployed from source if the proper Node.js runtime is provided. These instructions relate to a Windows deployment, but the app will run just as well wherever Node.JS is available. 
+STIG Manager can be deployed from source if the proper Node.js runtime is provided. These instructions relate to a Windows deployment, but the app will run just as well wherever Node.js is available. 
 
 
 Requirements
 ~~~~~~~~~~~~~~
 
-- `Node.js 14.15+ <https://nodejs.org/en/>`_
+- `Node.js 16.13+ <https://nodejs.org/en/>`_
+- :ref:`OIDC Authentication Provider <keycloak>`
+- :ref:`mySQL`
 - `git <https://git-scm.com/downloads>`_ *(recommended)*
 
 

docs/_build/html/_sources/installation-and-setup/logging.rst.txt

@@ -1,26 +1,53 @@
 .. _logging:
 
 
-STIG Manager Logging 
+Logging 
 ########################################
 
 
-STIG Manager writes all log entries to STDOUT. Use the ``docker logs`` or equivalent container engine command to view them.
+STIG Manager writes all log entries to STDOUT.  How you capture and persist these log entries will depend on your Organizational requirements. 
 
 
-How you capture and persist these log entries will depend on your Organizational requirements. 
+.. rubric:: Log format
 
+The API implements a structured logging format in JSON, and supports several logging levels and modes.
+
+
+Log entries will conform to the following JSON schema:
+
+.. code-block:: yaml
+
+    type: object
+    properties:
+        date:
+            type: string
+        level:
+            type: integer
+        component:
+            type: string
+        type:
+            type: string
+        data:
+            type: object
+    required:
+    - date
+    - level
+    - component
+    - type
+    - data
 
 
-.. rubric:: Log format
 
-HTTP transactions handled by the API are logged to STDOUT following the Apache Common Log Format. Fields are in this order:
+The ``data`` object is extensible and will contain structured details concerning the event. 
 
-``:remote-addr :forwarded-for :token-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length]``
+The contents of the logs can be controlled with the following :ref:`Environment Variables`: 
 
-At startup log entries may be preceded by labels such ``[AUTH]`` or ``[DB]`` indicating the portion of the API that is attempting to establish itself. 
+STIGMAN_LOG_LEVEL
+    - Default: ``3``
+    - Controls the granularity of the generated log output, from 1 to 4. Each level is inclusive of the ones before it. Level 1 will log only errors, level 2 includes warnings, level 3 includes status and transaction logs, and level 4 includes debug-level logs. 
 
+STIGMAN_LOG_MODE
+    - Default: ``combined``
+    - Controls whether the API will create one "combined" log entry for http requests that includes both the request and response information; or two separate log entries, one for the request and one for the response, that can be correlated via a generated Request GUID in each entry.  Any value other than "combined" will produce separate log entries. 
 
-.. note::
-    The logging conventions currently implemented are candidates for future development. 
 

docs/_build/html/_sources/installation-and-setup/reverse-proxy.rst.txt

@@ -1,7 +1,7 @@
 .. _reverse-proxy:
 
 
-STIG Manager TLS 
+Deploy with TLS 
 ########################################
 
 

docs/_build/html/_static/css/custom.css

@@ -48,11 +48,11 @@ p.rubric-big {
 }
 
 
-/* .rst-content .toctree-wrapper>p.caption, h1, h2, h3, h4, h5, h6, legend {
+.rst-content .toctree-wrapper>p.caption, h1, h2, h3, h4, h5, h6, legend {
   margin-top: 0;
   font-weight: 700;
-  font-family: Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;
-} */
+  font-family: Lato,ff-tisa-web-pro,Georgia,Arial,sans-serif;
+}
 
 
 

docs/_build/html/admin-guide/admin-guide.html

@@ -98,7 +98,7 @@
               <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../features/index.html">Introduction and Features</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../installation-and-setup/index.html">Install, Setup, and Run</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../installation-and-setup/index.html">Setup and Deployment</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../user-guide/index.html">For Users</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="index.html">For Admins</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="admin-quickstart.html">1. STIGMan Application Manager (Administrator) Walkthrough</a></li>
@@ -216,7 +216,7 @@
 <span id="admin-guide-doc"></span><h1><span class="section-number">2. </span>STIGMan Application Management Guide<a class="headerlink" href="#stigman-application-management-guide" title="Permalink to this headline">¶</a></h1>
 <div class="section" id="stigman-app-manager-guide">
 <h2><span class="section-number">2.1. </span>STIGMan App Manager Guide<a class="headerlink" href="#stigman-app-manager-guide" title="Permalink to this headline">¶</a></h2>
-<p>Lists functionality available to App Managers (often called “admins” for short) in the STIG Manager app.  For information about administering a deployment of STIG Manager, please see <a class="reference internal" href="../installation-and-setup/index.html#installation-and-setup-index"><span class="std std-ref">Install, Setup, and Run</span></a>.</p>
+<p>Lists functionality available to App Managers (often called “admins” for short) in the STIG Manager app.  For information about administering a deployment of STIG Manager, please see <a class="reference internal" href="../installation-and-setup/index.html#installation-and-setup-index"><span class="std std-ref">Setup and Deployment</span></a>.</p>
 <div class="section" id="navigation-tree">
 <h3><span class="section-number">2.1.1. </span>Navigation Tree<a class="headerlink" href="#navigation-tree" title="Permalink to this headline">¶</a></h3>
 <p>App Managers will see the Application Management branch in the Navigation tree, as well as the Collections branch available to all users.</p>
@@ -267,7 +267,11 @@ <h3><span class="section-number">2.2.2. </span>User Grants Admin Panel<a class="
                      height="auto"
                      alt=""/>
                 </a><figcaption>User Grants Administration</figcaption>
-            </figure></div>
+            </figure><div class="section" id="user-properties">
+<h4><span class="section-number">2.2.2.1. </span>User Properties<a class="headerlink" href="#user-properties" title="Permalink to this headline">¶</a></h4>
+<p>Last Claims</p>
+</div>
+</div>
 <hr class="docutils" />
 <div class="section" id="stig-and-scap-benchmarks-admin-panel">
 <h3><span class="section-number">2.2.3. </span>STIG and SCAP Benchmarks Admin Panel<a class="headerlink" href="#stig-and-scap-benchmarks-admin-panel" title="Permalink to this headline">¶</a></h3>

docs/_build/html/admin-guide/admin-quickstart.html

@@ -98,7 +98,7 @@
               <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../features/index.html">Introduction and Features</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../installation-and-setup/index.html">Install, Setup, and Run</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../installation-and-setup/index.html">Setup and Deployment</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../user-guide/index.html">For Users</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="index.html">For Admins</a><ul class="current">
 <li class="toctree-l2 current"><a class="current reference internal" href="#">1. STIGMan Application Manager (Administrator) Walkthrough</a><ul>

docs/_build/html/admin-guide/index.html

@@ -99,7 +99,7 @@
               <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="../features/index.html">Introduction and Features</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../installation-and-setup/index.html">Install, Setup, and Run</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../installation-and-setup/index.html">Setup and Deployment</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../user-guide/index.html">For Users</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">For Admins</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="admin-quickstart.html">1. STIGMan Application Manager (Administrator) Walkthrough</a></li>