README

PHP Aspis: Taint tracking for PHP via source-to-source rewriting
===============================================================================

PHP Aspis provides transparent protection against injection attacks using taint
tracking at the source code level. Please, do not proceed without reading the
USENIX WebApps 2011 paper titled "PHP Aspis: Using Partial Taint Tracking To
Protect Against Injection Attacks". It contains everything you need to know in
order to understand what this prototype does. Google the title and you will find 
the pdf.

Bewarned: this is a proof-of-concept research prototype.

===============================================================================

Dependencies
------------

PHP Aspis is a C/Flex/Bison project so build-essential/bison/flex should be
enough under Ubuntu. It's also good to have Python (I use 2.7.1) and PHP (I use
5.3.5).


===============================================================================

Installation
------------

$ git clone git://github.com/jpapayan/aspis.git ~/aspis_home

$ cd ~/aspis_home

$ make

Make sure that $ASPIS_HOME points to the repo dir and that the repo dir is in
your $PATH before continuing.

===============================================================================

Basic Usage
-----------

Type 

$ aspis

to get a list of the parameters that PHP Aspis requires. You definitely need to
pass a PHP file to parse (-in) and a file with the taint category definitions
(-categories). For the second, have a look in 
tests/taint_propagation/generic.categories
to see an example of such a file. The output must be a dir and can be specified
with -out (by default "results"). In the output dir, PHP Aspis will generate the
transformed file (same name as the input file) and it will also copy the runtime
library that the transformed application will require to execute.

Example:

$ cd ~/aspis_home
$ echo "<?php echo \"Hello PHP Aspis\n\";?>" > my_test.php
$ aspis -in my_test.php -categories tests/taint_propagation/generic.categories
        -out my_results
$ php my_test.php
$ php my_results/my_test.php

If everything is ok, the two PHP invocations should generate the same output.

===============================================================================

Tests
-----

The purpose of PHP Aspis is to generate scripts that behave almost identically
to the original script (minus any differences due to sanitisation of course).
Given the extensive transformations applied, this is often a challenge.
During development, a test suit under "tests" was used that contains about 80
php scripts. These should generate the same output before and after the
transformation.

To help automate things, the python script aspis_tests.py can take one (or more)
php files, transform them, and then test if their output is the same before and
after the transformation.

So, repeat what the previous example did, but with a file from the test suite:

$ cd ~/aspis_home
$ aspis_tests.py -dir tests 
              -file tests/test_categories_simple.php 
              -categories tests/taint_propagation/generic.categories 
              -out tests/results/

This will invoke make, and verify that aspis works correctly with the file
specified. To run all the tests in the test suite repeat the previous without
the -file parameter:

$ aspis_tests.py -dir tests 
              -categories tests/taint_propagation/generic.categories 
              -out tests/results/

Almost all of them should succeed. Try again if some fail, a few will only
work the second time (ie they include() files that transform in the first try).
Note: A couple of them still break PHP Aspis.

===============================================================================

Transforming PHP Projects
-------------------------

Transforming files one by one is not enough. So, PHP Aspis comes with a second 
python script "do_project.py". This recursively iterates in a directory,
invokes PHP Aspis in all the php scripts it finds and outputs the result.
Hopefully, it returns a transformed project dir, ready to be deployed. So, 
assuming that you have an application under ~/public_html/app, you may do:

$ aspis_project.py -dir ~/public_html/app
                -out ~/public_html/app_aspis 
                -categories tests/taint_propagation/generic.categories

This should parse successfully all of the files, segmentation faults are a bad
sign. Try then to see if app_aspis works as intented! Note that this script is
appending the individual aspis' output to a file called aspis_project.log. 
If you see a segmentation fault, this may be useful.

===============================================================================

Partial Taint Tracking
----------------------

In order to achieve partial taint tracking, all binaries should be called with
an additional two parameters:

$ aspis_project.py -dir ~/public_html/app
                -out ~/public_html/app_aspis 
                -categories tests/taint_propagation/generic.categories
                -taints ~/app.tainted
                -prototypes ~/app.prototypes

[-taints taintsfile]
This first file specifies the contexts that should be considered tainted. In 
that file, you can add [function names or script names] and then [class names].
Alphabetical "strcmp" order is required for both subcategories. See the various 
*.tainted files under /tests/taint_propagation for inspiration.
PS. Leave the categories >functions and >classes there, the parsing routines are
    not particularly smart.

[-prototypes protoypesfile]
This file lists all the function/methods used by the transformed application.
For each of them, it specifies the parameters that are passed by reference. This
is necessary to enable PHP Aspis to adapt function parameters between tracking
and non tracking code.


Function Lists
--------------

PHP Aspis can generate the prototypes file for you. To do so, use the 
"-fused on" parameter when you call aspis_project.py:

$ aspis_project.py -dir ~/public_html/app -fused on

This will invoke PHP Aspis for all project files and it will generate in the 
current dir two files:
--current.prototypes
This is the the file you are after.
--fused.txt
This is a list of PHP lib functions (not sorted, see misc/fused_sort.php) that
the application is using. This is very useful to limit the number of
interceptors that you may want to write. Otherwise, you can ignore it.


===============================================================================

FAQ:

Q: Where do I put my Guards?
Append them in any of the php files under "phplib" (eg phplib/AspisTaints.php).
Your guards should handle values that are aspis-transformed.