AcCoRuTe - Access Control Rules Tester
========================================================================================
This project aims to create tool that automates the process of finding 
access control flaws in web applications.


HISTORY
========================================================================================
The first version of the tool was created by Andrew Petukhov <petand@lvk.cs.msu.su> 
as his GSoC'08 work for OWASP project. 
See http://www.owasp.org/index.php/Category:OWASP_Access_Control_Rules_Tester_Project


THEORY
========================================================================================
The underlying theory was first proposed by Andrew Petukhov <petand@lvk.cs.msu.su> 
and then reviewed and improved by George Noseevich as the part of a term paper.
Detailed explaination should appear within the project documentation once the codebase 
grows mature enough.
Some theoretical material may be found in docs


PROJECT STRUCTURE
========================================================================================
The current version under development is being built from scratch (though borrowing some
code and ideas from the first version) and aims to overcome drawbacks of the first 
version.

The tool consists of 2 major parts: 

 * Web application markup helper, written as a FireFox extension.
 * Web application Access Control engine tester, a standalone Java application.

BUILDING THE APPLICATION
=======================================================================================
To build the scanner, you need to:
 1. Make sure that java and ant are installed on your system
 2. Change to the scanner dir and run `ant`. This will get all project dependencies 
 from maven repo via ivy (ivy itself is located at scanner/lib.ivy). Internet 
 connection is required for this. 
 3. The scanner.jar will appear in the current directory
The mapper should be installed as described in mapper/INSTALLATION

RUNNING MAPPER
======================================================================================
 1. Start firefox with the profile for which you installed the extension
 2. Open the capture console by pressing the "toggle capconsole" button.
 3. Enter the information about the application in the Basic tab.
 4. Enumerate webapp role names at the Roles tab
 5. Enter users and credentials at the Users tab
 6. At the Use case tab, for each state-changing use case in the app, do the following:
   a. Navigate the application to the page from which you can trigger the use case
   b. Enter the name and user and press the Start button
   c. Trigger the use case (i.e. click the link or submit the form)
   d. Press the Finish button
 7. Specify dependecies and cancellations on corresponding tabs
 8. The "export to file" button actually (surprise surprise!) exports the capture to file. This is a JSON dump, in case you wonder.

RUNNING SCANNER
======================================================================================
 1. Run it with java -jar scanner.jar <bean-file.xml>
 2. The bean-file is essentially a config for scanner. Sample configurations are 
 in scanner/src/resources folder. The all-mighty howto describing all possible 
 configuration that can be made through that files is yet to appear.
 Among the configuration you also have to specify the location of the capture file
 that was generated by the mapper tool.
 3. Before the run, the web application must be reset to its initial state (we use
 virtual machine snapshots for that, but you may do that manually if you wish)
 4. LOADS of debug output will flood. 
 5. When (if ever) the tool ends execution, explore the report/ folder, that will 
 contain the report*.xml files (the main one is report.xml, files with numbers are
 separate reports in each state). Also, sitemaps in dot/graphViz format are generated
 and placed in the same folder. You may then run the gengraph.sh script to generate
 beautifull images from them. 
 6. Examples of what you might get are in the experiments folder. 

WARNING!
======================================================================================
THIS IS EXPERIMENTAL SOFTWARE!
The code is yet buggy, its performance may suck^W be slow, it may hung forever and
consume unlimited amounts of memory.
After all, this is still a (though rather advanced) proof of concept.

You patches and ideas are VERY welcome.

-- George