Workflows

Detailed Description

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...

---

Class Documentation

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 ()

Additional Inherited Members
Public Attributes inherited from BinaryNinja::CoreRefCountObject< BNAnalysisContext, BNNewAnalysisContextReference, BNFreeAnalysisContext >
std::atomic< int >	m_refs
bool	m_registeredRef
BNAnalysisContext *	m_object

Constructor & Destructor Documentation

AnalysisContext()

AnalysisContext::AnalysisContext

(

BNAnalysisContext *

analysisContext

)

~AnalysisContext()

AnalysisContext::~AnalysisContext ( )

virtual

Member Function Documentation

GetBinaryView()

Ref< BinaryView > AnalysisContext::GetBinaryView

(

)

Get the BinaryView for the current AnalysisContext.

Returns

The binary view for the current context

GetFunction()

Ref< Function > AnalysisContext::GetFunction

(

)

Get the Function for the current AnalysisContext.

Returns

The function for the current context

GetLiftedILFunction()

Ref< LowLevelILFunction > AnalysisContext::GetLiftedILFunction

(

)

Get the lifted IL function for the current AnalysisContext.

Returns

The Lifted IL LowLevelILFunction for the current context

GetLowLevelILFunction()

Ref< LowLevelILFunction > AnalysisContext::GetLowLevelILFunction

(

)

Get the low level IL function for the current AnalysisContext.

Returns

The LowLevelILFunction for the current context

GetMediumLevelILFunction()

Ref< MediumLevelILFunction > AnalysisContext::GetMediumLevelILFunction

(

)

Get the medium level IL function for the current AnalysisContext.

Returns

The MediumLevelILFunction for the current context

GetHighLevelILFunction()

Ref< HighLevelILFunction > AnalysisContext::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()

void AnalysisContext::SetLiftedILFunction

(

Ref< LowLevelILFunction >

liftedIL

)

Set new lifted IL for the current analysis context.

Parameters

liftedIL

The new lifted IL

SetLowLevelILFunction()

void AnalysisContext::SetLowLevelILFunction

(

Ref< LowLevelILFunction >

lowLevelIL

)

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()

void AnalysisContext::SetHighLevelILFunction

(

Ref< HighLevelILFunction >

highLevelIL

)

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

Additional Inherited Members
Public Attributes inherited from BinaryNinja::CoreRefCountObject< BNActivity, BNNewActivityReference, BNFreeActivity >
std::atomic< int >	m_refs
bool	m_registeredRef
BNActivity *	m_object

Constructor & Destructor Documentation

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

(

BNActivity *

activity

)

~Activity()

Activity::~Activity ( )

virtual

Member Function Documentation

RunAction()

void Activity::RunAction ( void * ctxt, BNAnalysisContext * analysisContext )

staticprotected

CheckEligibility()

bool Activity::CheckEligibility ( void * ctxt, BNActivity * activity, BNAnalysisContext * analysisContext )

staticprotected

GetName()

string Activity::GetName

(

)

const

Get the Activity name.

Returns

Activity name

Member Data Documentation

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.

Additional Inherited Members
Public Attributes inherited from BinaryNinja::CoreRefCountObject< BNWorkflow, BNNewWorkflowReference, BNFreeWorkflow >
std::atomic< int >	m_refs
bool	m_registeredRef
BNWorkflow *	m_object

Constructor & Destructor Documentation

Workflow() [1/4]

BinaryNinja::Workflow::Workflow

(

const std::string &

name = ""

)

Workflow() [2/4]

Workflow::Workflow

(

BNWorkflow *

workflow

)

Workflow() [3/4]

Workflow::Workflow	(	BNWorkflow *	workflow,
		Ref< BinaryView >	view )

Workflow() [4/4]

Workflow::Workflow	(	BNWorkflow *	workflow,
		Ref< Function >	function )

~Workflow()

virtual BinaryNinja::Workflow::~Workflow ( )

inlinevirtual

Member Function Documentation

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

name	Workflow name

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

name	Workflow name

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

name	Workflow name

Returns

The workflow.

RegisterWorkflow()

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

static

Register a workflow, making it immutable and available for use.

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 = {} )

Register an Activity with this Workflow.

Parameters

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

Returns

Register an Activity with this Workflow

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 = {} )

Register an Activity with this Workflow.

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()

bool Workflow::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