Before we can address the threat we need to have an understanding of exactly what we are trying to protect against. The final “clean” version of the requested page will be used for file includes which have a particular set of threats:

1. Root directory access – a UNIX path that begins with a forward slash (/) is an absolute path. As this can access any directory on the system we clearly do not want this. Mitigation – check the first character.
2. Directory traversal – UNIX designates the parent directory as two fullstops (..) which, if allowed, can once again permit access to any directory on the system. A sufficient number of parent directories (../../../../ etc.) is equivalent to root directory access. Mitigation – check for fullstops.
3. Remote file includes – if we were to allow any piece of code to be included an attacker could create their own PHP script, host it anywhere and reference it in the path provided – e.g. index.php?page=http://malicious-domain.tld/script which is clearly not an ideal situation. Something important to know is that a reference to a remote script relies on either a fully qualified domain name or an IP address, both of which must contain at least one fullstop. Mitigation – check for fullstops – same as (2).
4. Null bytes (%00) will cause PHP to truncate the end of a string. It is easy to believe that because we will be placing “.php” at the end of our include statement that we are safe. However, include “malicious-path%00.php”; and include “malicious-path”; are equivalent. Mitigation – check for a null byte.
5. Unknown – it is very possible that we have not covered all threats here and it is definitely a sound security measure to include a final catch-all check. As this negates the need for all previous checks it is possible to only utilise this approach, however a defense in depth strategy is advisable. Mitigation – duplicate the regular expressions used in the RewriteRules.

For now, the response to a potentially malicious path will simply be to redirect the user to the home page main, but in the future we will always have the ability to log the incident and potentially temporarily block the IP address¹. As all responses are the same (and so too is the response to an empty page request) we can utilise a try-catch statement and throw an exception any time we detect a problem. For brevity I have excluded the full function definition but note that the only parameter is $dirty which will receive $_GET[‘page’].

try {

if(empty($dirty)) throw new Exception();  //nothing provided

if(substr($dirty, 0, 1)==”/”) throw new Exception();  //point (1)

if(strpos($dirty, “.”)!==false) throw new Exception(); //points (2) and (3)

if(!preg_match(“/^(?:[\/a-z0-9_-]+)$/i”, $dirty)) throw new Exception(); //points (4) and (5)

$clean = strtolower($dirty); //it passed all the tests

}

catch(Exception $e){ //something is wrong so send them to the home page

$clean = “main”;

}

Should the “dirty” string fail any of our tests then we automatically default to the home page by catching the exception. Note the use of the negative double equality (!==) and not the single (!=); as zero (0) is registered as false by PHP the single will fail to throw an exception if the first character matches (returning an index of 0). The use of the double enforces matching of the boolean false (no match).

In conforming with the URL conventions we need to handle the case of a trailing slash (/) which is a request for the directory index main.

if(substr($clean, -1)==”/”) $clean .= “main”;

Now that we have a “clean” path we can set it as a constant using Phramework::define() as detailed in the last post. Later in the development it will prove useful to also have the path broken down into an array describing the directory structure. This storage of “clean” data is the exact reason why there is no unlocking function associated with define.

$this->define(‘PAGE’, $clean);

$this->define(‘PAGES’, explode(“/”, $clean));

If I have overlooked any issues please let me know via a comment. If anyone would like to write a unit test for this function it would be much appreciated.

Current text version of Phramework.php

¹ Later in the development of Phramework I will detail implementation of an intruder detection system and our responses.

