PHP Phar Stream Wrapper
Abstract & History
Based on Sam Thomas' findings concerning insecure deserialization in combination with obfuscation strategies allowing to hide Phar files inside valid image resources, the TYPO3 project decided back then to introduce a PharStreamWrapper to intercept invocations of the phar:// stream in PHP and only allow usage for defined locations in the file system.
Since the TYPO3 mission statement is inspiring people to share, we thought it would be helpful for others to release our PharStreamWrapper as standalone package to the PHP community.
The mentioned security issue was reported to TYPO3 on 10th June 2018 by Sam Thomas and has been addressed concerning the specific attack vector and for this generic PharStreamWrapper in TYPO3 versions 7.6.30 LTS, 8.7.17 LTS and 9.3.1 on 12th July 2018.
- https://blog.secarma.co.uk/labs/near-phar-dangerous-unserialization-wherever-you-are
- https://youtu.be/GePBmsNJw6Y
- https://typo3.org/security/advisory/typo3-psa-2018-001/
- https://typo3.org/security/advisory/typo3-psa-2019-007/
- https://typo3.org/security/advisory/typo3-psa-2019-008/
License
In general the TYPO3 core is released under the GNU General Public License version 2 or any later version (GPL-2.0-or-later). In order to avoid licensing issues and incompatibilities this PharStreamWrapper is licenced under the MIT License. In case you duplicate or modify source code, credits are not required but really appreciated.
Credits
Thanks to Alex Pott, Drupal for creating back-ports of all sources in order to provide compatibility with PHP v5.3.
Installation
The PharStreamWrapper is provided as composer package typo3/phar-stream-wrapper and has minimum requirements of PHP v5.3 (v2 branch) and PHP v7.0 (master branch).
Installation for PHP v7.0
composer require typo3/phar-stream-wrapper ^3.0
Installation for PHP v5.3
composer require typo3/phar-stream-wrapper ^2.0
Example
The following example is bundled within this package, the shown PharExtensionInterceptor denies all stream wrapper invocations files not having the .phar suffix. Interceptor logic has to be individual and adjusted to according requirements.
\TYPO3\PharStreamWrapper\Manager::initialize(
(new \TYPO3\PharStreamWrapper\Behavior())
->withAssertion(new \TYPO3\PharStreamWrapper\Interceptor\PharExtensionInterceptor())
);
if (in_array('phar', stream_get_wrappers())) {
stream_wrapper_unregister('phar');
stream_wrapper_register('phar', \TYPO3\PharStreamWrapper\PharStreamWrapper::class);
}
PharStreamWrapperdefined as class reference will be instantiated each timephar://streams shall be processed.Manageras singleton pattern being called byPharStreamWrapperinstances in order to retrieve individual behavior and settings.Behaviorholds reference to interceptor(s) that shall assert correct/allowed invocation of a given$pathfor a given$command. Interceptors implement the interfaceAssertable. Interceptors can act individually on following commands or handle all of them in case not defined specifically:COMMAND_DIR_OPENDIRCOMMAND_MKDIRCOMMAND_RENAMECOMMAND_RMDIRCOMMAND_STEAM_METADATACOMMAND_STREAM_OPENCOMMAND_UNLINKCOMMAND_URL_STAT
Interceptors
The following interceptor is shipped with the package and ready to use in order to block any Phar invocation of files not having a .phar suffix. Besides that individual interceptors are possible of course.
class PharExtensionInterceptor implements Assertable
{
/**
* Determines whether the base file name has a ".phar" suffix.
*
* @param string $path
* @param string $command
* @return bool
* @throws Exception
*/
public function assert(string $path, string $command): bool
{
if ($this->baseFileContainsPharExtension($path)) {
return true;
}
throw new Exception(
sprintf(
'Unexpected file extension in "%s"',
$path
),
1535198703
);
}
/**
* @param string $path
* @return bool
*/
private function baseFileContainsPharExtension(string $path): bool
{
$baseFile = Helper::determineBaseFile($path);
if ($baseFile === null) {
return false;
}
$fileExtension = pathinfo($baseFile, PATHINFO_EXTENSION);
return strtolower($fileExtension) === 'phar';
}
}
ConjunctionInterceptor
This interceptor combines multiple interceptors implementing Assertable. It succeeds when all nested interceptors succeed as well (logical AND).
\TYPO3\PharStreamWrapper\Manager::initialize(
(new \TYPO3\PharStreamWrapper\Behavior())
->withAssertion(new ConjunctionInterceptor([
new PharExtensionInterceptor(),
new PharMetaDataInterceptor(),
]))
);
PharExtensionInterceptor
This (basic) interceptor just checks whether the invoked Phar archive has an according .phar file extension. Resolving symbolic links as well as Phar internal alias resolving are considered as well.
\TYPO3\PharStreamWrapper\Manager::initialize(
(new \TYPO3\PharStreamWrapper\Behavior())
->withAssertion(new PharExtensionInterceptor())
);
PharMetaDataInterceptor
This interceptor is actually checking serialized Phar meta-data against PHP objects and would consider a Phar archive malicious in case not only scalar values are found. A custom low-level Phar\Reader is used in order to avoid using PHP's Phar object which would trigger the initial vulnerability.
\TYPO3\PharStreamWrapper\Manager::initialize(
(new \TYPO3\PharStreamWrapper\Behavior())
->withAssertion(new PharMetaDataInterceptor())
);
Reader
Phar\Reader::__construct(string $fileName): Creates low-level reader for Phar archivePhar\Reader::resolveContainer(): Phar\Container: Resolves model representing Phar archivePhar\Container::getStub(): Phar\Stub: Resolves (plain PHP) stub section of Phar archivePhar\Container::getManifest(): Phar\Manifest: Resolves parsed Phar archive manifest as documented at http://php.net/manual/en/phar.fileformat.manifestfile.phpPhar\Stub::getMappedAlias(): string: Resolves internal Phar archive alias defined in stub usingPhar::mapPhar('alias.phar')- actually the plain PHP source is analyzed herePhar\Manifest::getAlias(): string- Resolves internal Phar archive alias defined in manifest usingPhar::setAlias('alias.phar')Phar\Manifest::getMetaData(): string: Resolves serialized Phar archive meta-dataPhar\Manifest::deserializeMetaData(): mixed: Resolves deserialized Phar archive meta-data containing only scalar values - in case an object is determined, an accordingPhar\DeserializationExceptionwill be thrown
$reader = new Phar\Reader('example.phar');
var_dump($reader->resolveContainer()->getManifest()->deserializeMetaData());
Helper
Helper::determineBaseFile(string $path): string: Determines base file that can be accessed using the regular file system. For instance the following pathphar:///home/user/bundle.phar/content.txtwould be resolved to/home/user/bundle.phar.Helper::resetOpCache(): Resets PHP's OPcache if enabled as work-around for issues ininclude()orrequire()calls and OPcache delivering wrong results. More details can be found in PHP's bug tracker, for instance like https://bugs.php.net/bug.php?id=66569
Security Contact
In case of finding additional security issues in the TYPO3 project or in this PharStreamWrapper package in particular, please get in touch with the TYPO3 Security Team.
![[TASK] Silence PHP opcache warnings](https://avatars.githubusercontent.com/u/1081870?v=4)
9 Oct 21, 2022
4.4k Jan 2, 2023
3k Jan 4, 2023
2.4k Jan 7, 2023
384 Dec 13, 2022
1.2k Dec 25, 2022
165 Nov 10, 2022
170 Dec 25, 2022
40 Aug 20, 2022
31.1k Jan 8, 2023
52 Nov 28, 2022
6 Aug 19, 2022
8 Oct 7, 2022
4 Jan 9, 2022
1 Oct 12, 2021
2 Nov 3, 2021
192 Dec 17, 2022
541 Dec 30, 2022