Skip to content

OBFUSCATION_INSTRUCTION.md

Latest commit

 

History

History
629 lines (466 loc) · 25.4 KB

OBFUSCATION_INSTRUCTION.md

File metadata and controls

629 lines (466 loc) · 25.4 KB

Русский | English

Инструкция по обфускации VBA-кода

Инструмент: MACROTools v2.0
Класс: clsObfuscator
Модуль запуска: modToolsObfuscation
Версия: 2.0.38

📋 Содержание

  1. Что такое обфускация
  2. Зачем нужна обфускация
  3. Подготовка к обфускации
  4. Запуск обфускации
  5. Этапы обфускации
  6. Результаты обфускации
  7. Лист настроек OBFUSCATION_VARIABLE
  8. Что обфусцируется
  9. Что НЕ обфусцируется
  10. Восстановление и отладка
  11. ⚠️🚨 Ограничения и предупреждения ← КРИТИЧЕСКИ ВАЖНЫЙ РАЗДЕЛ!
  12. Часто задаваемые вопросы

Что такое обфускация

Обфускация — это процесс преобразования исходного кода в форму, сохраняющую его функциональность, но затрудняющую понимание, анализ и модификацию.

При обфускации VBA-проекта:

  • ✅ Идентификаторы (имена переменных, процедур, модулей) заменяются на сгенерированные
  • ✅ Строковые литералы выносятся в отдельный модуль констант
  • ✅ Riddon вызовы в XML заменяются на сгенерированные
  • ✅ Создаётся отчёт о всех выполненных заменах
  • ✅ Функциональность кода полностью сохраняется

Зачем нужна обфускация

🔐 Защита интеллектуальной собственности

  • Скрывает логику работы алгоритмов
  • Затрудняет обратный инжиниринг
  • Защищает коммерческие решения

📦 Уменьшение читаемости кода

  • Переменные получают имена вида O01l1l01l1l0
  • Процедуры переименовываются в O01l1l01l1l0
  • Модули получают имена O01l1l01l1l0

Подготовка к обфускации

✅ Требования

  1. Доступ к VBA-проекту

    • Проект не должен быть защищён паролем
    • Включён доступ к объектной модели VBA:
      • Excel → Файл → Параметры → Центр доверия → Параметры макросов → ✅ Доверять доступ к объектной модели VBA

  2. Резервная копия

    • ⚠️ Обфускация необратима!
    • Обязательно создайте копию файла перед запуском
    • Аддин автоматически создаёт резервную копию, но дополнительная защита не повредит

  3. Тестирование

    • Протестируйте обфускацию на копии файла
    • Убедитесь, что код работает после обфускации
    • Проверьте все макросы, привязанные к кнопкам и шейпам

⚙️ Настройка листа OBFUSCATION_VARIABLE

Перед запуском обфускации необходимо собрать данные о VBA-проекте:

  1. Откройте целевую книгу Excel

  2. В MACROTools выберите: Tools → Collect Data for Obfuscation

  3. Аддин создаст лист OBFUSCATION_VARIABLE с данными:

    • Модули и их код
    • Процедуры и функции
    • Переменные и константы
    • Контролы UserForm
    • Объявления (Declarations)

  4. Проверьте данные на листе:

    • Убедитесь, что все элементы собраны корректно
    • При необходимости отредактируйте список
    • Проверьте типы элементов (TypeElement)
    • Исключите переменные которые не хотите шифровать, удалением их из списка

Запуск обфускации

Способ 1: Через Ribbon UI

  1. Откройте Excel с загруженным аддином MACROTools
  2. Перейдите на вкладку MACROTools в Ribbon
  3. Нажмите кнопку Obfuscate VBA Project (btnObfuscator)
  4. Выберите целевую книгу (если открыто несколько)
  5. Дождитесь завершения процесса

Способ 2: Через VBE

  1. Откройте Visual Basic Editor (Alt+F11)
  2. В контекстном меню выберите Tools → Obfuscate VBA Project
  3. Подтвердите действие

Способ 3: Программно

Sub RunObfuscation()
    Call ObfuscationVBAProject
End Sub

Процесс выполнения

Во время обфускации:

  • 🔄 Отключается обновление экрана (ScreenUpdating = False)
  • 🔄 Отключаются предупреждения (DisplayAlerts = False)
  • 🔄 Создаётся резервная копия файла
  • 🔄 Последовательно выполняются этапы обфускации
  • 🔄 Генерируется отчёт на листе OBFUSCATION_REPORT

Этапы обфускации

Обфускация выполняется в 9 этапов:

Этап 1: Строковые литералы (Literals)

Что происходит:

  • Извлекаются все строковые значения из кода
  • Создаётся новый модуль modLiterals с константами
  • В исходном коде строки заменяются ссылками на константы

