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 и идеи приветствуются!

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

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

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

Лицензия

MIT © 2025 — Вы.