From 1420a8b3236010a423416a40f4f934eef404d792 Mon Sep 17 00:00:00 2001 From: cert-ee-raidar Date: Fri, 20 Sep 2024 10:03:08 +0300 Subject: [PATCH 1/2] chore: Changed default configuration values to match new Quickstart and documentation --- core/cuckoo/config.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/cuckoo/config.py b/core/cuckoo/config.py index 14335b14..d66f22b0 100644 --- a/core/cuckoo/config.py +++ b/core/cuckoo/config.py @@ -34,13 +34,13 @@ def constraints(self, value): "cuckoo.yaml": { "machineries": config.List(Machinery, value=["qemu"]), "resultserver": { - "listen_ip": config.String(default_val="192.168.30.101"), + "listen_ip": config.String(default_val="192.168.30.1"), "listen_port": config.Int(default_val=2042, min_value=1024) }, "tcpdump": { "enabled": config.Boolean(default_val=True), "path": config.FilePath( - default_val="/usr/sbin/tcpdump", must_exist=True + default_val="/usr/bin/tcpdump", must_exist=True ) }, "network_routing": { From ec9ac3fbf8b55184449c33b6ad18c13cce295cf7 Mon Sep 17 00:00:00 2001 From: cert-ee-raidar Date: Fri, 20 Sep 2024 10:06:02 +0300 Subject: [PATCH 2/2] docs: Quickstart - Updated README with new Quickstart section - Added QUICKSTART.md as walkthrough - Fixed spelling mistakes --- INSTALL/QUICKSTART.md | 167 ++++++++++++++++++++++++++++++++++++++++++ README.md | 36 ++++++--- 2 files changed, 192 insertions(+), 11 deletions(-) create mode 100644 INSTALL/QUICKSTART.md diff --git a/INSTALL/QUICKSTART.md b/INSTALL/QUICKSTART.md new file mode 100644 index 00000000..60ab2564 --- /dev/null +++ b/INSTALL/QUICKSTART.md @@ -0,0 +1,167 @@ +# Quickstart installation + +Cuckoo comes with an automation shell script that installs Cuckoo, VMCloak, and related dependencies with predefined configuration — the Quickstart. + +This configuration has been tested and is known to work for general use or experimentation for regular users. For more fine-tuned installation, please refer to [Installing Cuckoo3](https://cuckoo-hatch.cert.ee/static/docs/installation/cuckoo). + +This is a semi-guided installation and will ask for user name and password for Cuckoo installation (Cuckoo will be run as non-root-user) and Python-related prompts if the current Python version does not meet the requirements. + +## Quickstart will install: +- System dependencies + +- Cuckoo will be installed with a custom configuration +- VMCloak will be installed for VM and snapshot creation +- Qemu will be installed for VMCloak to use +- Windows 10 will be downloaded for sandboxing +- Standard Nginx configuration will be created for hosting Cuckoo web. + +## Installation + +For the Quickstart setup, run: +```console +curl -sSf https://cuckoo-hatch.cert.ee/static/install/quickstart | sudo bash +``` + +--- + +## Script structure + +### Flight checks +The install script does a few checks to make sure that it is run with the correct user at different steps and that Python requirements are met. + +1. It checks if the script is run with sudo privileges. Some setup parts like installing system dependencies, creating Cuckoo users, and installing Python-related dependencies or repositories. +2. Checks if you are running the supported Ubuntu 22.04 release. + +### Interactive part + +#### User creation + +If `y` is selected, then: + +- The script creates a new non-privileged user to run Cuckoo. +- It asks for a username and password to create it. + + !!! note "Remember!" + Please don't forget the credentials. You need them later to use Cuckoo. + +If `n` is selected, then: + +- The script asks for the username and password for the previously created user. +**NOTE!** Make sure the user does not have sudo privileges. + +#### VM creation + +If `y` is selected, then: + +- This script will download the Windows 10 image form cert-ee. +- Install software on it. +- Make snapshots. + +### Templates +The script uses "templates", which are basically helper functions, to initiate commands under the created Cuckoo user. + +- **install_vmcloak_with** - installs VMCloak for VM creation in Cuckoo users home directory. It also creates VMCloak-specific .vmcloak directory in users home for vm creation later on. +- **install_cuckoo_with** - installs Cuckoo in Cuckoo users home directory. It also creates .cuckoocwd directory in users home for Cuckoo-related configurations later on. +- **configure_cuckoo_for** - Unpacks monitor and signatures to `cuckoocwd`. It also builds documentation, performs Django's `collectstatic` command, and generates uwsgi and nginx configurations into users cuckoo3 directory. +- **download_images_for** - Downloads Windows 10 image from cert-ee. +- **create_vms_for** - This command creates an iso image for Windows 10 with agent, installs software on it, and creates 3 snapshots. +- **configure_vms_for** - Imports VMs to Cuckoo and deletes the example machine. It also runs database migrations. +- **run_cuckoo_for** - This allows bash to run Cuckoo user specific commands. + +--- + +## Detailed actions with accompanying configuration + +### System dependencies +Quickstart installs the following dependencies for: + +- building Python packages + - build-essential + - software-properties-common +- unpacking monitor and signatuers + - unzip +- hyperscan + - libhyperscan5 + - libhyperscan-dev +- Sflock + - libjpeg8-dev + - zlib1g-dev + - p7zip-full + - rar + - unace-nonfree + - cabextract +- Yara + - yara +- Tcpdump + - tcpdump +- Python dependencies + - libssl-dev libcapstone-dev +- VM creation with VMCloak + - genisoimage + - qemu-system-common + - qemu-utils + - qemu-system-x86 +- serving Cuckoo frontend + -uwsgi + - uwsgi-plugin-python3 + - nginx +- Python3 + - python3.10 + - python3.10-venv + - python3.10-dev - required for python C headers + +### VMCloak +Quickstart will: + +1. clone git repo from `https://github.com/cert-ee/vmcloak.git` and +checkout `main` branch +2. pip installs dependencies +3. create a new network bridge interface named `br0` with +subnet `192.168.30.1/24` +4. create a new conf file in `/etc/qemu/bridge.conf` with content +`allow br0` +5. set setuid bit for `/usr/lib/qemu/qemu-bridge-helper` +6. download Windows 10 image from CERT-EE repository to +`/home/cuckoo/` as `win10x64.iso` +7. create a mount at `/mnt/win10x64` +8. create a Windows 10 image with settings + + |Parameter|Value| + |---|---| + |Disk|128GB| + |CPU|2| + |RAM|4096| + |Subnet|192.168.30.0/24| + |Virtual Machinery|qemu| + |Remote Display (RDP/VNC)|true| + |Remote Display port|1 (offset 5900)| + |Guest IP address|192.168.30.2| + |Mount point|`/mnt/win10x64`| + |VM name|win10base| + |Network adapter|br0| + +9. install default software and configuration to Windows 10 +10. make 3 snapshots with IP address starting from `192.168.30.10` +11. delete default Cuckoo VM qemu profile +11. import created VMs to Cuckoo. + +### User configuration +User will be added to kvm and pcap groups. First is to be able to create VMs with Qemu and second is to use tcpdump +Quickstart will also disable tcpdump apparmor profile. + +### Cuckoo web +For Cuckoo frontend to work, Quickstart needs to change some configuration values: + +1. it will add a new subnet 192.168.68.0/24 to allowed subnets +2. add STATIC_ROOT location +3. make directories for STATIC_ROOT and change ownership to Cuckoo user +4. add user to www-data group +5. remove uwsgi configuration if it exists and deliver a new configuration to `/etc/uwsgi/apps-available/` +6. symlinks uwsgi to `apps-enabled` +7. does the same for nginx +8. changes nginx listen port 8080 +9. restarts `uwsgi` and `nginx` services +10. creates helper script in the home of user who ran the script. It helps bring up network interface and mount iso. `sudo ~/.helper_script.sh`. + +Last step Quickstart takes in run `cuckoo --debug` which runs cuckoo in debug mode + diff --git a/README.md b/README.md index 10a59264..756c48a7 100644 --- a/README.md +++ b/README.md @@ -10,28 +10,42 @@ Cuckoo3 is an open-source tool to test suspicious files or links in a controlled environment. -It will test them in sandboxed platform emulator(s) and generate a report, showing what the files +It will test them in a sandboxed platform emulator(s) and generate a report, showing what the files or websites did during the test. -> ⚠️ You can currently only set up Cuckoo3 on Linux(Ubuntu) -machines and run Windows sandboxes. -Check our [Cuckoo3 requirements](https://cuckoo-hatch.cert.ee/static/docs/introduction/cuckoo/) -for more information +> ⚠️ You can currently only set up Cuckoo3 on Linux(Ubuntu) machines with Python 3.10 and run Windows sandboxes. +Check our [Cuckoo3 requirements](https://cuckoo-hatch.cert.ee/static/docs/introduction/cuckoo/) for more information. You can see it in action at our [online Cuckoo3 Sandbox](https://cuckoo-hatch.cert.ee/). For more insight into our plans, [check out our roadmap here](https://github.com/orgs/cert-ee/projects/1/views/1). ## Quickstart -To be added very soon. +To get started, we have created Quickstart script that installs and sets up everything you need to test out Cuckoo3. + +Run the following command in your terminal and follow on screen prompts. +```bash +curl -sSf https://cuckoo-hatch.cert.ee/static/install/quickstart | sudo bash + +``` + +### A brief overview of Quickstart +Here is a short overview of what it will do: + +- Create a new non sudo Cuckoo user. +- Install Cuckoo3 and VMCloak under that user. +- Download and prepare virtual machines. +- Configure Cuckoo. +- Installs UWSGI and Nginx. +- Serve the frontend using UWSGI and Nginx. + +For the full list of things this script does, check out our [Quickstart walkthrough](INSTALL/QUICKSTART.md). + -For now, run the `install.sh` scripct to install Cuckoo3 and follow -the instructions in documentation at -[Cuckoo installation](https://cuckoo-hatch.cert.ee/static/docs/installation/cuckoo/). ## Next steps -- For more indepth guides and references, please check out our [documentation](https://cuckoo-hatch.cert.ee/static/docs/) +- For more in-depth guides and references, please check out our [documentation](https://cuckoo-hatch.cert.ee/static/docs/). ## IMPORTANT! **This is not a production ready solution just yet. -We highly advise you not to use it production environment!** +We highly advise you not to use it in production environment!**