Пример:

' До:
MsgBox "Hello, World!"

' После:
MsgBox O01l1l01l1l0  ' где O01l1l01l1l0 = "Hello, World!"

Этап 2: Локальные переменные (Local Variables)

Что происходит:

  • Переименовываются локальные переменные внутри процедур
  • Переименовываются параметры процедур
  • Переименовываются локальные константы

Пример:

' До:
Dim userName As String
userName = "John"

' После:
Dim O01l1l01l1l0 As String
O01l1l01l1l0 = "John"

Этап 3: UserForms Controls

Что происходит:

  • Переименовываются все контролы на UserForm
  • Обновляются ссылки в коде форм
  • Обновляются ссылки во всех модулях проекта

Пример:

' До:
TextBox1.Value = "Test"

' После:
O01l1l01l1l0.Value = "Test"

Этап 4: Процедуры и функции (Procedures)

Что происходит:

  • Переименовываются все процедуры и функции
  • Обновляются вызовы во всех модулях
  • Обрабатываются макросы, привязанные к шейпам
  • Обрабатываются Ribbon UI callbacks

Пример:

' До:
Sub CalculateTotal()
    ' ...
End Sub

' После:
Sub O01l1l01l1l0()
    ' ...
End Sub

Этап 5: Объявления (Declarations)

Что происходит:

  • Переименовываются переменные уровня модуля
  • Обрабатываются WithEvents объявления
  • Обновляются ссылки на классы с событиями

Этап 6: Переименование модулей (Modules Renaming)

Что происходит:

  • Все модули получают новые имена
  • Стандартные модули → OXXXXXXXXXXXX
  • Классы → OXXXXXXXXXXXX
  • UserForm → OXXXXXXXXXXXX

Пример:

' До:
modTools.bas
clsHelper.cls
UserForm1.frm

' После:
O01l1l01l1l0.bas
O01l1l01l1l1.cls
O01l1l01l1ll.frm

Этап 7: Запись UI элементов

Что происходит:

  • Сохраняются изменения в интерфейсе UserForm
  • Обновляются свойства контролов

Этап 8: Запись изменений в проект

Что происходит:

  • Изменённый код записывается в VBComponents
  • Модули переименовываются в VBA-проекте
  • Проект сохраняется

Этап 9: Генерация отчёта (Report)

Что происходит:

  • Создаётся лист OBFUSCATION_REPORT
  • Записываются все соответствия: Новое имя → Оригинальное значение
  • Формируется полная карта обфускации

Результаты обфускации

📊 Лист OBFUSCATION_REPORT

После завершения обфускации создаётся лист с отчётом:

Столбец Описание
A Тип элемента (Literals, Module, Procedure, и т.д.)
B Подтип элемента
C Дополнительная информация
D Имя модуля
E Новое обфусцированное имя

🔍 Структура отчёта

OBFUSCATION_REPORT
├── Literals.<ModuleName>.<StringValue> → OXXXXXXXXXXXX
├── Module.<ModuleName> → OXXXXXXXXXXXX
├── Procedure.<ModuleName>.<ProcName> → OXXXXXXXXXXXX
├── Declaration.<ModuleName>.<VarName> → OXXXXXXXXXXXX
├── Local Variable.<Module>.<Proc>.<VarLines> → OXXXXXXXXXXXX
└── UserForm.<Module>.<ControlName> → OXXXXXXXXXXXX

💾 Сохранение файла

  • Файл автоматически сохраняется после обфускации
  • Резервная копия создаётся перед началом
  • ⚠️ Рекомендуется сразу проверить работоспособность

Лист настроек OBFUSCATION_VARIABLE

Структура данных

Лист OBFUSCATION_VARIABLE содержит информацию о VBA-проекте:

Столбец Данные Описание
A TypeElement Тип элемента (Module, Procedure, Declaration, и т.д.)
B ModuleName Имя модуля
C ModuleType Тип модуля (Standard, Class, UserForm)
D ProcName Имя процедуры/переменной
E ProcType Тип (Function, Sub, WithEvents, и т.д.)
F ProcLines Номера строк или идентификатор
G ProcDeclaration Декларация процедуры
H-J Дополнительные данные Внутренние параметры

Типы элементов (TypeElement)

Тип Описание
Module Стандартный модуль, класс или UserForm
Procedure Процедура или функция
Declaration Объявление переменной уровня модуля
UserForms Контрол на UserForm
Parametr Параметр процедуры
Local Variable Локальная переменная
Local Const Локальная константа

Как обновить данные

Если вы изменили код после сбора данных:

  1. Удалите лист OBFUSCATION_VARIABLE
  2. Запустите: Tools → Collect Data for Obfuscation
  3. Данные будут собраны заново

