DESCRIPTION:
------------------------------
Imalse (Integrated MALware Simulator and Emulator) is a framework to help
researchers to implement prototype of botnet based network malware. Researchers
just need to implement the malware behaviour once and then it can run the
following modes:
    1. emulation mode: In this mode, each copy of imalse will behave exactly
    like a real malware. You can install it in a real machine, or in a virtual
    machine and set up a testbed to test the characteristic of the
    malware.(Don’t use it to attack other people’s machines;) ) [Note: you can
    potentially work with Common Open Research Emulator to emulate a lot of
    nodes in one machine]
    2. netns3 simulation mode: You can specifiy the topology of the network and
    the ip addresses of each node in this mode. IMALSE will launch virtual
    machines (linux namespace) for each node in the network and construct the
    network automatically. All virtualized nodes will connect to NS3 through
    tapbridge and all traffic will consume there. The simulation will be in real
    time. It is based on netns3 project.
    3. pure ns3 simulation mode: No virtual machince will be launched for the
    pure ns3 simulation mode, the whole simulation will be done in ns3. ns3
    default scheduler will be used instead of the real time scheduler in netns3
    case, which saves much time.  One simulation day may only consume several
    real seconds.  4. hybrid approach: of pure ns3 mode and netns3 mode

COMPARISON WITH OTHER TOOLS
------------------------------
NS3:
    As shown by its name, the primary goal for NS3 is to provide a network
    simulator, which means primarily there will be no real packet passing
    through the real network interface. Although the emulation support has been
    added, the development of simulation and emulation are mostly unconnected,
    which wastes a lot of development resource. However, the development goal of
    Imalse is not just simulator or emulator, it is a up layer that unifies the
    development of simulation and emulation tools( at least for botnet based
    malware simulation). Actually, the simulations in Imalse are mostly done by
    NS3 in the backend.

CORE:
    Imalse depends on CORE for its gui editor and its capsulation of linux name
    space. CORE is a very excellent network emulator. However, what CORE intends
    to do is to create a new network and run application in real time. However,
    as noted above, Imalse try to make the switch between simulation and
    emulation (for botnet based malware simulation) effortless.

The utimate goal of Imalse a tool help you to run your code on both
NS3, CORE and real nework. In the current stage, we focus on botnet based
malware simulation.

USER CASE
------------------------------
The following user case will help to determine whether you should use Imalse or
not.

Suppose Conan is a Ph.D student who has proposed a novel anomaly detection
technique for Internet traffic. He wants to demostrate the usefulness of this
approach. To do this, he designs a scenario that 100 client computers accessing
a server through the internet, 10 of which had already been compromised and
controlled by botmaster through botnet. At some point, the botmaster will
initiate a ddos attack by asking all compromised computers to send ping requests
to the servers. The anomaly detection technique requires all the incoming and
outcoming traffic of the server for at least two days. 

How can he collect the data he want? imalse provides different solutions at
different abstract level. He decides to use **TopoSimExperiment** in which he
can load some topology file generated by `Inet
<http://topology.eecs.umich.edu/inet/>`_ topology generator and select
**ddos_ping_attack** attacking scenario from the imalse software which provide
exactly what he wants.

The first question is since the method is not mature, Conan wants to test it
under different parameter combinations. It will be forever if each simulation
takes more than two days. Fortunately, by running the simulation under **pure
ns3 simulation mode** Conan can finish one simulation with less 100 real
seconds, though the time has past for more than two days in the simulator.

After extensive testing, Conan has been quite confident about the performance of
the anomaly detection techinique now. But he is still a little bit worried about
whether the result of ns3 is convincing enough. As a result, he run a complete
simulation under **netns3 simulation model** and collect data. Of course, this
time it runs more than two days, but he doesn't care that much because he only
need to run it for very few times. Conan generates some plots and writes a paper
with data of **netns3 simulation model** and satisfied with this.

A rich company named NetSecurity reads this paper and think it is a good method.
They want to deploy it but need more realistic test before deployment, so they
decide to test it under their intranet. They ask Conan for a copy of the code
and select several computer in the intranet to join the botnet, each computer
run an independent copy of imalse under **emulation client mode**, there is a
computer serving as botmster and running a imalse under **emulation server
model**\ (the server refers to the C&C server in the botnet). The data of
attacked server is recorded and analyzed with Conan's tools. It turns out to be
good, and the Company decide to use this method.

As a lazy Ph.D student, Conan just need to write one copy of code to describe
the secnario during the whole process. With the help of imalse, he can have more
time to sleep and enjoy the classical music. :)

INSTALLATION
------------------------------
Refer INSTALL for the installation instruction


GET YOURSELF STARTED
-------------------------------
before you do anything, update the ROOT variable in settings.py to be the
absolute path of current folder. no slash '/' at the end.

if you want to use emulator, run
    $ ./emulate.py

if you want to use simulator, you have two ways:
    1. going to NS3 path and type:
        $ ./waf shell
       you will enter ns3 waf-sh. Then in this shell, go back to this folder and type
        $ ./simulate.py
    2. if you are lazy. just update the NS3_PATH value in settings.py and type
        $ ./sim


WHERE CAN YOU GET HELP
-----------------------------
You can go to the following webpage for help document
http://people.bu.edu/wangjing/open-source/imalse/html/index.html

You can view wiki in the following webpage:
https://bitbucket.org/hbhzwj/imalse/wiki/Home

You can report issue in the following webpage:
https://bitbucket.org/hbhzwj/imalse/issues?status=new&status=open


ROADMAP
-----------------------------
Imalse is just a newbie. The features I am considering to add:

* Background Traffic Generator
    Now Imalse only describe the behaviour of abnormal nodes( which is so called
    "scenario"). Because of the lack of time, I haven't implemented the
    behaviour for normal nodes. An immediate feature that need to be added is to
    provide some modes for the normal nodes. It may require different
    implementation for sim node, netns3 node and read node, but they need to
    provide unified interface. My preliminary idea is to use NS3 on-off
    application for sim node.

* Full support of Common Open Research Emulator.
    The dependency of Imalse on CORE are two aspects. The CORE GUI is used with
    support of exporting Imalse Configuration Script. The netns3 mode rely on
    some components of the CORE. However, the whole procedure is not
    integrated and there are some features of CORE that has problems.

* More Practical Attacking Scenario and More APIs for Node
    Imalse is useful only when there are more pratical attacking scenario. Also, 
    different scenario may require different APIs for nodes. For example,
    key logger may need a node API to record key log. Whenever a Node API is
    added, support for Sim Node, Net ns3 Node and real node need to be
    implemented.