Updated docs (kevoreilly#2249)

* Update CITATION.cff

* Fixing heading level

* Highlighted the python 32-bit limitation. Fixed typo

* Added 'Where to start diagnosing' chapter

* Fixed indentation

CITATION.cff

@@ -8,8 +8,6 @@ authors:
   - given-names: Andriy
     family-names: Brukhovetskyy
 url: "https://github.com/kevoreilly/CAPEv2"
-repository-code: "https://github.com/kevoreilly/CAPEv2"
-url: "https://capev2.readthedocs.io/en/latest/#"
 version: 2
 abstract: >
   CAPEv2: Malware Configuration And Payload Extraction is a
@@ -20,4 +18,4 @@ keywords:
   - cape
   - capev2
   - analysis
-license: GPL-3.0
+license: GPL-3.0

docs/book/src/installation/guest/agent.rst

@@ -18,19 +18,19 @@ spawned, with a title similar to ``C:\Windows\py.exe``. If you want to hide this
 *agent.py* to **agent.pyw** which will prevent the window from
 spawning upon launching the script. 
 
-   .. warning::
-      It is **encouraged** to use the agent in its window-less version (``.pyw`` extension) 
-      given that opening a ``cmd`` window will definitely interfere with `human.py <https://github.com/kevoreilly/CAPEv2/blob/master/analyzer/windows/modules/auxiliary/human.py>`_, causing 
-      several problems like blocking the `agent.py <https://github.com/kevoreilly/CAPEv2/blob/master/agent/agent.py>`_. communication with the host or 
-      producing no **behavioral analysis** output, just to mention some.
+.. warning::
+   It is **encouraged** to use the agent in its window-less version (``.pyw`` extension) 
+   given that opening a ``cmd`` window will definitely interfere with `human.py <https://github.com/kevoreilly/CAPEv2/blob/master/analyzer/windows/modules/auxiliary/human.py>`_, causing 
+   several problems like blocking the `agent.py <https://github.com/kevoreilly/CAPEv2/blob/master/agent/agent.py>`_. communication with the host or 
+   producing no **behavioral analysis** output, just to mention some.
 
 Don't forget to test the agent before saving the snapshot. You can do it both navigating to ``VM_IP:8000`` with a browser from your Host or be executing: ``curl VM_IP:8000``. You should see an output similar to the following:
 
-   .. image:: ../../_images/screenshots/running_agentpy_within_guest_0.png
-        :align: center
+.. image:: ../../_images/screenshots/running_agentpy_within_guest_0.png
+     :align: center
 
-   .. image:: ../../_images/screenshots/running_agentpy_within_guest_1.png
-        :align: center
+.. image:: ../../_images/screenshots/running_agentpy_within_guest_1.png
+     :align: center
 
 
 Prior To Windows 10

docs/book/src/installation/guest/network.rst

@@ -22,24 +22,24 @@ Windows 10
 ==========
 To do so in Windows 10, open Control Panel and search for ``Windows Defender Firewall``. Disable it completely:
 
-    .. image:: ../../_images/screenshots/guest_win10_disable_firewall.png
-        :align: center
+.. image:: ../../_images/screenshots/guest_win10_disable_firewall.png
+    :align: center
 
-    .. image:: ../../_images/screenshots/guest_win10_disable_firewall_1.png
-        :align: center
+.. image:: ../../_images/screenshots/guest_win10_disable_firewall_1.png
+    :align: center
 
 The next step is disabling automatic updates. To do so, open Control Panel and search for ``Administrative Tools``. Open it, then open ``Services``. Look for the ``Windows Update`` entry and double-click on it. Set Startup type to disabled and click stop.
 
-    .. image:: ../../_images/screenshots/guest_win10_disable_updates.png
-            :align: center
+.. image:: ../../_images/screenshots/guest_win10_disable_updates.png
+        :align: center
 
 Windows XP
 ==========
 
 You can do so from Windows' Control Panel as shown in the picture:
 
-    .. image:: ../../_images/screenshots/windows_security.png
-        :align: center
+.. image:: ../../_images/screenshots/windows_security.png
+    :align: center
 
 Virtual Networking
 ==================
@@ -81,18 +81,18 @@ The recommended setup is using an isolated network for your VM. In order to do s
 
 First, in the Virtual Machine Manager GUI click con **Edit** -> **Connection Details**.
 
-    .. image:: ../../_images/screenshots/creating_isolated_network_0.png
-            :align: center
+.. image:: ../../_images/screenshots/creating_isolated_network_0.png
+        :align: center
 
 In the opened window click on the **+** sign, at the bottom left corner of the image. We are now defining the details of the new network. Give it a name (hostonly, for example) and make sure you select **Isolated** mode. Then, click on the **IPv$ configuration** drop-down menu and define the range of your network. In the image below only the third octet is changed.
 
-    .. image:: ../../_images/screenshots/creating_isolated_network_1.png
-            :align: center
+.. image:: ../../_images/screenshots/creating_isolated_network_1.png
+        :align: center
 
 Once the new isolated network is created, if you already created a VM, you can select it from Virtual Machine Manager by clicking ``Show virtual hardware details`` of that specific VM. Then click on the network adapter and choose the recently created network. Then click ``Apply``.
 
-    .. image:: ../../_images/screenshots/creating_isolated_network_2.png
-            :align: center
+.. image:: ../../_images/screenshots/creating_isolated_network_2.png
+        :align: center
 
 The next thing is checking the new interface was indeed created and the VM is actually using it. From your Host, execute the following command from a command prompt::
 
@@ -128,28 +128,30 @@ To set up a static IP it is first recommended to inspect the assigned IP, which
 
 > ipconfig /all
 
-    .. image:: ../../_images/screenshots/guest_win10_static_IP.png
-            :align: center
+.. image:: ../../_images/screenshots/guest_win10_static_IP.png
+        :align: center
 
-    .. note:: The IP addresses and ranges used throughout this chapter are just examples. Please make sure you use your own working configurations and addresses.
+.. note:: 
+    The IP addresses and ranges used throughout this chapter are just examples. Please make sure you use your own working configurations and addresses.
 
 Open ``Control Panel`` and search for ``Network``. Find and open the ``Network and Sharing Center``. Click ``Change adapter settings.``
 
-    .. image:: ../../_images/screenshots/guest_win10_static_IP_1.png
-            :align: center
+.. image:: ../../_images/screenshots/guest_win10_static_IP_1.png
+        :align: center
 
 Now open the Ethernet adapter and click ``Properties``.
 
-    .. image:: ../../_images/screenshots/guest_win10_static_IP_2.png
-            :align: center
+.. image:: ../../_images/screenshots/guest_win10_static_IP_2.png
+        :align: center
 
 Then click ``Internet Protocol Version 4 (TCP/IPv4)`` and ``Properties``. Set the IP address, Subnet mask, Default gateway and DNS Server according to the results of the ipconfig command.
 
-    .. image:: ../../_images/screenshots/guest_win10_static_IP_3.png
-            :align: center
+.. image:: ../../_images/screenshots/guest_win10_static_IP_3.png
+        :align: center
 
 
-    .. note:: You can set as static IP address the address previously given by DHCP or any other address you like within the range of your interface.
+.. note:: 
+    You can set as static IP address the address previously given by DHCP or any other address you like within the range of your interface.
 
 Wait a few seconds and you should have Internet access (in case you are using NAT. Bear in mind an isolated network will not provide Internet connection).
 
@@ -158,12 +160,12 @@ It is important to check connectivity between the Host and the Guest, like in th
 This stage is very much up to your requirements and the
 characteristics of your virtualization software.
 
-    .. warning:: Virtual networking errors!
-        Virtual networking is a vital component for CAPE. You must be
-        sure that connectivity works between the host and the guests.
-        Most of the issues reported by users are related to an incorrect networking setup.
-        If you aren't sure about your networking, check your virtualization software
-        documentation and test connectivity with ``ping`` and ``telnet``.
+.. warning:: Virtual networking errors!
+    Virtual networking is a vital component for CAPE. You must be
+    sure that connectivity works between the host and the guests.
+    Most of the issues reported by users are related to an incorrect networking setup.
+    If you aren't sure about your networking, check your virtualization software
+    documentation and test connectivity with ``ping`` and ``telnet``.
 
 
 Disable Noisy Network Services

docs/book/src/installation/guest/requirements.rst

@@ -9,28 +9,28 @@ Install Python
 ==============
 
 Python is a strict requirement for the CAPE guest component (*analyzer*) to run properly.
-    .. note::
+.. warning::
 
-        Please note that only 32-bit (x86) versions of Python3 are
-        supported at this time for Windows, due to the way the analyzer
-        interacts with low-level Windows libraries. Using a 64-bit version
-        of Python will crash the analyzer in Windows. For other platforms the
-        version of Python can be 64-bit (x64).
+    Please note that **only 32-bit (x86) versions of Python3 are
+    supported** at this time for Windows, due to the way the analyzer
+    interacts with low-level Windows libraries. Using a 64-bit version
+    of Python will crash the analyzer in Windows. For other platforms the
+    version of Python can be 64-bit (x64).
 
 You can download the proper `Windows`_ / `Linux`_ installer from the `official website`_.
 Python versions > 3.6 are preferred.
 
-    .. warning::
-        When installing Python, it is recommended to select the `Add Python <version> to PATH` option. And remove from that PATH `%USERPROFILE%\AppData\Local\Microsoft\WindowsApps`
+.. important::
+    When installing Python, it is recommended to select the `Add Python <version> to PATH` option. And remove from that PATH `%USERPROFILE%\AppData\Local\Microsoft\WindowsApps`
 
-        .. image:: ../../_images/screenshots/python_guest_win10_installation_PATH.png
-            :align: center
+    .. image:: ../../_images/screenshots/python_guest_win10_installation_PATH.png
+        :align: center
 
-        When the installation is done, tt is recommended to test whether Python is correctly set into your PATH environment variable. In order to do so, you can execute the following commands from a command prompt::
+When the installation is done, it is recommended to test whether Python is correctly set into your PATH environment variable. In order to do so, you can execute the following commands from a command prompt::
 
-        > python --version
+> python --version
 
-        You should be prompted with Python's installed version. **If not**, make sure you add the binaries to your PATH. There are tutorials galore on the Internet.
+You should be prompted with Python's installed version. **If not**, make sure you add the binaries to your PATH. There are tutorials galore on the Internet.
 
 Some Python libraries are optional and provide some additional features to the
 CAPE guest component. They include:
@@ -61,18 +61,18 @@ Depending on what kind of files you want to analyze and what kind of sandbox
 environment you want to run the malware samples in, you may want to install
 additional software such as browsers, PDF readers, office suites, etc.
 
-    .. note::
+.. note::
 
-        Remember to disable the "Auto Update" or "Check For Updates" feature of
-        any additional software that you install.
+    Remember to disable the "Auto Update" or "Check For Updates" feature of
+    any additional software that you install.
 
-        For Microsoft Office we recommend Office 2010 SP2. This is both for its
-        susceptibility to exploits typically used in maldocs, and its proven
-        compatibility with CAPE. The only recommended alternative is Office 2016
-        (32-bit).
+    For Microsoft Office we recommend Office 2010 SP2. This is both for its
+    susceptibility to exploits typically used in maldocs, and its proven
+    compatibility with CAPE. The only recommended alternative is Office 2016
+    (32-bit).
 
-        We do not recommend any Office version more recent than 2016 due to lack
-        of proven compatibility with both maldocs and CAPE.
+    We do not recommend any Office version more recent than 2016 due to lack
+    of proven compatibility with both maldocs and CAPE.
 
 For hints about what your needs may be, give the :doc:`../../introduction/sandboxing` chapter a read.
 

docs/book/src/installation/guest/troubleshooting.rst

@@ -2,6 +2,48 @@
 Troubleshooting
 ===============
 
+Where to start diagnosing
+=========================
+
+Given the large number of technologies involved in CAPE installation, configuration and usage, chances are high one or more of them start failing, crashing or simply *dying*. When this happens, there are a few places you should always look first, since it could help you diagnosing the real problem and avoid wasting time looking at rabbit holes. These places are (no surprise here) the logs generated by each fundamental service involved in CAPE's execution. While all of them can be checked in their corresponding directories, `journalctl <https://man7.org/linux/man-pages/man1/journalctl.1.html>`_ can be leveraged to check all of them at once.
+
+.. note::
+    Please note the following errors are just random examples used to show how and where to start dealing with CAPE problems. You may never face this errors at all!
+
+Regardless of the error you are facing there are two places where you should start looking: (1) CAPE's logs (naming inherited from cuckoo) and (2) virtqemu logs (assuming you have :ref:`installed KVM/QEMU using the kvm_qemu.sh script <installation_kvm>`.)
+
+For example, lets consider the following situation:
+
+    **CAPE submission (either via web or <submit.py>) apparently works, but the VM is never spawned (and analysis never launched).**
+
+Without prior indication, the first place to check are CAPE logs, located in ``/opt/CAPEv2/log/`` (installation directory). The logs corresponding to the analyses are rotated daily, and the current log is ``cuckoo.log``. Checking the contents of ``/opt/CAPEv2/log/cuckoo.log`` one could easily spot the culprit:
+
+.. error::
+    *Error example in <cuckoo.log> file.*
+
+    .. image:: ../../_images/screenshots/troubleshooting_error_0.png
+        :align: center
+
+Furthermore, the error states something about ``libvirt``. This is a clear indication that the corresponding logs must also be inspected. In this case, the logs of ``libvirt`` are stored under the ``virtqemud`` service. **Whenever something seems wrong regarding the virtual machines, this is the place to look after**. It can be inspected with ``$ sudo journalctl -u virtqemud -r``:
+
+.. error::
+    *Error examples by inspecting vertqemud logs with journalctl.*
+
+    .. image:: ../../_images/screenshots/troubleshooting_error_1.png
+        :align: center  
+
+    .. image:: ../../_images/screenshots/troubleshooting_error_2.png
+        :align: center
+
+Additionally, you should always try to see if you are able to manually replicate the error in order to discard technologies and find out which one is failing. Considering the scenario above, when trying to manually spawn the virtual machines:
+
+.. error::
+    *Error example in Virtual Manager - KVM.*
+
+    .. image:: ../../_images/screenshots/troubleshooting_error_3.png
+        :align: center  
+
+
 No Internet connection in the guest
 ===================================
 There are reasons galore why your guest VM has no Internet connection when an analysis is fired up. Before digging into this problem, please make sure you followed the steps at :ref:`Network Configuration` to set up both the virtual machine and its connections. Furthermore, you should read the :ref:`routing` chapter in order to know and understand the different routing modes as well as the :ref:`rooter` chapter to understand what the ``Rooter`` is. 

docs/book/src/installation/host/installation.rst

@@ -119,7 +119,6 @@ Optional dependencies
    sudo -u cape poetry run pip install -r extra/optional_dependencies.txt
 
 
-============================
 **ATTENTION!** ``cape`` user
 ============================