Merge pull request #164 from cert-ee/docs/documentation_overhaul

Docs/documentation overhaul

docs/mkdocs.yml

@@ -1,46 +1,86 @@
-site_name: Cuckoo 3 docs
+site_name: Cuckoo3 docs
 site_url: https://cuckoo-hatch.cert.ee/static/docs/
 theme:
-  name: readthedocs
-  highlightjs: true
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: cert-ee-light
+      toggle:
+        icon: material/toggle-switch-off-outline
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode
+  logo: assets/images/cuckoo3-docs-round.png
+  favicon: assets/images/favicon.png
+  font: false
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - content.code.copy
+    - search.suggest
+    - search.highlight
+    - search.share
+
+extra_css:
+  - extra.css
+#   - style.css
+
 markdown_extensions:
 - admonition
 - attr_list
+- pymdownx.highlight:
+    anchor_linenums: true
+    line_spans: __span
+    pygments_lang_class: true
+- pymdownx.inlinehilite
+- pymdownx.snippets
+- pymdownx.superfences
+- pymdownx.details
+- toc:
+    permalink: true
 
 plugins:
 - include-markdown
+- search
 
 docs_dir: src
+
 nav:
-- Introduction:
-  - Cuckoo 3: introduction/cuckoo.md
-  - Sandboxing: introduction/sandboxing.md
-
-- Installation:
-  - Cuckoo 3 installation: installation/cuckoo.md
-  - System dependencies: installation/deps.md
-  - Machinery modules: installation/machineries.md
-  - VM Creation: installation/vmcreation.md
-  - Network routing: installation/routing.md
-
-- Configuration:
-  - System settings: configuration/system.md
-  - Cuckoo 3 configuration:
-    - Cuckoo.yaml: configuration/cuckooconfs/cuckooyaml.md
-    - Distributed.yaml: configuration/cuckooconfs/distributedyaml.md
-    - Web configuration:
-      - Web.yaml: configuration/cuckooconfs/webconfs/webyaml.md
-    - Node configuration:
-      - Routing.yaml: configuration/cuckooconfs/nodeconfs/routingyaml.md
-
-
-- Usage:
-  - Submission: usage/submission/index.md
-  - Web API:
-    - Setup: usage/webapi/setup.md
-    - Endpoints: usage/webapi/endpoints.md
-  - Web UI: usage/webui/setup.md
-  - Commands: usage/commands.md
-
-- Development:
-  - Creating new machinery modules: development/creating_machinery.md
+- About:
+  - Cuckoo3: about/cuckoo.md
+  - Sandboxing: about/sandboxing.md
+  - Terminology: about/terminology.md
+
+- Installing:
+  - Overview: installing/overview.md
+  - System dependencies: installing/dependencies.md
+  - Quickstart: installing/quickstart.md
+  - VMCloak: installing/vmcloak.md
+  - Cuckoo3: installing/cuckoo.md
+
+- Configuring:
+  - System dependencies: configuring/system.md
+  - VMCloak: configuring/vmcloak.md
+  - Cuckoo3: configuring/cuckoo.md
+  - Web UI: configuring/web-ui.md
+  - Web API: configuring/web-api.md
+  - Network routing: configuring/routing.md
+
+- Creating:
+  - Virtual machines: creating/vms.md
+  - Machinery modules: creating/machinery.md
+
+- Using:
+  - CLI API: using/cli-api.md
+  - Web API: using/web-api-endpoints.md
+  - Web UI: using/web-ui.md
+  - Commands: using/commands.md
+
+- Troubleshooting:
+  - Common errors: faq/common.md

docs/requirements.txt

@@ -1,2 +1,2 @@
-mkdocs
+mkdocs-material
 mkdocs-include-markdown-plugin

docs/src/about/cuckoo.md

@@ -0,0 +1,22 @@
+# What is Cuckoo3?
+
+Cuckoo3 is an open-source tool to test suspicious files or links in a controlled 
+environment.  
+
+It will test them in [sandboxed](sandboxing.md) platform emulator(s) and generate a report, 
+showing what the files or websites did during the test.
+
+## Cuckoo3 requirements
+
+|Supported|Name|version|
+|---|---|---|
+|Host|Linux||
+|OS|Ubuntu|22.04|
+|Language|Python|3.10|
+
+## Supported sandbox environments
+
+|Operating system|Version|Stager|Monitor|VMCloak option|
+|---|---|---|---|---|
+|Windows 7||Tmstage|Threemon|`--win7x64`|
+|Windows 10|Build 1703|Tmstage|Threemon|`--win10x64`|

docs/src/about/sandboxing.md

@@ -0,0 +1,32 @@
+# Sandboxing
+As defined by Wikipedia, "in computer security, a sandbox is a security mechanism for separating running programs. It is often used to execute untested code or untrusted programs from unverified third parties, suppliers, untrusted users, and untrusted websites.".
+
+This concept applies to malware analysis's sandboxing too: our goal is to run an unknown and untrusted application or file inside an isolated environment and get information on what it does.
+
+Malware sandboxing is a practical application of the dynamical analysis approach: instead of statically analyzing the binary file, it gets executed and monitored in real-time.
+
+This approach obviously has pros and cons, but it's a valuable technique to obtain additional details on the malware, such as its network behavior. Therefore, it's a good practice to perform both static and dynamic analysis while inspecting malware in order to gain a deeper understanding of it.
+
+Simple as it is, Cuckoo is a tool that allows you to perform sandboxed malware analysis.
+
+## Using a Sandbox
+Before starting to install, configure, and use Cuckoo, you should take some time to think about what you want to achieve with it and how.
+
+Some questions you should ask yourself:
+
+What kind of files do I want to analyze?
+What volume of analyses do I want to be able to handle?
+Which platform do I want to use to run my analysis on?
+What kind of information do I want about the file?
+The creation of the isolated environment (for example, a virtual machine) is probably the most critical and important part of a sandbox deployment; it should be done carefully and with proper planning.
+
+Before getting hands on the virtualization product of your choice, you should already have a design plan that defines:
+
+Which software to install and which versions (particularly important when analyzing exploits).
+Consider that automated malware analysis is not deterministic and its success might depend on a trillion factors: you are trying to make malware run in a virtualized system as it would do on a native one, which could be tricky to achieve and may not always succeed. Your goal should be both to create a system able to handle all the requirements you need as well as try to make it as realistic as possible.
+
+For example, you could consider leaving some intentional traces of normal usage, such as browsing history, cookies, documents, images, etc. If malware is designed to operate, manipulate, or steal such files, you'll be able to notice it.
+
+Virtualized operating systems usually carry a lot of traces with them, which makes them very easily detectable. Even if you shouldn't overestimate this problem, you might want to take care of this and try to hide as many virtualization traces as possible. There is a lot of literature on the Internet regarding virtualization detection techniques and countermeasures.
+
+Once you finish designing and preparing the prototype of the system you want, you can proceed with creating it and deploying it. You will always be in time to change things or slightly fix them, but remember that good planning at the beginning always means fewer troubles in the long run.

docs/src/about/terminology.md

@@ -0,0 +1,3 @@
+!!! info "In the works"
+
+    This section is scheduled in the future.