Binary Ninja API C++: Workflows

Searching...

No Matches

Classes
class	BinaryNinja::AnalysisContext
class	BinaryNinja::Activity
class	BinaryNinja::Workflow
	Workflows are represented as Directed Acyclic Graphs (DAGs), where each node corresponds to an Activity (an individual analysis or action). More...

◆ BinaryNinja::AnalysisContext

class BinaryNinja::AnalysisContext

Public Member Functions
	AnalysisContext (BNAnalysisContext *analysisContext)
virtual	~AnalysisContext ()
Ref< BinaryView >	GetBinaryView ()
	Get the BinaryView for the current AnalysisContext.
Ref< Function >	GetFunction ()
	Get the Function for the current AnalysisContext.
Ref< LowLevelILFunction >	GetLiftedILFunction ()
	Get the lifted IL function for the current AnalysisContext.
Ref< LowLevelILFunction >	GetLowLevelILFunction ()
	Get the low level IL function for the current AnalysisContext.
Ref< MediumLevelILFunction >	GetMediumLevelILFunction ()
	Get the medium level IL function for the current AnalysisContext.
Ref< HighLevelILFunction >	GetHighLevelILFunction ()
	Get the high level IL function for the current AnalysisContext.
void	SetBasicBlockList (std::vector< Ref< BasicBlock > > basicBlocks)
	Set a new BasicBlock list for the current analysis context.
void	SetLiftedILFunction (Ref< LowLevelILFunction > liftedIL)
	Set new lifted IL for the current analysis context.
void	SetLowLevelILFunction (Ref< LowLevelILFunction > lowLevelIL)
	Set the new Low Level IL for the current analysis context.
void	SetMediumLevelILFunction (Ref< MediumLevelILFunction > mediumLevelIL, std::unordered_map< size_t, size_t > llilSsaToMlilInstrMap={}, std::vector< BNExprMapInfo > llilSsaToMlilExprMap={})
	Set the new Medium Level IL for the current analysis context.
void	SetHighLevelILFunction (Ref< HighLevelILFunction > highLevelIL)
	Set the new High Level IL for the current analysis context.
bool	Inform (const char *request)
bool	Inform (const std::string &request)
template<typename... Args>
bool	Inform (Args... args)
Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNAnalysisContext, BNNewAnalysisContextReference, BNFreeAnalysisContext >
	CoreRefCountObject ()
virtual	~CoreRefCountObject ()
BNAnalysisContext *	GetObject () const
void	AddRef ()
void	Release ()
void	AddRefForRegistration ()
void	ReleaseForRegistration ()
void	AddRefForCallback ()
void	ReleaseForCallback ()

◆ AnalysisContext()

◆ ~AnalysisContext()

AnalysisContext::~AnalysisContext

(

)

virtual

◆ GetBinaryView()

Get the BinaryView for the current AnalysisContext.

Returns: The binary view for the current context

◆ GetFunction()

Get the Function for the current AnalysisContext.

Returns: The function for the current context

◆ GetLiftedILFunction()

Get the lifted IL function for the current AnalysisContext.

Returns: The Lifted IL LowLevelILFunction for the current context

◆ GetLowLevelILFunction()

Get the low level IL function for the current AnalysisContext.

Returns: The LowLevelILFunction for the current context

◆ GetMediumLevelILFunction()

◆ GetHighLevelILFunction()

Get the high level IL function for the current AnalysisContext.

Returns: The HighLevelILFunction for the current context

◆ SetBasicBlockList()

void AnalysisContext::SetBasicBlockList

(

std::vector< Ref< BasicBlock > >

basicBlocks

)

Set a new BasicBlock list for the current analysis context.

Parameters

basicBlocks

The new list of BasicBlocks

◆ SetLiftedILFunction()

Set new lifted IL for the current analysis context.

Parameters

liftedIL

The new lifted IL

◆ SetLowLevelILFunction()

Set the new Low Level IL for the current analysis context.

Parameters

lowLevelIL

the new Low Level IL

◆ SetMediumLevelILFunction()

void AnalysisContext::SetMediumLevelILFunction	(	Ref< MediumLevelILFunction >	mediumLevelIL,
		std::unordered_map< size_t, size_t >	llilSsaToMlilInstrMap = {},
		std::vector< BNExprMapInfo >	llilSsaToMlilExprMap = {} )

