diff options
| -rw-r--r-- | binaryninjaapi.h | 23 | ||||
| -rw-r--r-- | docs/dev/workflows.md | 28 | ||||
| -rw-r--r-- | docs/guide/settings.md | 4 | ||||
| -rw-r--r-- | examples/workflows/inliner/inliner.cpp | 6 | ||||
| -rw-r--r-- | examples/workflows/tailcall/tailcall.cpp | 6 | ||||
| -rw-r--r-- | view/sharedcache/workflow/SharedCacheWorkflow.cpp | 2 |
6 files changed, 29 insertions, 40 deletions
diff --git a/binaryninjaapi.h b/binaryninjaapi.h index 941c7541..50e2838c 100644 --- a/binaryninjaapi.h +++ b/binaryninjaapi.h @@ -9942,15 +9942,6 @@ namespace BinaryNinja { public: /*! - - \code{.cpp} - MyClass::MyActionMethod(Ref<AnalysisContext> ac); - ... - // Create a clone of the default workflow named "core.function.myWorkflowName" - Ref<Workflow> wf = BinaryNinja::Workflow::Instance("core.function.defaultAnalysis")->Clone("core.function.myWorkflowName"); - wf->RegisterActivity(new BinaryNinja::Activity("core.function.myWorkflowName.resolveMethodCalls", &MyClass::MyActionMethod)); - \endcode - \param configuration a JSON representation of the activity configuration \param action Workflow action, a function taking a Ref<AnalysisContext> as an argument. */ @@ -9979,15 +9970,13 @@ namespace BinaryNinja { bool ClearOverride(const std::string& activity); }; - /*! A Binary Ninja Workflow is an abstraction of a computational binary analysis pipeline and it provides the extensibility - mechanism needed for tailored binary analysis and decompilation. More specifically, a Workflow is a repository of activities along with a - unique strategy to execute them. Binary Ninja provides two Workflows named ``core.module.defaultAnalysis`` and ``core.function.defaultAnalysis`` - which expose the core analysis. - - A Workflow starts in the unregistered state from either creating a new empty Workflow, or cloning an existing Workflow. While unregistered - it's possible to add and remove activities, as well as change the execution strategy. In order to use the Workflow on a binary it must be - registered. Once registered the Workflow is immutable and available for use. + /*! Workflows are represented as Directed Acyclic Graphs (DAGs), where each node corresponds to an Activity (an individual analysis or action). + Workflows are used to tailor the analysis process for :class:`BinaryView` or :class:`Function` objects, providing granular control over + analysis tasks at module or function levels. + A Workflow starts in an unregistered state, either by creating a new empty Workflow or by cloning an existing one. While unregistered, it + is possible to add and remove Activity objects, as well as modify the execution strategy. To apply a Workflow to a binary, it must be + registered. Once registered, the Workflow becomes immutable and is available for use. \ingroup workflow */ class Workflow : public CoreRefCountObject<BNWorkflow, BNNewWorkflowReference, BNFreeWorkflow> diff --git a/docs/dev/workflows.md b/docs/dev/workflows.md index bc92059b..f2c4e374 100644 --- a/docs/dev/workflows.md +++ b/docs/dev/workflows.md @@ -81,9 +81,9 @@ As always, it's possible to interact with these settings programmatically using # Function settings scope Settings().get_string("analysis.workflows.functionWorkflow", current_function) 'core.function.metaAnalysis' -Settings().set_string("analysis.workflows.functionWorkflow", 'core.function.defaultAnalysis', current_function) +Settings().set_string("analysis.workflows.functionWorkflow", 'core.function.baseAnalysis', current_function) Settings().get_string("analysis.workflows.functionWorkflow", current_function) -'core.function.defaultAnalysis' +'core.function.baseAnalysis' # BinaryView settings scope Settings().get_string("analysis.workflows.functionWorkflow", bv) @@ -96,15 +96,15 @@ Settings().get_string("analysis.workflows.moduleWorkflow", bv) Binary Ninja provides a set of foundational workflows that serve as the basis for both module-level and function-level analysis. These workflows are designed to meet standard analysis needs while also serving as a starting point for customization. -**Immutable Core Workflows** +**Immutable Base Workflows** -These workflows are immutable and represent the core analysis functionality in Binary Ninja. They provide a reliable baseline for analysis and cannot be altered directly: +These workflows are immutable and represent the base analysis functionality in Binary Ninja. They provide a reliable baseline for analysis and cannot be altered directly: -- **Default Module Analysis** (`core.module.defaultAnalysis`): Defines the core analysis tasks for module-level analysis on a `BinaryView` object. This workflow ensures consistent and thorough analysis of the entire binary. -- **Default Function Analysis** (`core.function.defaultAnalysis`): Defines the core analysis tasks for function-level analysis. It provides a stable and reliable framework for disassembling and analyzing individual functions. +- **Base Module Analysis** (`core.module.baseAnalysis`): Defines the base analysis tasks for module-level analysis on a `BinaryView` object. This workflow ensures consistent and thorough analysis of the entire binary. +- **Base Function Analysis** (`core.function.baseAnalysis`): Defines the base analysis tasks for function-level analysis. It provides a stable and reliable framework for disassembling and analyzing individual functions. **Mutable Meta Workflows** -These workflows are clones of the default core workflows but are mutable, allowing for advanced customization and extensibility: +These workflows are clones of the default base workflows but are mutable, allowing for advanced customization and extensibility: - **Meta Module Analysis** (`core.module.metaAnalysis`): A mutable version of the default module analysis workflow. It can be customized to add or remove analysis stages, modify dependencies, or integrate new analyses. - **Meta Function Analysis** (`core.function.metaAnalysis`): A mutable version of the default function analysis workflow. It can be customized to extend or modify the analysis process for individual functions. @@ -112,7 +112,7 @@ These workflows are clones of the default core workflows but are mutable, allowi These foundational workflows are designed to be cloned and customized to create new workflows tailored to specific needs. By leveraging these base workflows, you can build upon existing analyses and extend the capabilities of Binary Ninja. !!! note - The workflow settings default to the meta workflows to facilitate seamless integration and customization by installed plugins or scripts. This approach ensures that multiple plugins can extend or modify the analysis pipeline without conflicting with the core workflows. The term "meta" reflects the workflow's role as a flexible and composable foundation, enabling collaborative customization while preserving the integrity of the default analyses. + The workflow settings default to the meta workflows to facilitate seamless integration and customization by installed plugins or scripts. This approach ensures that multiple plugins can extend or modify the analysis pipeline without conflicting with the base workflows. The term "meta" reflects the workflow's role as a flexible and composable foundation, enabling collaborative customization while preserving the integrity of the default analyses. !!! note Binary Ninja's analysis is structured through the Workflow system, providing immediate extensibility for interposing custom analysis steps. While most Activities within the Workflow represent specific analysis tasks, some serve purely to maintain the pipeline's functionality. These non-analysis Activities are transitional and will be phased out as we refine and modernize the underlying infrastructure. @@ -142,20 +142,20 @@ You can query the list of all registered workflows or filter them by type using ```python # List all Module and Function workflows list(Workflow) -[<Workflow: core.function.defaultAnalysis>, +[<Workflow: core.function.baseAnalysis>, <Workflow: core.function.dsc>, <Workflow: core.function.metaAnalysis>, <Workflow: core.function.objectiveC>, -<Workflow: core.module.defaultAnalysis>, +<Workflow: core.module.baseAnalysis>, <Workflow: core.module.metaAnalysis>] # List all module workflows from the Settings API Settings().query_property_string_list("analysis.workflows.moduleWorkflow", "enum") -['core.module.defaultAnalysis', 'core.module.metaAnalysis'] +['core.module.baseAnalysis', 'core.module.metaAnalysis'] # List all function workflows from the Settings API >>> Settings().query_property_string_list("analysis.workflows.functionWorkflow", "enum") -['core.function.defaultAnalysis', 'core.function.dsc', 'core.function.metaAnalysis', 'core.function.objectiveC'] +['core.function.baseAnalysis', 'core.function.dsc', 'core.function.metaAnalysis', 'core.function.objectiveC'] ``` Once you've queried the available workflows, you can create your own by cloning and modifying an existing workflow. Below are some simple examples that demonstrate how to modify module-level analysis. @@ -172,7 +172,7 @@ workflow = Workflow("core.module.metaAnalysis").clone() workflow.show_topology() # Get the root activity of the workflow -root = workflow.get_activity("core.module.defaultAnalysis") +root = workflow.get_activity("core.module.baseAnalysis") # Clear all activities in the workflow workflow.clear() @@ -196,7 +196,7 @@ This example demonstrates how to create a custom workflow that performs only the stringsWorkflowOnly = Workflow("core.module.metaAnalysis").clone("stringsAnalysisOnly") # Retrieve relevant activities for strings analysis -root = stringsWorkflowOnly.get_activity("core.module.defaultAnalysis") +root = stringsWorkflowOnly.get_activity("core.module.baseAnalysis") sa1 = stringsWorkflowOnly.get_activity("core.module.queueRegionsForStringsAnalysis") sa2 = stringsWorkflowOnly.get_activity("core.module.stringsAnalysis") diff --git a/docs/guide/settings.md b/docs/guide/settings.md index 0d5cc22e..d39dbec9 100644 --- a/docs/guide/settings.md +++ b/docs/guide/settings.md @@ -119,12 +119,12 @@ All settings are uniquely identified with an identifier string. Identifiers are |analysis|UTF-32 Encoding|Whether or not to consider UTF-32 code points when searching for strings.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.unicode.utf32'>analysis.unicode.utf32</a>| |analysis|UTF-8 Encoding|Whether or not to consider UTF-8 code points when searching for strings.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.unicode.utf8'>analysis.unicode.utf8</a>| |analysis|Function Workflow|Specifies the workflow to be used for function-level analysis, including tasks such as disassembly and IL transformations.|`string`|`core.function.metaAnalysis`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.workflows.functionWorkflow'>analysis.workflows.functionWorkflow</a>| -| | | enum: This workflow defines the core function analysis provided by Binary Ninja.|`enum`|`core.function.defaultAnalysis`| | | +| | | enum: This workflow defines the base function analysis provided by Binary Ninja.|`enum`|`core.function.baseAnalysis`| | | | | | enum: Shared Cache Workflow|`enum`|`core.function.dsc`| | | | | | enum: This workflow defines the adaptive function analysis for Binary Ninja, enabling adaptive composability of the default function analysis.|`enum`|`core.function.metaAnalysis`| | | | | | enum: Enhanced analysis for Objective-C code.|`enum`|`core.function.objectiveC`| | | |analysis|Module Workflow|Specifies the workflow to be used for module-level analysis, focusing on processing module-level data and coordinating function analyses.|`string`|`core.module.metaAnalysis`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.workflows.moduleWorkflow'>analysis.workflows.moduleWorkflow</a>| -| | | enum: This workflow defines the core module analysis for Binary Ninja.|`enum`|`core.module.defaultAnalysis`| | | +| | | enum: This workflow defines the base module analysis for Binary Ninja.|`enum`|`core.module.baseAnalysis`| | | | | | enum: This workflow defines the adaptive module analysis for Binary Ninja, enabling adaptive composability of the default module analysis.|`enum`|`core.module.metaAnalysis`| | | |arch|AARCH64 Alignment Requirement|Require instructions be on 4-byte aligned addresses to be disassembled.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='arch.aarch64.disassembly.alignRequired'>arch.aarch64.disassembly.alignRequired</a>| |arch|AARCH64 Prefer Intrinsics for Vector Operations|Prefer generating calls to intrinsics (where one is available) to lifting vector operations as unrolled loops (where available). Note that not all vector operations are currently lifted as either intrinsics or unrolled loops.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='arch.aarch64.disassembly.preferIntrinsics'>arch.aarch64.disassembly.preferIntrinsics</a>| diff --git a/examples/workflows/inliner/inliner.cpp b/examples/workflows/inliner/inliner.cpp index 392935eb..7db6efec 100644 --- a/examples/workflows/inliner/inliner.cpp +++ b/examples/workflows/inliner/inliner.cpp @@ -158,14 +158,14 @@ extern "C" }, inlinerIsValid); - Ref<Workflow> inlinerWorkflow = Workflow::Instance("core.function.defaultAnalysis")->Clone("InlinerWorkflow"); + Ref<Workflow> inlinerWorkflow = Workflow::Instance("core.function.baseAnalysis")->Clone("InlinerWorkflow"); inlinerWorkflow->RegisterActivity(new Activity("extension.functionInliner", &FunctionInliner)); inlinerWorkflow->Insert("core.function.translateTailCalls", "extension.functionInliner"); Workflow::RegisterWorkflow(inlinerWorkflow, R"#({ "title" : "Function Inliner (Example)", - "description" : "This analysis stands in as an example to demonstrate Binary Ninja's extensible analysis APIs. ***Note** this feature is under active development and subject to change without notice.", - "capabilities" : [] + "description" : "This analysis stands in as an example to demonstrate Binary Ninja's extensible analysis APIs.", + "targetType" : "function" })#"); return true; diff --git a/examples/workflows/tailcall/tailcall.cpp b/examples/workflows/tailcall/tailcall.cpp index 2cb77b8e..294b6471 100644 --- a/examples/workflows/tailcall/tailcall.cpp +++ b/examples/workflows/tailcall/tailcall.cpp @@ -117,15 +117,15 @@ extern "C" BINARYNINJAPLUGIN bool CorePluginInit() { - Ref<Workflow> customTailCallWorkflow = Workflow::Instance("core.function.defaultAnalysis")->Clone("CustomTailCallWorkflow"); + Ref<Workflow> customTailCallWorkflow = Workflow::Instance("core.function.baseAnalysis")->Clone("CustomTailCallWorkflow"); customTailCallWorkflow->RegisterActivity(new Activity("extension.translateTailCalls", &TailCallTranslation)); customTailCallWorkflow->Replace("core.function.translateTailCalls", "extension.translateTailCalls"); customTailCallWorkflow->Remove("core.function.translateTailCalls"); Workflow::RegisterWorkflow(customTailCallWorkflow, R"#({ "title" : "Tail Call Translation (Example)", - "description" : "This analysis stands in as an example to demonstrate Binary Ninja's extensible analysis APIs. ***Note** this feature is under active development and subject to change without notice.", - "capabilities" : [] + "description" : "This analysis stands in as an example to demonstrate Binary Ninja's extensible analysis APIs.", + "targetType" : "function" })#"); return true; diff --git a/view/sharedcache/workflow/SharedCacheWorkflow.cpp b/view/sharedcache/workflow/SharedCacheWorkflow.cpp index 88353bf7..61832e93 100644 --- a/view/sharedcache/workflow/SharedCacheWorkflow.cpp +++ b/view/sharedcache/workflow/SharedCacheWorkflow.cpp @@ -518,7 +518,7 @@ void fixObjCCallTypes(Ref<AnalysisContext> ctx) void SharedCacheWorkflow::Register() { - Ref<Workflow> wf = BinaryNinja::Workflow::Instance("core.function.defaultAnalysis")->Clone("core.function.dsc"); + Ref<Workflow> wf = BinaryNinja::Workflow::Instance("core.function.baseAnalysis")->Clone("core.function.dsc"); wf->RegisterActivity(new BinaryNinja::Activity("core.analysis.dscstubs", &SharedCacheWorkflow::FixupStubs)); wf->RegisterActivity(new BinaryNinja::Activity("core.analysis.fixObjCCallTypes", &fixObjCCallTypes)); wf->Insert("core.function.analyzeTailCalls", "core.analysis.fixObjCCallTypes"); |