Что обфусцируется

✅ Полностью обфусцируется

Элемент Пример Результат
Строковые литералы "Hello" O7A3B9C2D1E5
Локальные переменные Dim x As Long Dim O4F8A2C9D3E7 As Long
Параметры процедур Sub Test(name As String) Sub Test(O2D7E4A1B8C3 As String)
Процедуры Sub CalculateTotal() Sub O9B3C6D2E5A1()
Функции Function GetValue() Function O5A9B2C7D3E1()
Переменные модуля Private m_count As Long Private O3F7C2D8E5A1 As Long
Контролы UserForm TextBox1 O2D7E4A1B8C3
Модули modTools O5A9B2C7D3E1
Классы clsHelper O8D4E1A6B9C2
UserForm UserForm1 O3F7C2D8E5A1
WithEvents WithEvents App As Application WithEvents O1C5D9E3A7B2 As Application

🔗 Обновляются ссылки

  • Вызовы процедур во всех модулях
  • Обработчики событий контролов
  • Макросы, привязанные к шейпам
  • Ribbon UI callbacks
  • Ссылки на классы с событиями

Что НЕ обфусцируется

❌ Системные процедуры

Имя Причина
Class_Initialize Системный конструктор класса
Class_Terminate Системный деструктор класса
Auto_Open Автоматический запуск книги
Auto_Close Автоматическое закрытие книги

❌ События рабочих листов и книги

Имя Пример
Workbook events Workbook_Open, Workbook_SheetChange
Worksheet events Worksheet_Change, Worksheet_Activate
UserForm events UserForm_Initialize, UserForm_Click

❌ События WithEvents

' НЕ обфусцируется:
Private Sub App_WorkbookOpen(ByVal Wb As Workbook)
    ' Имя события сохраняется
End Sub

❌ Внешние ссылки и API

  • Вызовы Windows API (Declare Function)
  • Ссылки на внешние библиотеки
  • Имена встроенных функций VBA

❌ Строки в формулах Excel

Обфусцируются только строки в коде VBA, не в формулах ячеек.

Восстановление и отладка

🔙 Восстановление оригинального кода

ВАЖНО: Обфускация НЕОБРАТИМА автоматически.

Варианты восстановления:

  1. Из резервной копии

    • Используйте автоматически созданную копию файла
    • Или вашу ручную резервную копию

  2. Через лист отчёта

    • Лист OBFUSCATION_REPORT содержит карту соответствий
    • Столбец E → новое имя
    • Столбцы A-D → оригинальное описание
    • Можно вручную восстановить имена

  3. Через OBFUSCATION_VARIABLE

    • Лист настроек содержит оригинальные имена
    • Используйте как справочник

🐛 Отладка обфусцированного кода

Проблемы:

  • ❌ Имена переменных неинформативны
  • ❌ Трассировка кода затруднена
  • ❌ Окно Immediate показывает OXXXXXXXXXXXX

Рекомендации:

  1. Отлаживайте НЕобфусцированную версию

    • Всегда сохраняйте оригинал
    • Ведите разработку в оригинале
    • Обфусцируйте только для распространения

  2. Используйте лист отчёта

    • Откройте OBFUSCATION_REPORT
    • Найдите нужное новое имя в столбце E
    • Определите оригинальное назначение

  3. Комментируйте код ДО обфускации

    • Добавьте подробные комментарии
    • Комментарии сохраняются при обфускации
    • Это поможет понимать логику позже

  4. Ведите журнал изменений

    • Фиксируйте, что и зачем обфусцировали
    • Сохраняйте версию до обфускации

Ограничения и предупреждения

⚠️ Важные ограничения

  1. Конфликт имён переменных со свойствами объектов

    • ⚠️ Если имя переменной совпадает с именем свойства объекта, обфускация может ошибочно заменить свойство
    • Пример проблемы:
    ' До обфускации:
Public Sub example()
    Dim oList As MSForms.ListBox
    Dim Value As String
    Debug.Print oList.Value = "value"
End Sub

' ❌ После обфускации (НЕВЕРНО):
Public Sub example()
    Dim oList As MSForms.ListBox
    Dim o01010l01l01l0 As String
    Debug.Print oList.o01010l01l01l0 = "value"  ' ← Ошибка: заменено свойство .Value
End Sub
    • Решение: Переименуйте переменную, чтобы она не совпадала со свойствами объектов:
    ' ✅ Правильный вариант (переменная sValue вместо Value):
Public Sub example()
    Dim oList As MSForms.ListBox
    Dim sValue As String
    Debug.Print oList.Value = "value"
End Sub

' ✅ После обфускации (ВЕРНО):
Public Sub example()
    Dim oList As MSForms.ListBox
    Dim o01010l01l01l0 As String
    Debug.Print oList.Value = "value"  ' ← Свойство .Value сохранено
