%!TEX encoding = IsoLatin
%!TEX main = honeypot_and_generative_ai.tex

This manual is a comprehensive guide for end users, detailing system requirements, installation instructions, and a usage guide for SYNAPSE. It aims to help users effectively set up and operate the honeypot system, offering troubleshooting guidance and additional information to explore SYNAPSE's capabilities further.

\section*{System Requirements}

\textbf{Operating System}:
\begin{itemize}
    \item Linux OS: Ubuntu\footnote{\url{https://www.ubuntu-it.org/}} (tested on version 22.04 LTS).
\end{itemize}
\textbf{Software Dependencies}:
\begin{itemize}
    \item Python\footnote{\url{https://www.python.org/}}: version 3.8 or higher.
    \item Git\footnote{\url{https://git-scm.com/}}: required for cloning the project repository.
    \item Pip\footnote{\url{https://pypi.org/project/pip/}}: required for installing Python dependencies (version 20.0 or higher).
\end{itemize}
\textbf{API Keys}:
\begin{itemize}
    \item OpenAI API Key\footnote{\url{https://openai.com/index/openai-api/}}: required for integrating the ``gpt-4o'' model.
    \item VirusTotal API Key\footnote{\url{https://www.virustotal.com/gui/my-apikey}}: required for checking IP and domain reputations.
\end{itemize}
\textbf{Cloud Platform (Optional)}:
\begin{itemize}
    \item SYNAPSE can be hosted on cloud platforms, such as Oracle OCI\footnote{\url{https://www.oracle.com/it/cloud/}}, to ensure scalability and ease of remote access. Follow the cloud provider's guidelines for setting up a virtual machine (VM) with Ubuntu.
\end{itemize}

\section*{Installation Instructions}

\subsection*{1. Clone the Repository}

To download the SYNAPSE project, open a terminal and clone the GitHub repository:
\begin{verbatim}
    git clone https://github.com/eneagizzarelli/SYNAPSE.git
\end{verbatim}

\subsection*{2. Install Python Dependencies}

Navigate to the project directory and install the required Python packages using \texttt{pip}:
\begin{verbatim}
    cd SYNAPSE/
    pip install -r requirements.txt
\end{verbatim}

\subsection*{3. Setup API Keys}

Create a \texttt{.env} file in the parent directory of the project and add your API keys for OpenAI and VirusTotal in the following format:
\begin{verbatim}
    OPENAI_API_KEY=`YOUR KEY'
    VIRUSTOTAL_API_KEY=`YOUR KEY'
\end{verbatim}

\noindent
\textbf{Note 1}: in the original configuration, the \texttt{SYNAPSE} project folder has been cloned under the specific path \texttt{/home/enea/SYNAPSE}. Every script/source file in this project refers to other scripts/source files using the above absolute path as a base path. If you plan to use an alternative configuration (such as a different location or user), remember to change the paths and replace \texttt{enea} everywhere in the code.

\subsection*{4. Run the Configuration Script}

Copy the \texttt{configSYNAPSE.sh} script from the \texttt{scripts/} folder outside the \texttt{SYNAPSE} directory. After assigning the necessary permissions, run the script:
\begin{verbatim}
    chmod +x configSYNAPSE.sh
    ./configSYNAPSE.sh
\end{verbatim}
This will complete the configuration of SYNAPSE, creating the necessary folders, downloading the GeoLite2 database, and assigning ownership and permissions to the user \texttt{enea} (or the user you have specified).

\subsection*{5. Configure the SSH Server}

Modify your \texttt{/etc/ssh/sshd\_config} file to run the \texttt{startSYNAPSE.sh} script (after assigning the necessary permissions) and turn off certain SSH parameters not handled by the SYNAPSE code. These modifications should apply whenever the user \texttt{enea} (or the user you have specified) connects to your machine using SSH:
\begin{verbatim}
    Match User enea
       ForceCommand /home/enea/SYNAPSE/scripts/startSYNAPSE.sh
       X11Forwarding no
       AllowTcpForwarding no
       AllowAgentForwarding no
       PermitTunnel no
       PermitOpen none
\end{verbatim}

\noindent
\textbf{Note 2}: if you are hosting the code on a VM like Oracle OCI and you want to allow password authentication, remember to modify your \texttt{/etc/ssh/sshd\_config.d/60-cloudimg-settings.conf} file by setting:
\begin{verbatim}
    PasswordAuthentication yes
\end{verbatim}
After making these changes, restart the SSH service:
\begin{verbatim}
    sudo systemctl restart sshd
\end{verbatim}

\section*{Usage Guide}

Adopting the configuration mentioned above will run SYNAPSE's simulated terminal instead of the real one whenever user \texttt{enea} (or the user you specifically decided) connects to your SSH server.

\subsection*{1. SYNAPSE-to-MITRE}

To start the SYNAPSE-to-MITRE extension, assign the necessary permissions to the corresponding script in the \texttt{scripts/} folder and run it:
\begin{verbatim}
    chmod +x startSYNAPSE-to-MITRE.sh
    ./startSYNAPSE-to-MITRE.sh
\end{verbatim}
    If the AI detects an attack based on the session data, this script will convert the classification files into attack files containing the corresponding MITRE ATT\&CK object content.

\subsection*{2. Dataset Build}

To re-build the dataset used to train the SYNAPSE-to-MITRE model:
\begin{enumerate}
    \item Replace the \texttt{capec} or \texttt{enterprise-attack} databases in the \texttt{SYNAPSE-to-MITRE/data} folder with your preferred versions.
    \item Ensure the file and folder names remain unchanged.
    \item Build the dataset by executing:
\begin{verbatim}
    chmod +x startDatasetBuild.sh
    ./startDatasetBuild.sh
\end{verbatim}
\end{enumerate}

\subsection*{3. Model Training}

To re-train the model with the newly created dataset:
\begin{verbatim}
    chmod +x startModelTraining.sh
    ./startModelTraining.sh
\end{verbatim}

\subsection*{4. AI vs AI}

To run the AI vs AI interactions, move to the \texttt{use\_cases} folder and run the preferred script:
\begin{verbatim}
    python3 AI_vs_SYNAPSE_basic_interaction.py
\end{verbatim}
or
\begin{verbatim}
    python3 AI_vs_SYNAPSE_attacker_interaction.py
\end{verbatim}
The second script's number of attacks can be modified by changing variable \texttt{attacks\_num} in the code.

\subsection*{5. System Log Analysis}

To perform a system log analysis of Linux OS logs using AI:
\begin{verbatim}
    chmod +x startSystemLogsAnalysis.sh
    ./startSystemLogsAnalysis.sh
\end{verbatim}
    This script analyzes \texttt{auth.log}, \texttt{kern.log}, and \texttt{syslog} files using generative AI and provides a report summarizing system events.

\section*{Troubleshooting}

If you experience an error like 
\begin{verbatim}
    Resource X not found
\end{verbatim}
and, further on, 
\begin{verbatim}
    >>> nltk.download(`X')
\end{verbatim}
when using SYNAPSE-to-MITRE, please try the following command:
\begin{verbatim}
    python3 -m nltk.downloader X
\end{verbatim}
This issue generally occurs for resources such as \texttt{punkt} and \texttt{wordnet}.

\section*{Related Resources}

To consult the DENDRITE manual, please refer to the following link: 
\url{https://github.com/eneagizzarelli/DENDRITE}