Set the new Medium Level IL for the current analysis context.

If mapping parameters are left as default (empty), then they will be automatically computed for you based on previous calls to AddExpr() and AddInstruction()

Parameters

mediumLevelIL	the new Medium Level IL
llilSsaToMlilInstrMap	New mappings from LLIL SSA -> MLIL instruction indices
llilSsaToMlilExprMap	New mappings from LLIL SSA -> MLIL expression indices

◆ SetHighLevelILFunction()

Set the new High Level IL for the current analysis context.

Parameters

highLevelIL

the new High Level IL

◆ Inform() [1/3]

bool AnalysisContext::Inform

(

const char *

request

)

◆ Inform() [2/3]

bool BinaryNinja::AnalysisContext::Inform

(

const std::string &

request

)

◆ Inform() [3/3]

template<typename... Args>

bool BinaryNinja::AnalysisContext::Inform

(

Args...

args

)

inline

◆ BinaryNinja::Activity

class BinaryNinja::Activity

Public Member Functions
	Activity (const std::string &configuration, const std::function< void(Ref< AnalysisContext >)> &action, const std::function< bool(Ref< Activity >, Ref< AnalysisContext >)> &eligibility=nullptr)
	Activity (BNActivity *activity)
virtual	~Activity ()
std::string	GetName () const
	Get the Activity name.
Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNActivity, BNNewActivityReference, BNFreeActivity >
	CoreRefCountObject ()
virtual	~CoreRefCountObject ()
BNActivity *	GetObject () const
void	AddRef ()
void	Release ()
void	AddRefForRegistration ()
void	ReleaseForRegistration ()
void	AddRefForCallback ()
void	ReleaseForCallback ()
Static Protected Member Functions
static void	RunAction (void ctxt, BNAnalysisContext analysisContext)
static bool	CheckEligibility (void ctxt, BNActivity activity, BNAnalysisContext *analysisContext)
Protected Attributes
std::function< void(Ref< AnalysisContext > analysisContext)>	m_action
std::function< bool(Ref< Activity >, Ref< AnalysisContext >)>	m_eligibility

◆ Activity() [1/2]

BinaryNinja::Activity::Activity	(	const std::string &	configuration,
		const std::function< void(Ref< AnalysisContext >)> &	action,
		const std::function< bool(Ref< Activity >, Ref< AnalysisContext >)> &	eligibility = nullptr )

Parameters

configuration	a JSON representation of the activity configuration
action	Workflow action, a function taking a Ref<AnalysisContext> as an argument.
eligibility	A function that determines whether the activity is eligible to run

◆ Activity() [2/2]

◆ ~Activity()

Activity::~Activity

(

)

virtual

◆ RunAction()

◆ CheckEligibility()

◆ GetName()

string Activity::GetName

(

)

const

Get the Activity name.

Returns: Activity name

◆ m_action

std::function<void(Ref<AnalysisContext> analysisContext)> BinaryNinja::Activity::m_action

protected

◆ m_eligibility

std::function<bool(Ref<Activity>, Ref<AnalysisContext>)> BinaryNinja::Activity::m_eligibility

protected

◆ BinaryNinja::Workflow

class BinaryNinja::Workflow

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.

Public Member Functions
	Workflow (const std::string &name="")
	Workflow (BNWorkflow *workflow)
	Workflow (BNWorkflow *workflow, Ref< BinaryView > view)
	Workflow (BNWorkflow *workflow, Ref< Function > function)
virtual	~Workflow ()
Ref< Workflow >	Clone (const std::string &name="", const std::string &activity="")
	Clone a workflow, copying all Activities and the execution strategy.
Ref< Activity >	RegisterActivity (const std::string &configuration, const std::function< void(Ref< AnalysisContext >)> &action, const std::vector< std::string > &subactivities={})
	Register an Activity with this Workflow.
Ref< Activity >	RegisterActivity (Ref< Activity > activity, const std::vector< std::string > &subactivities={})
	Register an Activity with this Workflow.
bool	Contains (const std::string &activity)
	Determine if an Activity exists in this Workflow.
std::string	GetConfiguration (const std::string &activity="")
	Retrieve the configuration as an adjacency list in JSON for the Workflow, or if specified just for the given ``activity``.