if(substr($dirty, 0, 1)=="/"){

As this Phramework object is representative of a single request there should only ever be one such instance per Apache process, thus Phramework should implement the singleton pattern. The singleton code is an exact copy of that provided by the PHP documentation and results in object instantiation by:

$p = Phramework::singleton(); //returns the same instance no matter where it is called from
$p = new Phramework(); //triggers an error as the Phramework constructor is private

Before developing the functions to handle the page requested via the .htaccess RewriteRules there is some basic functionality that needs to be implemented for storage of data. Particularly, the define function needs to be reworked in order to allow values other than scalars (null, integer, string, float and boolean), such as arrays and objects, to be stored. This will be useful later on for security reasons as we will only define “clean” values.

In order to do this, we rely on the PHP magic methods __set() and __get()¹. These methods are called when there is an attempt to declare (__set) or retrieve (__get) an attribute of an object that has not been explicitly declared². As we are extending the define function we need to declare two arrays; the first for storage of values and the second for storage of “locked” keys.

private $values = array();
private $locked = array();

Before attempting to save a value into the $values array, __set will first check that the key is not in the $locked array. Return values mimic the standard PHP define function.

public function __set($key, $val){

//Check for no locking before saving
if(!in_array($key, $this->locked)){

$this->values[$key] = $val;
return true;

}
return false;

}

With this check in place, all that is needed is a function to lock a particular key (note that a key should not be able to be unlocked so we don’t define the corresponding function).

public function lock($key){

if(!in_array($key, $this->locked)){

$this->locked[] = $key;

}

}

Now comes the final step, the extended define function. Technically this is just a convenience wrapper for setting a value and then locking it. Once again, return values should mimic those of the original PHP define function. In the event that we are defining a value and it already exists but is not locked, I have decided to trigger a warning as a courtesy.

public function define($key, $val){

//Overwriting?

if(isset($this->values[$key]) && !in_array($key, $this->locked)){

trigger_error(“Value of Phramework::{$key} is being overwritten by Phramework::define()”, E_USER_WARNING);

}

if($this->__set($key, $val)){

$this->lock($key);
return true;

}

return false;

}

Note that if the value is already locked then __set() will return false and so too will Phramework::define().

With these basics in place we are able to move on to the first interesting method Phramework::findRequestedPage() which will be discussed in the next post.

Current text version of Phramework.php

¹ I believe that having all methods and attributes of the Phramework class being static would provide a better solution than the singleton pattern described above but these two magic methods cannot be declared statically.

² While their use in this case is simple, later in the project I will demonstrate a more complex and particularly useful implementation of __set and __get with regards to database access.

Here we will be dealing with the path of the URL (the part that tells the server what page is being requested). This is generally separated into a directory structure by forward slashes (/). The URL conventions are:

• Allowed characters are alpha (a-z), numeric (0-9), hyphen (-) and underscore (_)
• A trailing slash (/) will be treated as if the directory index has been requested
• The directory index is called main
• At least one page or directory is required
• URLs have no extension

This first rule matches for a URL with any number of directories (zero or more) as well as a specific file:

RewriteRule ^([a-z0-9_-]+)((\/[a-z0-9_-]+)*)$ index.php?page=$1$2 [NC,L,QSA]

The first set of parentheses match the mandatory page or directory. The second set is almost identical except for the fact that every remaining part will be prefixed with a slash (/). This path is then concatenated as a single string and passed to index.php for handling. Note that it is not case-sensitive (NC), it is a final match (L) and any query string is still passed (QSA).

A couple of examples:

• my-path is rewritten as index.php?page=my-path
• directory/structure/to/my-path is matched as $1 = directory while $2 = /structure/to/my-path and is rewritten as index.php?page=directory/structure/to/my-path

This second rule is almost identical to the first. The only difference is the inclusion of a trailing slash which, as described in the conventions, is a request for the directory index called main.

RewriteRule ^([a-z0-9_-]+)((\/[a-z0-9_-]+)*)\/$ index.php?page=$1$2/main [nc,L,QSA]

An example:

• directory/ is equivalent to directory/main and is rewritten as index.php?page=directory/main

I am by no means an expert in mod_rewrite nor regular expressions and I am quite confident that the efficiency of these two rules can be greatly improved. If you have any suggestions please post them as comments.

Current text version of .htaccess

Where appropriate, common OOP design patterns or modifications thereof will be used. The first that comes to mind is the MVC pattern. I have found that a direct implementation of this pattern can sometimes be limiting and therefore use a modified approach while maintaining the strict separation of logic and presentation. This will be detailed when we reach this section of the development and as usual, commentary is encouraged.

The framework will be built with the following LAMP software in mind:

• Linux distribution independent
• Apache 2.x
• PHP 5.x
• MySQL 5.x with other database connectivity planned for in the future
• memcached – a distributed, memory-based caching system

Check out the first step in creating this architecture – mod_rewrite & .htaccess

However, in the interests of community involvement, I will be doing so in a progressive manner. As each element is released as a blog post, I will call for comments, criticisms, recommendations or applause. In response to such commentary I will make all necessary adjustments and mold the framework accordingly.

Through this I hope to collaboratively build a framework that encompasses the following:

• Free – all software requirements and code will be free to use for both commercial and non-commercial projects (see the terms of use)
• Computational efficiency – benchmarked for both speed and memory usage
• Human efficiency – automation of regular tasks in order to promote rapid development
• Secure – implicit controls to limit the extent of human errors that cause security vulnerabilities
• Horizontal scalability – particularly with regards to data caching

I invite everyone to subscribe to our RSS feed and provide input at every stage of the development. In the end we will all benefit.

Check out the first post – Framework Architecture