installing.tex

\chapter{Installation}\label{chap:installation}

\newcommand{\configstmt}[2]{
\subsection{Configuration File Path Resolution}\label{plat:#1}
    
The \texttt{cxanalytix.config} and \texttt{cxanalytix.log4net} configuration files are included in the distribution zip by default.  These
files can be left in the same directory as the runtime or deployed to different paths to make upgrades easier to manage.\\

\noindent\\On the #1 platform, the search path is:\\
\begin{enumerate}
    \item The current working directory of the running application.
    \item The path specified by the \texttt{CXANALYTIX\_CONFIG\_PATH} environment variable.
    \item The directory path \texttt{#2}.
\end{enumerate}
}

\newcommand{\clistmt}[2]{
    \subsection{CxAnalytix CLI}
    The CxAnalytix CLI provides a method of invoking a one-time crawl.  It is recommended that any crawling services running in the background
    are stopped before invoking the CLI.

    \noindent\\On the #1 platform, the \texttt{CxAnalytixCLI#2} executable can be run from any path.  The CLI follows the search logic described in section \ref{plat:#1}.
}


\section{Installing on Windows}
\newcommand{\windowsconfigpathbase}{\%PROGRAMDATA\%/cxanalytix}
\newcommand{\windowsconfigpath}{\windowsconfigpathbase/cxanalytix.config}
\configstmt{Windows}{\windowsconfigpath}
\clistmt{Windows}{.exe}

\subsection{CxAnalytix Service}
\begin{enumerate}
    \item Open Powershell or Windows command prompt as administrator.
    \item Execute: \texttt{sc.exe create CxAnalytix binpath="\{install folder path\}/CxAnalytixService.exe"}
    \item Make the directory \texttt{\windowsconfigpathbase}
    \item Move the \texttt{cxanalytix.config} and \texttt{cxanalytix.log4net} \\to \windowsconfigpathbase.
    \item Ensure permissions for the folder \texttt{\windowsconfigpathbase} allow Read/Write access to the service account that is running
    CxAnalytixService.\footnote{Usually this is set to SYSTEM by default and does not need modification.}
\end{enumerate}



\noindent\\The CxAnalytix service and now be started and stopped from the Service Control Manager.


\section{Installing on Linux}
\configstmt{Linux}{/etc/cxanalytix}
\clistmt{Linux}{}

\subsection{CxAnalytix Daemon}
There is not a platform-specific installer for CxAnalytix at the time this documentation was written. The following steps can 
be used to install the CxAnalytix Daemon on a Linux system that uses \verb|systemd|\footnote{Perform the installation steps as the root user.}.


\begin{enumerate}
    \item Configure the system running CxAnalytix to have the same time zone as the SAST Manager if SAST scans will be crawled.
    \footnote{SAST uses localtime for some time fields; this may make some scans to be 
    crawled with a delay equal to the time zone difference between CxAnalytix and the SAST Manager.}

    \item Make directory \texttt{/var/log/cxanalytix}

    \item Execute \texttt{chown root:nobody /var/log/cxanalytix}

    \item Execute \texttt{chmod g+w /var/log/cxanalytix}

    \item Make directory \texttt{/etc/cxanalytix}

    \item Move the \texttt{cxanalytix.config} and \texttt{cxanalytix.log4net} files to \texttt{/etc/cxanalytix}

    \item Execute: \texttt{chown root:nobody /etc/cxanalytix}

    \item Execute \texttt{chmod g+w /etc/cxanalytix}

    \item Make the directory \texttt{/opt/cxanalytix} and copy the installation artifacts there.

    \item Execute: \texttt{chown root:nobody /opt/cxanalytix}

    \item Modify the \texttt{cxanalytix.log4net} file to output logs into \texttt{/var/log/cxanalytix}
    
    \item Copy the file \texttt{cxanalytix.service} to \texttt{/etc/systemd/system/}

    \item Enable automatic startup of the daemon by executing: \texttt{systemctl enable cxanalytix}

    \item \textit{(optional)} Start the daemon by executing: \texttt{systemctl start cxanalytix}

\end{enumerate}

\noindent\\After CxAnalytix is installed, modify the \texttt{cxanalytix.config} and/or \texttt{cxanalytix.log4net} files according to the 
configuration instructions in Chapter \ref{chap:configuration}.

\section{Running CxAnalytix as a Docker Container}

CxAnalytix is published as a docker image in the \href{https://github.com/checkmarx-ts/CxAnalytix/pkgs/container/cxanalytix%2Fcxanalytix}{Checkmarx TS} GitHub 
packages repository. You can reference the image using \verb|ghcr.io/checkmarx-ts/cxanalytix/cxanalytix:<tag>| where \verb|tag| can be:

\begin{itemize}
    \item \verb|latest| to get the latest release
    \item \verb|vx.x.x| to get a specific release version
    \item \verb|vx.x.x-x-prerelease| to get a specific build of a pre-release version
\end{itemize}

\subsection{Configuration with Environment Variables}

Several of the configuration fields support environment variable expansion.  The default configuration file will use the log4net output
module to place the data files in \verb|/var/logs/cxanalytix| table \ref{tab:env} shows the environment variables required for a 
basic CxAnalytix runtime configuration.

\begin{table}
    \centering
    \begin{tabular}{|c|c|l|}
        \toprule
        \textbf{Environment Variable} & \textbf{Default} & \textbf{Description}\\
        \midrule
        \verb|CHECKMARX_URL| & None & The URL to the SAST server.\\
        \midrule
        \verb|CHECKMARX_USERNAME| & None & The username of the account that will log into CxSAST.\\
        \midrule
        \verb|CHECKMARX_PASSWORD| & None & The password for the user account logging into CxSAST.\\
        \midrule
        \verb|CHECKMARX_STATE_PATH| & \verb|/var/cxanalytix| & The path where state files will be stored.\\
        \bottomrule
    \end{tabular}
    \caption{Docker configuration environment variables}
    \label{tab:env}
\end{table}

\noindent\\By default, the state storage path is \verb|/var/cxanalytix|. The state storage files will be lost after the Docker image exits unless a volume is mapped 
to \verb|/var/cxanalytix|. A custom configuration can be used to change the location of the state storage, or a volume can be mapped to 
\verb|/var/cxanalytix| to allow the state storage files to be persisted across container executions.


\subsection{Other Container Configuration Options}

Some of the configuration options in CxAnalytix can be too complex for using environment variables alone.  There are a few different options
that will allow for a user-supplied configuration to be used by the running container.

\subsubsection{Extending the CxAnalytix Docker Image}

The base docker image can be customized using \verb|FROM ghcr.io/checkmarx-ts/cxanalytix/cxanalytix:<tag>| and copying 
the \verb|cxanalytix.log4net| and \verb|cxanalytix.config| files to /etc/cxanalytix. You can refer to the Dockerfile to re-use the \verb|ENTRYPOINT| or 
provide your own entry point.

\noindent\\The state file storage location can be configured in the custom configuration files to write the state files at a location where a 
volume is mapped.  This will allow the state to persist across container executions.


\subsubsection{Volume Mapping}

Volume or host path mounts can be mounted to various locations when running the CxAnalytix Docker image.  Table \ref{tab:mounts} shows
the paths that should be considered for volume mounting.

\begin{table}
    \centering
    \begin{tabular}{|l|l|}
        \toprule
        \textbf{Location} & \textbf{Description}\\
        \midrule
        \verb|/etc/cxanalytix| & \makecell[l]{Place the \texttt{cxanalytix.log4net} and \texttt{cxanalytix.config} configuration files here.
        \\The daemon will run and use these files to configure the runtime.}\\
        \midrule
        \verb|/var/cxanalytix| & This is where the state files are written as scans are crawled.\\
        \midrule
        \verb|/var/logs/cxanalytix| & If configured to output to log files, this is where the log files are written by default.\\
        \bottomrule
    \end{tabular}
    \caption{Container Mount Locations}
    \label{tab:mounts}
\end{table}


\section{Logging Configuration}

Log4Net is used to produce both application logs and logs containing exported JSON key/value pairs when using the Logging Output component. 
CxAnalytix produces logging useful for troubleshooting and/or execution tracking purposes even when not using the Log4Net output method.  The 
\texttt{cxanalytix.log4net} file is generally located in the same directory as the \texttt{cxanalytix.config} file, and will allow for
customizing the logging output location and verbosity.

\section{MongoDB Schema Initialization}\label{sec:mongotool}

Versions of CxAnalytix prior to 2.1.1 initialized the MongoDB collection schema on the first run after the MongoDB output is configured. Prior 
versions would also create several default indexes as part of the collection schema creation. This is no longer the case.

\noindent\\As of CxAnalytix 2.1.1, it is now required to execute \texttt{MongoTool} prior to the first start after initial installtion, 
upgrades or configuration changes that would change the MongoDB collection schema.  Any indexes that were created by CxAnalytix in versions 
prior to version 2.1.1 can be safely dropped if desired.  See Section \ref{sec:bringyourownindex} for information regarding defining indexes
appropriate for your querying needs.

\noindent\\The executable \texttt{MongoTool} command line parameters are described in Table \ref{tab:mongo_tool_opts}.  


\subsection{MongoDB Secure Usage Pattern}

Many applications that use databases deploy the runtime application with a user account that does
not have administrative privileges.  Using a non-administrative user in the configured
\hyperref[sec:mongo_config]{MongoDB connection URL} may be desired to limit the capability
of the CxAnalytix MongoDB user if the credentials are somehow exposed. Using \texttt{MongoTool},
these steps can be followed to configure CxAnalytix to access MongoDB with a minimally privileged
user account:

\begin{enumerate}
    \item Using the \texttt{-u} or \texttt{--url} option, provide the MongoDB connection
    URL to \texttt{MongoTool} that contains the administrative account and password.
    This allows \texttt{MongoTool} to create collections and users with the appropriate roles.

    \item Provide the \texttt{----mongo-user} and \texttt{--mongo-password} options
    to \texttt{MongoTool}.  These are the credentials for a minimally-privileged user
    that will be created as part of the MongoDB schema creation.

    \item Configure the \hyperref[sec:mongo_config]{MongoDB connection URL} with the
    user credentials for the minimally-privileged user created by \texttt{MongoTool}.
\end{enumerate}


\begin{table}
    \centering
    \begin{tabular}{|l|l|l|l|}
        \toprule
        \textbf{Option} & \textbf{Required} & \textbf{Default} & \textbf{Description}\\
        \midrule
        \makecell[cl]{\texttt{-d}\\
        \texttt{---debug}} & No & False & \makecell[cl]{Turns on debug logging.}\\
        \midrule
        \makecell[cl]{\texttt{-u}\\
        \texttt{---url}} & No & N/A & \makecell[cl]{Specify the URL to use for the MongoDB connection. This must\\
        be provided if the \texttt{-c} flag is not provided.  This option and the \\
        \texttt{-c} option can not be used at the same time.}\\
        \midrule
        \makecell[cl]{\texttt{-c}} & No & N/A & \makecell[cl]{Use the existing CxAnalytix configuration to connect to\\
        MongoDB if the \texttt{-u} or \texttt{---url} option is not provided.  This option\\
        can not be used with the \texttt{-u} or \texttt{---url} options.}\\
        \midrule
        \makecell[cl]{\texttt{-l}\\
        \texttt{---login-db}} & No & "admin" & \makecell[cl]{The MongoDB database used for login.}\\
        \midrule
        \makecell[cl]{\texttt{---mongo-user}} & No & null & \makecell[cl]{If provided, the name of the MongoDB user to\\
        create and assign to the CxAnalytix database\\
        with minimal privileges.}\\
        \midrule
        \makecell[cl]{\texttt{---mongo-password}} & No & null & \makecell[cl]{The password to set for the user name defined with\\
        the option \texttt{---mongo-user}.}\\
        \bottomrule
    \end{tabular}
    \caption{MongoTool Command Line Options}
    \label{tab:mongo_tool_opts}
\end{table}



\section{Upgrading}

Configuration elements found in \texttt{cxanalytix.config} are generally backwards compatible for versions
of CxAnalytix with the same major version\footnote{The major version is the first 
number in the version stamp.  e.g. v2.0.0 has a major version of 2.}.  New features may require additions
to the \texttt{cxanalytix.config} file. Please refer to Chapter \ref{chap:configuration} for additional details
about modifying the configuration file.


\noindent\\When configuring CxAnalytix, it is recommended that the configuration, state, and log files are stored
in directories separate from the CxAnalytix binaries.  This will prevent the inadvertent misconfiguration on upgrade.


\noindent\\Note that if installing from the CxAnalytix zip binary that there is a default version of \texttt{cxanalytix.config}
and \texttt{cxanalytix.log4net} in the zip binary.  These default configuration files are provided for first time installers to
use to get CxAnalytix running for the first time.  These files should be removed upon upgrading the CxAnalytix binaries.  If
CxAnalytix fails to start properly after upgrade, the example files may be loaded first according to the rules described in
Chapter \ref{chap:installation}: \textit{Configuration File Path Resolution}.

\noindent\\If your output is MongoDB and the upgrade will change the collection schema, you should run \texttt{MongoTool} as
described in Section \ref{sec:mongotool}