clarifying documentation

manual/operation/configuration.tex

@@ -11,17 +11,17 @@ \subsubsection{Trusting Self-Signed Certificates}\label{sec:self-signed-certs}
 corporate proxies use certificates signed by a private CA. If so, it is possible to
 import custom CA certificates when using \cxoneflow.
 
-\noindent\\The custom certificates must meet the following criteria:
+\noindent\\Each custom certificate to import must meet the following criteria:
 
 \begin{itemize}
-    \item Must be in the PEM format.
     \item Must be in a file ending with the extension .crt.
-    \item Only one certificate is in the file.
-    \item Must be mapped to the container path /usr/local/share/ca-certificates.
+    \item The contents of the file must be one certificate stored in the PEM format.
+    \item Each file must be mapped to the container path /usr/local/share/ca-certificates.
 \end{itemize}
 
 
-\noindent\\As an example, if using Docker, it is possible to map a local file to a file in the container with this mapping option added to the container execution command line:
+\noindent\\As an example, if using Docker, it is possible to map a single local file to a file in the container with this mapping 
+option added to the container execution command line:
 
 \begin{code}{Custom CA Mapping Option}{[Docker]}{}
 -v $(pwd)/custom-ca.pem:/usr/local/share/ca-certificates/custom-ca.crt
@@ -44,7 +44,8 @@ \subsubsection{The \texttt{ssl-verify} Option}\label{sec:ssl-verify-general}
 \subsubsection{Configuring SSL for the \cxoneflow Endpoint}
 
 To make the \cxoneflow endpoint use SSL for communication, obtain an SSL certificate public/private key pair
-and then set the following environment variables in the runtime environment:
+and map the files to a location on the container.  The following environment variables must then be set in the
+runtime environment:
 
 \begin{table}[ht]
     \caption{SSL Environment Variables}        
@@ -60,7 +61,7 @@ \subsubsection{Configuring SSL for the \cxoneflow Endpoint}
 \end{table}
 
 \noindent\\If your SSL certificate is self-signed or signed with a non-public CA, you'll want
-to import the custom CA as described in Section \ref{sec:self-signed-certs}.
+to import the self-signed certificate and/or non-public CA as described in Section \ref{sec:self-signed-certs}.
 
 
 \subsection{Runtime Control Environment Variables}
@@ -71,7 +72,7 @@ \subsection{Runtime Control Environment Variables}
         \toprule
         \textbf{Variable} & \textbf{Required} & \textbf{Default} & \textbf{Description}\\
         \midrule
