Stars: 239
Forks: 25
Pull Requests: 1
Issues: 6
Watchers: 12
Last Updated: 2022-04-16 15:20:36
PHP function tracker
License:
Languages: Batchfile, Shell, Makefile, M4, JavaScript, PHP, Vim Script, C, Dockerfile
Fracker is a suite of tools that allows to easily trace and analyze PHP function calls, its goal is to assist the researcher during manual security assessments of PHP applications.
It consists of:
a PHP extension that needs to be installed in the environment of the target web application that sends tracing information to the listener;
a listener application that is in charge of receiving the tracing information and performing some analysis in order to show some meaningful data to the user.
Clone or download this repository then move into the root directory.
Spin a new Docker container running Apache with PHP support:
$ docker run --rm -d -p 80:80 --name hello-fracker php:apache
Create some dummy PHP script as index:
$ docker exec -i hello-fracker tee /var/www/html/index.php <<\EOF
<?php
function foo($cmd) {
system('echo ' . preg_replace('/[^a-z]/i', '', $cmd));
}
$a = explode(' ', $_GET['x']);
var_dump($a);
foreach ($a as $cmd) {
foo($cmd);
}
EOF
Test that the PHP file is properly served:
$ curl 'http://localhost/?x=Hello+Fracker!'
Deploy Fracker to the container:
$ scripts/deploy.sh hello-fracker
Install the dependencies locally (this just needs to be performed once):
$ npm install -C app
Start Fracker with:
$ app/bin/fracker.js
Run the above curl
command again. (The output should be similar to the above screenshot.)
Run Fracker again with --help
and experiment with other options too.
Stop and remove the container:
$ docker stop hello-fracker
Every PHP request or command line invocation triggers a TCP connection with the listener. The protocol is merely a stream of newline-terminated JSON objects from the PHP extension to the listener, such objects contain information about the current request, the calls performed and the return values.
This decoupling allows the users to implement their own tools. Raw JSON objects can be inspected by dumping the stream content to standard output, for example:
$ socat tcp-listen:6666,fork,reuseaddr 'exec:jq .,fdout=0'
The PHP extension is forked from Xdebug hence the installation process is fairly the same so is the troubleshooting.
The most convenient way to use Fracker is probably to deploy it to the Docker container where the web server resides using the provided script. Use the manual approach for a more versatile solution.
This script should work out-of-the-box with Debian-like distributions:
$ scripts/deploy.sh <container> [<port> [<host>]]
It configures the PHP module to connect to specified host on the specified port (defaults to the host running Docker and port 6666).
Install the PHP development files and other dependencies. For example, on a Debian-like distribution:
$ apt-get install php7.0-dev libjson-c-dev pkg-config
The following operations need to be performed in the ext
directory.
Build the PHP extension with:
$ phpize
$ ./configure
$ make
(To rebuild after nontrivial code changes just rerun make
.)
To check that everything is working fine, start the listener application then run PHP like this:
$ php -d "zend_extension=$PWD/.libs/xdebug.so" -r 'var_dump("Hello Fracker!");'
Finally, install the PHP extension in the usual way, briefly:
make install
;zend_extension=xdebug.so
in a INI file parsed by PHP along with any other custom settings if needed.Clean the source directory with:
$ make distclean
$ phpize --clean
The default INI settings should work just fine in most cases. The following serves as a template for some common ways to override the default values:
; trace only those requests with XDEBUG_TRACE=FRACKER in GET, POST or cookie
xdebug.auto_trace = 0
xdebug.trace_enable_trigger = 1
xdebug.trace_enable_trigger_value = FRACKER
; do not collect function arguments
xdebug.collect_params = 0
; do not collect return values
xdebug.collect_return = 0
; custom listener application address (instead of 127.0.0.1:6666)
xdebug.trace_fracker_host = 10.10.10.10
xdebug.trace_fracker_port = 1234
The provided listener application is a Node.js package. Install the dependencies with:
$ npm install -C app
Optionally install the executable globally by creating a symlink to this folder:
$ npm install -g app
Then just run fracker
, or run it locally with app/bin/fracker.js
.
Command line options in long format can be written in YAML files (camel case) and passed as command line arguments. Multiple files with increasing priority can be specified, but command line options will have the highest priority.
For convenience some configuration files listing some classes of interesting PHP functions are provided along with this repo. Use them like:
$ fracker app/configs/file-* # ...
This product includes Xdebug, freely available from https://xdebug.org/. Unless explicitly stated otherwise, for the PHP extension itself, the copyright is retained by the original authors.
The listener application instead is released under a different license.