web-datafilter 0.2.0

Security-oriented Python library for detecting SQLi, SSTI and XSS payloads

DataFilter - документация

Автор: qwertyvs
Репозиторий: https://github.com/qwertyvs/DataFilter

Оглавление

• Кратко о проекте

• Установка

• Структура репозитория

• Ожидаемое поведение

  • Обычный пользователь
  • Нарушитель (злоумышленник)
  • Значения статусов

• Глобальные параметры

• Классы

  • DataFilterException
  • filterReport

• Функции

  • strSQLICheck()
  • strSSTICheck()
  • strXSSCheck()
  • strMultCheck()

• Пример использования

• Обратная связь

Кратко о проекте

DataFilter - это лёгкая библиотека на Python, предназначенная для анализа входных данных и обнаружения возможных попыток эксплуатации распространённых веб‑уязвимостей.

Библиотека умеет обнаруживать признаки:

• SQL Injection (SQLi)
• Server-Side Template Injection (SSTI)
• Cross-Site Scripting (XSS)

DataFilter выполняет статический анализ строк и ищет сигнатуры, характерные для вредоносных полезных нагрузок.

---

Установка

1. Установите библиотеку:

pip install web-datafilter

2. Импортируйте нужные функции:

import DataFilter

или

from DataFilter import ...

---

Структура репозитория

DataFilter
    ├── .gitignore
    ├── DataFilter.py
    ├── LICENCE
    ├── README.md
    ├── testWebApp.py
    ├── database.db
    └── requirements.txt

testWebApp.py - тестовое веб-приложение
requirements.txt - нужные для работы тестового веб-приложения библиотеки

---

Ожидаемое поведение

Обычный пользователь

Обычный пользователь отправляет обычные значения:

• имена пользователей
• email
• короткие текстовые поля

В этом случае библиотека должна вернуть:

status = OK
issecure = True

Нарушитель (злоумышленник)

Злоумышленник может отправлять вредоносные полезные нагрузки, например:

1' OR 1=1 --
<script>alert(1)</script>
{{7*7}}

В таких случаях библиотека должна вернуть:

status = FOUND
или
status = DETECTED

Значения статусов

Статус: Значение

OK: Подозрительных паттернов не обнаружено
FOUND*: Обнаружены подозрительные признаки
DETECTED: Высокая вероятность вредоносной нагрузки

* В strSQLICheck означает, что найдено ключевое слово sql, в контексте проверки осмысленного текста на английском языке является защитой от ложных срабатываний

---

Глобальные параметры

В библиотеке есть три глобальных параметра, отвечающих за защиту от слишком долгого выполнения регулярных выражений.

sqli_patern_time = 0.1
ssti_patern_time = 0.1
xss_patern_time = 0.2

Эти значения задают максимальное время выполнения одного regex‑паттерна в секундах.

Если выполнение превышает тайм‑аут, библиотека помечает это как:

dos_payload

Это может указывать на попытку ReDoS‑атаки (нагрузки через сложные регулярные выражения).

Если процессор досточно мощный можно уменьшить, переопределив в программе

---

Классы

DataFilterException

Внутреннее исключение библиотеки.

Возникает если:

• переданы неверные типы данных
• произошла внутренняя ошибка

Пример сообщения:

INVALID_INPUT: expected str

---

filterReport

Структура отчёта, возвращаемая всеми функциями проверки.

Поля:

Поле: Описание

data: исходная проверенная строка
type: тип проверки (SQLI / SSTI / XSS)
status: итоговый статус
detections: список сработавших сигнатур
issecure: True если строка считается безопасной
processtime: время выполнения проверки в наносекундах

---

Функции

В библиотеке есть три глобальных таймаута, которые определяют максимальное время выполнения одного regex-паттерна для каждой категории проверки. Вы можете изменить их в рантайме с помощью специальных функций.

set_sqli_timeout(value: float)

Устанавливает таймаут для проверки SQL Injection (SQLi).

Параметры:

• value — максимальное время выполнения одного паттерна в секундах. Должно быть положительным числом.

Пример использования:

from DataFilter import set_sqli_timeout

set_sqli_timeout(0.5)  # Таймаут 0.5 секунды для SQLi

---

set_ssti_timeout(value: float)

Устанавливает таймаут для проверки Server-Side Template Injection (SSTI).

Параметры:

• value — максимальное время выполнения одного паттерна в секундах. Должно быть положительным числом.

Пример использования:

from DataFilter import set_ssti_timeout

set_ssti_timeout(0.3)  # Таймаут 0.3 секунды для SSTI

---

set_xss_timeout(value: float)

Устанавливает таймаут для проверки Cross-Site Scripting (XSS).

Параметры:

• value — максимальное время выполнения одного паттерна в секундах. Должно быть положительным числом.

Пример использования:

from DataFilter import set_xss_timeout

set_xss_timeout(0.2)  # Таймаут 0.2 секунды для XSS

---

После изменения таймаута, соответствующие функции (strSQLICheck, strSSTICheck, strXSSCheck) будут использовать новое значение

---

strSQLICheck()

Проверяет строку на признаки SQL Injection.

Параметры:

data : str
allowedSymbols : str

Если параметр allowedSymbols задан и строка содержит символ вне этого набора, функция сразу возвращает:

status = DETECTED
detections = ["banned_symbol_usage"]

Функция ищет такие признаки SQL‑инъекций как:

• UNION SELECT
• SQL комментарии
• логические таутологии
• time‑based атаки
• ключевые SQL слова

Возвращает объект filterReport.

---

strSSTICheck()

Проверяет строку на Server-Side Template Injection.

Обнаруживает конструкции, используемые в шаблонизаторах.

Примеры:

{{ ... }}
{% ... %}
${ ... }
#{ ... }

Также ищет опасные вызовы:

eval()
exec()
os.popen()
Runtime.getRuntime()

Возвращает filterReport.

---

strXSSCheck()

Проверяет строку на признаки Cross-Site Scripting.

Перед анализом строка проходит нормализацию:

1. URL‑декодирование
2. декодирование HTML‑сущностей
3. удаление управляющих символов
4. нормализация Unicode

После этого выполняется поиск таких паттернов как:

• <script>
• протокол javascript:
• обработчики событий onload=
• <iframe>
• теги svg или math

Возвращает filterReport.

---

strMultCheck()

Позволяет выполнить несколько проверок сразу.

Пример:

strMultCheck(data, modes=["SQLI","SSTI","XSS"])

Возвращает словарь:

{
 "SQLI": filterReport,
 "SSTI": filterReport,
 "XSS": filterReport,
 "total_status": str,
 "total_issecure": bool,
 "total_processtime": int
}

---

Пример использования

from DataFilter import strMultCheck

payload = "1' OR 1=1 --"

result = strMultCheck(payload)

print(result["SQLI"].status)
print(result["total_status"])

---

Обратная связь

Контакты

Пожалуйста помните, что ни одно решение не является идеальным, и DataFilter - не исключение.

Если у вас есть вопросы или предложения, вы можете написать мне.
Я постараюсь ответить как только появится возможность (обычно в течение одного рабочего дня).

Спасибо за использование DataFilter!