Skip to content

xss-protection-guidelines.md

Latest commit

 

History

History
323 lines (227 loc) · 8.78 KB

xss-protection-guidelines.md

File metadata and controls

323 lines (227 loc) · 8.78 KB
Raw

XSS Protection Guidelines for MikoPBX Modules

Overview

Cross-Site Scripting (XSS) защита является критически важной для безопасности веб-интерфейса MikoPBX. Данные рекомендации основаны на применённых подходах в системе и должны соблюдаться при разработке новых модулей.

1. PHP Backend Protection

SecurityHelper Class

Используйте класс SecurityHelper для контекстно-зависимого экранирования:

use MikoPBX\AdminCabinet\Library\SecurityHelper;

// HTML контекст
$safeHtml = SecurityHelper::escapeHtml($userInput);

// JavaScript строки
$safeJs = SecurityHelper::escapeJs($userInput);

// URL параметры
$safeUrl = SecurityHelper::escapeUrl($userInput);

// CSS значения
$safeCss = SecurityHelper::escapeCss($userInput);

// HTML атрибуты
$safeAttr = SecurityHelper::escapeAttribute($userInput);

В Volt шаблонах

Всегда используйте автоматическое экранирование:

{# Рекомендуется - автоматическое экранирование #}
{{ userInput|e }}

{# Для сложных случаев #}
{{ userInput|escape('html') }}
{{ userInput|escape('js') }}
{{ userInput|escape('url') }}

Проверка опасного контента

// Проверить на наличие опасных паттернов
if (SecurityHelper::containsDangerousContent($input)) {
    // Дополнительная валидация или логирование
    $safeInput = SecurityHelper::escapeHtml($input);
}

Санитизация имён файлов

$safeFilename = SecurityHelper::sanitizeFilename($userFilename);

2. JavaScript Frontend Protection

SecurityUtils Class

Используйте глобальный класс SecurityUtils для безопасного отображения:

// Базовое экранирование HTML
const safeContent = SecurityUtils.escapeHtml(userInput);

// С разрешением безопасных иконок
const safeContentWithIcons = SecurityUtils.escapeHtml(userInput, true);

// Для атрибутов
const safeAttr = SecurityUtils.sanitizeAttribute(userInput);

// Для dropdown элементов (строгий режим)
const safeDropdownText = SecurityUtils.sanitizeForDropdown(userInput);

// Для отображения с выбором режима строгости
const safeDisplay = SecurityUtils.sanitizeForDisplay(userInput, strictMode);

Безопасные иконки

SecurityUtils поддерживает безопасные иконки Fomantic UI:

// Разрешённые иконки
const safeIcon = '<i class="phone icon"></i>';
const safeNestedIcon = '<i class="icons"><i class="user outline icon"></i></i>';

// Опасные иконки будут экранированы
const dangerousIcon = '<i class="phone icon" onclick="alert(1)"></i>';

Создание безопасных элементов

// Безопасные option элементы
const safeOption = SecurityUtils.createSafeOption(value, text, strictMode);

// Безопасная установка HTML содержимого
SecurityUtils.setHtmlContent($element, content, strictMode);

Extensions API санитизация

Для контента Extensions API используйте специальный метод:

const safeExtensionContent = SecurityUtils.sanitizeExtensionsApiContent(apiContent);

3. SystemSanitizer для REST API

Для полей с системными значениями используйте SystemSanitizer:

use MikoPBX\PBXCoreREST\Lib\Common\SystemSanitizer;

// Правила санитизации для extension полей
$extensionRule = SystemSanitizer::getExtensionSanitizationRule(20, true);

// Правила для routing полей  
$routingRule = SystemSanitizer::getRoutingSanitizationRule(20, true);

// Валидация
if (SystemSanitizer::isValidExtension($value)) {
    // Значение корректно
}

// Санитизация
$cleanValue = SystemSanitizer::sanitizeExtension($userInput);

4. Контекстно-зависимая защита

HTML контекст

// PHP
echo SecurityHelper::escapeHtml($data);
{# Volt #}
{{ data|e }}
// JavaScript
element.textContent = data; // Безопасно
// ИЛИ
$(element).text(data); // Безопасно с jQuery

HTML атрибуты

// PHP
echo '<div id="' . SecurityHelper::escapeAttribute($id) . '">';
{# Volt #}
<div id="{{ id|escape('html_attr') }}">

JavaScript строки

// PHP в JavaScript
echo 'var message = "' . SecurityHelper::escapeJs($message) . '";';

URL параметры

// PHP
$url = 'search?q=' . SecurityHelper::escapeUrl($query);

5. Опасные паттерны - ЗАПРЕЩЕНО

Никогда не используйте:

// ОПАСНО - прямой вывод
echo $userInput;

// ОПАСНО - в атрибутах
echo '<div onclick="' . $userInput . '">';
{# ОПАСНО - без экранирования #}
{{ userInput|raw }}

{# ОПАСНО - в JavaScript #}
<script>var data = "{{ userInput }}";</script>
// ОПАСНО - innerHTML с пользовательскими данными
element.innerHTML = userInput;

// ОПАСНО - eval или Function
eval(userInput);
new Function(userInput);

// ОПАСНО - document.write
document.write(userInput);

6. Проверка безопасности

Автоматическая проверка

// Проверка на опасные паттерны
const isDangerous = SecurityUtils.containsDangerousPatterns(input);

// Проверка безопасности для dropdown
const isSafeForDropdown = SecurityUtils.isSafeForDropdown(input);

// Статистика обработки
const stats = SecurityUtils.getProcessingStats(input);
console.log('Safe icons:', stats.safeSimpleIcons);
console.log('Dangerous patterns:', stats.dangerousPatterns);

7. Рекомендации для модулей

1. Валидация на входе

// В контроллерах
$data = self::sanitizeData($this->request->getPost(), $this->filter);

2. Экранирование на выходе

// В представлениях
$this->view->safeData = SecurityHelper::escapeHtml($data);

3. Использование форм

// В формах Phalcon
$this->add(new Text('name', [
    'filters' => ['trim', 'string']
]));

4. AJAX ответы

// Безопасная обработка AJAX
$.api({
    onSuccess(response) {
        const safeMessage = SecurityUtils.escapeHtml(response.message);
        UserMessage.showInfo(safeMessage);
    }
});

8. Отладка и мониторинг

Режим отладки

// Включить отладку SecurityUtils
SecurityUtils.debug = true;

// Логи будут показывать процесс санитизации

Логирование подозрительного контента

if (SecurityHelper::containsDangerousContent($input)) {
    error_log("Suspicious content detected: " . $input);
}

9. Типичные ошибки

❌ Неправильно

echo "<div>" . $_POST['data'] . "</div>";
$('#content').html(userInput);

✅ Правильно

echo "<div>" . SecurityHelper::escapeHtml($_POST['data']) . "</div>";
SecurityUtils.setHtmlContent($('#content'), userInput, true);

10. Проверочный список

  • Все пользовательские данные экранируются перед выводом
  • Используется контекстно-зависимое экранирование
  • Опасные паттерны проверяются на входе
  • SecurityHelper/SecurityUtils используются во всех модулях
  • Тестирование с XSS payloads выполнено
  • Логирование подозрительного контента настроено

Заключение

Следование этим рекомендациям обеспечит надёжную защиту от XSS атак в модулях MikoPBX. Всегда помните принцип: экранировать на выходе, валидировать на входе.