@weizman/shield
v0.0.1
Published
Shield your DOM against clobbering attacks effortlessly
Downloads
11
Readme
Shield JS 🛡
Shield (npm) is a tiny JavaScript shim/library that applies protection against DOM Clobbering attacks at runtime with close to zero integration friction.
See for yourself - visit live demo/playground
Installation
Include Shield via a script tag:
<script src="https://cdn.jsdelivr.net/npm/@weizman/shield/shield.min.js"></script>
That's it.
It's best to include it as close as possible to the beginning of the <head>
(the earliest it runs, the better it protects).
Usage
Shield supports optional configuration:
<script src="https://cdn.jsdelivr.net/npm/@weizman/shield/shield.min.js"
allowlist="id1,id2"
reportOnly="false"
reportTo="https://report-server/report/"
></script>
allowlist
- a list of ids you allow to be clobbered into the DOM (shield will overlook them when applying its protection).reportOnly
- whether to report forbidden access attempt or to throw an error. If enabled,reportTo
must also be provided.reportTo
- a validhttps:
URL to report forbidden access attempt to in casereportOnly
is enabled (CSP format):
{
"csp-report": {
"blocked-property": "id3",
"disposition": "report",
"document-uri": "https://my-app.com/some-route/",
"effective-directive": "dom-clobbering",
"original-policy": "no-access",
"referrer": "https://my-app.com/some-route/",
"violated-directive": "dom-clobbering"
}
}
Result
Shield will collect the values of all id/name properties that were introduced to DOM at runtime and will redefine
them on the window
to throw an error when JavaScript code attempts to access them.
That's because while we use id/name attributes for our DOM nodes, we don't expect JavaScript code to access them, so when this happens it can only be done by a malicious entity - and that's what Shield blocks:
Unless the id/name was explicitly provided via the allowlist
argument, which in that case Shield will allow JavaScript to access it:
Making Shield a very simple and elegant solution that requires you to do nothing but include the script in your app - shield will do the rest!
About
- EXPERIMENTAL ⚠️ - Use at your own risk
- Compressed online using https://www.toptal.com/developers/javascript-minifier
- By Gal Weizman