Using this package? Please consider donating to support my open source work ❤️
Help @kitajs/ts-html-plugin grow! Star and share this amazing repository with your friends and co-workers!
🏛️ KitaJS TypeScript Html Plugin
@kitajs/ts-html-plugin is a CLI tool & TypeScript LSP for finding XSS vulnerabilities in your TypeScript code.
- [Installing](#installing)
- [Preview](#preview)
- [Getting Started](#getting-started)
- [Running as CLI](#running-as-cli)
- [Handling Warnings](#handling-warnings)
- [Vscode](#vscode)
- [Error codes](#error-codes)
- [K601](#k601)
- [K602](#k602)
- [K603](#k603)
- [K604](#k604)
- [JSX](#jsx)
- [Special cases](#special-cases)
## Installing
```sh
npm install @kitajs/ts-html-plugin
```
## Preview
## Getting Started
Install `@kitajs/html` alongside `@kitajs/ts-html-plugin` with your favorite package
manager, and put this inside your `tsconfig.json`.
```jsonc
// tsconfig.json
{
"compilerOptions": {
"jsx": "react",
"jsxFactory": "Html.createElement",
"jsxFragmentFactory": "Html.Fragment",
"plugins": [{ "name": "@kitajs/ts-html-plugin" }]
}
}
```
[Make sure to understand what language service plugins can and cannot do.](https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin#whats-a-language-service-plugin)
## Running as CLI
You can also run this project as a CLI tool. Which is a great way to ensue project-wide
security. Also it's a great way to integrate with your CI/CD pipeline.
```sh
npm install -g @kitajs/ts-html-plugin
```
```sh
$ xss-scan --help
ts-html-plugin v1.3.1 - A CLI tool & TypeScript LSP for finding XSS vulnerabilities in your TypeScript code.
Usage: xss-scan [options] ...
ts-html-plugin [options] ...
Options:
--cwd The current working directory to use (defaults to process.cwd())
-p, --project The path to the tsconfig.json file to use (defaults to 'tsconfig.json')
-s, --simplified Use simplified diagnostics
-h, --help Show this help message
--version Show the version number
... The files to check (defaults to all files in tsconfig.json)
Examples:
$ xss-scan
$ xss-scan --cwd src
$ xss-scan --project tsconfig.build.json
$ xss-scan src/index.tsx src/App.tsx
Exit codes:
0 - No XSS vulnerabilities were found
1 - XSS vulnerabilities were found
2 - Only XSS warnings were found
```
## Handling Warnings
Sometimes, the plugin may not detect that a string or variable is safe for use and may
emit warnings, even when you are confident there are no security issues. Here are ways to
address this:
1. **Keep using use the `safe` Attribute:** Even if you are certain that the content is
free from XSS vulnerabilities, you can still use the `safe` attribute for added
assurance. After all, what's the problem of being safe twice?
```tsx
const html = {content}
;
```
2. **Prepend the Variable with `safe`:** Indicate to the plugin that you are confident the
variable is safe to use by adding `safe` before it.
```tsx
const safeContent = '';
const html = {safeContent}
;
```
3. **Cast to `'safe'`:** When using raw values or function calls without saving them into
a variable, you can append `as 'safe'` to the expression to inform the plugin.
```tsx
const html = {content as 'safe'}
;
```
## Vscode
If you are using vscode and this plugin is not working properly, make sure to use the
current project's typescript version.
```jsonc
// .vscode/settings.json
{
"typescript.tsdk": "node_modules/typescript/lib",
"typescript.enablePromptUseWorkspaceTsdk": true
}
```
## Error codes
### K601
Usage of JSX expression without safe attribute. This could lead to XSS vulnerabilities.
Please use the safe attribute on the JSX element or prepend your variable with `safe`.
```tsx
// ❌ Content variable may have a value of ``
// which will lead to XSS vulnerabilities.
const html = {content}
;
// ✅ Content variable may have a value of ``,
// but it's safe to use because it will get escaped to =
// `<script>alert('xss')</script>`.
const html = {content}
;
// ⚠️ Content variable may have a value of ``,
// but variable starts with safe, so the error is suppressed.
const safeContent = content;
const html = {safeContent}
;
```
### K602
Usage of safe attribute on a JSX element whose children contains other JSX elements. It
will lead to double escaping. If this is intended behavior, please extract the children
into a separate variable and use that instead.
```tsx
// ❌ Safe attribute in the outer element will also escape inner elements.
// In this // case the tag will also be escaped, resulting into
// `<b>1</b>`.
const html = (
1
);
// ✅ Safe attribute in the inner element will escape only the inner element.
// In this case the tag will be escaped, resulting into
// `1`.
const html = (
1
);
```
### K603
You are using a xss-prone element as a children of a component. Please wrap it into a
Html.escapeHtml() call or prepend it as a variable starting with `safe`.
This error is similar to [K601](#k601), but instead of using `safe` native attribute, you
need to use `Html.escapeHtml()` function because its a component and not a native JSX.
```tsx
// ❌ Content variable may have a value of ``
// which will lead to XSS vulnerabilities.
const html = {content};
// ✅ Content variable may have a value of ``,
// but it's safe to use because you manually call the escape function.
const html = {Html.escapeHtml(content)};
// ⚠️ Content variable may have a value of ``,
// but variable starts with safe, so the error is suppressed.
const safeContent = content;
const html = {safeContent};
```
### K604
You are using the safe attribute on expressions that does not contain any XSS
vulnerabilities. Please remove the safe attribute or prepend your variable with `unsafe`.
```tsx
// ⚠️ The variable will never have any harmful XSS content, so the safe attribute is
// not needed and can be removed.
const html = {numberVariable}
;
// ✅ This variable will never have any harmful XSS content, so we can use it
// as is.
const html = {numberVariable}
;
// ✅ You manually told this plugin that the variable is unsafe, so errors will
// be thrown.
const unsafeVariable = numberVariable;
const html = {unsafeVariable}
;
```
## JSX
For JSX support, please go to [kitajs/html](https://github.com/kitajs/html) for more
information.
## Special cases
1. Anything inside a `;
```
2. Ternary and binary operations are evaluated in both sides separately and will throw
errors if any of the sides is not safe, even their condition never gets hit at runtime.
```tsx
const html = {true ? safeContent : content}
;
// ~~~~~~~
```
