Expand web, api, and submission docs

NicolasFR · Dec 1, 2021 · 7f1176f · 7f1176f
1 parent db2ccb3
commit 7f1176f
Show file tree

Hide file tree

Showing 5 changed files with 346 additions and 7 deletions.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -35,7 +35,9 @@ nav:
 
 
 - 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 
diff --git a/docs/src/usage/commands.md b/docs/src/usage/commands.md
@@ -1,6 +1,6 @@
 # Cuckoo commands and tools
 
-This page lists all available tools and commands.
+This page lists available tools and commands.
 
 #### cuckoo
 
@@ -41,7 +41,7 @@ The main Cuckoo command. Used to:
 
 #### cuckoonode
 
-The Cuckoo node command is used to start a Cuckoo task running node.
+The Cuckoo node command is used to start a Cuckoo task running node. Only used if running Cuckoo in distributed mode.
 
 ##### Help
 
@@ -65,7 +65,8 @@ The Cuckoo node command is used to start a Cuckoo task running node.
 #### cuckoosafelist
 
 This command/tool is used to manage Cuckoo safelists. The safelists are used
-in modules such as network processing.
+in modules such as network processing. 
+A restart of Cuckoo is usually needed after adding entries.
 
 ##### Help
 

diff --git a/docs/src/usage/submission/index.md b/docs/src/usage/submission/index.md
@@ -0,0 +1,123 @@
+# Submitting files/URLs
+
+Submitting files/urls can be done in multiple ways: over command line, the web API, or the web UI.
+
+This page will mostly be focusing on how command line submissions work. 
+See the [web API page](../webapi/endpoints.md) for API submission help.
+
+#### File identification
+
+After submission, Cuckoo tries to automatically determine the type of file that was submitted. It uses this information for multiple purposes:
+
+- To automatically choose a platform to run the sample on. (if no platform(s) are specified).
+- To determine if it can run the sample at all.
+- To determine how it should start the sample.
+
+File identification can be tricky, and some files can be identified incorrectly. This mostly happens with script/text files.
+This can result in failed tasks. You can tell Cuckoo to use the original file extension by using the `--orig-filename` flag or 'Use original filename' checkbox in the web UI.
+
+#### Cuckoo analysis
+
+An analysis in Cuckoo is created when a submission is made. It consists of one or more tasks, analysis settings, and per-task settings.
+
+#### Cuckoo task
+
+A task is part of an analysis. Cuckoo supports selecting multiple platforms for each analysis.
+An example of this is choosing both Windows 10 and 7. Or two Windows 10 platforms with a different network route.
+Each selected platform will result in a created task.
+
+#### A platform
+
+By platform we mean an OS name, OS version, and settings for this platform. Most settings are on analysis level. Some can be changed on a platform level.
+Platform level settings override the settings on an analysis level.
+Examples of the platform level settings are:
+
+- `command`
+  A command used to start the submitted sample. If none is specified, Cuckoo determines one automatically. An example of when to use this is when you want to run a specific function from a DLL.
+- `route`
+  A network route. Drop, A VPN, or 'dirty line'/internet routing. See [network routing](../../installation/routing.md#using-cuckoo-rooter) for more information.
+- `browser`
+  The browser to open a URL in. Browsers are discovered by search for machines with a `browser_browsername` tag.
+
+#### Command line submission
+
+Command line submissions are created using the `cuckoo submit` command.
+
+The tools help message is:
+
+```bash
+Usage: cuckoo submit [OPTIONS] [TARGET]...
+
+  Create a new file/url analysis. Use index,value of the used --platform
+  parameter to specify a platform specific setting. No index given means the
+  setting is the default for all platforms.
+
+  E.G: --platform windows --browser 0,browsername
+
+Options:
+  -u, --url            Submit URL(s) instead of files.
+  --platform TEXT      The platform and optionally the OS version the analysis
+                       task must run on. Specified as platform,osversion or
+                       just platform. Use <index of param>,value to specific
+                       browser, command, and route settings.
+  --timeout INTEGER    Analysis timeout in seconds.
+  --priority INTEGER   The priority of this analysis. A higher number means a
+                       higher priority.
+  --orig-filename      Ignore auto detected file extension and use the
+                       original file extension.
+  --browser TEXT       The browser to use for a URL analysis. (Supports per
+                       platform configuration).
+  --command TEXT       The command/args that should be used to start the
+                       target. Enclose in quotes. Use %PAYLOAD% where the
+                       target should be in the command. (Supports per platform
+                       configuration)
+  --route-type TEXT    The route type to use. (Supports per platform
+                       configuration)
+  --route-option TEXT  Option for given route. Key=value format. (Supports per
+                       platform configuration)
+  --option TEXT        Option for the analysis. Key=value format.
+  --help               Show this message and exit.
+
+```
+
+##### Submitting a file, simple
+
+The following command will create an analysis and automatically choose a platform to run it on.
+
+```bash  
+$ cuckoo submit /tmp/file.exe
+Submitted file: 20210501-GN3EIA -> /tmp/file.exe
+```
+
+##### Submitting a file, multi platform
+
+The following command creates an analysis for multiple platforms. In the example we want to run a DLL twice, on the same OS, but run a different function.
+Each platform setting must have an index number that indicates to what `--platform` argument it applies.
+
+```bash
+cuckoo submit --platform windows,10 --platform windows,10 --command "0,rundll32.exe %PAYLOAD%,func1" --command "1,rundll32.exe %PAYLOAD%,func2" /tmp/file.dll
+```
+
+The `--command` arguments start with a 0 and 1. These are the indexes that refer to first and second `--platform` arguments.
+
+##### Submitting a file, multiple different routes
+
+A route-type is the type of route, such as: vpn, drop, or internet. The route-option is an option to for a route. 
+An example of this is the country for a vpn.
+
+The following command creates an analysis with two platforms. 
+One Windows 10, and a Windows 7. The first `--route-type` applies at analysis level. 
+The second one on the index 1. This means the VPN route and option apply to the Windows 7 platform.
+
+```bash
+cuckoo submit --platform windows,10 --platform windows,7 --route-type internet --route-type 1,vpn --route-option 1,country=countryname /tmp/file.exe
+```
+
+##### Submitting a URL, multiple browsers.
+
+The following command submits a URL and creates two tasks. One for the Internet Explorer browser, one for Edge.
+This example assumes machines with the `browser_edge` and `browser_internet_explorer` exist.
+
+```bash
+cuckoo submit --url --platform windows,10 --platform windows,10 --browser "0,edge" --browser "1, internet explorer" http://example.com
+```
diff --git a/docs/src/usage/webapi/setup.md b/docs/src/usage/webapi/setup.md
@@ -26,9 +26,9 @@ Options:
   --help              Show this message and exit.
 
 Commands:
-  djangocommand  Arguments for this command are passed to Django.
-  token          List, create, and delete API tokens.
-
+  djangocommand   Arguments for this command are passed to Django.
+  generateconfig  Generate basic configurations for uWSGI and NGINX
+  token           List, create, and delete API tokens.
 ```
 
 
@@ -84,7 +84,7 @@ Output similar to this will appear:
 
 `Created key cb60aa0d689d7f0281a5ae4d661544927273b087 with ID: 1`
 
-This is the key that should be send in an Authentication header when using the API.
+This is the key that should be sent in an Authentication header when using the API.
 The header format must be: `Authentication: token <api key>`.
 
 Example: 
@@ -110,3 +110,81 @@ The API can be started using the `cuckoo api` command. The following starts the
 
 `cuckoo api --host <listen ip> --port <listen port>`
 
+#### Serving the API with uWSGI and NGINX
+
+The `cuckoo api` command will start the Django development server. To actually serve the API in production, it is advisable to use a
+combination of uWSGI (to run the API) and NGINX (to serve the running API). Cuckoo can generate a basic configuration for both of these.
+
+The `uwsgi-plugin-python3` system package or the `uwsgi` Python package must be installed in the virtualenv for this to work.
+
+The generated configs will contain the paths of your Cuckoo install and virtualenv. Do not copy this following example configurations, generate them instead.
+
+**Generating a uWSGI config**
+
+    cuckoo api generateconfig --uwsgi
+
+Example output:
+
+```ini
+; This is a basic uWSGI configuration generated by Cuckoo. It is
+; recommended to review it and change it where needed. This configuration
+; is meant to be used together with the generated NGINX configuration.
+[uwsgi]
+; To run this, the uwsgi-plugin-python3 system package must be installed or
+; it must be run from a Python3 installation that has uwsgi installed.
+plugins = python3,logfile
+chdir = /home/cuckoo/cuckoo3/web/cuckoo/web
+wsgi-file = api/wsgi.py
+; The socket for NGINX to talk to. This should not listen on other
+; addresses than localhost.
+socket = 127.0.0.1:9080
+
+; Verify that the users below are not root users and can read/write to/from 
+; the Cuckoo CWD and installation. The configuration generator simply enters
+; the user generating the configuration.
+uid = cuckoo
+gid = cuckoo
+
+need-app = true
+master = true
+env = CUCKOO_APP=api
+env = CUCKOO_CWD=/home/cuckoo/.cuckoocwd
+env = CUCKOO_LOGLEVEL=debug
+
+; Log uWSGI app and Cuckoo web logs to the following file. Change this to
+; any path, but be sure the uid/gid user has write permissions to this path. 
+logger = file:logfile=/tmp/cuckooapi-uwsgi.log
+
+; The path of the Python 3 virtualenv Cuckoo is installed in.
+virtualenv = /home/cuckoo/cuckoo3venv
+```
+
+**Generating a NGINX config**
+
+    cuckoo api generateconfig --nginx
+
+Example output:
+
+```
+# This is a basic NGINX configuration generated by Cuckoo. It is
+# recommended to review it and change it where needed. This configuration
+# is meant to be used together with the generated uWSGI configuration.
+upstream _uwsgi_cuckoo_api {
+    server 127.0.0.1:9080;
+}
+
+server {
+    listen 127.0.0.1:8090;
+
+    # It is not recommended to cache paths, this can cause results to be
+    # outdated/wrong.
+    location / {
+        client_max_body_size 1G;
+        proxy_redirect off;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        include uwsgi_params;
+        uwsgi_pass _uwsgi_cuckoo_api;
+    }
+}
+
+```