From d86583e8f7dd2ad3cf18d4cb895deb91ffae5393 Mon Sep 17 00:00:00 2001 From: kat Date: Wed, 10 Aug 2022 18:59:34 -0400 Subject: Add Workflow, Action, AnalysisContext C++ Docs --- binaryninjaapi.h | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 199 insertions(+), 1 deletion(-) (limited to 'binaryninjaapi.h') diff --git a/binaryninjaapi.h b/binaryninjaapi.h index 7c73d066..be5d6adb 100644 --- a/binaryninjaapi.h +++ b/binaryninjaapi.h @@ -5189,15 +5189,58 @@ namespace BinaryNinja { AnalysisContext(BNAnalysisContext* analysisContext); virtual ~AnalysisContext(); + /*! Get the Function for the current AnalysisContext + + \return The function for the current context + */ Ref GetFunction(); + + /*! Get the low level IL function for the current AnalysisContext + + \return The LowLevelILFunction for the current context + */ Ref GetLowLevelILFunction(); + + /*! Get the medium level IL function for the current AnalysisContext + + \return The MediumLevelILFunction for the current context + */ Ref GetMediumLevelILFunction(); + + /*! Get the high level IL function for the current AnalysisContext + + \return The HighLevelILFunction for the current context + */ Ref GetHighLevelILFunction(); + /*! Set a new BasicBlock list for the current analysis context + + \param basicBlocks The new list of BasicBlocks + */ void SetBasicBlockList(std::vector> basicBlocks); + + /*! Set new lifted IL for the current analysis context + + \param liftedIL The new lifted IL + */ void SetLiftedILFunction(Ref liftedIL); + + /*! Set the new Low Level IL for the current analysis context + + \param lowLevelIL the new Low Level IL + */ void SetLowLevelILFunction(Ref lowLevelIL); + + /*! Set the new Medium Level IL for the current analysis context + + \param mediumLevelIL the new Medium Level IL + */ void SetMediumLevelILFunction(Ref mediumLevelIL); + + /*! Set the new High Level IL for the current analysis context + + \param highLevelIL the new High Level IL + */ void SetHighLevelILFunction(Ref highLevelIL); bool Inform(const std::string& request); @@ -5231,49 +5274,204 @@ namespace BinaryNinja { static void Run(void* ctxt, BNAnalysisContext* analysisContext); public: + /*! + + \code{.cpp} + MyClass::MyActionMethod(Ref ac); + ... + // Create a clone of the default workflow named "core.function.myWorkflowName" + Ref wf = BinaryNinja::Workflow::Instance()->Clone("core.function.myWorkflowName"); + wf->RegisterActivity(new BinaryNinja::Activity( + "core.function.myWorkflowName.resolveMethodCalls", &MyClass::MyActionMethod)); + \endcode + + \param name Name of the activity to register + \param action Workflow action, a function taking a Ref as an argument. + */ Activity(const std::string& name, const std::function)>& action); Activity(BNActivity* activity); virtual ~Activity(); + /*! Get the Activity name + + \return Activity name + */ std::string GetName() const; }; + /*! 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. + + */ class Workflow : public CoreRefCountObject { public: Workflow(const std::string& name = ""); Workflow(BNWorkflow* workflow); virtual ~Workflow() {} - + + /*! Get a list of all workflows + + \return A list of Workflows + */ static std::vector> GetList(); + + /*! Get an instance of a workflow by name. If it is already registered, this will return the registered Workflow. + If not, it will create and return a new Workflow. + + \param name Workflow name + \return The registered workflow. + */ static Ref Instance(const std::string& name = ""); + /*! Register a workflow, making it immutable and available for use + + \param workflow The workflow to register + \param description A JSON description of the Workflow + \return true on success, false otherwise + */ static bool RegisterWorkflow(Ref workflow, const std::string& description = ""); + /*! Clone a workflow, copying all Activities and the execution strategy + + \param name Name for the new Workflow + \param activity If specified, perform the clone with `activity` as the root + \return A new Workflow + */ Ref Clone(const std::string& name, const std::string& activity = ""); + + /*! Register an Activity with this Workflow + + \param activity The Activity to register + \param description A JSON description of the Activity + \return + */ bool RegisterActivity(Ref activity, const std::string& description = ""); bool RegisterActivity(Ref activity, std::initializer_list initializer) { return RegisterActivity(activity, std::vector(initializer.begin(), initializer.end())); } + /*! Register an Activity with this Workflow + + \param activity The Activity to register + \param subactivities The list of Activities to assign + \param description A JSON description of the Activity + \return + */ bool RegisterActivity( Ref activity, const std::vector& subactivities, const std::string& description = ""); + /*! Determine if an Activity exists in this Workflow + + \param activity The Activity name + \return Whether the Activity exists in this workflow + */ bool Contains(const std::string& activity); + + /*! Retrieve the configuration as an adjacency list in JSON for the Workflow, + or if specified just for the given ``activity``. + + \param activity If specified, return the configuration for the ``activity`` + \return An adjacency list representation of the configuration in JSON + */ std::string GetConfiguration(const std::string& activity = ""); + + /*! Get the workflow name + + \return The workflow name + */ std::string GetName() const; + + /*! Check whether the workflow is registered + + \return Whether the workflow is registered + */ bool IsRegistered() const; + + /*! Get the amount of registered activities for this Workflow + + \return The amount of registered workflows + */ size_t Size() const; + /*! Retrieve an activity by name + + \param activity The Activity name + \return The Activity object + */ Ref GetActivity(const std::string& activity); + + /*! Retrieve the list of activity roots for the Workflow, or if specified just for the given `activity`. + + \param activity If specified, return the roots for `activity` + \return A list of root activity names. + */ std::vector GetActivityRoots(const std::string& activity = ""); + + /*! Retrieve the list of all activities, or optionally a filtered list. + + \param activity If specified, return the direct children and optionally the descendants of the `activity` (includes `activity`) + \param immediate whether to include only direct children of `activity` or all descendants + \return A list of Activity names + */ std::vector GetSubactivities(const std::string& activity = "", bool immediate = true); + + /*! Assign the list of `activities` as the new set of children for the specified `activity`. + + \param activity The activity node to assign children + \param subactivities the list of Activities to assign + \return true on success, false otherwise + */ bool AssignSubactivities(const std::string& activity, const std::vector& subactivities = {}); + + /*! Remove all activity nodes from this Workflow + + \return true on success, false otherwise + */ bool Clear(); + + /*! Insert an activity before the specified activity and at the same level. + + \param activity Name of the activity to insert the new one before + \param newActivity Name of the new activity to be inserted + \return true on success, false otherwise + */ bool Insert(const std::string& activity, const std::string& newActivity); + + /*! Insert a list of activities before the specified activity and at the same level. + + \param activity Name of the activity to insert the new one before + \param newActivity Name of the new activities to be inserted + \return true on success, false otherwise + */ bool Insert(const std::string& activity, const std::vector& activities); + + /*! Remove an activity by name + + \param activity Name of the activity to remove + \return true on success, false otherwise + */ bool Remove(const std::string& activity); + + /*! Replace the activity name + + \param activity Name of the activity to replace + \param newActivity Name of the new activity + \return true on success, false otherwise + */ bool Replace(const std::string& activity, const std::string& newActivity); + /*! Generate a FlowGraph object for the current Workflow + + \param activity if specified, generate the Flowgraph using ``activity`` as the root + \param sequential whether to generate a **Composite** or **Sequential** style graph + \return FlowGraph on success + */ Ref GetGraph(const std::string& activity = "", bool sequential = false); void ShowReport(const std::string& name); -- cgit v1.3.1