tsec - Extended TypeScript compiler checking Trusted Types compatibility
This is not an officially supported Google product.
tsec is a wrapper for the official TypeScript compiler tsc with additional checks on the codebase's compatibility with Trusted Types.
tsec supports most compilation flags as tsc does. For code pattern patterns that is potentially incompatible with Trusted Types, tsec emits compilation errors.
Supported checks
tsec perform a basket of security checks to find possible XSS issues in your code. In particular, the checks ban using dangerous DOM sink APIs with plain string values. Any violation of the checks can hinder Trusted Types adoption either directly or indirectly. To fix the violations, you should construct Trusted Types values to feed into these sinks. At the moment, tsec covers most of the Trusted Types sinks that are enforced by the browser. See here for the complete list of available checks. We will be adding the missing ones soon.
Run
First add tsec as a dev dependency of your TypeScript project.
yarn add tsec --dev
Then choose the right configuration file to build the project with tsec and check its Trusted Types compatibility.
yarn tsec -p tsconfig.json
Add --noEmit
flag to skip emitting JS code from compilation.
Trusted Type awareness in tsec rules
Using Trusted Types in TypeScript has
a limitation and
currently you must use workarounds to TS compiler to bypass its checks. We've
implemented various patterns you can use in order to satisfy both tsc
and
tsec
rules.
Casting Trusted Type to unknown to string
For example:
declare const trustedHTML: TrustedHTML;
// the next line will be allowed by both tsc and tsec
document.body.innerHTML = trustedHTML as unknown as string;
Using Trusted Type union with string and casting to string
For example:
// such value can be created if application uses string as a fallback when
// Trusted Types are not enabled/supported
declare const trustedHTML: TrustedHTML | string;
// the next line will be allowed by both tsc and tsec
document.body.innerHTML = trustedHTML as string;
Using unwrapper function
The first argument to the unwrapper function must be the Trusted Type that is required by the specific sink and must return value accepted by the sink (string). The unwrapper function can have additional arguments or even accept TS union of values for the first parameter.
For example:
declare const trustedHTML: TrustedHTML;
declare const unwrapHTML: (html: TrustedHTML, ...other: any[]) => string;
// the next line will be allowed by both tsc and tsec
document.body.innerHTML = unwrapHTML(trustedHTML);
Note: All of these variants must be at the assignment/call of the particular sink and not before. For example:
declare const trustedHTML: TrustedHTML;
// cast before the actual usage in sink
const castedTrustedHTML = trustedHTML as unknown as string;
// tsec is flow insensitive and treats `castedTrustedHTML` as a regular string
document.body.innerHTML = castedTrustedHTML; // tsec violation!
Language service plugin
Tsec can be integrated as a plugin to your TypeScript project allowing you to see the violations directly in your IDE. For this to work you need to:
-
Use workspace version of TypeScript
-
Add the plugin via plugins compiler option in the tsconfig. If you are using tsec as a package then the path to the plugin might look like this:
{ "compilerOptions": { "plugins": [ { "name": "tsec" } ] } }
-
Restart the editor to reload TS initialization features.
Make sure the LSP is using (requiring) the same workspace version of TS used by the IDE.
Debugging
Language service plugin is experimental, if it doesn't work, you can create an issue or try to debug locally. If you are using VSCode you can do so by following these steps:
-
Turn on
verbose
tsserver logging in the settings. -
Restart the IDE. You can use
Developer: Reload Window
command for this. -
Use
Developer: Open Logs Folder
to open the log folder -
Find
tsserver.log
inside the folder (you can usefind
command line utility) and open the file(s). There should be an error somewhere in the logs which should get you started.
Configure exemptions
You can configure tsec to exempt certain violations. Add an "exemptionConfig"
option in the configuration for the tsec language service plugin. The value of
that field is a string indicating the path to the exemption list, relative to
the path of tsconfig.json
. See an exemption below.
{
"compilerOptions": {
"plugins": [
{
"name": "tsec",
"exemptionConfig": "./exemption_list.json"
}
]
}
}
Note that although this configuration appears to be for the language service plugin, it also works for the command line use of tsec.
The exemption list is a JSON file of which each entry is the name of a rule. The value of the entry is a list of files that you would like to exempt from that rule.
Here is an example. Suppose you have a file src/foo.ts
in your project that
triggers the following error from tsec:
src/foo.ts:10:5 - error TS21228: Assigning directly to Element#innerHTML can result in XSS vulnerabilities.
10 element.innerHTML = someVariable;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can exempt it by creating an exemption_list.json
file along side your
tsconfig.json
with the following content:
{
"ban-element-innerhtml-assignments": ["src/foo.ts"]
}
The exemption list supports the glob syntax. For example, if you want to completely disable a check, you can write:
{
"ban-element-innerhtml-assignments": ["**/*.ts"]
}
Note that exemptions are granted at the file granularity. If you exempt a file from a rule, all violations in that file will be exempted.
You can exempt files from all rules by setting the exemption list for the
wildcard rule name "*"
. This can be useful when the compiler configuration of
your project include files for testing.
{
"*": ["**/test/*.ts", "**/*.test.ts", "**/*.spec.ts"]
}
Developing locally
We recommend developing using VS Code. We have
preconfigured the project such that debugging works out of the box. If you press
F5 (Debug: Start debugging) tsec
will be freshly built and executed on the
project files (files included in tsconfig). Currently, we have tests only
internally at Google, but you can create a test.ts
file with some violationg
code anywhere in the project to get started. You can then add breakpoints in any
tsec source file.
Contributing
See CONTRIBUTING.md.