Firmware Ninja reference tree API

Author: zznop

binaryninjaapi.h

@@ -18397,6 +18397,59 @@ namespace BinaryNinja {
 		size_t unique;
 	};
 
+
+	/*! FirmwareNinjaReferenceNode is a class used to build reference trees to memory regions, functions, and data
+		variables. This class is only available in the Ultimate Edition of Binary Ninja.
+
+		\ingroup firmwareninja
+	*/
+	class FirmwareNinjaReferenceNode : public CoreRefCountObject<BNFirmwareNinjaReferenceNode, BNNewFirmwareNinjaReferenceNodeReference, BNFreeFirmwareNinjaReferenceNode>
+	{
+		BNFirmwareNinjaReferenceNode* m_object;
+	public:
+		FirmwareNinjaReferenceNode(BNFirmwareNinjaReferenceNode* node);
+		~FirmwareNinjaReferenceNode();
+
+		/*! Determine if the reference tree node is for a function
+
+			\return true if the reference tree node is for a function, false otherwise
+		 */
+		bool IsFunction();
+
+		/*! Determine if the reference tree node is for a data variable
+
+			\return true if the reference tree node is for a data variable, false otherwise
+		 */
+		bool IsDataVariable();
+
+		/*! Determine if the reference tree node contains child nodes
+
+			\return true if the reference tree node contains child nodes, false otherwise
+		 */
+		bool HasChildren();
+
+		/*! Query the function contained in the reference tree node
+
+			\param function Output function object
+			\return true if the function was queried successfully, false otherwise
+		 */
+		bool GetFunction(Ref<Function>& function);
+
+		/*! Query the data variable contained in the reference tree node
+
+			\param function Output data variable object
+			\return true if the data variable was queried successfully, false otherwise
+		 */
+		bool GetDataVariable(DataVariable& variable);
+
+		/*! Query the child nodes contained in the reference tree node
+
+			\return Vector of child reference tree nodes
+		 */
+		std::vector<Ref<FirmwareNinjaReferenceNode>> GetChildren();
+	};
+
+
 	/*! FirmwareNinja is a class containing features specific to embedded firmware analysis. This class is only
 		available in the Ultimate Edition of Binary Ninja.
 
@@ -18485,6 +18538,47 @@ namespace BinaryNinja {
 		 */
 		std::vector<FirmwareNinjaDeviceAccesses> GetBoardDeviceAccesses(
 			const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma);
+
+
+		/*! Returns a tree of reference nodes that reference the memory region represented by the given device
+
+			\param device Firmware Ninja device
+			\param fma Vector of Firmware Ninja function memory accesses information
+			\param value (Optional) only include components that originate with a write of this value to the device
+			\return Root reference node of tree
+		 */
+		Ref<FirmwareNinjaReferenceNode> GetReferenceTree(
+			FirmwareNinjaDevice& device,
+			const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma,
+			uint64_t* value = nullptr
+		);
+
+		/*! Returns a tree of reference nodes that reference the memory region represented by the given section
+
+			\param device Firmware Ninja device
+			\param fma Vector of Firmware Ninja function memory accesses information
+			\param value (Optional) only include components that originate with a write of this value to the device
+			\return Root reference node of tree
+		 */
+		Ref<FirmwareNinjaReferenceNode> GetReferenceTree(
+			Section& section,
+			const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma,
+			uint64_t* value = nullptr
+		);
+
+
+		/*! Returns a tree of reference nodes that reference the given address
+
+			\param device Firmware Ninja device
+			\param fma Vector of Firmware Ninja function memory accesses information
+			\param value (Optional) only include components that originate with a write of this value to the device
+			\return Root reference node of tree
+		 */
+		Ref<FirmwareNinjaReferenceNode> GetReferenceTree(
+			uint64_t address,
+			const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma,
+			uint64_t* value = nullptr
+		);
 	};
 
 

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 87
+#define BN_CURRENT_CORE_ABI_VERSION 88
 
 // 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
@@ -301,6 +301,7 @@ extern "C"
 	typedef struct BNUndoEntry BNUndoEntry;
 	typedef struct BNDemangler BNDemangler;
 	typedef struct BNFirmwareNinja BNFirmwareNinja;
+	typedef struct BNFirmwareNinjaReferenceNode BNFirmwareNinjaReferenceNode;
 
 	//! Console log levels
 	typedef enum BNLogLevel
