113 documentation for python package

README.en.md

@@ -32,7 +32,60 @@ The collected information is stored as a knowledge base about the tested library
 When usage contexts are available, FUTAG searches for function calls, builds dependencies between the discovered calls, and constructs call contexts.
 
 The workflow of FUTAG is illustrated in the following figure:
-![](futag-work.png)
+
+```mermaid
+graph TD
+    subgraph Inputs
+        A["Library Source Code C/C++"]
+        B["Consumer Source Code - optional"]
+        C["Natch JSON - optional"]
+    end
+
+    subgraph "Layer 1: Build Infrastructure"
+        D["custom-llvm / build.sh — Download and patch LLVM 14/18/19"]
+    end
+
+    D -->|"futag-llvm toolchain"| E
+
+    subgraph "Layer 2: C++ Clang Checkers"
+        E["scan-build + FutagAnalyzer — Extract functions, types, call contexts, includes"]
+        F["scan-build + FutagConsumerAnalyzer — Extract usage contexts from consumer programs"]
+    end
+
+    A --> E
+    B --> F
+    E -->|"JSON analysis files"| G
+    F -->|"JSON context files"| H
+
+    subgraph "Layer 3: Python Orchestration"
+        G["Builder.analyze — futag-analysis-result.json"]
+        H["ConsumerBuilder.analyze — futag-contexts.json"]
+
+        G --> I
+        H --> I
+        C --> I
+
+        subgraph "Generator Backends"
+            I{"Choose Generator"}
+            I --> J1["Generator - memcpy from buffer"]
+            I --> J2["FuzzDataProviderGenerator - type-safe FDP API"]
+            I --> J3["ContextGenerator - consumer contexts"]
+            I --> J4["NatchGenerator - crash traces"]
+        end
+
+        J1 & J2 & J3 & J4  --> K["gen_targets and compile_targets"]
+        K --> L["Fuzzer / NatchFuzzer"]
+    end
+
+    subgraph Outputs
+        M["Fuzz Drivers"]
+        N["Crash Logs"]
+        O["Coverage Reports"]
+        P["SVRES XML"]
+    end
+
+    L --> M & N & O & P
+```
 
 This project is built on LLVM with Clang static analysis and is distributed under the "GPL v3" license (see: https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework).
 

README.md

@@ -32,8 +32,61 @@ FUTAG  использует, в  качестве внешнего интерф
 
 В Futag так же реализована возможность получения контекстов использования тестируемой библиотеки от инструмента для определения поверхности атаки [Natch](https://github.com/ispras/natch).
 
-Работа Futag иллюстрируется на следующем рисунке: 
-![](futag-work.png)
+Работа Futag иллюстрируется на следующей диаграмме:
+
+```mermaid
+graph TD
+    subgraph "Входные данные"
+        A["Исходный код библиотеки C/C++"]
+        B["Исходный код потребителя - опционально"]
+        C["JSON от Natch - опционально"]
+    end
+
+    subgraph "Уровень 1: Инфраструктура сборки"
+        D["custom-llvm / build.sh — Загрузка и патч LLVM 14/18/19"]
+    end
+
+    D -->|"инструментарий futag-llvm"| E
+
+    subgraph "Уровень 2: С/C++ Clang анализаторы"
+        E["scan-build + FutagAnalyzer — Извлечение функций, типов, контекстов вызовов"]
+        F["scan-build + FutagConsumerAnalyzer — Извлечение контекстов использования"]
+    end
+
+    A --> E
+    B --> F
+    E -->|"JSON файлы анализа"| G
+    F -->|"JSON файлы контекстов"| H
+
+    subgraph "Уровень 3: Python оркестрация"
+        G["Builder.analyze — futag-analysis-result.json"]
+        H["ConsumerBuilder.analyze — futag-contexts.json"]
+
+        G --> I
+        H --> I
+        C --> I
+
+        subgraph "Бэкенды генераторов"
+            I{"Выбор генератора"}
+            I --> J1["Generator - memcpy из буфера"]
+            I --> J2["FuzzDataProviderGenerator - типобезопасный FDP API"]
+            I --> J3["ContextGenerator - контексты потребителя"]
+            I --> J4["NatchGenerator - трассы крашей"]
+        end
+
+        J1 & J2 & J3 & J4 --> K["gen_targets и compile_targets"]
+        K --> L["Fuzzer / NatchFuzzer"]
+    end
+
+    subgraph "Результаты"
+        M["Фаззинг-обёртки"]
+        N["Логи крашей"]
+        O["Отчёты покрытия"]
+        P["SVRES XML"]
+    end
+
+    L --> M & N & O & P
+```
 
 Данный проект основан на LLVM со статическим анализом Clang и распространяется под лицензией ["GPL v3 license"](https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework)
 

futag-work.mmd

@@ -0,0 +1,52 @@
+graph TD
+    subgraph Inputs
+        A["Library Source Code C/C++"]
+        B["Consumer Source Code - optional"]
+        C["Natch JSON - optional"]
+    end
+
+    subgraph "Layer 3: Build Infrastructure"
+        D["custom-llvm / build.sh — Download and patch LLVM 14/18/19"]
+    end
+
+    D -->|"futag-llvm toolchain"| E
+
+    subgraph "Layer 1: C++ Clang Checkers"
+        E["scan-build + FutagAnalyzer — Extract functions, types, call contexts, includes"]
+        F["scan-build + FutagConsumerAnalyzer — Extract usage contexts from consumer programs"]
+    end
+
+    A --> E
+    B --> F
+    E -->|"JSON analysis files"| G
+    F -->|"JSON context files"| H
+
+    subgraph "Layer 2: Python Orchestration"
+        G["Builder.analyze — futag-analysis-result.json"]
+        H["ConsumerBuilder.analyze — futag-contexts.json"]
+
+        G --> I
+        H --> I
+        C --> I
+
+        subgraph "Generator Backends"
+            I{"Choose Generator"}
+            I --> J1["Generator - memcpy from buffer"]
+            I --> J2["FuzzDataProviderGenerator - type-safe FDP API"]
+            I --> J3["BlobStamperGenerator"]
+            I --> J4["ContextGenerator - consumer contexts"]
+            I --> J5["NatchGenerator - crash traces"]
+        end
+
+        J1 & J2 & J3 & J4 & J5 --> K["gen_targets and compile_targets"]
+        K --> L["Fuzzer / NatchFuzzer"]
+    end
+
+    subgraph Outputs
+        M["Fuzz Drivers"]
+        N["Crash Logs"]
+        O["Coverage Reports"]
+        P["SVRES XML"]
+    end
+
+    L --> M & N & O & P