std::string	GetName () const
	Get the workflow name.
bool	IsRegistered () const
	Check whether the workflow is registered.
size_t	Size () const
	Get the amount of registered activities for this Workflow.
Ref< Activity >	GetActivity (const std::string &activity)
	Retrieve an activity by name.
std::vector< std::string >	GetActivityRoots (const std::string &activity="")
	Retrieve the list of activity roots for the Workflow, or if specified just for the given `activity`.
std::vector< std::string >	GetSubactivities (const std::string &activity="", bool immediate=true)
	Retrieve the list of all activities, or optionally a filtered list.
bool	AssignSubactivities (const std::string &activity, const std::vector< std::string > &subactivities={})
	Assign the list of `activities` as the new set of children for the specified `activity`.
bool	Clear ()
	Remove all activity nodes from this Workflow.
bool	Insert (const std::string &activity, const std::string &newActivity)
	Insert an activity before the specified activity and at the same level.
bool	Insert (const std::string &activity, const std::vector< std::string > &activities)
	Insert a list of activities before the specified activity and at the same level.
bool	InsertAfter (const std::string &activity, const std::string &newActivity)
	Insert an activity after the specified activity and at the same level.
bool	InsertAfter (const std::string &activity, const std::vector< std::string > &activities)
	Insert a list of activities after the specified activity and at the same level.
bool	Remove (const std::string &activity)
	Remove an activity by name.
bool	Replace (const std::string &activity, const std::string &newActivity)
	Replace the activity name.
Ref< FlowGraph >	GetGraph (const std::string &activity="", bool sequential=false)
	Generate a FlowGraph object for the current Workflow.
void	ShowReport (const std::string &name)
std::vector< std::string >	GetEligibilitySettings ()
WorkflowMachine *	GetWorkflowMachine () const
Public Member Functions inherited from BinaryNinja::CoreRefCountObject< BNWorkflow, BNNewWorkflowReference, BNFreeWorkflow >
	CoreRefCountObject ()
virtual	~CoreRefCountObject ()
BNWorkflow *	GetObject () const
void	AddRef ()
void	Release ()
void	AddRefForRegistration ()
void	ReleaseForRegistration ()
void	AddRefForCallback ()
void	ReleaseForCallback ()
Static Public Member Functions
static std::vector< Ref< Workflow > >	GetList ()
	Get a list of all workflows.
static Ref< Workflow >	Get (const std::string &name)
	Get an instance of an existing registered workflow by name.
static Ref< Workflow >	GetOrCreate (const std::string &name)
	Get an instance of a workflow by name.
static Ref< Workflow >	Instance (const std::string &name="")
	Get an instance of a workflow by name.
static bool	RegisterWorkflow (Ref< Workflow > workflow, const std::string &description="")
	Register a workflow, making it immutable and available for use.

◆ Workflow() [1/4]

BinaryNinja::Workflow::Workflow

(

const std::string &

name = ""

)

◆ Workflow() [2/4]

◆ Workflow() [3/4]

◆ Workflow() [4/4]

◆ ~Workflow()

virtual BinaryNinja::Workflow::~Workflow

(

)

inlinevirtual

◆ GetList()

vector< Ref< Workflow > > Workflow::GetList

(

)

static

Get a list of all workflows.

Returns: A list of Workflows

◆ Get()

Ref< Workflow > Workflow::Get

(

const std::string &

name

)

static

Get an instance of an existing registered workflow by name.

If no registered workflow exists, nullptr will be returned.

Note: Be sure to handle the nullptr case if you're retrieving anything other than a built-in workflow.

Parameters

Returns: The registered workflow, or nullptr if none exists.

◆ GetOrCreate()

Ref< Workflow > Workflow::GetOrCreate

(

const std::string &

name

)

static

Get an instance of a workflow by name.

If it is already registered, this will return the registered Workflow. If not, a new Workflow will be created and returned.

Note: If a new workflow is returned it will have no activities. Attempting to register new activities on it via `Insert` and `InsertAfter` will fail.

Parameters

Returns: The workflow.

◆ Instance()

Ref< Workflow > BinaryNinja::Workflow::Instance

(

const std::string &

name = ""

)

inlinestatic

Get an instance of a workflow by name.

