Expose - PHP Intrusion Detection

Expose is an Intrusion Detection System for PHP loosely based on the PHPIDS project (and using it’s ruleset for detecting potential threats). You can find the latest version over on it’s github page.

ALL CREDIT for the rule set for Expose goes to the PHP IDS project. Expose literally uses the same JSON configuration for its execution. I am not claiming any kind of ownership or authorship of these rules. Please see the PHPIDS github README for names of those who have contributed.

Requirements

Expose requires:

• PHP 5.3
• MongoDB support
• A MongoDB server to write to

The Mongo instance is used for two things - to write out the logging for the tool and, optionally, for use with the offline processing via the queue.

Sample Code

The code below is a simple example of using Expose to handle the incoming data ($data) and process it against the filter rules. It also shows some of the helper methods you can get to get the results of the filter run.

$data = array(
    'POST' => array(
        'test' => 'foo',
        'bar' => array(
            'baz' => 'quux',
            'testing' => '<script>test</script>'
        )
    )
);

$filters = new \Expose\FilterCollection();
$filters->load();

$manager = new \Expose\Manager($filters);
$manager->run($data);

echo 'impact: '.$manager->getImpact()."\n"; // should return 8

// get all matching filter reports
$reports = $manager->getReports();
print_r($reports);

// export out the report in the given format ("text" is default)
echo $manager->export();
echo "\n\n";

Real-time versus Queued Handling

Expose allows for two kinds of processing - real-time as the request comes in and delayed (queued). This can be controlled with the queue_requests setting in the configuration. If it is set to true, Expose will take the request data and insert it into the data store.

Real-time reporting will process the impact scores of the matching rules and report back the results. These results can be fetched with the getReports method (as shown above). You’re then free to do with the results as you wish.

Queued processing can be handled by something like a cron job using the command-line tool. When enabled, the request data is pushed into the data store with a processed value of false. The CLI then grabs the latest entries from this queue and processes them against the rules. The results are either directly outputted in a JSON format or can be written to an external file.

See the section on command line usage for more information.

Exceptions

Expose lets you define two things to help with the evaluation of the data - exceptions and restrictions. Here’s a definition of each:

Exceptions

An exception basically allows you to say “evaluate everything except this value”. For example, to bypass the POSTed value of “foo” you would use:

$manager->setException('POST.foo');

This bypasses the value for that field and doesn’t execute the filters on it.

Restrictions

A restriction lets you tell Expose to only evaluate certain values and ignore all others. For example, we might have more data than we care around coming in and only want to check the value of POST.foo.bar:

$data = array(
    'POST' => array(
        'foo' => array(
            'bar' => 'test one'
        ),
        'baz' => 'test two'
    )
);

$filters = new \Expose\FilterCollection();
$filters->load();

$manager = new \Expose\Manager($filters);
$manager->setRestriction('POST.foo.bar');
$manager->run($data);

In this case, the filters would only run on POST.foo.bar and not on POST.baz.

Command Line

Expose comes with a command-line tool to help make using the system simpler. You’ll find it in the bin/ directory inside of your installation. The CLI script inclues a few different commands:

• filter
• process-queue

Below are examples of how to use these commands.

Command Line - Filters

The filter command gives you information about the filters loaded into the system. By default, it will give you a list of the filters and their descriptions:

bin/expose filter

The result is a list of IDs and the summaries from the filters, for example:

1: finds html breaking injections including whitespace attacks
2: finds attribute breaking injections including whitespace attacks
3: finds unquoted attribute breaking injections
4: Detects url-, name-, JSON, and referrer-contained payload attacks
5: Detects hash-contained xss payload attacks, setter usage and property overloading
6: Detects self contained xss via with(), common loops and regex to string conversion
7: Detects JavaScript with(), ternary operators and XML predicate attacks

To get more information about a filter, use the id option:

bin/expose filter --id=2

You’ll be given the details about that filter:

bin/expose --id=2

[2] finds unquoted attribute breaking injections
    Rule: (?:^>[\w\s]*<\/?\w{2,}>)
    Tags: xss, csrf
    Impact: 2

Or, if you’d like information on more than one filter at a time, you can append them with a comma:

bin/expose --id=2,3

[2] finds unquoted attribute breaking injections
    Rule: (?:^>[\w\s]*<\/?\w{2,}>)
    Tags: xss, csrf
    Impact: 2

[3] Detects url-, name-, JSON, and referrer-contained payload attacks
        Rule: (?:[+\/]\s*name[\W\d]*[)+])|(?:;\W*url\s*=)|(?:[^\w\s\/?:>]\s*(?:location|referrer|name)\s*[^\/\w\s-])
        Tags: xss, csrf
        Impact: 5

Command Line - Queue

The process-queue command lets you work with the queued request data. To use the queue processing, you need to enable it with the queue_requests configuration option.

To process the current items in the queue, you can execute it without any command line options:

bin/expose process-queue

This will provide you some messaging about how many items it will be processing (the default is 10 records at a time) and output the resulting filter matches as JSON data.

If you’d like to output these results to a file instead, you can use the export-file option:

bin/expose process-queue --export-file=/tmp/output.txt

This will apprend to the file if it already exists.