End Sub
    • Рекомендация: Используйте префиксы для имён переменных:
      • sValue, sName, sPath (строки)
      • lCount, lIndex, lTotal (числа Long)
      • bFlag, bEnabled, bVisible (булевы)
      • oObject, oList, oRange (объекты)

  2. Пароль на VBA-проект

    • ❌ Обфускация не работает с защищёнными проектами
    • Снимите защиту перед запуском

  3. Необратимость

    • ⚠️ Нет автоматического отката
    • Обязательно создавайте резервную копию

  4. Сложные проекты

    • ⚠️ Большие проекты могут обрабатываться долго
    • Рекомендуется тестировать на копии

  5. API-вызовы

    • ⚠️ Некоторые функции используют API-хуки
    • Может потребоваться дополнительная настройка

  6. Ссылки на другие проекты

    • ⚠️ Внешние ссылки не обфусцируются
    • Проверьте совместимость после обфускации

🚫 Известные проблемы

Проблема Решение
Late Binding объекты Могут некорректно обфусцироваться
Динамическое создание контролов Проверьте после обфускации
CallByName вызовы Строковые имена не обновляются автоматически
Evaluate() с именами процедур Может потребоваться ручная правка

🔒 Безопасность

  • Обфусцированный код защищён от чтения, но не от выполнения
  • Для полной защиты используйте дополнительно Unviewable VBA Project
  • Обфускация затрудняет, но не делает невозможным обратный инжиниринг

Часто задаваемые вопросы

❓ Обфускация замедлит мой код?

Нет. Обфускация не влияет на производительность. Меняются только имена, логика остаётся прежней.

❓ Можно выбрать, что обфусцировать?

Да. Отредактируйте лист OBFUSCATION_VARIABLE перед запуском — удалите строки, которые не нужно обфусцировать.

❓ Что если обфускация завершилась с ошибкой?

  1. Проверьте лог: ...\AppData\Roaming\Microsoft\AddIns\MACROTools_logs.csv
  2. Убедитесь, что VBA-проект не защищён паролем
  3. Проверьте корректность данных на листе OBFUSCATION_VARIABLE
  4. Попробуйте на простой тестовой книге

❓ Можно обфусцировать несколько книг сразу?

Нет. Обфускация выполняется для одной книги за раз. Повторите процесс для каждой.

❓ Сохранятся ли комментарии в коде?

Нет. Комментарии удаляются.

❓ Будут ли работать макросы на кнопках?

Да. Ссылки на макросы в шейпах и контролах обновляются автоматически.

❓ Как проверить, что всё работает?

  1. Запустите все основные макросы
  2. Проверьте UserForm
  3. Протестируйте кнопки и шейпы
  4. Проверьте Ribbon UI callbacks
  5. Убедитесь, что события работают

❓ Нужно ли удалять лист OBFUSCATION_VARIABLE после обфускации?

Рекомендуется:

  • ✅ Сохраните копию файла с листами отчёта
  • ✅ Удалите листы из финальной версии для безопасности
  • ✅ Или скройте листы: xlSheetVeryHidden

❓ Можно запустить обфускацию программно из другой книги?

Да. Используйте:

Sub ObfuscateTargetWorkbook()
    Dim wb As Workbook
    Set wb = Workbooks("TargetBook.xlsm")
    
    If wb.VBProject.Protection = vbext_pp_locked Then
        MsgBox "Project is protected!", vbCritical
        Exit Sub
    End If
    
    Dim oObs As Object
    Set oObs = CreateObject("clsObfuscator")
    
    Application.ScreenUpdating = False
    Application.DisplayAlerts = False
    
    If oObs.Execute(wb) Then
        MsgBox "Success!", vbInformation
    Else
        MsgBox "Failed!", vbExclamation
    End If
    
    Set oObs = Nothing
End Sub

📚 Дополнительные материалы

  • MODULES_REFERENCE.md — Справочник всех модулей MACROTools
  • clsObfuscator.cls — Исходный код класса обфускации
  • modToolsObfuscation.bas — Модуль запуска обфускации

📞 Поддержка

При возникновении проблем:

  1. Проверьте лог-файл:
    ...\AppData\Roaming\Microsoft\AddIns\MACROTools_logs.csv

  2. Убедитесь, что доступ к VBA разрешён

  3. Перезагрузите Excel и проверьте активацию аддина

  4. Тестируйте только на копиях файлов

⚖️ Лицензия

Apache License
Автор: VBATools
Версия аддина: v2.0.38

⚠️ Помните: Обфускация — это инструмент защиты от случайного чтения кода, а не от целенаправленного взлома. Используйте комплексные меры защиты для критически важных проектов.