Skip to content

Latest commit

 

History

History
executable file
·
188 lines (151 loc) · 7.88 KB

MANUAL.md

File metadata and controls

executable file
·
188 lines (151 loc) · 7.88 KB
Raw

VisiBot - Installation and Setup

Note for Markers:

  • For ease of setup, I have included pre-configured .env files in the source code .zip submitted for marking
  • These .env files contain API keys, usernames, and passwords and should therefore be kept private and secure
  • As .env files are provided, you can skip .env related instructions for the setup of the VisiBot Processing System and Web App
  • IMPORTANT! You will have to copy VisiBot/src/.env.lisa to /path/to/LiSa/.env to make use of the VirusTotal API key included in the lisa .env file

Setup Requirements

LiSa Sandbox

Setting up modified LiSa server

  • Install docker and docker-compose
  • git clone the fork of LiSa available here
  • install docker and docker-compose onto your host
  • From within the LiSa directory, enter the following commands:
# Create/edit .env file using example template (see note for markers below before doing this)
➜  ~ cp .env.example .env
➜  ~ vim .env

# Build/run using docker-compose and specify number of workers
➜  ~ sudo docker-compose build
➜  ~ sudo docker-compose up --scale worker=3

Make sure the .env file contains the following and that you:

  • Un-comment API_SUCCESS_URL, API_FAILURE_URL, and VIRUSTOTAL_API_KEY
  • replace [API_KEY_HERE] with your VirusTotal API key
LISA_WEBHOST=localhost
LISA_PORT=4242
LISA_STORAGE_PATH=./data/storage
LISA_DB_PATH=./data/db
LISA_VPN_PATH=./vpn

MYSQL_PASSWORD=lisa
RABBITMQ_DEFAULT_PASS=lisa

API_SUCCESS_URL=http://172.42.0.1:5001/api/lisa-analysis/success/<task_id>
API_FAILURE_URL=http://172.42.0.1:5001/api/lisa-analysis/failure/<task_id>
VIRUSTOTAL_API_KEY=[API_KEY_HERE]

(Optional) Configuring LiSa to use a VPN

You can skip this process if you do not have a VPN available or are not concerned with using one.

  • Download an .ovpn file from your VPN Provider
  • Create a directory inside of the base LiSa directory called vpn
  • If your VPN requires a username or password:
    • Open the .ovpn with a text editor and change auth-user-pass to auth-user-pass /vpn/pass.txt
    • Create a file called pass.txt inside of the vpn directory and fill it with your VPN credentials line-by-line: 
      [email protected]
your-vpn-password
  • Move the .ovpn into the vpn directory
  • Lastly, edit docker-compose.yml and uncomment # - VPN=/vpn and rebuild/run the docker containers

VisiBot Processing System

Running the VisiBot Processing System

# Step 1: Create/edit .env file using example template (please see note at top of page)
➜  ~ cd src/processing
➜  ~ cp .env.example .env
➜  ~ vim .env

# Step 3: Build/run using docker-compose and specify number of workers
➜  ~ sudo docker-compose build
➜  ~ sudo docker-compose up --scale worker=6

Example contents for .env

# src/processing/.env

# GeoIP Variables
GEO_ACCOUNT_ID=[ENTER_ACCOUNT_ID]
GEO_LICENSE_KEY=[ENTER_API_KEY]

# Schedular Variables
FIRST_RUN=False
FIRST_RUN_HOURS=2
EVENT_MINUTE=15
FLOWER_URL=http://localhost:5555
BAD_PACKETS_API_KEY=[ENTER_API_KEY]

# Worker Variables
REDIS_PASSWORD=[ENTER_A_SECURE_PASSWORD]
IP_INFO_C2_ONLY=False
IP_INFO_API_KEY=[ENTER_IPINFO_API_KEY]
MONGO_URL=[ENTER_MONGO_DB_URL]
LISA_API_URL=http://149.28.227.219:4242/api
LISA_EXEC_TIME_SEC=30

# Flower Variables
FLOWER_USER=vb-admin
FLOWER_PASS=[ENTER_A_SECURE_PASSWORD]

Note: variable assignments in [brackets] should be replaced with relevant credentials.

Using the Processing System

Once staarting the Processing System using the docker-compose up command shown above, you can:

  • View a list of all running docker apps by running docker ps
  • View logs for a specific application by running docker logs <container_id>
  • Run the processor as a daemon by adding -d to the docker-compose command
    • If you do this, use docker-compose down to shut down the docker application
  • View Celery Worker progress by visiting the Flower Web Dashboard
    • Visit the URL: http://localhost:5555/
    • The default username/password for logging in is included in the .env file

You can also monitor progress by viewing the MongoDB Atlas dash-board of the database you have included in the .env file.

VisiBot Web Application

Running Nuxt.js and Express.js locally

  • Make sure you have the latest version of NodeJS installed
  • Make sure ports 8080 and 3000 are available for running dev servers
  • Once configured, run local Nuxt.js and Express.js development servers using the following commands:
# Navigate to webapp and install the node_modules
➜  ~ cd src/webapp
➜  ~ npm install

# Create/edit .env file using example template (please see note at top of page)
➜  ~ cp backend/.env.example backend/.env
➜  ~ vim backend/.env

# Run the following to start the express.js server at port 8080
➜  ~ npm run exp-dev

# Open a new terminal at src/webapp and run:
➜  ~ npm run nuxt-dev
  • Note: If you encounter any issues related to node-fibers, try deleting node_modules and re-running npm install
  • Following these steps, You will be able to view the development server for VisiBot Web App at http://localhost:3000

Example contents for .env

# src/webapp/backend/.env

MONGO_URL=[ENTER_MONGO_DB_URL]
FRONTEND_BASE_URL=http://localhost:3000
NODE_ENV=development

Note: variable assignments in [brackets] should be replaced with relevant credentials.

Using the Web App

Once the web application loads, a map will be presented with a number of clusters and markers which you can interact with.

  • When a cluster is clicked, it the map will zoom in and expand the cluster into markers or sub-clusters
  • When a marker is clicked, a sub-menu will pop up allowing you to either
    • View network interactions between the marker and other logged IP addresses
    • View additional information about the marker via a pop-up panel
    • View VirusTotal information about the selected IP address
  • When the map slidebar toggle button is clicked at the top of the application navbar, you can:
    • Toggle markers on and off based on the marker type
    • Change the clustering radius
    • Toggle clustering settings like automatic zoom-in
    • Search for a specific IP address
    • Filter markers based on CVE, category, or description
  • The site theme (light/dark mode) can be toggled by clicking the 'sun' icon in the navbar
  • The site language can be toggled by selecting a new language from the drop-down menu
  • Information about the website can also be viewed by clicking the 'information' tab in the navbar