{"id":19109251,"url":"https://github.com/typo3/phar-stream-wrapper","last_synced_at":"2025-05-15T22:08:49.233Z","repository":{"id":46951191,"uuid":"146160794","full_name":"TYPO3/phar-stream-wrapper","owner":"TYPO3","description":"Interceptors for PHP's native phar:// stream handling in order to enhance security.","archived":false,"fork":false,"pushed_at":"2024-12-10T00:51:53.000Z","size":2310,"stargazers_count":58,"open_issues_count":0,"forks_count":14,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-31T15:32:45.254Z","etag":null,"topics":["deserialization","insecure-deserialization","phar","php","security","stream-wrapper"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TYPO3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-26T07:33:56.000Z","updated_at":"2024-12-10T00:51:57.000Z","dependencies_parsed_at":"2024-11-06T00:04:30.071Z","dependency_job_id":"646a1f97-f209-4a72-84a3-dfc64d4b8006","html_url":"https://github.com/TYPO3/phar-stream-wrapper","commit_stats":{"total_commits":118,"total_committers":8,"mean_commits":14.75,"dds":"0.13559322033898302","last_synced_commit":"8e3d17d6143438d360ce9f12f300ba97d66888ff"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TYPO3%2Fphar-stream-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TYPO3%2Fphar-stream-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TYPO3%2Fphar-stream-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TYPO3%2Fphar-stream-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TYPO3","download_url":"https://codeload.github.com/TYPO3/phar-stream-wrapper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809962,"owners_count":20999816,"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":["deserialization","insecure-deserialization","phar","php","security","stream-wrapper"],"created_at":"2024-11-09T04:19:38.601Z","updated_at":"2025-04-08T09:07:47.938Z","avatar_url":"https://github.com/TYPO3.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/TYPO3/phar-stream-wrapper/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/TYPO3/phar-stream-wrapper/?branch=master)\n[![GitHub Build Status Ubuntu](https://github.com/typo3/phar-stream-wrapper/actions/workflows/tests-ubuntu.yml/badge.svg)](https://github.com/typo3/phar-stream-wrapper/actions/workflows/tests-ubuntu.yml)\n[![GitHub Build Status Windows](https://github.com/typo3/phar-stream-wrapper/actions/workflows/tests-windows.yml/badge.svg)](https://github.com/typo3/phar-stream-wrapper/actions/workflows/tests-windows.yml)\n[![Downloads](https://poser.pugx.org/typo3/phar-stream-wrapper/downloads.svg)](https://packagist.org/packages/typo3/phar-stream-wrapper)\n\n# PHP Phar Stream Wrapper\n\n\u003e [!NOTE]\n\u003e With PHP 8.0.0 the default behavior changed, and meta-data is not deserialized automatically anymore:\n\u003e\n\u003e * see [`typo3/phar-stream-wrapper` issue #64](https://github.com/TYPO3/phar-stream-wrapper/issues/64)\n\u003e * see https://php.watch/versions/8.0/phar-stream-wrapper-unserialize\n\n## Abstract \u0026 History\n\nBased on Sam Thomas' findings concerning\n[insecure deserialization in combination with obfuscation strategies](https://www.secarma.com/labs/near-phar-dangerous-unserialization-wherever-you-are.html)\nallowing to hide Phar files inside valid image resources, the TYPO3 project\ndecided back then to introduce a `PharStreamWrapper` to intercept invocations\nof the `phar://` stream in PHP and only allow usage for defined locations in\nthe file system.\n\nSince the TYPO3 mission statement is **inspiring people to share**, we thought\nit would be helpful for others to release our `PharStreamWrapper` as standalone\npackage to the PHP community.\n\nThe mentioned security issue was reported to TYPO3 on 10th June 2018 by Sam Thomas\nand has been addressed concerning the specific attack vector and for this generic\n`PharStreamWrapper` in TYPO3 versions 7.6.30 LTS, 8.7.17 LTS and 9.3.1 on 12th\nJuly 2018.\n\n* https://blog.secarma.co.uk/labs/near-phar-dangerous-unserialization-wherever-you-are\n* https://youtu.be/GePBmsNJw6Y\n* https://typo3.org/security/advisory/typo3-psa-2018-001/\n* https://typo3.org/security/advisory/typo3-psa-2019-007/\n* https://typo3.org/security/advisory/typo3-psa-2019-008/\n\n## License\n\nIn general the TYPO3 core is released under the GNU General Public License version\n2 or any later version (`GPL-2.0-or-later`). In order to avoid licensing issues and\nincompatibilities this `PharStreamWrapper` is licenced under the MIT License. In case\nyou duplicate or modify source code, credits are not required but really appreciated.\n\n## Credits\n\nThanks to [Alex Pott](https://github.com/alexpott), Drupal for creating\nback-ports of all sources in order to provide compatibility with PHP v5.3.\n\n## Installation\n\nThe `PharStreamWrapper` is provided as composer package `typo3/phar-stream-wrapper`\nand has minimum requirements of PHP v5.3 ([`v2`](https://github.com/TYPO3/phar-stream-wrapper/tree/v2) branch),\nPHP v7.0 - v8.3 ([`v3`](https://github.com/TYPO3/phar-stream-wrapper/tree/v3) branch) and PHP v7.1 - v8.4+ ([`v3`](https://github.com/TYPO3/phar-stream-wrapper) branch).\n\n### Installation for PHP v7.1 - v8.4\n\n```\ncomposer require typo3/phar-stream-wrapper ^4.0\n```\n\n### Installation for PHP v7.0 - v8.3\n\n```\ncomposer require typo3/phar-stream-wrapper ^3.0\n```\n\n### Installation for PHP v5.3\n\n```\ncomposer require typo3/phar-stream-wrapper ^2.0\n```\n\n## Example\n\nThe following example is bundled within this package, the shown\n`PharExtensionInterceptor` denies all stream wrapper invocations files\nnot having the `.phar` suffix. Interceptor logic has to be individual and\nadjusted to according requirements.\n\n```\n\\TYPO3\\PharStreamWrapper\\Manager::initialize(\n    (new \\TYPO3\\PharStreamWrapper\\Behavior())\n        -\u003ewithAssertion(new \\TYPO3\\PharStreamWrapper\\Interceptor\\PharExtensionInterceptor())\n);\n\nif (in_array('phar', stream_get_wrappers())) {\n    stream_wrapper_unregister('phar');\n    stream_wrapper_register('phar', \\TYPO3\\PharStreamWrapper\\PharStreamWrapper::class);\n}\n```\n\n* `PharStreamWrapper` defined as class reference will be instantiated each time\n  `phar://` streams shall be processed.\n* `Manager` as singleton pattern being called by `PharStreamWrapper` instances\n  in order to retrieve individual behavior and settings.\n* `Behavior` holds reference to interceptor(s) that shall assert correct/allowed\n  invocation of a given `$path` for a given `$command`. Interceptors implement\n  the interface `Assertable`. Interceptors can act individually on the following\n  commands or handle all of them in case they were not defined specifically:\n  + `COMMAND_DIR_OPENDIR`\n  + `COMMAND_MKDIR`\n  + `COMMAND_RENAME`\n  + `COMMAND_RMDIR`\n  + `COMMAND_STEAM_METADATA`\n  + `COMMAND_STREAM_OPEN`\n  + `COMMAND_UNLINK`\n  + `COMMAND_URL_STAT`\n\n## Interceptors\n\nThe following interceptor is shipped with the package and ready to use in order\nto block any Phar invocation of files not having a `.phar` suffix. Besides that\nindividual interceptors are possible of course.\n\n```\nclass PharExtensionInterceptor implements Assertable\n{\n    /**\n     * Determines whether the base file name has a \".phar\" suffix.\n     *\n     * @param string $path\n     * @param string $command\n     * @return bool\n     * @throws Exception\n     */\n    public function assert(string $path, string $command): bool\n    {\n        if ($this-\u003ebaseFileContainsPharExtension($path)) {\n            return true;\n        }\n        throw new Exception(\n            sprintf(\n                'Unexpected file extension in \"%s\"',\n                $path\n            ),\n            1535198703\n        );\n    }\n\n    /**\n     * @param string $path\n     * @return bool\n     */\n    private function baseFileContainsPharExtension(string $path): bool\n    {\n        $baseFile = Helper::determineBaseFile($path);\n        if ($baseFile === null) {\n            return false;\n        }\n        $fileExtension = pathinfo($baseFile, PATHINFO_EXTENSION);\n        return strtolower($fileExtension) === 'phar';\n    }\n}\n```\n\n### ConjunctionInterceptor\n\nThis interceptor combines multiple interceptors implementing `Assertable`.\nIt succeeds when all nested interceptors succeed as well (logical `AND`).\n\n```\n\\TYPO3\\PharStreamWrapper\\Manager::initialize(\n    (new \\TYPO3\\PharStreamWrapper\\Behavior())\n        -\u003ewithAssertion(new ConjunctionInterceptor([\n            new PharExtensionInterceptor(),\n            new PharMetaDataInterceptor(),\n        ]))\n);\n```\n\n### PharExtensionInterceptor\n\nThis (basic) interceptor just checks whether the invoked Phar archive has\nan according `.phar` file extension. Resolving symbolic links as well as\nPhar internal alias resolving are considered as well.\n\n```\n\\TYPO3\\PharStreamWrapper\\Manager::initialize(\n    (new \\TYPO3\\PharStreamWrapper\\Behavior())\n        -\u003ewithAssertion(new PharExtensionInterceptor())\n);\n```\n\n### PharMetaDataInterceptor\n\nThis interceptor is actually checking serialized Phar meta-data against\nPHP objects and would consider a Phar archive malicious in case not only\nscalar values are found. A custom low-level `Phar\\Reader` is used in order to\navoid using PHP's `Phar` object which would trigger the initial vulnerability.\n\n```\n\\TYPO3\\PharStreamWrapper\\Manager::initialize(\n    (new \\TYPO3\\PharStreamWrapper\\Behavior())\n        -\u003ewithAssertion(new PharMetaDataInterceptor())\n);\n```\n\n## Reader\n\n* `Phar\\Reader::__construct(string $fileName)`: Creates low-level reader for Phar archive\n* `Phar\\Reader::resolveContainer(): Phar\\Container`: Resolves model representing Phar archive\n* `Phar\\Container::getStub(): Phar\\Stub`: Resolves (plain PHP) stub section of Phar archive\n* `Phar\\Container::getManifest(): Phar\\Manifest`: Resolves parsed Phar archive manifest as\n  documented at http://php.net/manual/en/phar.fileformat.manifestfile.php\n* `Phar\\Stub::getMappedAlias(): string`: Resolves internal Phar archive alias defined in stub\n  using `Phar::mapPhar('alias.phar')` - actually the plain PHP source is analyzed here\n* `Phar\\Manifest::getAlias(): string` - Resolves internal Phar archive alias defined in manifest\n  using `Phar::setAlias('alias.phar')`\n* `Phar\\Manifest::getMetaData(): string`: Resolves serialized Phar archive meta-data\n* `Phar\\Manifest::deserializeMetaData(): mixed`: Resolves deserialized Phar archive meta-data\n  containing only scalar values - in case an object is determined, an according\n  `Phar\\DeserializationException` will be thrown\n\n```\n$reader = new Phar\\Reader('example.phar');\nvar_dump($reader-\u003eresolveContainer()-\u003egetManifest()-\u003edeserializeMetaData());\n```\n\n## Helper\n\n* `Helper::determineBaseFile(string $path): string`: Determines base file that can be\n  accessed using the regular file system. For instance the following path\n  `phar:///home/user/bundle.phar/content.txt` would be resolved to\n  `/home/user/bundle.phar`.\n* `Helper::resetOpCache()`: Resets PHP's OPcache if enabled as work-around for\n  issues in `include()` or `require()` calls and OPcache delivering wrong\n  results. More details can be found in PHP's bug tracker, for instance like\n  https://bugs.php.net/bug.php?id=66569\n\n## Security Contact\n\nIn case of finding additional security issues in the TYPO3 project or in this\n`PharStreamWrapper` package in particular, please get in touch with the\n[TYPO3 Security Team](mailto:security@typo3.org).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypo3%2Fphar-stream-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypo3%2Fphar-stream-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypo3%2Fphar-stream-wrapper/lists"}