xss-defender

XssDefender

Надёжная защита от XSS‑атак для современных веб‑приложений на TypeScript

XssDefender — это лёгкая TypeScript‑библиотека для детектирования и нейтрализации XSS‑векторов, включая Unicode‑обфусцированные скрипты, javascript:‑URL, data:‑URI, CSS‑expression() и десятки других приёмов, которые остаются актуальными и завтра.

Ключевые особенности

• Глубокая эвристика — расширенные регулярные выражения ловят даже нестандартные и смешанные регистром вставки.
• Гибкая конфигурация — разрешайте только нужные теги/атрибуты, управляйте логированием.
• Безопасность по умолчанию — если тег не разрешён, он будет либо удалён, либо закодирован.
• Полная типизация — написано на TypeScript, API удобно использовать в Node .js и браузере.
• Продуманное логирование — лаконичное или подробное, чтобы быстро разбирать реальные инциденты.
• Высокое покрытие тестами — десятки edge‑кейсов уже в репозитории.

Установка

npm i xss-defender
# или
yarn add xss-defender

Библиотека не имеет внешних зависимостей и легко встраивается в любую сборку.

Быстрый старт

import { XssDefender } from "xss-defender";

const defender = new XssDefender();

defender.sanitizeString(`<script>alert('XSS')</script>`);
// => ""

defender.hasXssRisks("<img src=x onerror=alert(1)>");
// => true

Кастомная конфигурация

import {
  XssDefender,
  DEFAULT_SANITIZATION_CONFIG,
  SanitizationConfig,
} from "xss-defender";

const config: Partial<SanitizationConfig> = {
  ...DEFAULT_SANITIZATION_CONFIG,
  allowedTags: ["p", "a"],
  allowedAttributes: ["href"],
  stripIgnoreTag: true,
  enableLogging: true,
  logFormat: "detailed",
};

const defender = new XssDefender(config);

API

Метод	Описание
sanitizeString(value)	Возвращает очищенную строку. null/undefined/"" → "".
hasXssRisks(value)	true, если в строке найден потенциальный XSS.
sanitizeObject(obj)	Рекурсивно проходит по объекту/массиву и очищает все строковые поля.
sanitizeHtmlForElement(el, html)	Безопасно устанавливает innerHTML DOM‑элемента.
checkUrlParams(params)	Анализирует URL‑параметры: { isSafe, issues[] }.
setConfig(partial)	Патч‑обновление конфигурации на лету.
getConfig()	Текущая конфигурация (readonly).

Параметры конфигурации

Поле	Тип	По умолчанию	Значение
allowedTags	string[]	список распространённых безопасных тегов	Какие теги оставить живыми.
allowedAttributes	string[]	["id","class","style","href","target","src"]	Разрешённые атрибуты для разрешённых тегов.
stripIgnoreTag	boolean	false	true — вырезать запрещённые теги, false — HTML‑кодировать их.
enableLogging	boolean	false	Включить консольное логирование.
logFormat	'simple' | 'detailed'	'simple'	Формат логов.

Совет: оставляйте stripIgnoreTag = true, если очищаете данные перед вставкой в DOM. Кодирование полезно при хранении/отображении «как есть».

Проверка URL‑параметров

const { isSafe, issues } = defender.checkUrlParams({
  search: "<script>alert(1)</script>",
  page: "2",
});

if (!isSafe) {
  console.warn("Опасные параметры!", issues);
}

Работа с React/Vue/Angular

sanitizeString подходит для любого UI‑фреймворка. Просто пропускайте туда данные, полученные от пользователя или API, прежде чем показать их в dangerouslySetInnerHTML / v-html / innerHTML.

Тесты

npm test

В репозитории лежат spec‑тесты на Jest (см. spec/core/xss-defender.spec.ts). Они демонстрируют работу со сложными нагрузками: смешанный регистр, скрытые комментарии, Unicode‑экранирование.

План развития

• 🔍 Расширяемые паттерны — возможность добавлять/отключать собственные регулярки.
• ⚙️ Web‑Worker режим для тяжёлых потоков очистки.
• 🧩 Плагины (например, отчёты Sentry).

Ваши PR и идеи приветствуются!

Вклад и поддержка

• Сделайте fork и создайте ветку feature/<название>.
• Запустите npm i и npm test — убедитесь, что все тесты зелёные.
• Оформите PR с описанием мотивации и изменений.

Перед отправкой не забудьте добавить/обновить тесты для новых сценариев.

Лицензия

MIT © 2025 — Вы.