workflow module¶
Class |
Description |
---|---|
|
|
|
|
|
|
A simple framework for writing line-oriented command interpreters. |
- class Activity[source]
Bases:
object
Activity
in Binary Ninja represents an individual analysis or action to be performed on aBinaryView
orFunction
object.Activities are the fundamental units of execution within a
Workflow
. Each Activity encapsulates a specific task and defines its own behavior, dependencies, and eligibility criteria. Activities are executed in the context of anAnalysisContext
, which provides access to binary data, analysis state, and utility functions.- __init__(configuration: str = '', handle: LP_BNActivity | None = None, action: Callable[[Any], None] | None = None, eligibility: Callable[[Any], bool] | None = None)[source]
- property name: str
Activity name (read-only)
- class AnalysisContext[source]
Bases:
object
AnalysisContext
is a proxy object that provides access to the current analysis context, including the associatedBinaryView
,Function
, and intermediate language (IL) representations. It provides APIs to retrieve and modify the in-progress analysis state and allows users to notify the analysis system of any changes or updates.- __init__(handle: LP_BNAnalysisContext)[source]
- Parameters:
handle (LP_BNAnalysisContext) –
- set_mlil_function(new_func: MediumLevelILFunction, llil_ssa_to_mlil_instr_map: mediumlevelil.LLILSSAToMLILInstructionMapping | None = None, llil_ssa_to_mlil_expr_map: mediumlevelil.LLILSSAToMLILExpressionMapping | None = None) None [source]
Set the Medium Level IL function in the current analysis, giving updated Low Level IL (SSA) to Medium Level IL instruction and expression mappings. :param new_func: New MLIL function :param llil_ssa_to_mlil_instr_map: Mapping from every LLIL SSA instruction to every MLIL instruction :param llil_ssa_to_mlil_expr_map: Mapping from every LLIL SSA expression to one or more MLIL expressions (first expression will be the primary)
- Parameters:
new_func (MediumLevelILFunction) –
llil_ssa_to_mlil_instr_map (mediumlevelil.LLILSSAToMLILInstructionMapping | None) –
llil_ssa_to_mlil_expr_map (mediumlevelil.LLILSSAToMLILExpressionMapping | None) –
- Return type:
None
- property basic_blocks: BasicBlockList
function.BasicBlockList of BasicBlocks in the current function (writable)
- property hlil: HighLevelILFunction | None
HighLevelILFunction used to represent High Level IL (writable)
- property lifted_il: LowLevelILFunction | None
LowLevelILFunction used to represent lifted IL (writable)
- property llil: LowLevelILFunction | None
LowLevelILFunction used to represent Low Level IL (writable)
- property mlil: MediumLevelILFunction | None
MediumLevelILFunction used to represent Medium Level IL (writable)
- property view: BinaryView | None
BinaryView for the current AnalysisContext (writable)
- class Workflow[source]
Bases:
object
class Workflow
in Binary Ninja defines the set of analyses to perform on a binary, including their dependencies and execution order.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 forBinaryView
orFunction
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.- Example:
# Define the custom activity configuration configuration = json.dumps({ "name": "analysis.plugins.xorStringDecoder", "title": "XOR String Decoder", "description": "This analysis step transforms XOR-encoded strings within the current function.", "eligibility": { "auto": { "default": False } } }) # Clone the meta function workflow for customization workflow = Workflow("core.function.metaAnalysis").clone() # Register a new activity workflow.register_activity(Activity( configuration, action=lambda analysis_context: log_warn( f"Decoder running for function: {hex(analysis_context.function.start)}" # Insert decoder logic here :P ) )) # Insert the new activity before the "generateHighLevelIL" step workflow.insert("core.function.generateHighLevelIL", ["analysis.plugins.xorStringDecoder"]) # Register the modified meta function workflow workflow.register()
- __init__(name: str = '', handle: LP_BNWorkflow | None = None, query_registry: bool = True, object_handle: LP_BNFunction | LP_BNBinaryView | None = None)[source]
- activity_roots(activity: Activity | str = '') List[str] [source]
activity_roots
Retrieve the list of activity roots for the Workflow, or if specified just for the givenactivity
.
- assign_subactivities(activity: Activity, activities: List[str] | str) bool [source]
assign_subactivities
Assign the list ofactivities
as the new set of children for the specifiedactivity
.
- clear() bool [source]
clear
Remove all Activity nodes from this Workflow.- Returns:
True on success, False otherwise
- Return type:
- clone(name: str | None = None, activity: Activity | str = '') Workflow [source]
clone
Clone a new Workflow, copying all Activities and the execution strategy.
- configuration(activity: Activity | str = '') str [source]
configuration
Retrieve the configuration as an adjacency list in JSON for the Workflow, or if specified just for the givenactivity
.- Parameters:
activity (ActivityType) – if specified, return the configuration for the
activity
- Returns:
an adjacency list representation of the configuration in JSON
- Return type:
- contains(activity: Activity | str) bool [source]
contains
Determine if an Activity exists in this Workflow.- Parameters:
activity (ActivityType) – the Activity name
- Returns:
True if the Activity exists, False otherwise
- Return type:
- eligibility_settings() List[str] [source]
eligibility_settings
Retrieve the list of eligibility settings for the Workflow.
- get_activity(activity: Activity | str) Activity | None [source]
get_activity
Retrieve the Activity object for the specifiedactivity
.
- graph(activity: Activity | str = '', sequential: bool = False, show: bool = True) FlowGraph | None [source]
graph
Generate a FlowGraph object for the current Workflow and optionally show it in the UI.- Parameters:
- Returns:
FlowGraph object on success, None on failure
- Return type:
- insert(activity: Activity | str, activities: List[str] | str) bool [source]
insert
Insert the list ofactivities
before the specifiedactivity
and at the same level.
- insert_after(activity: Activity | str, activities: List[str] | str) bool [source]
insert_after
Insert the list ofactivities
after the specifiedactivity
and at the same level.
- register(configuration: str = '') bool [source]
register
Register this Workflow, making it immutable and available for use.
- register_activity(activity: Activity, subactivities: List[Activity | str] = []) Activity | None [source]
register_activity
Register an Activity with this Workflow.
- replace(activity: Activity | str, new_activity: str) bool [source]
replace
Replace the specifiedactivity
.
- subactivities(activity: Activity | str = '', immediate: bool = True) List[str] [source]
subactivities
Retrieve the list of all activities, or optionally a filtered list.
- property machine
- property name: str
- class WorkflowMachine[source]
Bases:
object
- __init__(handle: LP_BNFunction | LP_BNBinaryView | None = None)[source]
- Parameters:
handle (LP_BNFunction | LP_BNBinaryView | None) –
- breakpoint_delete(activities)[source]
- breakpoint_query()[source]
- breakpoint_set(activities)[source]
- cli()[source]
- delay(duration)[source]
- disable()[source]
- dump()[source]
- enable()[source]
- halt()[source]
- override_clear(activity)[source]
- override_query(activity=None)[source]
- override_set(activity, enable)[source]
- request(request)[source]
- reset()[source]
- status()[source]
- step()[source]
- class WorkflowMachineCLI[source]
Bases:
Cmd
- __init__(machine: WorkflowMachine)[source]
Instantiate a line-oriented interpreter framework.
The optional argument ‘completekey’ is the readline name of a completion key; it defaults to the Tab key. If completekey is not None and the readline module is available, command completion is done automatically. The optional arguments stdin and stdout specify alternate input and output file objects; if not specified, sys.stdin and sys.stdout are used.
- Parameters:
machine (WorkflowMachine) –
- do_breakpoint(line)[source]
Handle breakpoint commands.
- do_configure(line)[source]
Configure the workflow machine.
- do_disable(line)[source]
Disable the workflow machine.
- do_dump(line)[source]
Dump metrics from the workflow system.
- do_enable(line)[source]
Enable the workflow machine.
- do_halt(line)[source]
Halt the workflow machine.
- do_log(line)[source]
Control workflow logging.
- do_metrics(line)[source]
Control workflow metrics collection.
- do_override(line)[source]
Handle override commands.
- do_quit(line)[source]
Exit the WorkflowMachine CLI.
- do_reset(line)[source]
Reset the workflow machine.
- do_resume(line)[source]
Continue/Resume execution of a workflow.
- do_run(line)[source]
Run the workflow machine and generate a default configuration if the workflow is not configured.
- do_status(line)[source]
Retrieve the current machine status.
- do_step(line)[source]
Step to the next activity in the workflow machine.
- help(arg)[source]
- precmd(line)[source]
Hook method executed just before the command line is interpreted, but after the input prompt is generated and issued.
- aliases = {'b': 'breakpoint', 'c': 'resume', 'd': 'dump', 'h': 'halt', 'l': 'log', 'm': 'metrics', 'o': 'override', 'q': 'quit', 'r': 'run', 's': 'step'}
- intro = "Welcome to the Workflow Orchestrator. Type 'help' to list available commands."
- prompt = '(dechora) '
Activity¶
- class Activity[source]¶
Bases:
object
Activity
in Binary Ninja represents an individual analysis or action to be performed on aBinaryView
orFunction
object.Activities are the fundamental units of execution within a
Workflow
. Each Activity encapsulates a specific task and defines its own behavior, dependencies, and eligibility criteria. Activities are executed in the context of anAnalysisContext
, which provides access to binary data, analysis state, and utility functions.
AnalysisContext¶
- class AnalysisContext[source]¶
Bases:
object
AnalysisContext
is a proxy object that provides access to the current analysis context, including the associatedBinaryView
,Function
, and intermediate language (IL) representations. It provides APIs to retrieve and modify the in-progress analysis state and allows users to notify the analysis system of any changes or updates.- set_mlil_function(new_func: MediumLevelILFunction, llil_ssa_to_mlil_instr_map: mediumlevelil.LLILSSAToMLILInstructionMapping | None = None, llil_ssa_to_mlil_expr_map: mediumlevelil.LLILSSAToMLILExpressionMapping | None = None) None [source]¶
Set the Medium Level IL function in the current analysis, giving updated Low Level IL (SSA) to Medium Level IL instruction and expression mappings. :param new_func: New MLIL function :param llil_ssa_to_mlil_instr_map: Mapping from every LLIL SSA instruction to every MLIL instruction :param llil_ssa_to_mlil_expr_map: Mapping from every LLIL SSA expression to one or more MLIL expressions (first expression will be the primary)
- Parameters:
new_func (MediumLevelILFunction) –
llil_ssa_to_mlil_instr_map (mediumlevelil.LLILSSAToMLILInstructionMapping | None) –
llil_ssa_to_mlil_expr_map (mediumlevelil.LLILSSAToMLILExpressionMapping | None) –
- Return type:
None
- property basic_blocks: BasicBlockList¶
function.BasicBlockList of BasicBlocks in the current function (writable)
- property hlil: HighLevelILFunction | None¶
HighLevelILFunction used to represent High Level IL (writable)
- property lifted_il: LowLevelILFunction | None¶
LowLevelILFunction used to represent lifted IL (writable)
- property llil: LowLevelILFunction | None¶
LowLevelILFunction used to represent Low Level IL (writable)
- property mlil: MediumLevelILFunction | None¶
MediumLevelILFunction used to represent Medium Level IL (writable)
- property view: BinaryView | None¶
BinaryView for the current AnalysisContext (writable)
Workflow¶
- class Workflow[source]¶
Bases:
object
class Workflow
in Binary Ninja defines the set of analyses to perform on a binary, including their dependencies and execution order.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 forBinaryView
orFunction
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.- Example:
# Define the custom activity configuration configuration = json.dumps({ "name": "analysis.plugins.xorStringDecoder", "title": "XOR String Decoder", "description": "This analysis step transforms XOR-encoded strings within the current function.", "eligibility": { "auto": { "default": False } } }) # Clone the meta function workflow for customization workflow = Workflow("core.function.metaAnalysis").clone() # Register a new activity workflow.register_activity(Activity( configuration, action=lambda analysis_context: log_warn( f"Decoder running for function: {hex(analysis_context.function.start)}" # Insert decoder logic here :P ) )) # Insert the new activity before the "generateHighLevelIL" step workflow.insert("core.function.generateHighLevelIL", ["analysis.plugins.xorStringDecoder"]) # Register the modified meta function workflow workflow.register()
- __init__(name: str = '', handle: LP_BNWorkflow | None = None, query_registry: bool = True, object_handle: LP_BNFunction | LP_BNBinaryView | None = None)[source]¶
- activity_roots(activity: Activity | str = '') List[str] [source]¶
activity_roots
Retrieve the list of activity roots for the Workflow, or if specified just for the givenactivity
.
- assign_subactivities(activity: Activity, activities: List[str] | str) bool [source]¶
assign_subactivities
Assign the list ofactivities
as the new set of children for the specifiedactivity
.
- clear() bool [source]¶
clear
Remove all Activity nodes from this Workflow.- Returns:
True on success, False otherwise
- Return type:
- clone(name: str | None = None, activity: Activity | str = '') Workflow [source]¶
clone
Clone a new Workflow, copying all Activities and the execution strategy.
- configuration(activity: Activity | str = '') str [source]¶
configuration
Retrieve the configuration as an adjacency list in JSON for the Workflow, or if specified just for the givenactivity
.- Parameters:
activity (ActivityType) – if specified, return the configuration for the
activity
- Returns:
an adjacency list representation of the configuration in JSON
- Return type:
- contains(activity: Activity | str) bool [source]¶
contains
Determine if an Activity exists in this Workflow.- Parameters:
activity (ActivityType) – the Activity name
- Returns:
True if the Activity exists, False otherwise
- Return type:
- eligibility_settings() List[str] [source]¶
eligibility_settings
Retrieve the list of eligibility settings for the Workflow.
- get_activity(activity: Activity | str) Activity | None [source]¶
get_activity
Retrieve the Activity object for the specifiedactivity
.
- graph(activity: Activity | str = '', sequential: bool = False, show: bool = True) FlowGraph | None [source]¶
graph
Generate a FlowGraph object for the current Workflow and optionally show it in the UI.- Parameters:
- Returns:
FlowGraph object on success, None on failure
- Return type:
- insert(activity: Activity | str, activities: List[str] | str) bool [source]¶
insert
Insert the list ofactivities
before the specifiedactivity
and at the same level.
- insert_after(activity: Activity | str, activities: List[str] | str) bool [source]¶
insert_after
Insert the list ofactivities
after the specifiedactivity
and at the same level.
- register(configuration: str = '') bool [source]¶
register
Register this Workflow, making it immutable and available for use.
- register_activity(activity: Activity, subactivities: List[Activity | str] = []) Activity | None [source]¶
register_activity
Register an Activity with this Workflow.
- replace(activity: Activity | str, new_activity: str) bool [source]¶
replace
Replace the specifiedactivity
.
- show_topology() None [source]¶
show_topology
Show the Workflow topology in the UI.- Return type:
None
- subactivities(activity: Activity | str = '', immediate: bool = True) List[str] [source]¶
subactivities
Retrieve the list of all activities, or optionally a filtered list.
- property machine¶
WorkflowMachine¶
- class WorkflowMachine[source]¶
Bases:
object
- __init__(handle: LP_BNFunction | LP_BNBinaryView | None = None)[source]¶
- Parameters:
handle (LP_BNFunction | LP_BNBinaryView | None) –
WorkflowMachineCLI¶
- class WorkflowMachineCLI[source]¶
Bases:
Cmd
- __init__(machine: WorkflowMachine)[source]¶
Instantiate a line-oriented interpreter framework.
The optional argument ‘completekey’ is the readline name of a completion key; it defaults to the Tab key. If completekey is not None and the readline module is available, command completion is done automatically. The optional arguments stdin and stdout specify alternate input and output file objects; if not specified, sys.stdin and sys.stdout are used.
- Parameters:
machine (WorkflowMachine) –
- do_run(line)[source]¶
Run the workflow machine and generate a default configuration if the workflow is not configured.
- precmd(line)[source]¶
Hook method executed just before the command line is interpreted, but after the input prompt is generated and issued.
- aliases = {'b': 'breakpoint', 'c': 'resume', 'd': 'dump', 'h': 'halt', 'l': 'log', 'm': 'metrics', 'o': 'override', 'q': 'quit', 'r': 'run', 's': 'step'}¶
- intro = "Welcome to the Workflow Orchestrator. Type 'help' to list available commands."¶
- prompt = '(dechora) '¶