@@ -3537,7 +3538,6 @@ extern "C"
 		size_t unique;
 	} BNFirmwareNinjaDeviceAccesses;
 
-
 	BINARYNINJACOREAPI char* BNAllocString(const char* contents);
 	BINARYNINJACOREAPI char* BNAllocStringWithLength(const char* contents, size_t len);
 	BINARYNINJACOREAPI void BNFreeString(char* str);
@@ -8038,12 +8038,24 @@ extern "C"
 	BINARYNINJACOREAPI int BNFirmwareNinjaQueryBoardDevices(BNFirmwareNinja* fn, BNArchitecture* arch, const char* board, BNFirmwareNinjaDevice** devices);
 	BINARYNINJACOREAPI int BNFirmwareNinjaFindSectionsWithEntropy(BNFirmwareNinja* fn, BNFirmwareNinjaSection** sections, float highCodeEntropyThreshold, float lowCodeEntropyThreshold, size_t blockSize, BNFirmwareNinjaSectionAnalysisMode mode);
 	BINARYNINJACOREAPI void BNFirmwareNinjaFreeSections(BNFirmwareNinjaSection *sections, int size);
-	BINARYNINJACOREAPI int BNFirmwareNinjaGetFunctionMemoryAccesses(BNFirmwareNinja* fn, BNFirmwareNinjaFunctionMemoryAccesses*** mmio, BNProgressFunction progress, void* progressContext);
-	BINARYNINJACOREAPI void BNFirmwareNinjaFreeFunctionMemoryAccesses(BNFirmwareNinjaFunctionMemoryAccesses **mmio, int size);
-	BINARYNINJACOREAPI void BNFirmwareNinjaStoreFunctionMemoryAccessesToMetadata(BNFirmwareNinja* fn, BNFirmwareNinjaFunctionMemoryAccesses** mmio, int size);
-	BINARYNINJACOREAPI int BNFirmwareNinjaQueryFunctionMemoryAccessesFromMetadata(BNFirmwareNinja* fn, BNFirmwareNinjaFunctionMemoryAccesses*** mmio);
-	BINARYNINJACOREAPI int BNFirmwareNinjaGetBoardDeviceAccesses(BNFirmwareNinja* fn, BNFirmwareNinjaFunctionMemoryAccesses** mmio, int size, BNFirmwareNinjaDeviceAccesses** accesses, BNArchitecture* arch);
+	BINARYNINJACOREAPI int BNFirmwareNinjaGetFunctionMemoryAccesses(BNFirmwareNinja* fn, BNFirmwareNinjaFunctionMemoryAccesses*** fma, BNProgressFunction progress, void* progressContext);
+	BINARYNINJACOREAPI void BNFirmwareNinjaFreeFunctionMemoryAccesses(BNFirmwareNinjaFunctionMemoryAccesses **fma, int size);
+	BINARYNINJACOREAPI void BNFirmwareNinjaStoreFunctionMemoryAccessesToMetadata(BNFirmwareNinja* fn, BNFirmwareNinjaFunctionMemoryAccesses** fma, int size);
+	BINARYNINJACOREAPI int BNFirmwareNinjaQueryFunctionMemoryAccessesFromMetadata(BNFirmwareNinja* fn, BNFirmwareNinjaFunctionMemoryAccesses*** fma);
+	BINARYNINJACOREAPI int BNFirmwareNinjaGetBoardDeviceAccesses(BNFirmwareNinja* fn, BNFirmwareNinjaFunctionMemoryAccesses** fma, int size, BNFirmwareNinjaDeviceAccesses** accesses, BNArchitecture* arch);
 	BINARYNINJACOREAPI void BNFirmwareNinjaFreeBoardDeviceAccesses(BNFirmwareNinjaDeviceAccesses *accesses, int size);
