Python APIs for basic block analysis

Author: zznop

architecture.cpp

@@ -313,7 +313,7 @@ void Architecture::AnalyzeBasicBlocksCallback(void *ctxt, BNFunction* function,
 {
 	CallbackRef<Architecture> arch(ctxt);
 	Ref<Function> func(new Function(BNNewFunctionReference(function)));
-	arch->AnalyzeBasicBlocks(*func, context);
+	arch->AnalyzeBasicBlocks(*func, *context);
 }
 
 
@@ -936,7 +936,7 @@ bool Architecture::GetInstructionLowLevelIL(const uint8_t*, uint64_t, size_t&, L
 }
 
 
-void Architecture::AnalyzeBasicBlocks(Function& function, BNBasicBlockAnalysisContext* context)
+void Architecture::AnalyzeBasicBlocks(Function& function, BasicBlockAnalysisContext& context)
 {
 	DefaultAnalyzeBasicBlocks(function, context);
 }
@@ -1502,9 +1502,9 @@ bool CoreArchitecture::GetInstructionLowLevelIL(const uint8_t* data, uint64_t ad
 }
 
 
-void CoreArchitecture::AnalyzeBasicBlocks(Function& function, BNBasicBlockAnalysisContext* context)
+void CoreArchitecture::AnalyzeBasicBlocks(Function& function, BasicBlockAnalysisContext& context)
 {
-	BNArchitectureAnalyzeBasicBlocks(m_object, function.GetObject(), context);
+	BNArchitectureAnalyzeBasicBlocks(m_object, function.GetObject(), &context);
 }
 
 

binaryninjaapi.h

@@ -8064,6 +8064,7 @@ namespace BinaryNinja {
 	class RelocationHandler;
 
 	typedef size_t ExprId;
+	typedef BNBasicBlockAnalysisContext BasicBlockAnalysisContext;
 
 	/*! The Architecture class is the base class for all CPU architectures. This provides disassembly, assembly,
 	    patching, and IL translation lifting for a given architecture.
@@ -8172,7 +8173,7 @@ namespace BinaryNinja {
 			\param function Function to analyze
 			\param context Context for the analysis
 		*/
-		static void DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAnalysisContext* context);
+		static void DefaultAnalyzeBasicBlocks(Function& function, BasicBlockAnalysisContext& context);
 
 		/*! Get an Architecture by name
 
@@ -8277,7 +8278,7 @@ namespace BinaryNinja {
 			\param function Function to analyze
 			\param context Context for the analysis
 		*/
-		virtual void AnalyzeBasicBlocks(Function& function, BNBasicBlockAnalysisContext* context);
+		virtual void AnalyzeBasicBlocks(Function& function, BasicBlockAnalysisContext& context);
 
 		/*! Gets a register name from a register index.
 
@@ -8672,7 +8673,7 @@ namespace BinaryNinja {
 		    const uint8_t* data, uint64_t addr, size_t& len, std::vector<InstructionTextToken>& result) override;
 		virtual bool GetInstructionLowLevelIL(
 		    const uint8_t* data, uint64_t addr, size_t& len, LowLevelILFunction& il) override;
-		virtual void AnalyzeBasicBlocks(Function& function, BNBasicBlockAnalysisContext* context) override;
+		virtual void AnalyzeBasicBlocks(Function& function, BasicBlockAnalysisContext& context) override;
 		virtual std::string GetRegisterName(uint32_t reg) override;
 		virtual std::string GetFlagName(uint32_t flag) override;
 		virtual std::string GetFlagWriteTypeName(uint32_t flags) override;

binaryninjacore.h

@@ -37,7 +37,7 @@
 // Current ABI version for linking to the core. This is incremented any time
 // there are changes to the API that affect linking, including new functions,
 // new types, or modifications to existing functions or types.
-#define BN_CURRENT_CORE_ABI_VERSION 105
+#define BN_CURRENT_CORE_ABI_VERSION 106
 
 // Minimum ABI version that is supported for loading of plugins. Plugins that
 // are linked to an ABI version less than this will not be able to load and
@@ -4811,7 +4811,7 @@ extern "C"
 	BINARYNINJACOREAPI BNBasicBlockEdge* BNGetBasicBlockIncomingEdges(BNBasicBlock* block, size_t* count);
 	BINARYNINJACOREAPI void BNFreeBasicBlockEdgeList(BNBasicBlockEdge* edges, size_t count);
 	BINARYNINJACOREAPI bool BNBasicBlockHasUndeterminedOutgoingEdges(BNBasicBlock* block);
-	BINARYNINJACOREAPI void BNBasicBlockAddPendingOutgoingEdge(BNBasicBlock* block, BNBranchType type, 
+	BINARYNINJACOREAPI void BNBasicBlockAddPendingOutgoingEdge(BNBasicBlock* block, BNBranchType type,
 	    uint64_t addr, BNArchitecture* arch, bool fallThrough);
 	BINARYNINJACOREAPI BNPendingBasicBlockEdge* BNGetBasicBlockPendingOutgoingEdges(BNBasicBlock* block, size_t* count);
 	BINARYNINJACOREAPI void BNFreePendingBasicBlockEdgeList(BNPendingBasicBlockEdge* edges);

defaultabb.cpp

@@ -56,19 +56,19 @@ static bool GetNextFunctionAfterAddress(Ref<BinaryView> data, Ref<Platform> plat
 }
 
 
-void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAnalysisContext* context)
+void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BasicBlockAnalysisContext& context)
 {
 	auto data = function.GetView();
 	queue<ArchAndAddr> blocksToProcess;
 	map<ArchAndAddr, Ref<BasicBlock>> instrBlocks;
 	set<ArchAndAddr> seenBlocks;
 	map<ArchAndAddr, set<ArchAndAddr>> indirectBranches;
-	for (size_t i = 0; i < context->indirectBranchesCount; i++)
+	for (size_t i = 0; i < context.indirectBranchesCount; i++)
 	{
-		auto sourceLocation = ArchAndAddr(new CoreArchitecture(context->indirectBranches[i].sourceArch),
-			context->indirectBranches[i].sourceAddr);
-		auto destLocation = ArchAndAddr(new CoreArchitecture(context->indirectBranches[i].destArch),
-			context->indirectBranches[i].destAddr);
+		auto sourceLocation = ArchAndAddr(new CoreArchitecture(context.indirectBranches[i].sourceArch),
+			context.indirectBranches[i].sourceAddr);
+		auto destLocation = ArchAndAddr(new CoreArchitecture(context.indirectBranches[i].destArch),
+			context.indirectBranches[i].destAddr);
 		indirectBranches[sourceLocation].insert(destLocation);
 	}
 
@@ -148,7 +148,7 @@ void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAna
 	}
 
 	uint64_t totalSize = 0;
-	uint64_t maxSize = context->maxFunctionSize;
+	uint64_t maxSize = context.maxFunctionSize;
 	while (blocksToProcess.size() != 0)
 	{
 		if (data->AnalysisIsAborted())
@@ -356,7 +356,7 @@ void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAna
 							function.AddDirectCodeReference(location, info.branchTarget[i]);
 
 							auto otherFunc = function.GetCalleeForAnalysis(targetPlatform, target.address, true);
-							if (context->translateTailCalls && targetPlatform && otherFunc && (otherFunc->GetStart() != function.GetStart()))
+							if (context.translateTailCalls && targetPlatform && otherFunc && (otherFunc->GetStart() != function.GetStart()))
 							{
 								calledFunctions.insert(otherFunc);
 								if (info.branchType[i] == UnconditionalBranch)
@@ -371,7 +371,7 @@ void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAna
 									break;
 								}
 							}
-							else if (context->disallowBranchToString && data->GetStringAtAddress(location.address, strRef) && targetExceedsByteLimit(strRef))
+							else if (context.disallowBranchToString && data->GetStringAtAddress(location.address, strRef) && targetExceedsByteLimit(strRef))
 							{
 								BNLogInfo("Not adding branch target from 0x%" PRIx64 " to string at 0x%" PRIx64
 									" length:%zu",
@@ -503,7 +503,7 @@ void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAna
 									targetPlatform = funcPlatform->GetRelatedPlatform(branch.arch);
 
 								// Normal analysis should not inline indirect targets that are function starts
-								if (context->translateTailCalls && data->GetAnalysisFunction(targetPlatform, branch.address))
+								if (context.translateTailCalls && data->GetAnalysisFunction(targetPlatform, branch.address))
 									continue;
 
 								block->AddPendingOutgoingEdge(IndirectBranch, branch.address, branch.arch);
@@ -590,10 +590,10 @@ void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAna
 			// We prefer to allow disassembly when function analysis is disabled, but only up to the maximum size.
 			// The log message and tag are generated in ProcessAnalysisSkip
 			totalSize += info.length;
-			if (context->analysisSkipOverride == NeverSkipFunctionAnalysis)
+			if (context.analysisSkipOverride == NeverSkipFunctionAnalysis)
 				maxSize = 0;
-			else if (!maxSize && (context->analysisSkipOverride == AlwaysSkipFunctionAnalysis))
-				maxSize = context->maxFunctionSize;
+			else if (!maxSize && (context.analysisSkipOverride == AlwaysSkipFunctionAnalysis))
+				maxSize = context.maxFunctionSize;
 			if (maxSize && (totalSize > maxSize))
 				break;
 
@@ -609,7 +609,7 @@ void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAna
 				delayInstructionEndsBlock = endsBlock;
 			}
 
-			if (block->CanExit() && context->translateTailCalls && !delaySlotCount && hasNextFunc && (location.address == nextFuncAddr))
+			if (block->CanExit() && context.translateTailCalls && !delaySlotCount && hasNextFunc && (location.address == nextFuncAddr))
 			{
 				// Falling through into another function.  Don't consider this a tail call if the current block
 				// called the function, as this indicates a get PC construct.
@@ -644,5 +644,5 @@ void Architecture::DefaultAnalyzeBasicBlocks(Function& function, BNBasicBlockAna
 void Architecture::DefaultAnalyzeBasicBlocksCallback(BNFunction* function, BNBasicBlockAnalysisContext* context)
 {
 	Ref<Function> func(new Function(BNNewFunctionReference(function)));
-	Architecture::DefaultAnalyzeBasicBlocks(*func, context);
+	Architecture::DefaultAnalyzeBasicBlocks(*func, *context);
 }

python/architecture.py

@@ -40,6 +40,7 @@
 from . import function
 from . import binaryview
 from . import deprecation
+from .variable import IndirectBranchInfo
 
 RegisterIndex = NewType('RegisterIndex', int)
 RegisterStackIndex = NewType('RegisterStackIndex', int)
@@ -65,6 +66,16 @@
 IntrinsicType = Union[IntrinsicName, 'lowlevelil.ILIntrinsic', IntrinsicIndex]
 
 
+@dataclass(frozen=True)
+class BasicBlockAnalysisContext:
+	"""Used by ``analyze_basic_blocks`` and contains analysis settings and other contextual information."""
+	indirect_branches: List[IndirectBranchInfo]
+	analysis_skip_override: core.FunctionAnalysisSkipOverrideEnum
+	translate_tail_calls: bool
+	disallow_branch_to_string: bool
+	max_function_size: int
+
+
 @dataclass(frozen=True)
 class RegisterInfo:
 	full_width_reg: RegisterName
@@ -711,8 +722,21 @@ def _get_instruction_low_level_il(self, ctxt, data, addr, length, il):
 			log_error(traceback.format_exc())
 			return False
 
-	def _analyze_basic_blocks(self, ctx, func, context):
+	def _analyze_basic_blocks(self, ctx, func, ptr_bn_bb_context):
 		try:
+			bn_bb_context = ptr_bn_bb_context.contents
+			indirect_branches = []
+			for i in range(0, bn_bb_context.indirectBranchesCount):
+				ibi = IndirectBranchInfo()
+				ibi.source_arch = CoreArchitecture._from_cache(bn_bb_context.indirectBranches[i].sourceArch)
+				ibi.source_addr = bn_bb_context.indirectBranches[i].sourceAddr
+				ibi.dest_arch = CoreArchitecture._from_cache(bn_bb_context.indirectBranches[i].destArch)
+				ibi.dest_addr = bn_bb_context.indirectBranches[i].destAddr
+				ibi.auto_defined = bn_bb_context.indirectBranches[i].autoDefined
+				indirect_branches.append(ibi)
+
+			context = BasicBlockAnalysisContext(indirect_branches, bn_bb_context.analysisSkipOverride,
+				bn_bb_context.translateTailCalls, bn_bb_context.disallowBranchToString, bn_bb_context.maxFunctionSize)
 			self.analyze_basic_blocks(function.Function(handle=core.BNNewFunctionReference(func)), context)
 		except:
 			log_error(traceback.format_exc())
@@ -1432,18 +1456,31 @@ def get_instruction_low_level_il(self, data: bytes, addr: int, il: lowlevelil.Lo
 		"""
 		raise NotImplementedError
 
-	def analyze_basic_blocks(self, func, context):
+	def analyze_basic_blocks(self, func: 'function.Function', context: BasicBlockAnalysisContext) -> None:
 		"""
-		``analyze_basic_blocks`` performs function-level basic block recovery and commits the blocks to analysis
+		``analyze_basic_blocks`` performs basic block recovery and commits the results to the function analysis
 
-		.. note:: Architecture subclasses should not implement this method unless function-level lifting is required
+		.. note:: Architecture subclasses should only implement this method if function-level analysis is required
 
 		:param Function func: the function to analyze
 		:param BNBasicBlockAnalysisContext context: the analysis context
 		"""
 
 		try:
-			core.BNArchitectureDefaultAnalyzeBasicBlocks(func.handle, context)
+			bn_bb_context = core.BNBasicBlockAnalysisContext()
+			bn_bb_context.indirectBranchesCount = len(context.indirect_branches)
+			bn_bb_context.analysisSkipOverride = context.analysis_skip_override
+			bn_bb_context.translateTailCalls = context.translate_tail_calls
+			bn_bb_context.disallowBranchToString = context.disallow_branch_to_string
+			bn_bb_context.maxFunctionSize = context.max_function_size
+			bn_bb_context.indirectBranches = (core.BNIndirectBranchInfo * len(context.indirect_branches))()
+			for i in range(0, len(context.indirect_branches)):
+				bn_bb_context.indirectBranches[i].sourceArch = context.indirect_branches[i].source_arch.handle
+				bn_bb_context.indirectBranches[i].sourceAddr = context.indirect_branches[i].source_addr
+				bn_bb_context.indirectBranches[i].destArch = context.indirect_branches[i].dest_arch.handle
+				bn_bb_context.indirectBranches[i].destAddr = context.indirect_branches[i].dest_addr
+				bn_bb_context.indirectBranches[i].autoDefined = context.indirect_branches[i].auto_defined
+			core.BNArchitectureDefaultAnalyzeBasicBlocks(func.handle, ctypes.byref(bn_bb_context))
 		except:
 			log_error(traceback.format_exc())