Flask Web API for Tenjint Project
Tenjint is a Python 3 based platform for virtual machine introspection (VMI) on x86 and ARM. It allows developers to write third-party plugins.
To know more about Tenjint visit https://github.com/bedrocksystems/tenjint
The Tenjint Flask API project provides a web API where the user can submit Malware samples to analyze inside VM in tenjint space and query for output of the tenjint run. The web API allows to scale up Malware Analysis Infrastructure. Set up the Tenjint Flask Project on a server and several users can submit the sample files and retrieve the output.
For openAPI based Specification and Design Architecture visit docs
sudo apt-get install -y mongodb-org
systemctl start mongod
Ensure Libvirt is installed
Start the Libvirtd service.
service libvirtd start
Clone this repository.
git clone https://github.com/amanjiofficial/tenjint-flask.git
Create a virtualenv and activate.
python3 -m venv env
source env/bin/activate
Install requirement packages.
pip install -r requirements.txt
Install Tenjint and Rekall from Tenjint Repository within virtualenv.
Ensure modified QEMU/KVM is installed from tenjint-qemu
Ensure modified linux kernel is installed from tenjint-linux
Start the Flask application on your terminal window.
python app.py
Application is started at http://localhost:5000/
virsh pool-create-as --name $DISK-POOL-NAME --type dir --target $PATH
virt-install --virt-type=kvm --name=$VM_NAME --ram 2048 --vcpus=2 --virt-type=kvm --hvm --cdrom $ISO_FILE_PATH --network network=default --disk pool=$DISK_POOL_NAME,size=20,bus=virtio,format=qcow2 --filesystem $SOURCE,$TARGET
virsh shutdown $VM_NAME
virsh dumpxml $VM_NAME | grep "<source file"
qemu-img create -f qcow2 -F qcow2 -b $VM_NAME.qcow2 $VM_NAME_CLONE.qcow2
VM_folder_name
in configuration fileGenerate the XML of VM created in the previous step and save to another file.
virsh dumpxml $VM_NAME > $VM_XML.xml
Undefine the VM.
virsh undefine $VM_NAME
Edit $VM_NAME.xml file to include filesystem
block within devices
block.
<filesystem type='mount' accessmode='passthrough'>
<source dir='/home'/>
<target dir='temp'/>
</filesystem>
Edit $VM_NAME.xml and update source
under disk
block in devices
section with the path of $VM_NAME_CLONE.qcow2
Deploy a new guest OS as a linked clone using $VM_NAME.xml.
virsh create $VM_NAME.xml
Take a memory snapshot.
virsh snapshot-create-as --domain $VM_NAME $SNAPSHOT_NAME --memspec snapshot=internal
Shutdown the VM.
virsh shutdown $VM_NAME
Add the path to disk snapshot, name of disk snapshot and name of memory snapshot to configuration file
disk-snap
: disk snapshot qcow2 file path($VM_NAME_CLONE)snapshot
: memory snapshot($SNAPSHOT)disk-snap-name
: disk snapshot name($VM_NAME_CLONE)The following tables lists the parameters that can be configured and their default values. Configuration is available in configuration file
Parameter | Description | Default |
---|---|---|
api_host |
Host URL for Flask server | 127.0.0.1 |
api_port |
Host Port for Flask server | 5000 |
api_debug_mode |
Boolean to set debug mode for Flask server | True |
api_admin_token |
Token for Admin account authentication | foo |
api_database |
Mongo DB Database URL | mongodb://127.0.0.1:27017 |
api_database_name |
MongoDB database name to be used | tenjint |
max_vm_count |
Maximum number of VMs that can be run at a particular time | 1 |
max_tenjint_run_time |
Maximum allowed duration to run Malware sample in Tenjint | 3600000 |
min_tenjint_run_time |
Minimum allowed duration to run Malware sample in Tenjint | 100000 |
emulator_path |
Path of QEMU Emulator for Tenjint | /home/dell/Documents/opensource/tenjint/qemu/x86_64-softmmu/qemu-system-x86_64 |
tenjint_config_path |
Tenjint Configuration Path | /home/dell/Downloads/tenjint_config.yml |
VM_folder_name |
Folder path to store VMs for Tenjint | /home/dell/Documents/opensource/tenjint/VM_Folder/ |
plugin_dir |
Folder path for Tenjint plugins. It contains necessary plugins to run this Flask Server. | /home/dell/Documents/opensource/tenjint/tenjint-flask/plugins/ |
samples_store |
Folder path to store Malware samples. | /home/dell/Documents/opensource/tenjint/tenjint-flask/shared_samples |
VM |
List of available VMs. | Each VM constitutes disk-snap : disk snapshot qcow2 path , snapshot : memory snapshot and disk-snap-name : disk snapshot name |
api_admin_token
in configuration filewhen creating a new user, a token is provided as a response of the query. This token is to be used by users to authenticate for submitting Malware Samples.
API request example
curl -X POST \
'http://127.0.0.1:5000/submit?runTime=200000&guestImage=ubuntu-18-x86_64&api_key=5c76f51a419eb213813025ece8bb7ab1' \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F sample=@comment-15.txt
Visit openAPI specification to know more about each parameter.
Upcoming Features
Aman Ahuja - amanjiofficial@gmail.com
This project started as a part of Google Summer Of Code 2020 under the mentors Jonas Pfoh and Sebastian Vogl. To know more visit Project Description