{"id":13828294,"url":"https://github.com/cyrus-and/fracker","last_synced_at":"2025-04-13T04:59:35.881Z","repository":{"id":66185129,"uuid":"168396873","full_name":"cyrus-and/fracker","owner":"cyrus-and","description":"PHP function tracker","archived":false,"fork":false,"pushed_at":"2025-03-10T16:22:50.000Z","size":1363,"stargazers_count":241,"open_issues_count":0,"forks_count":20,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-13T04:59:26.849Z","etag":null,"topics":["analysis","function","json","pentesting","php","security-assesment","stacktrace","tracking","white-box","xdebug"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyrus-and.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-30T18:53:47.000Z","updated_at":"2025-03-10T16:22:54.000Z","dependencies_parsed_at":"2023-10-05T13:56:55.721Z","dependency_job_id":"21f97327-0e20-4ec5-8477-3d266291b9a0","html_url":"https://github.com/cyrus-and/fracker","commit_stats":{"total_commits":278,"total_committers":2,"mean_commits":139.0,"dds":0.003597122302158251,"last_synced_commit":"306f0923782e59dbaf9c4fd4dc72907be7ba943d"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Ffracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Ffracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Ffracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Ffracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyrus-and","download_url":"https://codeload.github.com/cyrus-and/fracker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665756,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis","function","json","pentesting","php","security-assesment","stacktrace","tracking","white-box","xdebug"],"created_at":"2024-08-04T09:02:40.081Z","updated_at":"2025-04-13T04:59:35.855Z","avatar_url":"https://github.com/cyrus-and.png","language":"JavaScript","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# Fracker\n\n[![CI status](https://github.com/cyrus-and/fracker/actions/workflows/ci.yml/badge.svg)](https://github.com/cyrus-and/fracker/actions?query=workflow:CI)\n\nFracker 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.\n\nIt consists of:\n\n- a [PHP extension](#php-extension) that needs to be installed in the environment of the target web application which sends tracing information to the listener application;\n\n- a [listener application](#listener-application) that runs locally and is in charge of receiving the tracing information from the PHP extension and performing some analysis in order to show some meaningful data to the user.\n\n![Screenshot](https://gist.githubusercontent.com/cyrus-and/20e1fe4ae91fcd3c823262e7e8344a75/raw/3955b75bd5f177ec096409750714e6d5e98cdd3e/screenshot.png)\n\n## Setup\n\nInstall the PHP extension, either by using the [deploy script](#deploy-script) or [manually](#manual-setup), then install the listener application [locally](#installation).\n\nOtherwise for a quick test, jump straight to the [demo](#demo).\n\n## Demo\n\n1. Install the [listener application](#installation).\n\n2. Spin a Docker container serving the PHP demo application:\n\n    ```console\n    docker run -d -p 80:80 -v \"$PWD/demo/:/var/www/html/\" --name hello-fracker php:8.2-apache\n    ```\n\n3. Check that the demo PHP application works as expected:\n\n    ```console\n    curl http://localhost/?expression=7*7\n    ```\n    ```\n    The result is: 49\n    ```\n\n4. Deploy Fracker to the container using the [deploy script](#deploy-script):\n\n    ```console\n    ./scripts/deploy.sh hello-fracker\n    ```\n\n5. Start Fracker in another terminal, then repeat the above `curl` command:\n\n    ```console\n    fracker\n    ```\n    ```\n    +++ │ Listening on 0.0.0.0:6666\n    +++ │\n    001 │ GET localhost/?expression=7*7\n    001 │ {main}() /var/www/html/index.php +0\n    001 │ »  is_safe(expression=\"7*7\") /var/www/html/index.php +16\n    001 │ »  »  preg_match(pattern=\"/^[0-9+.\\\\-*\\\\/() ]+/\", subject=\"7*7\") /var/www/html/index.php +12\n    001 │ »  calculate(expression=\"7*7\") /var/www/html/index.php +17\n    001 │ »  »  eval(\"return 7*7;\") /var/www/html/index.php +5\n    +++ │\n    +++ │ Shutting down...\n    ```\n\n6. Press Ctrl-C to exit Fracker, then run it again with `--help`, and experiment with other options too, for example, pass the `-v` option to show the return values too!\n\n7. Finally stop and remove the container with:\n\n    ```console\n    docker rm -f hello-fracker\n    ```\n\n## Architecture\n\nEvery 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.\n\nThis 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 (assuming the default [settings](#settings)):\n\n```console\nsocat tcp-listen:6666,fork,reuseaddr - | jq\n```\n\n## PHP extension\n\nThe PHP extension is a modification of [Xdebug](https://github.com/xdebug/xdebug), hence the installation process is fairly the same, so is the troubleshooting.\n\nThe most convenient way to use Fracker is probably to deploy it to the Docker container where the web server resides using the provided [deploy script](#deploy-script), use the [manual setup](#manual-setup) for a more versatile solution.\n\n### Deploy script\n\nThis script should work out-of-the-box with Debian-like distributions running Apache:\n\n```console\n./scripts/deploy.sh \u003ccontainer\u003e [\u003cport\u003e [\u003chost\u003e]]\n```\n\nIt configures the PHP module to connect to specified host on the specified port (defaults to the host running Docker and the [default](#settings) port).\n\n### Manual setup\n\nInstall the PHP development files and other dependencies. For example, on a Debian-like distribution:\n\n```console\napt-get install php8.2-dev libjson-c-dev pkg-config\n```\n\nThen move into the `./ext/` directory and just run `make` to fetch Xdebug, apply the patch, and build Fracker.\n\nTo check that everything is working fine, start the [listener application](#listener-application) then run PHP like this:\n\n```console\nphp -d \"zend_extension=$PWD/xdebug/modules/xdebug.so\" -r 'var_dump(\"Hello Fracker!\");'\n```\n\nFinally, install the PHP extension the usual way. Briefly:\n\n1. copy `./ext/xdebug/modules/xdebug.so` to the PHP extension directory (e.g., `php-config --extension-dir`);\n\n2. place `zend_extension=xdebug`, along with any other optional custom [settings](#settings), in some INI file that gets parsed by PHP in the target environment (SAPI) used by the application;\n\n3. if needed, reload the web server.\n\nAt this point the source repository is no more needed.\n\n### Settings\n\nThe default INI settings should work just fine in most cases, the following aspects can be configured.\n\n#### Address of the listener application\n\nBy default, the PHP extension will try to connect to `127.0.0.1` on the port `6666`. This can be changed with:\n\n```ini\nxdebug.trace_fracker_host = 10.10.10.10\nxdebug.trace_fracker_port = 1234\n```\n\n#### Trace only certain requests\n\nBy default, every request will be traced. It is possible to switch to an on-demand behaviour with:\n\n```ini\nxdebug.start_with_request = trigger\nxdebug.trigger_value = FRACKER\n```\n\nIn this way, only those requests having `XDEBUG_TRACE=FRACKER` in their GET, POST, or cookies parameters will be traced by Fracker.\n\n## Listener application\n\nThe provided listener application is a [Node.js](https://nodejs.org/en) package, it is commonly installed locally, but it can resides anywhere, provided that it can be reached by the PHP extension.\n\n### Installation\n\nInstall the dependencies with:\n\n```console\nnpm install -C ./app/\n```\n\nThen run Fracker locally with `./app/bin/fracker.js`.\n\nOptionally, install the executable globally by creating a symlink to this folder with:\n\n```console\nnpm install -g ./app/\n```\n\nAfter that, the `fracker` command will be globally available.\n\nUninstall with:\n\n```console\nrm -fr ./app/node_modules/\nnpm uninstall -g fracker\n```\n\n### Usage and configuration\n\nRun `fracker --help` to obtain the full usage.\n\nFor convenience some [configuration files](app/configs/) listing some classes of *interesting* PHP functions are provided along with this repository. Use them like:\n\n```console\nfracker ./app/configs/file-* # ...\n```\n\n## License\n\nThis product relies on [Xdebug](https://xdebug.org/), unless explicitly stated otherwise, for the PHP extension itself, the copyright is retained by the original authors.\n\nThe listener application instead is released under a [different](app/LICENSE) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrus-and%2Ffracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyrus-and%2Ffracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrus-and%2Ffracker/lists"}