If it is already registered, this will return the registered Workflow. If not, a new Workflow will be created and returned.

Deprecated: Use `Get` or `GetOrCreate` instead.

Note: If a new workflow is returned it will have no activities. Attempting to register new activities on it via `Insert` and `InsertAfter` will fail.

Parameters

Returns: The workflow.

◆ RegisterWorkflow()

bool Workflow::RegisterWorkflow	(	Ref< Workflow >	workflow,
		const std::string &	description = "" )

static

Parameters

workflow	The workflow to register
description	A JSON description of the Workflow

Returns: true on success, false otherwise

◆ Clone()

Ref< Workflow > Workflow::Clone	(	const std::string &	name = "",
		const std::string &	activity = "" )

Clone a workflow, copying all Activities and the execution strategy.

Parameters

name	If specified, name the new Workflow, otherwise the name is copied from the original
activity	If specified, perform the clone with `activity` as the root

Returns: A new Workflow

◆ RegisterActivity() [1/2]

Ref< Activity > BinaryNinja::Workflow::RegisterActivity	(	const std::string &	configuration,
		const std::function< void(Ref< AnalysisContext >)> &	action,
		const std::vector< std::string > &	subactivities = {} )

Parameters

activity	The Activity to register
description	A JSON description of the Activity

Returns

Parameters

configuration	a JSON representation of the activity configuration
action	Workflow action, a function taking a Ref<AnalysisContext> as an argument.
subactivities	The list of Activities to assign

Returns

◆ RegisterActivity() [2/2]

Ref< Activity > BinaryNinja::Workflow::RegisterActivity	(	Ref< Activity >	activity,
		const std::vector< std::string > &	subactivities = {} )

Parameters

activity	The Activity to register
subactivities	The list of Activities to assign

Returns

◆ Contains()

bool Workflow::Contains

(

const std::string &

activity

)

Determine if an Activity exists in this Workflow.

Parameters

activity

The Activity name

Returns: Whether the Activity exists in this workflow

◆ GetConfiguration()

string Workflow::GetConfiguration

(

const std::string &

activity = ""

)

Retrieve the configuration as an adjacency list in JSON for the Workflow, or if specified just for the given ``activity``.

Parameters

activity

If specified, return the configuration for the ``activity``

Returns: An adjacency list representation of the configuration in JSON

◆ GetName()

string Workflow::GetName

(

)

const

Get the workflow name.

Returns: The workflow name

◆ IsRegistered()

bool Workflow::IsRegistered

(

)

const

Check whether the workflow is registered.

Returns: Whether the workflow is registered

◆ Size()

size_t Workflow::Size

(

)

const

Get the amount of registered activities for this Workflow.

Returns: The amount of registered workflows

◆ GetActivity()

Ref< Activity > Workflow::GetActivity

(

const std::string &

activity

)

Retrieve an activity by name.

Parameters

activity

The Activity name

Returns: The Activity object

◆ GetActivityRoots()

vector< string > Workflow::GetActivityRoots

(

const std::string &

activity = ""

)

Retrieve the list of activity roots for the Workflow, or if specified just for the given `activity`.

Parameters

activity

If specified, return the roots for `activity`

Returns: A list of root activity names.

◆ GetSubactivities()

vector< string > Workflow::GetSubactivities	(	const std::string &	activity = "",
		bool	immediate = true )

Retrieve the list of all activities, or optionally a filtered list.

Parameters

activity	If specified, return the direct children and optionally the descendants of the `activity` (includes `activity`)
immediate	whether to include only direct children of `activity` or all descendants

Returns: A list of Activity names

◆ AssignSubactivities()

bool Workflow::AssignSubactivities	(	const std::string &	activity,
		const std::vector< std::string > &	subactivities = {} )

Assign the list of `activities` as the new set of children for the specified `activity`.

Parameters

activity	The activity node to assign children
subactivities	the list of Activities to assign

Returns: true on success, false otherwise

◆ Clear()

Remove all activity nodes from this Workflow.

Returns: true on success, false otherwise

◆ Insert() [1/2]

bool BinaryNinja::Workflow::Insert	(	const std::string &	activity,
		const std::string &	newActivity )

Insert an activity before the specified activity and at the same level.

Parameters

activity	Name of the activity to insert the new one before
newActivity	Name of the new activity to be inserted

