{"id":19109272,"url":"https://github.com/typo3/html-sanitizer","last_synced_at":"2025-05-08T21:24:31.043Z","repository":{"id":43732558,"uuid":"383434825","full_name":"TYPO3/html-sanitizer","owner":"TYPO3","description":"HTML sanitizer, written in PHP, aiming to provide XSS-safe markup based on explicitly allowed tags, attributes and values.","archived":false,"fork":false,"pushed_at":"2023-11-14T07:58:37.000Z","size":189,"stargazers_count":25,"open_issues_count":9,"forks_count":13,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-05-02T05:26:27.464Z","etag":null,"topics":["html","parser","php","sanitization","security","xss"],"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":"2021-07-06T10:50:14.000Z","updated_at":"2024-06-18T15:17:22.683Z","dependencies_parsed_at":"2024-06-18T15:17:18.653Z","dependency_job_id":null,"html_url":"https://github.com/TYPO3/html-sanitizer","commit_stats":{"total_commits":78,"total_committers":9,"mean_commits":8.666666666666666,"dds":"0.21794871794871795","last_synced_commit":"f8b9c466a08fe4b7bd32b4b8dbde5cf7fbfa9956"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TYPO3%2Fhtml-sanitizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TYPO3%2Fhtml-sanitizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TYPO3%2Fhtml-sanitizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TYPO3%2Fhtml-sanitizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TYPO3","download_url":"https://codeload.github.com/TYPO3/html-sanitizer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238044093,"owners_count":19407128,"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":["html","parser","php","sanitization","security","xss"],"created_at":"2024-11-09T04:19:46.380Z","updated_at":"2025-02-10T02:09:06.223Z","avatar_url":"https://github.com/TYPO3.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"![tests](https://github.com/TYPO3/html-sanitizer/actions/workflows/tests.yml/badge.svg)\n\n# TYPO3 HTML Sanitizer\n\n\u003e :information_source: Common safe HTML tags \u0026 attributes as given in\n\u003e [`\\TYPO3\\HtmlSanitizer\\Builder\\CommonBuilder`](src/Builder/CommonBuilder.php)\n\u003e still might be adjusted, extended or rearranged to more specific builders.\n\n## In a Nutshell\n\nThis `typo3/html-sanitizer` package aims to be a standalone component that can be used by any PHP-based\nproject or library. Albeit it is released within the TYPO3 namespace, it is agnostic to specifics of\n[TYPO3 CMS](https://github.com/typo3/typo3).\n\n+ [`\\TYPO3\\HtmlSanitizer\\Behavior`](src/Behavior.php) contains declarative settings for\n  a particular process for sanitizing HTML.\n+ [`\\TYPO3\\HtmlSanitizer\\Visitor\\VisitorInterface`](src/Visitor/VisitorInterface.php)\n  (multiple different visitors can exist at the same time) are actually doing the work\n  based on the declared `Behavior`. Visitors can modify nodes or mark them for deletion.\n+ [`\\TYPO3\\HtmlSanitizer\\Sanitizer`](src/Sanitizer.php) can be considered as the working\n  instance, invoking visitors, parsing and serializing HTML. In general this instance does\n  not contain much logic on how to handle particular nodes, attributes or values\n+ [`\\TYPO3\\HtmlSanitizer\\Builder\\BuilderInterface`](src/Builder/BuilderInterface.php) can\n  be used to create multiple different builder instances - in terms of \"presets\" - which\n  combine declaring a particular `Behavior`, initialization of `VisitorInterface` instances,\n  and finally returning a ready-to-use `Sanitizer` instance\n\n## Installation\n\n```bash\ncomposer req typo3/html-sanitizer\n```\n\n## Example \u0026 API\n\n```php\n\u003c?php\nuse TYPO3\\HtmlSanitizer\\Behavior;\nuse TYPO3\\HtmlSanitizer\\Behavior\\NodeInterface;\nuse TYPO3\\HtmlSanitizer\\Sanitizer;\nuse TYPO3\\HtmlSanitizer\\Visitor\\CommonVisitor;\n\nrequire_once 'vendor/autoload.php';\n\n$commonAttrs = [\n    new Behavior\\Attr('id'),\n    new Behavior\\Attr('class'),\n    new Behavior\\Attr('data-', Behavior\\Attr::NAME_PREFIX),\n];\n$hrefAttr = (new Behavior\\Attr('href'))\n    -\u003eaddValues(new Behavior\\RegExpAttrValue('#^https?://#'));\n\n// attention: only `Behavior` implementation uses immutability\n// (invoking `withFlags()` or `withTags()` returns new instance)\n$behavior = (new Behavior())\n    -\u003ewithFlags(Behavior::ENCODE_INVALID_TAG | Behavior::ENCODE_INVALID_COMMENT)\n    -\u003ewithoutNodes(new Behavior\\Comment())\n    -\u003ewithNodes(new Behavior\\CdataSection())\n    -\u003ewithTags(\n        (new Behavior\\Tag('div', Behavior\\Tag::ALLOW_CHILDREN))\n            -\u003eaddAttrs(...$commonAttrs),\n        (new Behavior\\Tag('a', Behavior\\Tag::ALLOW_CHILDREN))\n            -\u003eaddAttrs(...$commonAttrs)\n            -\u003eaddAttrs($hrefAttr-\u003ewithFlags(Behavior\\Attr::MANDATORY)),\n        (new Behavior\\Tag('br'))\n    )\n    -\u003ewithNodes(\n        (new Behavior\\NodeHandler(\n            new Behavior\\Tag('typo3'),\n            new Behavior\\Handler\\ClosureHandler(\n                static function (NodeInterface $node, ?DOMNode $domNode): ?DOMNode {\n                    return $domNode === null\n                        ? null\n                        : new DOMText(sprintf('%s says: \"%s\"',\n                            strtoupper($domNode-\u003enodeName),\n                            $domNode-\u003etextContent\n                        ));\n                }\n            )\n        ))\n    );\n\n$visitors = [new CommonVisitor($behavior)];\n$sanitizer = new Sanitizer($behavior, ...$visitors);\n\n$html = \u003c\u003c\u003c EOH\n\u003cdiv id=\"main\"\u003e\n    \u003ctypo3\u003eInspiring People To Share\u003c/typo3\u003e\n    \u003c!-- will be encoded, due to Behavior::ENCODE_INVALID_COMMENT --\u003e\n    \u003ca class=\"no-href\"\u003einvalidated, due to missing mandatory `href` attr\u003c/a\u003e\n    \u003ca href=\"https://typo3.org/\" data-type=\"url\" wrong-attr=\"is-removed\"\u003eTYPO3\u003c/a\u003e\u003cbr\u003e\n    (the \u003cspan\u003eSPAN, SPAN, SPAN\u003c/span\u003e tag shall be encoded to HTML entities)\n\u003c/div\u003e\nEOH;\n\necho $sanitizer-\u003esanitize($html);\n```\n\nwill result in the following sanitized output\n\n```html\n\u003cdiv id=\"main\"\u003e\n    TYPO3 says: \"Inspiring People To Share\"\n    \u0026lt;!-- will be encoded, due to Behavior::ENCODE_INVALID_COMMENT --\u0026gt;\n    \u0026lt;a class=\"no-href\"\u0026gt;invalidated, due to missing mandatory `href` attr\u0026lt;/a\u0026gt;\n    \u003ca href=\"https://typo3.org/\" data-type=\"url\"\u003eTYPO3\u003c/a\u003e\u003cbr\u003e\n    (the \u0026lt;span\u0026gt;SPAN, SPAN, SPAN\u0026lt;/span\u0026gt; tag shall be encoded to HTML entities)\n\u003c/div\u003e\n```\n\n### :information_source: Changes\n\n* since `v2.1.0` newly introduced nodes `Behavior\\Comment` and  `Behavior\\CdataSection` are enabled per\n  default for backward compatibility reasons, use e.g. `$behavior-\u003ewithoutNodes(new Behavior\\Comment())`\n  to remove them (later versions of this package won't have this fallback anymore)\n* since `v2.1.0` it is suggested to provide a `\\TYPO3\\HtmlSanitizer\\Behavior` when creating a\n  new instance of `\\TYPO3\\HtmlSanitizer\\Sanitizer`, e.g. `new Sanitizer($behavior, ...$visitors)`\n\nFind more details on all changes in [UPGRADING.md](UPGRADING.md).\n\n### `Behavior` flags\n\n* `Behavior::ENCODE_INVALID_TAG` keeps invalid tags, but \"disarms\" them (see `\u003cspan\u003e` in example)\n* `Behavior::ENCODE_INVALID_ATTR` keeps invalid attributes, but \"disarms\" the whole(!) tag\n* `Behavior::ENCODE_INVALID_COMMENT` \"disarms\" unexpected HTML comments by completely encoding them\n* `Behavior::ENCODE_INVALID_CDATA_SECTION` \"disarms\" unexpected HTML CDATA sections by completely encoding them\n* `Behavior::REMOVE_UNEXPECTED_CHILDREN` removes children for `Tag` entities that were created\n  without explicitly using `Tag::ALLOW_CHILDREN`, but actually contained child nodes\n* `Behavior::ALLOW_CUSTOM_ELEMENTS` allow using custom elements (having a hyphen `-`) - however,\n  it is suggested to explicitly name all known and allowed tags and avoid using this flag\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 package is licenced under the MIT License. In case  you\nduplicate or modify source code, credits are not required but really appreciated.\n\n## Local Testing\n\nComposer project [oliverhader/html-sanitizer-demo](https://github.com/ohader/html-sanitizer-demo)\noffers a local development server to ease manual testing for potentially vulnerable XSS payloads.\n\n## Security Contact\n\nIn case of finding additional security issues in the TYPO3 project or in this package in particular,\nplease get in touch with the [TYPO3 Security Team](mailto:security@typo3.org), or directly\n[report a vulnerability via GitHub](https://github.com/TYPO3/html-sanitizer/security/advisories/new).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypo3%2Fhtml-sanitizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypo3%2Fhtml-sanitizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypo3%2Fhtml-sanitizer/lists"}