From a7dcffa57fb95adcc9ecb2071ea8de18db1ac702 Mon Sep 17 00:00:00 2001 From: thientc Date: Thu, 19 Mar 2026 11:16:38 +0000 Subject: [PATCH 1/2] docs: Update README and add workflow diagram for FUTAG --- README.en.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++- README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++-- futag-work.mmd | 52 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 163 insertions(+), 3 deletions(-) create mode 100644 futag-work.mmd diff --git a/README.en.md b/README.en.md index 4324b159..7aa213ad 100644 --- a/README.en.md +++ b/README.en.md @@ -32,7 +32,61 @@ 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 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 +``` 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). diff --git a/README.md b/README.md index 10f41d49..2fb32ff9 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,62 @@ 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 "Уровень 3: Инфраструктура сборки" + D["custom-llvm / build.sh — Загрузка и патч LLVM 14/18/19"] + end + + D -->|"инструментарий futag-llvm"| E + + subgraph "Уровень 1: C++ Clang чекеры" + E["scan-build + FutagAnalyzer — Извлечение функций, типов, контекстов вызовов"] + F["scan-build + FutagConsumerAnalyzer — Извлечение контекстов использования"] + end + + A --> E + B --> F + E -->|"JSON файлы анализа"| G + F -->|"JSON файлы контекстов"| H + + subgraph "Уровень 2: 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["BlobStamperGenerator"] + I --> J4["ContextGenerator - контексты потребителя"] + I --> J5["NatchGenerator - трассы крашей"] + end + + J1 & J2 & J3 & J4 & J5 --> 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) diff --git a/futag-work.mmd b/futag-work.mmd new file mode 100644 index 00000000..fbe23ca0 --- /dev/null +++ b/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 From 0ff06921decb68df31b03068c2019e6622a1dabc Mon Sep 17 00:00:00 2001 From: thientc Date: Thu, 19 Mar 2026 13:00:03 +0000 Subject: [PATCH 2/2] docs: update layer numbering in build infrastructure and orchestration sections of README --- README.en.md | 13 ++++++------- README.md | 13 ++++++------- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/README.en.md b/README.en.md index 7aa213ad..0be1686b 100644 --- a/README.en.md +++ b/README.en.md @@ -41,13 +41,13 @@ graph TD C["Natch JSON - optional"] end - subgraph "Layer 3: Build Infrastructure" + 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 1: C++ Clang Checkers" + 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 @@ -57,7 +57,7 @@ graph TD E -->|"JSON analysis files"| G F -->|"JSON context files"| H - subgraph "Layer 2: Python Orchestration" + subgraph "Layer 3: Python Orchestration" G["Builder.analyze — futag-analysis-result.json"] H["ConsumerBuilder.analyze — futag-contexts.json"] @@ -69,12 +69,11 @@ graph TD 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"] + I --> J3["ContextGenerator - consumer contexts"] + I --> J4["NatchGenerator - crash traces"] end - J1 & J2 & J3 & J4 & J5 --> K["gen_targets and compile_targets"] + J1 & J2 & J3 & J4 --> K["gen_targets and compile_targets"] K --> L["Fuzzer / NatchFuzzer"] end diff --git a/README.md b/README.md index 2fb32ff9..d4f5933e 100644 --- a/README.md +++ b/README.md @@ -42,13 +42,13 @@ graph TD C["JSON от Natch - опционально"] end - subgraph "Уровень 3: Инфраструктура сборки" + subgraph "Уровень 1: Инфраструктура сборки" D["custom-llvm / build.sh — Загрузка и патч LLVM 14/18/19"] end D -->|"инструментарий futag-llvm"| E - subgraph "Уровень 1: C++ Clang чекеры" + subgraph "Уровень 2: С/C++ Clang анализаторы" E["scan-build + FutagAnalyzer — Извлечение функций, типов, контекстов вызовов"] F["scan-build + FutagConsumerAnalyzer — Извлечение контекстов использования"] end @@ -58,7 +58,7 @@ graph TD E -->|"JSON файлы анализа"| G F -->|"JSON файлы контекстов"| H - subgraph "Уровень 2: Python оркестрация" + subgraph "Уровень 3: Python оркестрация" G["Builder.analyze — futag-analysis-result.json"] H["ConsumerBuilder.analyze — futag-contexts.json"] @@ -70,12 +70,11 @@ graph TD I{"Выбор генератора"} I --> J1["Generator - memcpy из буфера"] I --> J2["FuzzDataProviderGenerator - типобезопасный FDP API"] - I --> J3["BlobStamperGenerator"] - I --> J4["ContextGenerator - контексты потребителя"] - I --> J5["NatchGenerator - трассы крашей"] + I --> J3["ContextGenerator - контексты потребителя"] + I --> J4["NatchGenerator - трассы крашей"] end - J1 & J2 & J3 & J4 & J5 --> K["gen_targets и compile_targets"] + J1 & J2 & J3 & J4 --> K["gen_targets и compile_targets"] K --> L["Fuzzer / NatchFuzzer"] end