Returns: true on success, false otherwise

◆ Insert() [2/2]

bool BinaryNinja::Workflow::Insert	(	const std::string &	activity,
		const std::vector< std::string > &	activities )

Insert a list of activities before the specified activity and at the same level.

Parameters

activity	Name of the activity to insert the new one before
newActivity	Name of the new activities to be inserted

Returns: true on success, false otherwise

◆ InsertAfter() [1/2]

bool BinaryNinja::Workflow::InsertAfter	(	const std::string &	activity,
		const std::string &	newActivity )

Insert an activity after the specified activity and at the same level.

Parameters

activity	Name of the activity to insert the new one after
newActivity	Name of the new activity to be inserted

Returns: true on success, false otherwise

◆ InsertAfter() [2/2]

bool BinaryNinja::Workflow::InsertAfter	(	const std::string &	activity,
		const std::vector< std::string > &	activities )

Insert a list of activities after the specified activity and at the same level.

Parameters

activity	Name of the activity to insert the new one after
newActivity	Name of the new activities to be inserted

Returns: true on success, false otherwise

◆ Remove()

bool Workflow::Remove

(

const std::string &

activity

)

Remove an activity by name.

Parameters

activity

Name of the activity to remove

Returns: true on success, false otherwise

◆ Replace()

bool Workflow::Replace	(	const std::string &	activity,
		const std::string &	newActivity )

Replace the activity name.

Parameters

activity	Name of the activity to replace
newActivity	Name of the new activity

Returns: true on success, false otherwise

◆ GetGraph()

Ref< FlowGraph > Workflow::GetGraph	(	const std::string &	activity = "",
		bool	sequential = false )

Generate a FlowGraph object for the current Workflow.

Parameters

activity	if specified, generate the Flowgraph using ``activity`` as the root
sequential	whether to generate a Composite or Sequential style graph

Returns: FlowGraph on success

◆ ShowReport()

void Workflow::ShowReport

(

const std::string &

name

)

◆ GetEligibilitySettings()

vector< string > Workflow::GetEligibilitySettings

(

)

◆ GetWorkflowMachine()

WorkflowMachine * BinaryNinja::Workflow::GetWorkflowMachine

(

)

const

inline

Classes

◆ BinaryNinja::AnalysisContext

Public Member Functions

◆ AnalysisContext()

◆ ~AnalysisContext()

◆ GetBinaryView()

◆ GetFunction()

◆ GetLiftedILFunction()

◆ GetLowLevelILFunction()

◆ GetMediumLevelILFunction()

◆ GetHighLevelILFunction()

◆ SetBasicBlockList()

◆ SetLiftedILFunction()

◆ SetLowLevelILFunction()

◆ SetMediumLevelILFunction()

◆ SetHighLevelILFunction()

◆ Inform() [1/3]

◆ Inform() [2/3]

◆ Inform() [3/3]

◆ BinaryNinja::Activity

Public Member Functions

Static Protected Member Functions

Protected Attributes

◆ Activity() [1/2]

◆ Activity() [2/2]

◆ ~Activity()

◆ RunAction()

◆ CheckEligibility()

◆ GetName()

◆ m_action

◆ m_eligibility

◆ BinaryNinja::Workflow

Public Member Functions

Static Public Member Functions

◆ Workflow() [1/4]

◆ Workflow() [2/4]

◆ Workflow() [3/4]

◆ Workflow() [4/4]

◆ ~Workflow()

◆ GetList()

◆ Get()

◆ GetOrCreate()

◆ Instance()

◆ RegisterWorkflow()

◆ Clone()

◆ RegisterActivity() [1/2]

◆ RegisterActivity() [2/2]

◆ Contains()

◆ GetConfiguration()

◆ GetName()

◆ IsRegistered()

◆ Size()

◆ GetActivity()

◆ GetActivityRoots()

◆ GetSubactivities()

◆ AssignSubactivities()

◆ Clear()

◆ Insert() [1/2]

◆ Insert() [2/2]

◆ InsertAfter() [1/2]

◆ InsertAfter() [2/2]

◆ Remove()

◆ Replace()

◆ GetGraph()

◆ ShowReport()

◆ GetEligibilitySettings()

◆ GetWorkflowMachine()