-        \texttt{CXONEFLOW\_WORKERS} & No & \texttt{(\# of CPUs / 2)} & \makecell[l]{The number of worker processes\\used for parallel execution. The\\maximum value will be\\set at \texttt{(\# of CPUs - 1)}}\\
+        \texttt{CXONEFLOW\_WORKERS} & No & \texttt{max(\# of CPUs / 2, 1)} & \makecell[l]{The number of worker processes\\used for parallel execution. The\\maximum value will be\\set at \texttt{(\# of CPUs - 1)}}\\
         \midrule
         \texttt{LOG\_LEVEL} & No & \texttt{INFO} & \makecell[l]{The logging verbosity level.  Set to\\\texttt{DEBUG} for increased logging\\verbosity.}\\
         \midrule
@@ -87,8 +88,9 @@ \subsection{Runtime Control Environment Variables}
 
 \section{Operational Configuration}\label{sec:op-config}
 
-The operational configuration is done using a YAML file mapped at \texttt{/opt/cxone/config.yaml}
-by default.  
+The operational configuration uses a YAML file mapped at \texttt{/opt/cxone/config.yaml}
+by default.  It is possible to map the \texttt{config.yaml} file to another location in the
+container and adjust the path via the \texttt{CONFIG\_YAML\_PATH} environment variable.
 
 \subsection{YAML Configuration Examples}
 

manual/operation/deployment.tex

@@ -59,12 +59,12 @@ \subsection{Hosting}
 \subsection{Scan Configuration Defaults}\label{sec:deployment-scan-defaults}
 
 Scan configuration defaults can be provided at the tenant-global and project scope
-in CheckmarxOne.  The \cxoneflow configuration can be configured to set configuration
-defaults for each scan.  It is important to understand how the CheckmarxOne default
+in Checkmarx One.  The \cxoneflow configuration can be configured to set configuration
+defaults for each scan.  It is important to understand how the Checkmarx One default
 scan configurations work given the \cxoneflow configuration can override all other
 settings based on how the tenant and project defaults are configured.
 
-The configurations in CheckmarxOne are defined in the tenant or project scope with a
+The configurations in Checkmarx One are defined in the tenant or project scope with a
 flag that allows the value to be overridden at a lower level of configuration.  A
 SAST scan default preset, for example, is generally configured at the tenant scope
 as "ASA Premium" with the ability to override the preset at the project scope.  The
@@ -77,10 +77,10 @@ \subsection{Scan Configuration Defaults}\label{sec:deployment-scan-defaults}
 option for configuring the preset would not appear in the project settings.
 
 Configuring the SAST preset as a per-scan default in \cxoneflow will override both
-the tenant and project scope settings if both are set to allow override.  This is 
-due to the scan scope being the lowest level configuration scope.  If a project scope
-configuration was such that the SAST preset could not be overridden, then the \cxoneflow
-default preset set at the time of scan will be ignored.
+the tenant and project scope settings if both are set to allow override.  The reason for this
+is that the scan configuration provided to the API when a scan is initiated is considered to override
+all other configuration scopes.  If a project scope configuration was such that the SAST preset could
+not be overridden, then the \cxoneflow provided default preset set at the time of scan will be ignored.
 
 The configurations at the tenant, project, and scan level scopes work based on overrides.
 This causes the value of a configuration to be set by the lowest level in which it is
@@ -100,7 +100,7 @@ \subsection{Scan Configuration Defaults}\label{sec:deployment-scan-defaults}
 
 \subsubsection{\cxoneflow Inheritance of \texttt{filter} Settings}
 
-The configuration scopes are implemented in CheckmarxOne as overrides for all
+The configuration scopes are implemented in Checkmarx One as overrides for all
 configuration elements.  This is ideal for most elements, but not ideal for elements
 such as \texttt{filter} that defines the file/folder filters in each engine.  \cxoneflow
 interprets \texttt{filter} settings in each scan engine so that they are inherited

manual/operation/quickstart.tex

@@ -21,13 +21,12 @@ \section{Step 2: Execute the \cxoneflow Container}
 
 The published \cxoneflow container can be executed with the proper runtime configuration.  Please refer
 to Section \ref{sec:runtime-config} for instructions about starting the \cxoneflow container instance with
-the proper runtime configuration.
+the proper runtime configuration. Section \ref{sec:deployment} has additional deployment information that
+may be useful in choosing how and where to host the \cxoneflow instance.
 
 
 \section{Step 3: Configure SCM Webhooks}
 
-Please refer to the chapter in Part \ref{part:scms} regarding your SCM's webhook configuration.
+Please refer to the chapter for your SCM platform in Part \ref{part:scms} for details about webhook configuration.
 
-\section{Step 4: Deploy}
 
-Please see Section \ref{sec:deployment} for deployment instructions.

manual/operation/yaml_full_example.tex

@@ -1,6 +1,5 @@
-This example shows a \cxoneflow configuration using all default options defined
-as a handler when using a single SCM.  This is the same as one of the simple examples if
-an example had explicitly defined omitted default connection elements.
+This example shows a \cxoneflow configuration explicitly setting default options in a service 
+configuration for a single SCM.  The minimal examples leave several of these options as default.
 
 The \texttt{scan-config} element has been added to this configuration to
 demonstrate some of the controls that can be implemented over scan options.  In this
@@ -11,6 +10,10 @@
 and described by
 \href{https://checkmarx.com/resource/documents/en/34965-68598-global-settings.html#UUID-8e38f06b-45d4-ea7f-5ff5-50deb22e43aa_UUID-1a4211ec-dbf9-a180-cb20-59e1246ec3fb}{Scanners Settings}.
 
+While there are options to apply scan configurations via \texttt{scan-config} elements, it is often the case that defining the scan configuration
+in \cxoneflow will have undesirable results.  When defined in the \cxoneflow configuration, the configuration will explicitly override Checkmarx One
+tenant and project level default scan configurations.  Details about utilizing the Checkmarx One configuration options for best results with \cxoneflow
+can be found in Section \ref{sec:deployment-scan-defaults}.
 
 \begin{code}{Full YAML Configuration Example}{[CxOne: oauth]}{[SCM: token auth]}
 secret-root-path: /run/secrets
@@ -59,6 +62,7 @@
             https: http://proxy.corp.com:8080
 \end{code}
 
+
 \pagebreak
 \noindent\\The next example shows a configuration where \cxoneflow has endpoint handlers for both
 BitBucket Data Center and Azure DevOps Enterprise.  Each SCM is configured to handle multiple distinct