ExploitReadme.txt

The process of integrating an exploit with the attack engine framework
is quite simple and uses a basic command line interface.

***Important Note*** Exploits must flush stdout! (explained below)

An easy workaround for python based scripts is to start them with

#!/usr/bin/python -u ***Important Note***

Each exploit will take as an argument the IP address of the team to
attack and an optional "cookie" value that can maintain some state
between executions of the exploit.

The run time interaction with the Attack Engine is done over stdout
with a simple line based mechanism. To use a command the exploit
simply just prints to stdout <COMMAND>:<msg>. The commands are case
sensitive. Currently, the commands supported are FLAG, COOKIE and TIMEOUT.

The FLAG command is used to notify the attack engine of a new flag. To
capture a flag, the exploit script should just output something in the
form of:

FLAG: <flag text>

COOKIE is a simple text string that can be used to keep track of some
state, between successive runs of an exploit. The cookie values are
associated with each IP address such that the exploit/IP pairs each
can have their own cookie value. This is passed into the exploit as
the optional second command line argument. The cookie value is never
automatically cleared and will persist for every subsequent call of
the exploit.

TIMEOUT is used to set a maximum running time for the script. The timeout
values are in seconds. For example,

TIMEOUT: 30

will ensure that this script is terminated in 30 seconds, unless it
exits or another timeout value is set. Setting TIMEOUT is optional. The
default behavior is that scripts are killed after 30 seconds of no
output. An exploit can set the TIMEOUT value to 0 to go back to this
default behavior. The attack engine ensures that terminated exploits
are restarted every couple of minutes.

****About stdout flush***

One interesting bit of knowledge gleaned from this project is that
stdout in the C standard is a buffered stream. This means that the
operating system controls when data is made available. More importantly,
there is no way for a parent process to force a child process to flush
stdout. One possible way around this is to build a virtual TTY like
device that explicitly unbuffers its output stream, and this is how
pexpect works. Another possible approach is to ensure that the child
process explicitly flush stdout, which is what I have decided to do.

The operating system will automatically flush stdout when either the child
process exits or when it writes enough data into the buffer. Therefore
if the exploit is a short lived program that simply fetches the most
recent flag the terminates, no additional work is necessary. If the
process is a long running script that tries to capture many flags, the
flushing output is an important step or the attack engine will terminate
the script after 30 seconds.

The most straight forward way in python to flush stdout is
simply to execute the command sys.stdout.flush() after every print
statement. However, one very good alternative is to start the python
script in unbuffered mode. IE

replace the #!/usr/bin/env python with

#!/usr/bin/python -u

Using the above as the shell command will cause python to automatically
unbuffer stdout and everything will work as expected.