Metadata-Version: 2.4
Name: web-datafilter
Version: 0.1.3
Summary: Security-oriented Python library for detecting SQLi, SSTI and XSS payloads
Author-email: qwertyvs <NuhUh@gmail.com>
License: MIT
Keywords: security,sqli,xss,ssti,input-validation
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: regex
Dynamic: license-file

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

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

## Оглавление

* [Кратко о проекте](#Кратко-о-проекте)
* [Установка](#установка)
* [Структура репозитория](#структура-репозитория)
* [Ожидаемое поведение](#ожидаемое-поведение)

  * [Обычный пользователь](#обычный-пользователь)
  * [Нарушитель (злоумышленник)](#нарушитель-злоумышленник)
  * [Значения статусов](#значения-статусов)
* [Глобальные параметры](#глобальные-параметры)
* [Классы](#классы)

  * [DataFilterException](#datafilterexception)
  * [filterReport](#filterreport)
* [Функции](#функции)

  * [strSQLICheck()](#strsqlicheck)
  * [strSSTICheck()](#strssticheck)
  * [strXSSCheck()](#strxsscheck)
  * [strMultCheck()](#strmultcheck)
* [Пример использования](#пример-использования)
* [Обратная связь](#обратная-связь)

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

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

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

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

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

------------------------------------------------------------------------

# Установка

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

``` bash
pip install web-datafilter
```

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

``` python
import DataFilter

или

from DataFilter import ...
```

------------------------------------------------------------------------

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

DataFilter<br>
&nbsp;&nbsp;&nbsp;&nbsp;├── .gitignore<br>
&nbsp;&nbsp;&nbsp;&nbsp;├── DataFilter.py<br>
&nbsp;&nbsp;&nbsp;&nbsp;├── LICENCE<br>
&nbsp;&nbsp;&nbsp;&nbsp;├── README.md<br>
&nbsp;&nbsp;&nbsp;&nbsp;├── testWebApp.py<br>
&nbsp;&nbsp;&nbsp;&nbsp;├── database.db<br>
&nbsp;&nbsp;&nbsp;&nbsp;└── requirements.txt

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

------------------------------------------------------------------------

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

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

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

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

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

    status = OK
    issecure = True

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

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

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

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

    status = FOUND
    или
    status = DETECTED

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

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

OK: Подозрительных паттернов не обнаружено<br>
FOUND*: Обнаружены подозрительные признаки<br>
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: исходная проверенная строка<br>
type: тип проверки (SQLI / SSTI / XSS)<br>
status: итоговый статус<br>
detections: список сработавших сигнатур<br>
issecure: True если строка считается безопасной<br>
processtime: время выполнения проверки в наносекундах

------------------------------------------------------------------------

# Функции

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

## set_sqli_timeout(value: float)

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

**Параметры:**

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

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

```python
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` — максимальное время выполнения одного паттерна в секундах. Должно быть положительным числом.

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

```python
from DataFilter import set_ssti_timeout

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

---

## set_xss_timeout(value: float)

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

**Параметры:**

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

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

```python
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()

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

Пример:

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

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

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

------------------------------------------------------------------------

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

``` python
from DataFilter import strMultCheck

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

result = strMultCheck(payload)

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

------------------------------------------------------------------------

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

## Контакты

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

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

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