+	BINARYNINJACOREAPI BNFirmwareNinjaReferenceNode* BNFirmwareNinjaGetMemoryRegionReferenceTree(BNFirmwareNinja* fn, uint64_t start, uint64_t end, BNFirmwareNinjaFunctionMemoryAccesses** fma, int size, uint64_t* value);
+	BINARYNINJACOREAPI BNFirmwareNinjaReferenceNode* BNFirmwareNinjaGetAddressReferenceTree(BNFirmwareNinja* fn, uint64_t address, BNFirmwareNinjaFunctionMemoryAccesses** fma, int size, uint64_t* value);
+
+	BINARYNINJACOREAPI bool BNFirmwareNinjaReferenceNodeIsFunction(BNFirmwareNinjaReferenceNode* node);
+	BINARYNINJACOREAPI bool BNFirmwareNinjaReferenceNodeIsDataVariable(BNFirmwareNinjaReferenceNode* node);
+	BINARYNINJACOREAPI bool BNFirmwareNinjaReferenceNodeHasChildren(BNFirmwareNinjaReferenceNode* node);
+	BINARYNINJACOREAPI BNFunction* BNFirmwareNinjaReferenceNodeGetFunction(BNFirmwareNinjaReferenceNode* node);
+	BINARYNINJACOREAPI BNDataVariable* BNFirmwareNinjaReferenceNodeGetDataVariable(BNFirmwareNinjaReferenceNode* node);
+	BINARYNINJACOREAPI BNFirmwareNinjaReferenceNode** BNFirmwareNinjaReferenceNodeGetChildren(BNFirmwareNinjaReferenceNode* parent, size_t* count);
+	BINARYNINJACOREAPI void BNFreeFirmwareNinjaReferenceNode(BNFirmwareNinjaReferenceNode* node);
+	BINARYNINJACOREAPI BNFirmwareNinjaReferenceNode* BNNewFirmwareNinjaReferenceNodeReference(BNFirmwareNinjaReferenceNode* node);
+	BINARYNINJACOREAPI void BNFreeFirmwareNinjaReferenceNodes(BNFirmwareNinjaReferenceNode** nodes, size_t count);
 #ifdef __cplusplus
 }
 #endif

firmwareninja.cpp

@@ -58,10 +58,83 @@ static void FreeMemoryInfoArray(BNFirmwareNinjaFunctionMemoryAccesses** fma, siz
 }
 
 
+FirmwareNinjaReferenceNode::FirmwareNinjaReferenceNode(BNFirmwareNinjaReferenceNode* node)
+{
+	m_object = node;
+}
+
+
+FirmwareNinjaReferenceNode::~FirmwareNinjaReferenceNode()
+{
+	BNFreeFirmwareNinjaReferenceNode(m_object);
+}
+
+
+bool FirmwareNinjaReferenceNode::IsFunction()
+{
+	return BNFirmwareNinjaReferenceNodeIsFunction(m_object);
+}
+
+
+bool FirmwareNinjaReferenceNode::IsDataVariable()
+{
+	return BNFirmwareNinjaReferenceNodeIsDataVariable(m_object);
+}
+
+
+bool FirmwareNinjaReferenceNode::HasChildren()
+{
+	return BNFirmwareNinjaReferenceNodeHasChildren(m_object);
+}
+
+
+bool FirmwareNinjaReferenceNode::GetFunction(Ref<Function>& function)
+{
+	auto bnFunction = BNFirmwareNinjaReferenceNodeGetFunction(m_object);
+	if (!bnFunction)
+		return false;
+
+	function = new Function(BNNewFunctionReference(bnFunction));
+	return true;
+}
+
+
+bool FirmwareNinjaReferenceNode::GetDataVariable(DataVariable& variable)
+{
+	auto bnVariable = BNFirmwareNinjaReferenceNodeGetDataVariable(m_object);
+	if (!bnVariable)
+		return false;
+
+	variable.address = bnVariable->address;
+	variable.type = Confidence(new Type(BNNewTypeReference(bnVariable->type)), bnVariable->typeConfidence);
+	variable.autoDiscovered = bnVariable->autoDiscovered;
+	BNFreeDataVariable(bnVariable);
+	return true;
+}
+
+
+std::vector<Ref<FirmwareNinjaReferenceNode>> FirmwareNinjaReferenceNode::GetChildren()
+{
+	std::vector<Ref<FirmwareNinjaReferenceNode>> result;
+	size_t count = 0;
+	auto bnChildren = BNFirmwareNinjaReferenceNodeGetChildren(m_object, &count);
+	result.reserve(count);
+	for (size_t i = 0; i < count; ++i)
+	{
+		result.push_back(new FirmwareNinjaReferenceNode(
+			BNNewFirmwareNinjaReferenceNodeReference(bnChildren[i])));
+	}
+
+	if (count)
+		BNFreeFirmwareNinjaReferenceNodes(bnChildren, count);
+	return result;
+}
+
+
 FirmwareNinja::FirmwareNinja(Ref<BinaryView> view)
 {
 	m_view = view;
-    m_object = BNCreateFirmwareNinja(view->GetObject());
+	m_object = BNCreateFirmwareNinja(view->GetObject());
 }
 
 
@@ -218,6 +291,9 @@ std::vector<FirmwareNinjaFunctionMemoryAccesses> FirmwareNinja::GetFunctionMemor
 
 void FirmwareNinja::StoreFunctionMemoryAccesses(const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma)
 {
+	if (fma.empty())
+		return;
+
 	BNFirmwareNinjaFunctionMemoryAccesses** fmaArray = MemoryInfoVectorToArray(fma);
 	BNFirmwareNinjaStoreFunctionMemoryAccessesToMetadata(m_object, fmaArray, fma.size());
 	FreeMemoryInfoArray(fmaArray, fma.size());
@@ -262,6 +338,9 @@ std::vector<FirmwareNinjaDeviceAccesses> FirmwareNinja::GetBoardDeviceAccesses(
 	const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma)
 {
 	std::vector<FirmwareNinjaDeviceAccesses> result;
+	if (fma.empty())
+		return result;
+
 	auto platform = m_view->GetDefaultPlatform();
 	if (!platform)
 		return result;
@@ -273,11 +352,9 @@ std::vector<FirmwareNinjaDeviceAccesses> FirmwareNinja::GetBoardDeviceAccesses(
 	BNFirmwareNinjaFunctionMemoryAccesses** fmaArray = MemoryInfoVectorToArray(fma);
 	BNFirmwareNinjaDeviceAccesses* accesses;
 	int count = BNFirmwareNinjaGetBoardDeviceAccesses(m_object, fmaArray, fma.size(), &accesses, arch->GetObject());
+	FreeMemoryInfoArray(fmaArray, fma.size());
 	if (count <= 0)
-	{
-		FreeMemoryInfoArray(fmaArray, fma.size());
 		return result;
-	}
 
 	result.reserve(count);
 	for (size_t i = 0; i < count; i++)
@@ -290,3 +367,56 @@ std::vector<FirmwareNinjaDeviceAccesses> FirmwareNinja::GetBoardDeviceAccesses(
 
 	return result;
 }
+
+
+Ref<FirmwareNinjaReferenceNode> FirmwareNinja::GetReferenceTree(
+	FirmwareNinjaDevice& device, const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma, uint64_t* value)
+{
+	BNFirmwareNinjaFunctionMemoryAccesses** fmaArray = nullptr;
+	if (!fma.empty())
+		fmaArray = MemoryInfoVectorToArray(fma);
+
+	auto bnReferenceTree = BNFirmwareNinjaGetMemoryRegionReferenceTree(
+		m_object, device.start, device.end, fmaArray, fma.size(), value);
+
+	FreeMemoryInfoArray(fmaArray, fma.size());
+	if (!bnReferenceTree)
+		return nullptr;
+
+	return new FirmwareNinjaReferenceNode(bnReferenceTree);
+}
+
+
+Ref<FirmwareNinjaReferenceNode> FirmwareNinja::GetReferenceTree(
+	Section& section, const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma, uint64_t* value)
+{
+	BNFirmwareNinjaFunctionMemoryAccesses** fmaArray = nullptr;
+	if (!fma.empty())
+		fmaArray = MemoryInfoVectorToArray(fma);
+
+	auto bnReferenceTree = BNFirmwareNinjaGetMemoryRegionReferenceTree(
+		m_object, section.GetStart(), section.GetStart() + section.GetLength(), fmaArray, fma.size(), value);
+
+	FreeMemoryInfoArray(fmaArray, fma.size());
+	if (!bnReferenceTree)
+		return nullptr;
+
+	return new FirmwareNinjaReferenceNode(bnReferenceTree);
+}
+
+
+Ref<FirmwareNinjaReferenceNode> FirmwareNinja::GetReferenceTree(
+	uint64_t address, const std::vector<FirmwareNinjaFunctionMemoryAccesses>& fma, uint64_t* value)
+{
+	BNFirmwareNinjaFunctionMemoryAccesses** fmaArray = nullptr;
+	if (!fma.empty())
+		fmaArray = MemoryInfoVectorToArray(fma);
+
+	auto bnReferenceTree = BNFirmwareNinjaGetAddressReferenceTree(m_object, address, fmaArray, fma.size(), value);
+
+	FreeMemoryInfoArray(fmaArray, fma.size());
+	if (!bnReferenceTree)
+		return nullptr;
+
+	return new FirmwareNinjaReferenceNode(bnReferenceTree);
+}