# coding=utf-8# Copyright (c) 2015-2025 Vector 35 Inc## Permission is hereby granted, free of charge, to any person obtaining a copy# of this software and associated documentation files (the "Software"), to# deal in the Software without restriction, including without limitation the# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or# sell copies of the Software, and to permit persons to whom the Software is# furnished to do so, subject to the following conditions:## The above copyright notice and this permission notice shall be included in# all copies or substantial portions of the Software.## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS# IN THE SOFTWARE.importstructimportthreadingimportqueueimporttracebackimportctypesimportabcimportjsonimportpprintimportinspectimportosimportuuidfromtypingimportCallable,Generator,Optional,Union,Tuple,List,Mapping,Any, \Iterator,Iterable,KeysView,ItemsView,ValuesView,Dict,overloadfromdataclassesimportdataclassfromenumimportIntFlagimportcollectionsfromcollectionsimportdefaultdict,OrderedDict,deque# Binary Ninja componentsimportbinaryninjafrom.import_binaryninjacoreascorefrom.importdecoratorsfrom.enumsimport(AnalysisState,SymbolType,Endianness,ModificationStatus,StringType,SegmentFlag,SectionSemantics,FindFlag,TypeClass,BinaryViewEventType,FunctionGraphType,TagReferenceType,TagTypeType,RegisterValueType,DisassemblyOption,RelocationType,DerivedStringLocationType)from.exceptionsimportRelocationWriteException,ExternalLinkExceptionfrom.importassociateddatastore# required for _BinaryViewAssociatedDataStorefrom.logimportlog_warn,log_error_for_exception,Loggerfrom.importtypelibraryfrom.importfileaccessorfrom.importdatabufferfrom.importbasicblockfrom.importcomponentfrom.importlineardisassemblyfrom.importmetadatafrom.importhighlightfrom.importsettingsfrom.importvariablefrom.importarchitecturefrom.importfilemetadatafrom.importlowlevelilfrom.importmainthreadfrom.importmediumlevelilfrom.importhighlevelilfrom.importdebuginfofrom.importflowgraphfrom.importprojectfrom.importtypearchive# The following are imported as such to allow the type checker disambiguate the module name# from properties and methods of the same namefrom.importworkflowas_workflowfrom.importfunctionas_functionfrom.importtypesas_typesfrom.importplatformas_platformfrom.importdeprecationfrom.importtypecontainerfrom.importexternallibraryfrom.importprojectfrom.importundofrom.importstringrecognizerPathType=Union[str,os.PathLike]InstructionsType=Generator[Tuple[List['_function.InstructionTextToken'],int],None,None]NotificationType=Mapping['BinaryDataNotification','BinaryDataNotificationCallbacks']ProgressFuncType=Callable[[int,int],bool]DataMatchCallbackType=Callable[[int,'databuffer.DataBuffer'],bool]LineMatchCallbackType=Callable[[int,'lineardisassembly.LinearDisassemblyLine'],bool]StringOrType=Union[str,'_types.Type','_types.TypeBuilder']
[docs]@dataclass(frozen=True)classReferenceSource:function:Optional['_function.Function']arch:Optional['architecture.Architecture']address:intdef__repr__(self):ifself.arch:returnf"<ref:{self.arch.name}@{self.address:#x}>"else:returnf"<ref:{self.address:#x}>"@classmethoddef_from_core_struct(cls,view:'BinaryView',ref:core.BNReferenceSource)->'ReferenceSource':ifref.func:func=_function.Function(view,core.BNNewFunctionReference(ref.func))else:func=Noneifref.arch:arch=architecture.CoreArchitecture._from_cache(ref.arch)else:arch=NonereturnReferenceSource(func,arch,ref.addr)@propertydefllil(self)->Optional[lowlevelil.LowLevelILInstruction]:"""Returns the low level il instruction at the current location if one exists"""ifself.functionisNoneorself.archisNone:returnNonereturnself.function.get_low_level_il_at(self.address,self.arch)@propertydefllils(self)->Iterator[lowlevelil.LowLevelILInstruction]:"""Returns the low level il instructions at the current location if any exists"""ifself.functionisNoneorself.archisNone:returnreturnself.function.get_low_level_ils_at(self.address,self.arch)@propertydefmlil(self)->Optional[mediumlevelil.MediumLevelILInstruction]:"""Returns the medium level il instruction at the current location if one exists"""llil=self.llilreturnllil.mlilifllilisnotNoneelseNone@propertydefmlils(self)->Iterator[mediumlevelil.MediumLevelILInstruction]:"""Returns the medium level il instructions at the current location if any exists"""ifself.functionisNoneorself.archisNone:returnforllilinself.llils:formlilinllil.mlils:yieldmlil@propertydefhlil(self)->Optional[highlevelil.HighLevelILInstruction]:"""Returns the high level il instruction at the current location if one exists"""mlil=self.mlilreturnmlil.hlilifmlilisnotNoneelseNone@propertydefhlils(self)->Iterator[highlevelil.HighLevelILInstruction]:"""Returns the high level il instructions at the current location if any exists"""ifself.functionisNoneorself.archisNone:returnforllilinself.llils:forhlilinllil.hlils:yieldhlil
classNotificationType(IntFlag):NotificationBarrier=1<<0DataWritten=1<<1DataInserted=1<<2DataRemoved=1<<3FunctionAdded=1<<4FunctionRemoved=1<<5FunctionUpdated=1<<6FunctionUpdateRequested=1<<7DataVariableAdded=1<<8DataVariableRemoved=1<<9DataVariableUpdated=1<<10DataMetadataUpdated=1<<11TagTypeUpdated=1<<12TagAdded=1<<13TagRemoved=1<<14TagUpdated=1<<15SymbolAdded=1<<16SymbolRemoved=1<<17SymbolUpdated=1<<18StringFound=1<<19StringRemoved=1<<20TypeDefined=1<<21TypeUndefined=1<<22TypeReferenceChanged=1<<23TypeFieldReferenceChanged=1<<24SegmentAdded=1<<25SegmentRemoved=1<<26SegmentUpdated=1<<27SectionAdded=1<<28SectionRemoved=1<<29SectionUpdated=1<<30ComponentNameUpdated=1<<31ComponentAdded=1<<32ComponentRemoved=1<<33ComponentMoved=1<<34ComponentFunctionAdded=1<<35ComponentFunctionRemoved=1<<36ComponentDataVariableAdded=1<<37ComponentDataVariableRemoved=1<<38ExternalLibraryAdded=1<<39ExternalLibraryRemoved=1<<40ExternalLibraryUpdated=1<<41ExternalLocationAdded=1<<42ExternalLocationRemoved=1<<43ExternalLocationUpdated=1<<44TypeArchiveAttached=1<<45TypeArchiveDetached=1<<46TypeArchiveConnected=1<<47TypeArchiveDisconnected=1<<48UndoEntryAdded=1<<49UndoEntryTaken=1<<50RedoEntryTaken=1<<51Rebased=1<<52DerivedStringFound=1<<53DerivedStringRemoved=1<<54BinaryDataUpdates=DataWritten|DataInserted|DataRemovedFunctionLifetime=FunctionAdded|FunctionRemovedFunctionUpdates=FunctionLifetime|FunctionUpdatedDataVariableLifetime=DataVariableAdded|DataVariableRemovedDataVariableUpdates=DataVariableLifetime|DataVariableUpdatedTagLifetime=TagAdded|TagRemovedTagUpdates=TagLifetime|TagUpdatedSymbolLifetime=SymbolAdded|SymbolRemovedSymbolUpdates=SymbolLifetime|SymbolUpdatedStringUpdates=StringFound|StringRemoved|DerivedStringFound|DerivedStringRemovedTypeLifetime=TypeDefined|TypeUndefinedTypeUpdates=TypeLifetime|TypeReferenceChanged|TypeFieldReferenceChangedSegmentLifetime=SegmentAdded|SegmentRemovedSegmentUpdates=SegmentLifetime|SegmentUpdatedSectionLifetime=SectionAdded|SectionRemovedSectionUpdates=SectionLifetime|SectionUpdatedComponentUpdates=ComponentAdded|ComponentRemoved|ComponentMoved|ComponentFunctionAdded|ComponentFunctionRemoved|ComponentDataVariableAdded|ComponentDataVariableRemovedExternalLibraryLifetime=ExternalLibraryAdded|ExternalLibraryRemovedExternalLibraryUpdates=ExternalLibraryLifetime|ExternalLibraryUpdatedExternalLocationLifetime=ExternalLocationAdded|ExternalLocationRemovedExternalLocationUpdates=ExternalLocationLifetime|ExternalLocationUpdatedTypeArchiveUpdates=TypeArchiveAttached|TypeArchiveDetached|TypeArchiveConnected|TypeArchiveDisconnectedUndoUpdates=UndoEntryAdded|UndoEntryTaken|RedoEntryTaken
[docs]classBinaryDataNotification:"""``class BinaryDataNotification`` provides an interface for receiving event notifications. Usage requires inheritingfrom this interface, overriding the relevant event handlers, and registering the `BinaryDataNotification` instancewith a `BinaryView` using the `register_notification` method.By default, a `BinaryDataNotification` instance receives notifications for all available notification types. Itis recommended for users of this interface to initialize the `BinaryDataNotification` base class with specificcallbacks of interest by passing the appropriate `NotificationType` flags into the `__init__` constructor.Handlers provided by the user should aim to limit the amount of processing within the callback. Thecallback context holds a global lock, preventing other threads from making progress during the callback phase.While most of the API can be used safely during this time, care must be taken when issuing a call that can block,as waiting for a thread requiring the global lock can result in deadlock.The `NotificationBarrier` is a special `NotificationType` that is disabled by default. To enable it, the`NotificationBarrier` flag must be passed to `__init__`. This notification is designed to facilitate efficientbatch processing of other notification types. The idea is to collect other notifications of interest into a cache,which can be very efficient as it doesn't require additional locks. After some time, the core generates a`NotificationBarrier` event, providing a safe context to move the cache for processing by a different thread.To control the time of the next `NotificationBarrier` event, return the desired number of milliseconds untilthe next event from the `NotificationBarrier` callback. Returning zero quiesces future `NotificationBarrier`events. If the `NotificationBarrier` is quiesced, the reception of a new callback of interest automaticallygenerates a new `NotificationBarrier` call after that notification is delivered. This mechanism effectivelyallows throttling and quiescing when necessary... note:: Note that the core generates a `NotificationBarrier` as part of the `BinaryDataNotification` registration \process. Registering the same `BinaryDataNotification` instance again results in a gratuitous `NotificationBarrier` \event, which can be useful in situations requiring a safe context for processing due to some other asynchronous \event (e.g., user interaction).:Example:>>> class NotifyTest(binaryninja.BinaryDataNotification):... def __init__(self):... super(NotifyTest, self).__init__(binaryninja.NotificationType.NotificationBarrier | binaryninja.NotificationType.FunctionLifetime | binaryninja.NotificationType.FunctionUpdated)... self.received_event = False... def notification_barrier(self, view: 'BinaryView') -> int:... has_events = self.received_event... self.received_event = False... log_info("notification_barrier")... if has_events:... return 250... else:... return 0... def function_added(self, view: 'BinaryView', func: '_function.Function') -> None:... self.received_event = True... log_info("function_added")... def function_removed(self, view: 'BinaryView', func: '_function.Function') -> None:... self.received_event = True... log_info("function_removed")... def function_updated(self, view: 'BinaryView', func: '_function.Function') -> None:... self.received_event = True... log_info("function_updated")...>>>>>> bv.register_notification(NotifyTest())>>>"""
[docs]def__init__(self,notifications:NotificationType=None):self.notifications=notifications
[docs]defnotification_barrier(self,view:'BinaryView')->int:return0
[docs]defdata_written(self,view:'BinaryView',offset:int,length:int)->None:pass
[docs]defdata_inserted(self,view:'BinaryView',offset:int,length:int)->None:pass
[docs]defdata_removed(self,view:'BinaryView',offset:int,length:int)->None:pass
[docs]deffunction_added(self,view:'BinaryView',func:'_function.Function')->None:""".. note:: `function_updated` will be triggered instead when a user function is added over an auto function."""pass
[docs]deffunction_removed(self,view:'BinaryView',func:'_function.Function')->None:""".. note:: `function_updated` will be triggered instead when a user function is removed over an auto function."""pass
[docs]deffunction_updated(self,view:'BinaryView',func:'_function.Function')->None:pass
[docs]deffunction_update_requested(self,view:'BinaryView',func:'_function.Function')->None:pass
[docs]defdata_var_added(self,view:'BinaryView',var:'DataVariable')->None:""".. note:: `data_var_updated` will be triggered instead when a user data variable is added over an auto data variable."""pass
[docs]defdata_var_removed(self,view:'BinaryView',var:'DataVariable')->None:""".. note:: `data_var_updated` will be triggered instead when a user data variable is removed over an auto data variable."""pass
[docs]defdata_var_updated(self,view:'BinaryView',var:'DataVariable')->None:pass
[docs]defdata_metadata_updated(self,view:'BinaryView',offset:int)->None:pass
[docs]deftag_type_updated(self,view:'BinaryView',tag_type)->None:pass
[docs]deftag_added(self,view:'BinaryView',tag:'Tag',ref_type:TagReferenceType,auto_defined:bool,arch:Optional['architecture.Architecture'],func:Optional[_function.Function],addr:int)->None:pass
[docs]deftag_updated(self,view:'BinaryView',tag:'Tag',ref_type:TagReferenceType,auto_defined:bool,arch:Optional['architecture.Architecture'],func:Optional[_function.Function],addr:int)->None:pass
[docs]deftag_removed(self,view:'BinaryView',tag:'Tag',ref_type:TagReferenceType,auto_defined:bool,arch:Optional['architecture.Architecture'],func:Optional[_function.Function],addr:int)->None:pass
[docs]defsymbol_added(self,view:'BinaryView',sym:'_types.CoreSymbol')->None:pass
[docs]defsymbol_updated(self,view:'BinaryView',sym:'_types.CoreSymbol')->None:pass
[docs]defsymbol_removed(self,view:'BinaryView',sym:'_types.CoreSymbol')->None:pass
[docs]defstring_found(self,view:'BinaryView',string_type:StringType,offset:int,length:int)->None:pass
[docs]defstring_removed(self,view:'BinaryView',string_type:StringType,offset:int,length:int)->None:pass
[docs]defderived_string_found(self,view:'BinaryView',string:'DerivedString')->None:pass
[docs]defderived_string_removed(self,view:'BinaryView',string:'DerivedString')->None:pass
[docs]deftype_defined(self,view:'BinaryView',name:'_types.QualifiedName',type:'_types.Type')->None:pass
[docs]deftype_undefined(self,view:'BinaryView',name:'_types.QualifiedName',type:'_types.Type')->None:pass
[docs]deftype_ref_changed(self,view:'BinaryView',name:'_types.QualifiedName',type:'_types.Type')->None:pass
[docs]deftype_field_ref_changed(self,view:'BinaryView',name:'_types.QualifiedName',offset:int)->None:pass
[docs]defsegment_added(self,view:'BinaryView',segment:'Segment')->None:pass
[docs]defsegment_updated(self,view:'BinaryView',segment:'Segment')->None:pass
[docs]defsegment_removed(self,view:'BinaryView',segment:'Segment')->None:pass
[docs]defsection_added(self,view:'BinaryView',section:'Section')->None:pass
[docs]defsection_updated(self,view:'BinaryView',section:'Section')->None:pass
[docs]defsection_removed(self,view:'BinaryView',section:'Section')->None:pass
[docs]defcomponent_added(self,view:'BinaryView',_component:component.Component)->None:pass
[docs]defcomponent_removed(self,view:'BinaryView',formerParent:component.Component,_component:component.Component)->None:pass
[docs]defcomponent_name_updated(self,view:'BinaryView',previous_name:str,_component:component.Component)->None:pass
[docs]defcomponent_moved(self,view:'BinaryView',formerParent:component.Component,newParent:component.Component,_component:component.Component)->None:pass
[docs]defcomponent_function_added(self,view:'BinaryView',_component:component.Component,func:'_function.Function'):pass
[docs]defcomponent_function_removed(self,view:'BinaryView',_component:component.Component,func:'_function.Function'):pass
[docs]defcomponent_data_var_added(self,view:'BinaryView',_component:component.Component,var:'DataVariable'):pass
[docs]defcomponent_data_var_removed(self,view:'BinaryView',_component:component.Component,var:'DataVariable'):pass
[docs]deftype_archive_attached(self,view:'BinaryView',id:str,path:str):pass
[docs]deftype_archive_detached(self,view:'BinaryView',id:str,path:str):pass
[docs]deftype_archive_connected(self,view:'BinaryView',archive:'typearchive.TypeArchive'):pass
[docs]deftype_archive_disconnected(self,view:'BinaryView',archive:'typearchive.TypeArchive'):pass
[docs]defundo_entry_added(self,view:'BinaryView',entry:'undo.UndoEntry'):pass
[docs]defundo_entry_taken(self,view:'BinaryView',entry:'undo.UndoEntry'):pass
[docs]defredo_entry_taken(self,view:'BinaryView',entry:'undo.UndoEntry'):pass
[docs]defrebased(self,old_view:'BinaryView',new_view:'BinaryView'):pass
[docs]classStringReference:_decodings={StringType.AsciiString:"ascii",StringType.Utf8String:"utf-8",StringType.Utf16String:"utf-16",StringType.Utf32String:"utf-32",}
[docs]def__init__(self,bv:'BinaryView',string_type:StringType,start:int,length:int):self._type=string_typeself._start=startself._length=lengthself._view=bv
def__repr__(self):returnf"<{self._type.name}:{self._start:#x}, len{self._length:#x}>"def__str__(self):returnself.valuedef__len__(self):returnself._length@propertydefvalue(self)->str:returnself._view.read(self._start,self._length).decode(self._decodings[self._type],errors='replace')@propertydefraw(self)->bytes:returnself._view.read(self._start,self._length)@propertydeftype(self)->StringType:returnself._type@propertydefstart(self)->int:returnself._start@propertydeflength(self)->int:returnself._length@propertydefview(self)->'BinaryView':returnself._view
[docs]classStringRef:"""Deduplicated reference to a string owned by the Binary Ninja core. Use `str` or `bytes` to convertthis to a standard Python string or sequence of bytes."""
[docs]def__init__(self,handle):self.handle=core.handle_of_type(handle,core.BNStringRef)
def__del__(self):ifcoreisnotNone:core.BNFreeStringRef(self.handle)def__bytes__(self):# Do not call the wrapper BNGetStringRefContents here, it will crash as the generator# does not understand that this API gives a direct reference to the stringvalue_ptr=core._BNGetStringRefContents(self.handle)value_len=core.BNGetStringRefSize(self.handle)buf=ctypes.create_string_buffer(value_len)ctypes.memmove(buf,value_ptr,value_len)returnbytes(buf.raw)def__str__(self):returncore.pyNativeStr(bytes(self))def__len__(self):returncore.BNGetStringRefSize(self.handle)def__repr__(self):returnrepr(str(self))def__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnbytes(self)==bytes(other)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__lt__(self,other)->bool:ifnotisinstance(other,self.__class__):returnNotImplementedreturnbytes(self)<bytes(self)def__gt__(self,other)->bool:ifnotisinstance(other,self.__class__):returnNotImplementedreturnbytes(self)>bytes(other)def__le__(self,other)->bool:ifnotisinstance(other,self.__class__):returnNotImplementedreturnbytes(self)<=bytes(other)def__ge__(self,other)->bool:ifnotisinstance(other,self.__class__):returnNotImplementedreturnbytes(self)>=bytes(other)def__hash__(self):returnhash(bytes(self))
[docs]@dataclass(frozen=True)classDerivedStringLocation:"""Location associated with a derived string. Locations are optional."""location_type:'DerivedStringLocationType'address:intlength:int
[docs]@dataclass(frozen=True)classDerivedString:"""Contains a string derived from code or data. The string does not need to be directly present inthe binary in its raw form. Derived strings can have optional locations to data or code. Whencreating new derived strings, a custom type should be registered with:py:func:`~binaryninja.stringrecognizer.CustomStringType.register` on :py:class:`~binaryninja.stringrecognizer.CustomStringType`."""value:'StringRef'location:Optional[DerivedStringLocation]custom_type:Optional[stringrecognizer.CustomStringType]
[docs]def__init__(self,value:Union['StringRef',str,bytes,bytearray,'databuffer.DataBuffer'],location:Optional[DerivedStringLocation],custom_type:Optional[stringrecognizer.CustomStringType]):ifisinstance(value,str):value=value.encode("utf-8")value=StringRef(core.BNCreateStringRefOfLength(value,len(value)))elifisinstance(value,bytes):value=StringRef(core.BNCreateStringRefOfLength(value,len(value)))elifisinstance(value,bytearray):value=bytes(value)value=StringRef(core.BNCreateStringRefOfLength(value,len(value)))elifisinstance(value,databuffer.DataBuffer):value=bytes(value)value=StringRef(core.BNCreateStringRefOfLength(value,len(value)))elifnotisinstance(value,StringRef):value=str(value).encode("utf-8")value=StringRef(core.BNCreateStringRefOfLength(value,len(value)))object.__setattr__(self,"value",value)object.__setattr__(self,"location",location)object.__setattr__(self,"custom_type",custom_type)
def_to_core_struct(self,owned:bool)->'core.BNDerivedString':result=core.BNDerivedString()ifowned:result.value=core.BNDuplicateStringRef(self.value.handle)else:result.value=self.value.handleresult.locationValid=self.locationisnotNoneifresult.locationValid:result.location.locationType=self.location.location_typeresult.location.addr=self.location.addressresult.location.len=self.location.lengthifself.custom_typeisNone:result.customType=Noneelse:result.customType=self.custom_type.handlereturnresult@staticmethoddef_from_core_struct(obj:'core.BNDerivedString',owned:bool)->'DerivedString':ifowned:value=StringRef(obj.value)else:value=StringRef(core.BNDuplicateStringRef(obj.value))ifobj.locationValid:location=DerivedStringLocation(DerivedStringLocationType(obj.location.locationType),obj.location.addr,obj.location.len)else:location=Noneifobj.customType:custom_type=stringrecognizer.CustomStringType(obj.customType)else:custom_type=NonereturnDerivedString(value,location,custom_type)
[docs]classAnalysisCompletionEvent:"""The ``AnalysisCompletionEvent`` object provides an asynchronous mechanism for receivingcallbacks when analysis is complete. The callback runs once. A completion event must be addedfor each new analysis in order to be notified of each analysis completion. TheAnalysisCompletionEvent class takes responsibility for keeping track of the object's lifetime.:Example:>>> def on_complete(self):...     print("Analysis Complete", self._view)...>>> evt = AnalysisCompletionEvent(bv, on_complete)>>>"""_pending_analysis_completion_events={}
[docs]def__init__(self,view:'BinaryView',callback:Union[Callable[['AnalysisCompletionEvent'],None],Callable[[],None]]):self._view=viewself.callback=callbackself._cb=ctypes.CFUNCTYPE(None,ctypes.c_void_p)(self._notify)self.handle=core.BNAddAnalysisCompletionEvent(self._view.handle,None,self._cb)self.__class__._pending_analysis_completion_events[id(self)]=self
def__del__(self):ifid(self)inself.__class__._pending_analysis_completion_events:delself.__class__._pending_analysis_completion_events[id(self)]ifcoreisnotNone:core.BNFreeAnalysisCompletionEvent(self.handle)def_notify(self,ctxt):ifid(self)inself.__class__._pending_analysis_completion_events:delself.__class__._pending_analysis_completion_events[id(self)]try:arg_offset=inspect.ismethod(self.callback)callback_spec=inspect.getfullargspec(self.callback)iflen(callback_spec.args)>arg_offset:self.callback(self)# type: ignoreelse:self.callback()# type: ignoreexcept:log_error_for_exception("Unhandled Python exception in AnalysisCompletionEvent._notify")def_empty_callback(self):pass
[docs]defcancel(self)->None:"""The ``cancel`` method will cancel analysis for an :py:class:`AnalysisCompletionEvent`... warning:: This method should only be used when the system is being shut down and no further analysis should be done afterward."""self.callback=self._empty_callbackcore.BNCancelAnalysisCompletionEvent(self.handle)ifid(self)inself.__class__._pending_analysis_completion_events:delself.__class__._pending_analysis_completion_events[id(self)]
@propertydefview(self)->'BinaryView':returnself._view
[docs]classBinaryViewEvent:"""The ``BinaryViewEvent`` object provides a mechanism for receiving callbackswhen a BinaryViewis Finalized or the initial analysis is finished. The BinaryView finalized callbacks run before theinitial analysis starts. The callbacks run one-after-another in the same order as they get registered.It is a good place to modify the BinaryView to add extra information to it.For newly opened binaries, the initial analysis completion callbacks run after the initial analysis,as well as linear sweepand signature matcher (if they are configured to run), completed. For loadingold databases, the callbacks run after the database is loaded, as well as any automatic analysisupdate finishes.The callback function receives a BinaryView as its parameter. It is possible to callBinaryView.add_analysis_completion_event() on it to set up other callbacks for analysis completion.:Example:>>> def callback(bv):... print('start: 0x%x' % bv.start)...>>> BinaryViewType.add_binaryview_finalized_event(callback)"""BinaryViewEventCallback=Callable[['BinaryView'],None]# This has no functional purposes;# we just need it to stop Python from prematurely freeing the object_binaryview_events={}
[docs]@classmethoddefregister(cls,event_type:BinaryViewEventType,callback:BinaryViewEventCallback)->None:callback_obj=ctypes.CFUNCTYPE(None,ctypes.c_void_p,ctypes.POINTER(core.BNBinaryView))(lambdactxt,view:cls._notify(view,callback))core.BNRegisterBinaryViewEvent(event_type,callback_obj,None)cls._binaryview_events[len(cls._binaryview_events)]=callback_obj
@staticmethoddef_notify(view:core.BNBinaryViewHandle,callback:BinaryViewEventCallback)->None:try:file_metadata=filemetadata.FileMetadata(handle=core.BNGetFileForView(view))view_obj=BinaryView(file_metadata=file_metadata,handle=core.BNNewViewReference(view))callback(view_obj)except:log_error_for_exception("Unhandled Python exception in BinaryViewEvent._notify")
[docs]@dataclass(frozen=True)classActiveAnalysisInfo:func:'_function.Function'analysis_time:intupdate_count:intsubmit_count:intdef__repr__(self):returnf"<ActiveAnalysisInfo{self.func}, analysis_time{self.analysis_time}, update_count{self.update_count}, submit_count{self.submit_count}>"
[docs]@dataclass(frozen=True)classAnalysisInfo:state:AnalysisStateanalysis_time:intactive_info:List[ActiveAnalysisInfo]def__repr__(self):returnf"<AnalysisInfo{self.state}, analysis_time{self.analysis_time}, active_info{self.active_info}>"
[docs]@dataclass(frozen=True)classAnalysisProgress:state:AnalysisStatecount:inttotal:intdef__str__(self):ifself.state==AnalysisState.InitialState:return"Initial"ifself.state==AnalysisState.HoldState:return"Hold"ifself.state==AnalysisState.IdleState:return"Idle"ifself.state==AnalysisState.DiscoveryState:return"Discovery"ifself.state==AnalysisState.DisassembleState:return"Disassembling (%d/%d)"%(self.count,self.total)ifself.state==AnalysisState.AnalyzeState:return"Analyzing (%d/%d)"%(self.count,self.total)return"Extended Analysis"def__repr__(self):returnf"<progress:{self}>"
[docs]classBinaryDataNotificationCallbacks:
[docs]def__init__(self,view:'BinaryView',notify:'BinaryDataNotification'):self._view=viewself._notify=notifyself._cb=core.BNBinaryDataNotification()self._cb.context=0if(nothasattr(notify,'notifications'))or(hasattr(notify,'notifications')andnotify.notificationsisNone):self._cb.notificationBarrier=self._cb.notificationBarrierself._cb.dataWritten=self._cb.dataWritten.__class__(self._data_written)self._cb.dataInserted=self._cb.dataInserted.__class__(self._data_inserted)self._cb.dataRemoved=self._cb.dataRemoved.__class__(self._data_removed)self._cb.functionAdded=self._cb.functionAdded.__class__(self._function_added)self._cb.functionRemoved=self._cb.functionRemoved.__class__(self._function_removed)self._cb.functionUpdated=self._cb.functionUpdated.__class__(self._function_updated)self._cb.functionUpdateRequested=self._cb.functionUpdateRequested.__class__(self._function_update_requested)self._cb.dataVariableAdded=self._cb.dataVariableAdded.__class__(self._data_var_added)self._cb.dataVariableRemoved=self._cb.dataVariableRemoved.__class__(self._data_var_removed)self._cb.dataVariableUpdated=self._cb.dataVariableUpdated.__class__(self._data_var_updated)self._cb.dataMetadataUpdated=self._cb.dataMetadataUpdated.__class__(self._data_metadata_updated)self._cb.tagTypeUpdated=self._cb.tagTypeUpdated.__class__(self._tag_type_updated)self._cb.tagAdded=self._cb.tagAdded.__class__(self._tag_added)self._cb.tagRemoved=self._cb.tagRemoved.__class__(self._tag_removed)self._cb.tagUpdated=self._cb.tagUpdated.__class__(self._tag_updated)self._cb.symbolAdded=self._cb.symbolAdded.__class__(self._symbol_added)self._cb.symbolRemoved=self._cb.symbolRemoved.__class__(self._symbol_removed)self._cb.symbolUpdated=self._cb.symbolUpdated.__class__(self._symbol_updated)self._cb.stringFound=self._cb.stringFound.__class__(self._string_found)self._cb.stringRemoved=self._cb.stringRemoved.__class__(self._string_removed)self._cb.derivedStringFound=self._cb.derivedStringFound.__class__(self._derived_string_found)self._cb.derivedStringRemoved=self._cb.derivedStringRemoved.__class__(self._derived_string_removed)self._cb.typeDefined=self._cb.typeDefined.__class__(self._type_defined)self._cb.typeUndefined=self._cb.typeUndefined.__class__(self._type_undefined)self._cb.typeReferenceChanged=self._cb.typeReferenceChanged.__class__(self._type_ref_changed)self._cb.typeFieldReferenceChanged=self._cb.typeFieldReferenceChanged.__class__(self._type_field_ref_changed)self._cb.segmentAdded=self._cb.segmentAdded.__class__(self._segment_added)self._cb.segmentRemoved=self._cb.segmentRemoved.__class__(self._segment_removed)self._cb.segmentUpdated=self._cb.segmentUpdated.__class__(self._segment_updated)self._cb.sectionAdded=self._cb.sectionAdded.__class__(self._section_added)self._cb.sectionRemoved=self._cb.sectionRemoved.__class__(self._section_removed)self._cb.sectionUpdated=self._cb.sectionUpdated.__class__(self._section_updated)self._cb.componentNameUpdated=self._cb.componentNameUpdated.__class__(self._component_name_updated)self._cb.componentAdded=self._cb.componentAdded.__class__(self._component_added)self._cb.componentRemoved=self._cb.componentRemoved.__class__(self._component_removed)self._cb.componentMoved=self._cb.componentMoved.__class__(self._component_moved)self._cb.componentFunctionAdded=self._cb.componentFunctionAdded.__class__(self._component_function_added)self._cb.componentFunctionRemoved=self._cb.componentFunctionRemoved.__class__(self._component_function_removed)self._cb.componentDataVariableAdded=self._cb.componentDataVariableAdded.__class__(self._component_data_variable_added)self._cb.componentDataVariableRemoved=self._cb.componentDataVariableRemoved.__class__(self._component_data_variable_removed)self._cb.typeArchiveAttached=self._cb.typeArchiveAttached.__class__(self._type_archive_attached)self._cb.typeArchiveDetached=self._cb.typeArchiveDetached.__class__(self._type_archive_detached)self._cb.typeArchiveConnected=self._cb.typeArchiveConnected.__class__(self._type_archive_connected)self._cb.typeArchiveDisconnected=self._cb.typeArchiveDisconnected.__class__(self._type_archive_disconnected)self._cb.undoEntryAdded=self._cb.undoEntryAdded.__class__(self._undo_entry_added)self._cb.undoEntryTaken=self._cb.undoEntryTaken.__class__(self._undo_entry_taken)self._cb.redoEntryTaken=self._cb.redoEntryTaken.__class__(self._redo_entry_taken)self._cb.rebased=self._cb.rebased.__class__(self._rebased)else:ifnotify.notifications&NotificationType.NotificationBarrier:self._cb.notificationBarrier=self._cb.notificationBarrier.__class__(self._notification_barrier)ifnotify.notifications&NotificationType.DataWritten:self._cb.dataWritten=self._cb.dataWritten.__class__(self._data_written)ifnotify.notifications&NotificationType.DataInserted:self._cb.dataInserted=self._cb.dataInserted.__class__(self._data_inserted)ifnotify.notifications&NotificationType.DataRemoved:self._cb.dataRemoved=self._cb.dataRemoved.__class__(self._data_removed)ifnotify.notifications&NotificationType.FunctionAdded:self._cb.functionAdded=self._cb.functionAdded.__class__(self._function_added)ifnotify.notifications&NotificationType.FunctionRemoved:self._cb.functionRemoved=self._cb.functionRemoved.__class__(self._function_removed)ifnotify.notifications&NotificationType.FunctionUpdated:self._cb.functionUpdated=self._cb.functionUpdated.__class__(self._function_updated)ifnotify.notifications&NotificationType.FunctionUpdateRequested:self._cb.functionUpdateRequested=self._cb.functionUpdateRequested.__class__(self._function_update_requested)ifnotify.notifications&NotificationType.DataVariableAdded:self._cb.dataVariableAdded=self._cb.dataVariableAdded.__class__(self._data_var_added)ifnotify.notifications&NotificationType.DataVariableRemoved:self._cb.dataVariableRemoved=self._cb.dataVariableRemoved.__class__(self._data_var_removed)ifnotify.notifications&NotificationType.DataVariableUpdated:self._cb.dataVariableUpdated=self._cb.dataVariableUpdated.__class__(self._data_var_updated)ifnotify.notifications&NotificationType.DataMetadataUpdated:self._cb.dataMetadataUpdated=self._cb.dataMetadataUpdated.__class__(self._data_metadata_updated)ifnotify.notifications&NotificationType.TagTypeUpdated:self._cb.tagTypeUpdated=self._cb.tagTypeUpdated.__class__(self._tag_type_updated)ifnotify.notifications&NotificationType.TagAdded:self._cb.tagAdded=self._cb.tagAdded.__class__(self._tag_added)ifnotify.notifications&NotificationType.TagRemoved:self._cb.tagRemoved=self._cb.tagRemoved.__class__(self._tag_removed)ifnotify.notifications&NotificationType.TagUpdated:self._cb.tagUpdated=self._cb.tagUpdated.__class__(self._tag_updated)ifnotify.notifications&NotificationType.SymbolAdded:self._cb.symbolAdded=self._cb.symbolAdded.__class__(self._symbol_added)ifnotify.notifications&NotificationType.SymbolRemoved:self._cb.symbolRemoved=self._cb.symbolRemoved.__class__(self._symbol_removed)ifnotify.notifications&NotificationType.SymbolUpdated:self._cb.symbolUpdated=self._cb.symbolUpdated.__class__(self._symbol_updated)ifnotify.notifications&NotificationType.StringFound:self._cb.stringFound=self._cb.stringFound.__class__(self._string_found)ifnotify.notifications&NotificationType.StringRemoved:self._cb.stringRemoved=self._cb.stringRemoved.__class__(self._string_removed)ifnotify.notifications&NotificationType.DerivedStringFound:self._cb.derivedStringFound=self._cb.derivedStringFound.__class__(self._derived_string_found)ifnotify.notifications&NotificationType.DerivedStringRemoved:self._cb.derivedStringRemoved=self._cb.derivedStringRemoved.__class__(self._derived_string_removed)ifnotify.notifications&NotificationType.TypeDefined:self._cb.typeDefined=self._cb.typeDefined.__class__(self._type_defined)ifnotify.notifications&NotificationType.TypeUndefined:self._cb.typeUndefined=self._cb.typeUndefined.__class__(self._type_undefined)ifnotify.notifications&NotificationType.TypeReferenceChanged:self._cb.typeReferenceChanged=self._cb.typeReferenceChanged.__class__(self._type_ref_changed)ifnotify.notifications&NotificationType.TypeFieldReferenceChanged:self._cb.typeFieldReferenceChanged=self._cb.typeFieldReferenceChanged.__class__(self._type_field_ref_changed)ifnotify.notifications&NotificationType.SegmentAdded:self._cb.segmentAdded=self._cb.segmentAdded.__class__(self._segment_added)ifnotify.notifications&NotificationType.SegmentRemoved:self._cb.segmentRemoved=self._cb.segmentRemoved.__class__(self._segment_removed)ifnotify.notifications&NotificationType.SegmentUpdated:self._cb.segmentUpdated=self._cb.segmentUpdated.__class__(self._segment_updated)ifnotify.notifications&NotificationType.SectionAdded:self._cb.sectionAdded=self._cb.sectionAdded.__class__(self._section_added)ifnotify.notifications&NotificationType.SectionRemoved:self._cb.sectionRemoved=self._cb.sectionRemoved.__class__(self._section_removed)ifnotify.notifications&NotificationType.SectionUpdated:self._cb.sectionUpdated=self._cb.sectionUpdated.__class__(self._section_updated)ifnotify.notifications&NotificationType.ComponentNameUpdated:self._cb.componentNameUpdated=self._cb.componentNameUpdated.__class__(self._component_name_updated)ifnotify.notifications&NotificationType.ComponentAdded:self._cb.componentAdded=self._cb.componentAdded.__class__(self._component_added)ifnotify.notifications&NotificationType.ComponentRemoved:self._cb.componentRemoved=self._cb.componentRemoved.__class__(self._component_removed)ifnotify.notifications&NotificationType.ComponentMoved:self._cb.componentMoved=self._cb.componentMoved.__class__(self._component_moved)ifnotify.notifications&NotificationType.ComponentFunctionAdded:self._cb.componentFunctionAdded=self._cb.componentFunctionAdded.__class__(self._component_function_added)ifnotify.notifications&NotificationType.ComponentFunctionRemoved:self._cb.componentFunctionRemoved=self._cb.componentFunctionRemoved.__class__(self._component_function_removed)ifnotify.notifications&NotificationType.ComponentDataVariableAdded:self._cb.componentDataVariableAdded=self._cb.componentDataVariableAdded.__class__(self._component_data_variable_added)ifnotify.notifications&NotificationType.ComponentDataVariableRemoved:self._cb.componentDataVariableRemoved=self._cb.componentDataVariableRemoved.__class__(self._component_data_variable_removed)ifnotify.notifications&NotificationType.TypeArchiveAttached:self._cb.typeArchiveAttached=self._cb.typeArchiveAttached.__class__(self._type_archive_attached)ifnotify.notifications&NotificationType.TypeArchiveDetached:self._cb.typeArchiveDetached=self._cb.typeArchiveDetached.__class__(self._type_archive_detached)ifnotify.notifications&NotificationType.TypeArchiveConnected:self._cb.typeArchiveConnected=self._cb.typeArchiveConnected.__class__(self._type_archive_connected)ifnotify.notifications&NotificationType.TypeArchiveDisconnected:self._cb.typeArchiveDisconnected=self._cb.typeArchiveDisconnected.__class__(self._type_archive_disconnected)ifnotify.notifications&NotificationType.UndoEntryAdded:self._cb.undoEntryAdded=self._cb.undoEntryAdded.__class__(self._undo_entry_added)ifnotify.notifications&NotificationType.UndoEntryTaken:self._cb.undoEntryTaken=self._cb.undoEntryTaken.__class__(self._undo_entry_taken)ifnotify.notifications&NotificationType.RedoEntryTaken:self._cb.redoEntryTaken=self._cb.redoEntryTaken.__class__(self._redo_entry_taken)ifnotify.notifications&NotificationType.Rebased:self._cb.rebased=self._cb.rebased.__class__(self._rebased)
def_register(self)->None:core.BNRegisterDataNotification(self._view.handle,self._cb)def_unregister(self)->None:core.BNUnregisterDataNotification(self._view.handle,self._cb)def_notification_barrier(self,ctxt,view:core.BNBinaryView)->int:try:returnself._notify.notification_barrier(self._view)exceptOSError:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._notification_barrier")def_data_written(self,ctxt,view:core.BNBinaryView,offset:int,length:int)->None:try:self._notify.data_written(self._view,offset,length)exceptOSError:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._data_written")def_data_inserted(self,ctxt,view:core.BNBinaryView,offset:int,length:int)->None:try:self._notify.data_inserted(self._view,offset,length)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._data_inserted")def_data_removed(self,ctxt,view:core.BNBinaryView,offset:int,length:int)->None:try:self._notify.data_removed(self._view,offset,length)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._data_removed")def_function_added(self,ctxt,view:core.BNBinaryView,func:core.BNFunctionHandle)->None:try:self._notify.function_added(self._view,_function.Function(self._view,core.BNNewFunctionReference(func)))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._function_added")def_function_removed(self,ctxt,view:core.BNBinaryView,func:core.BNFunctionHandle)->None:try:self._notify.function_removed(self._view,_function.Function(self._view,core.BNNewFunctionReference(func)))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._function_removed")def_function_updated(self,ctxt,view:core.BNBinaryView,func:core.BNFunctionHandle)->None:try:self._notify.function_updated(self._view,_function.Function(self._view,core.BNNewFunctionReference(func)))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._function_updated")def_function_update_requested(self,ctxt,view:core.BNBinaryView,func:core.BNFunctionHandle)->None:try:self._notify.function_update_requested(self._view,_function.Function(self._view,core.BNNewFunctionReference(func)))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._function_update_requested")def_data_var_added(self,ctxt,view:core.BNBinaryView,var:core.BNDataVariableHandle)->None:try:self._notify.data_var_added(self._view,DataVariable.from_core_struct(var[0],self._view))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._data_var_added")def_data_var_removed(self,ctxt,view:core.BNBinaryView,var:core.BNDataVariableHandle)->None:try:self._notify.data_var_removed(self._view,DataVariable.from_core_struct(var[0],self._view))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._data_var_removed")def_data_var_updated(self,ctxt,view:core.BNBinaryView,var:core.BNDataVariableHandle)->None:try:self._notify.data_var_updated(self._view,DataVariable.from_core_struct(var[0],self._view))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._data_var_updated")def_data_metadata_updated(self,ctxt,view:core.BNBinaryView,offset:int)->None:try:self._notify.data_metadata_updated(self._view,offset)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._data_metadata_updated")def_tag_type_updated(self,ctxt,view:core.BNBinaryView,tag_type:core.BNTagTypeHandle)->None:try:core_tag_type=core.BNNewTagTypeReference(tag_type)assertcore_tag_typeisnotNone,"core.BNNewTagTypeReference returned None"self._notify.tag_type_updated(self._view,TagType(core_tag_type))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._tag_type_updated")def_tag_added(self,ctxt,view:core.BNBinaryView,tag_ref:core.BNTagReferenceHandle)->None:try:ref_type=tag_ref[0].refTypeauto_defined=tag_ref[0].autoDefinedcore_tag=core.BNNewTagReference(tag_ref[0].tag)assertcore_tagisnotNone,"core.BNNewTagReference returned None"tag=Tag(core_tag)# Null for data tags (not in any arch or function)ifctypes.cast(tag_ref[0].arch,ctypes.c_void_p).valueisNone:arch=Noneelse:arch=architecture.CoreArchitecture._from_cache(tag_ref[0].arch)ifctypes.cast(tag_ref[0].func,ctypes.c_void_p).valueisNone:func=Noneelse:func=_function.Function(self._view,core.BNNewFunctionReference(tag_ref[0].func))addr=tag_ref[0].addrself._notify.tag_added(self._view,tag,ref_type,auto_defined,arch,func,addr)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._tag_added")def_tag_updated(self,ctxt,view:core.BNBinaryView,tag_ref:core.BNTagReferenceHandle)->None:try:ref_type=tag_ref[0].refTypeauto_defined=tag_ref[0].autoDefinedcore_tag=core.BNNewTagReference(tag_ref[0].tag)assertcore_tagisnotNonetag=Tag(core_tag)# Null for data tags (not in any arch or function)ifctypes.cast(tag_ref[0].arch,ctypes.c_void_p).valueisNone:arch=Noneelse:arch=architecture.CoreArchitecture._from_cache(tag_ref[0].arch)ifctypes.cast(tag_ref[0].func,ctypes.c_void_p).valueisNone:func=Noneelse:func=_function.Function(self._view,core.BNNewFunctionReference(tag_ref[0].func))addr=tag_ref[0].addrself._notify.tag_updated(self._view,tag,ref_type,auto_defined,arch,func,addr)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._tag_updated")def_tag_removed(self,ctxt,view:core.BNBinaryView,tag_ref:core.BNTagReferenceHandle)->None:try:ref_type=tag_ref[0].refTypeauto_defined=tag_ref[0].autoDefinedcore_tag=core.BNNewTagReference(tag_ref[0].tag)assertcore_tagisnotNone,"core.BNNewTagReference returned None"tag=Tag(core_tag)# Null for data tags (not in any arch or function)ifctypes.cast(tag_ref[0].arch,ctypes.c_void_p).valueisNone:arch=Noneelse:arch=architecture.CoreArchitecture._from_cache(tag_ref[0].arch)ifctypes.cast(tag_ref[0].func,ctypes.c_void_p).valueisNone:func=Noneelse:func=_function.Function(self._view,core.BNNewFunctionReference(tag_ref[0].func))addr=tag_ref[0].addrself._notify.tag_removed(self._view,tag,ref_type,auto_defined,arch,func,addr)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._tag_removed")def_symbol_added(self,ctxt,view:core.BNBinaryView,sym:core.BNSymbol)->None:try:_handle=core.BNNewSymbolReference(sym)assert_handleisnotNone,"core.BNNewSymbolReference returned None"self._notify.symbol_added(self._view,_types.CoreSymbol(_handle))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._symbol_added")def_symbol_updated(self,ctxt,view:core.BNBinaryView,sym:core.BNSymbol)->None:try:_handle=core.BNNewSymbolReference(sym)assert_handleisnotNone,"core.BNNewSymbolReference returned None"self._notify.symbol_updated(self._view,_types.CoreSymbol(_handle))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._symbol_updated")def_symbol_removed(self,ctxt,view:core.BNBinaryView,sym:core.BNSymbol)->None:try:_handle=core.BNNewSymbolReference(sym)assert_handleisnotNone,"core.BNNewSymbolReference returned None"self._notify.symbol_removed(self._view,_types.CoreSymbol(_handle))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._symbol_removed")def_string_found(self,ctxt,view:core.BNBinaryView,string_type:int,offset:int,length:int)->None:try:self._notify.string_found(self._view,StringType(string_type),offset,length)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._string_found")def_string_removed(self,ctxt,view:core.BNBinaryView,string_type:int,offset:int,length:int)->None:try:self._notify.string_removed(self._view,StringType(string_type),offset,length)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._string_removed")def_derived_string_found(self,ctxt,view:core.BNBinaryView,string)->None:try:self._notify.derived_string_found(self._view,DerivedString._from_core_struct(string[0],False))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._derived_string_found")def_derived_string_removed(self,ctxt,view:core.BNBinaryView,string)->None:try:self._notify.derived_string_removed(self._view,DerivedString._from_core_struct(string[0],False))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._derived_string_removed")def_type_defined(self,ctxt,view:core.BNBinaryView,name:str,type_obj:'_types.Type')->None:try:qualified_name=_types.QualifiedName._from_core_struct(name[0])self._notify.type_defined(self._view,qualified_name,_types.Type.create(core.BNNewTypeReference(type_obj),platform=self._view.platform))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._type_defined")def_type_undefined(self,ctxt,view:core.BNBinaryView,name:str,type_obj:'_types.Type')->None:try:qualified_name=_types.QualifiedName._from_core_struct(name[0])self._notify.type_undefined(self._view,qualified_name,_types.Type.create(core.BNNewTypeReference(type_obj),platform=self._view.platform))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._type_undefined")def_type_ref_changed(self,ctxt,view:core.BNBinaryView,name:str,type_obj:'_types.Type')->None:try:qualified_name=_types.QualifiedName._from_core_struct(name[0])self._notify.type_ref_changed(self._view,qualified_name,_types.Type.create(core.BNNewTypeReference(type_obj),platform=self._view.platform))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._type_ref_changed")def_type_field_ref_changed(self,ctxt,view:core.BNBinaryView,name:str,offset:int)->None:try:qualified_name=_types.QualifiedName._from_core_struct(name[0])self._notify.type_field_ref_changed(self._view,qualified_name,offset)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._type_field_ref_changed")def_segment_added(self,ctxt,view:core.BNBinaryView,segment_obj:core.BNSegment)->None:try:segment_handle=core.BNNewSegmentReference(segment_obj)assertsegment_handleisnotNone,"core.BNNewSegmentReference returned None"result=Segment(segment_handle)self._notify.segment_added(self._view,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._segment_added")def_segment_updated(self,ctxt,view:core.BNBinaryView,segment_obj:core.BNSegment)->None:try:segment_handle=core.BNNewSegmentReference(segment_obj)assertsegment_handleisnotNone,"core.BNNewSegmentReference returned None"result=Segment(segment_handle)self._notify.segment_updated(self._view,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._segment_updated")def_segment_removed(self,ctxt,view:core.BNBinaryView,segment_obj:core.BNSegment)->None:try:segment_handle=core.BNNewSegmentReference(segment_obj)assertsegment_handleisnotNone,"core.BNNewSegmentReference returned None"result=Segment(segment_handle)self._notify.segment_removed(self._view,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._segment_removed")def_section_added(self,ctxt,view:core.BNBinaryView,section_obj:core.BNSection)->None:try:section_handle=core.BNNewSectionReference(section_obj)assertsection_handleisnotNone,"core.BNNewSectionReference returned None"result=Section(section_handle)self._notify.section_added(self._view,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._section_added")def_section_updated(self,ctxt,view:core.BNBinaryView,section_obj:core.BNSection)->None:try:section_handle=core.BNNewSectionReference(section_obj)assertsection_handleisnotNone,"core.BNNewSectionReference returned None"result=Section(section_handle)self._notify.section_updated(self._view,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._section_updated")def_section_removed(self,ctxt,view:core.BNBinaryView,section_obj:core.BNSection)->None:try:section_handle=core.BNNewSectionReference(section_obj)assertsection_handleisnotNone,"core.BNNewSectionReference returned None"result=Section(section_handle)self._notify.section_removed(self._view,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._section_removed")def_component_added(self,ctxt,view:core.BNBinaryView,_component:core.BNComponent):try:component_handle=core.BNNewComponentReference(_component)assertcomponent_handleisnotNone,"core.BNNewComponentReference returned None"result=component.Component(component_handle)self._notify.component_added(self._view,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._component_added")def_component_removed(self,ctxt,view:core.BNBinaryView,formerParent:core.BNComponent,_component:core.BNComponent):try:formerParent_handle=core.BNNewComponentReference(formerParent)assertformerParent_handleisnotNone,"core.BNNewComponentReference returned None"formerParentResult=component.Component(formerParent_handle)component_handle=core.BNNewComponentReference(_component)assertcomponent_handleisnotNone,"core.BNNewComponentReference returned None"result=component.Component(component_handle)self._notify.component_removed(self._view,formerParentResult,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._component_removed")def_component_name_updated(self,ctxt,view:core.BNBinaryView,previous_name:str,_component:core.BNComponent):try:component_handle=core.BNNewComponentReference(_component)assertcomponent_handleisnotNone,"core.BNNewComponentReference returned None"result=component.Component(component_handle)self._notify.component_name_updated(self._view,previous_name,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._component_name_updated")def_component_moved(self,ctxt,view:core.BNBinaryView,formerParent:core.BNComponent,newParent:core.BNComponent,_component:core.BNComponent):try:formerParent_handle=core.BNNewComponentReference(formerParent)assertformerParent_handleisnotNone,"core.BNNewComponentReference returned None"formerParentResult=component.Component(formerParent_handle)newParent_handle=core.BNNewComponentReference(newParent)assertnewParent_handleisnotNone,"core.BNNewComponentReference returned None"newParentResult=component.Component(newParent_handle)component_handle=core.BNNewComponentReference(_component)assertcomponent_handleisnotNone,"core.BNNewComponentReference returned None"result=component.Component(component_handle)self._notify.component_moved(self._view,formerParentResult,newParentResult,result)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._component_moved")def_component_function_added(self,ctxt,view:core.BNBinaryView,_component:core.BNComponent,func:'_function.Function'):try:component_handle=core.BNNewComponentReference(_component)assertcomponent_handleisnotNone,"core.BNNewComponentReference returned None"result=component.Component(component_handle)function_handle=core.BNNewFunctionReference(func)assertfunction_handleisnotNone,"core.BNNewFunctionReference returned None"function=_function.Function(self._view,function_handle)self._notify.component_function_added(self._view,result,function)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._component_function_added")def_component_function_removed(self,ctxt,view:core.BNBinaryView,_component:core.BNComponent,func:'_function.Function'):try:component_handle=core.BNNewComponentReference(_component)assertcomponent_handleisnotNone,"core.BNNewComponentReference returned None"result=component.Component(component_handle)function_handle=core.BNNewFunctionReference(func)assertfunction_handleisnotNone,"core.BNNewFunctionReference returned None"function=_function.Function(self._view,function_handle)self._notify.component_function_removed(self._view,result,function)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._component_function_removed")def_component_data_variable_added(self,ctxt,view:core.BNBinaryView,_component:core.BNComponent,var:core.BNDataVariable):try:component_handle=core.BNNewComponentReference(_component)assertcomponent_handleisnotNone,"core.BNNewComponentReference returned None"result=component.Component(component_handle)self._notify.component_data_var_added(self._view,result,DataVariable.from_core_struct(var,self._view))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._component_data_variable_added")def_component_data_variable_removed(self,ctxt,view:core.BNBinaryView,_component:core.BNComponent,var:core.BNDataVariable):try:component_handle=core.BNNewComponentReference(_component)assertcomponent_handleisnotNone,"core.BNNewComponentReference returned None"result=component.Component(component_handle)self._notify.component_data_var_removed(self._view,result,DataVariable.from_core_struct(var,self._view))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._component_data_variable_removed")def_type_archive_attached(self,ctxt,view:core.BNBinaryView,id:ctypes.c_char_p,path:ctypes.c_char_p):try:self._notify.type_archive_attached(self._view,core.pyNativeStr(id),core.pyNativeStr(path))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._type_archive_attached")def_type_archive_detached(self,ctxt,view:core.BNBinaryView,id:ctypes.c_char_p,path:ctypes.c_char_p):try:self._notify.type_archive_detached(self._view,core.pyNativeStr(id),core.pyNativeStr(path))except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._type_archive_detached")def_type_archive_connected(self,ctxt,view:core.BNBinaryView,archive:core.BNTypeArchive):try:py_archive=typearchive.TypeArchive(handle=core.BNNewTypeArchiveReference(archive))self._notify.type_archive_connected(self._view,py_archive)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._type_archive_connected")def_type_archive_disconnected(self,ctxt,view:core.BNBinaryView,archive:core.BNTypeArchive):try:py_archive=typearchive.TypeArchive(handle=core.BNNewTypeArchiveReference(archive))self._notify.type_archive_disconnected(self._view,py_archive)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._type_archive_disconnected")def_undo_entry_added(self,ctxt,view:core.BNBinaryView,entry:core.BNUndoEntry):try:py_entry=undo.UndoEntry(handle=core.BNNewUndoEntryReference(entry))self._notify.undo_entry_added(self._view,py_entry)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._undo_entry_added")def_undo_entry_taken(self,ctxt,view:core.BNBinaryView,entry:core.BNUndoEntry):try:py_entry=undo.UndoEntry(handle=core.BNNewUndoEntryReference(entry))self._notify.undo_entry_taken(self._view,py_entry)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._undo_entry_taken")def_redo_entry_taken(self,ctxt,view:core.BNBinaryView,entry:core.BNUndoEntry):try:py_entry=undo.UndoEntry(handle=core.BNNewUndoEntryReference(entry))self._notify.redo_entry_taken(self._view,py_entry)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._redo_entry_taken")def_rebased(self,ctxt,old_view:core.BNBinaryView,new_view:core.BNBinaryView):try:file_metadata=filemetadata.FileMetadata(handle=core.BNGetFileForView(new_view))new_view_obj=BinaryView(file_metadata=file_metadata,handle=core.BNNewViewReference(new_view))self._notify.rebased(self._view,new_view_obj)except:log_error_for_exception("Unhandled Python exception in BinaryDataNotificationCallbacks._rebased")@propertydefview(self)->'BinaryView':returnself._view@propertydefnotify(self)->'BinaryDataNotification':returnself._notify
class_BinaryViewTypeMetaclass(type):def__iter__(self):binaryninja._init_plugins()count=ctypes.c_ulonglong()types=core.BNGetBinaryViewTypes(count)iftypesisNone:returntry:foriinrange(0,count.value):yieldBinaryViewType(types[i])finally:core.BNFreeBinaryViewTypeList(types)def__getitem__(self,value):binaryninja._init_plugins()view_type=core.BNGetBinaryViewTypeByName(str(value))ifview_typeisNone:raiseKeyError(f"'{value}' is not a valid view type")returnBinaryViewType(view_type)
[docs]classBinaryViewType(metaclass=_BinaryViewTypeMetaclass):"""The ``BinaryViewType`` object is used internally and should not be directly instantiated."""_platform_recognizers={}# Used to force Python callback objects to not get garbage collected
[docs]def__init__(self,handle:core.BNBinaryViewTypeHandle):_handle=core.BNBinaryViewTypeHandleself.handle=ctypes.cast(handle,_handle)
def__repr__(self):returnf"<view type: '{self.name}'>"def__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnctypes.addressof(self.handle.contents)==ctypes.addressof(other.handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):returnhash(ctypes.addressof(self.handle.contents))@propertydefname(self)->str:"""BinaryView name (read-only)"""returncore.BNGetBinaryViewTypeName(self.handle)@propertydeflong_name(self)->str:"""BinaryView long name (read-only)"""returncore.BNGetBinaryViewTypeLongName(self.handle)@propertydefis_deprecated(self)->bool:"""returns if the BinaryViewType is deprecated (read-only)"""returncore.BNIsBinaryViewTypeDeprecated(self.handle)@propertydefis_force_loadable(self)->bool:"""returns if the BinaryViewType is force loadable (read-only)"""returncore.BNIsBinaryViewTypeForceLoadable(self.handle)
[docs]defcreate(self,data:'BinaryView')->Optional['BinaryView']:view=core.BNCreateBinaryViewOfType(self.handle,data.handle)ifviewisNone:returnNonereturnBinaryView(file_metadata=data.file,handle=view)
[docs]defopen(self,src:PathType,file_metadata:'filemetadata.FileMetadata'=None)->Optional['BinaryView']:data=BinaryView.open(src,file_metadata)ifdataisNone:returnNonereturnself.create(data)
# TODO : Check if we need binary_view_type's at all after these deprecations? (move add_binaryview_finalized_event and add_binaryview_initial_analysis_completion_event to BinaryView?)
[docs]defparse(self,data:'BinaryView')->Optional['BinaryView']:view=core.BNParseBinaryViewOfType(self.handle,data.handle)ifviewisNone:returnNonereturnBinaryView(file_metadata=data.file,handle=view)
[docs]defis_valid_for_data(self,data:'BinaryView')->bool:returncore.BNIsBinaryViewTypeValidForData(self.handle,data.handle)
[docs]defget_load_settings_for_data(self,data:'BinaryView')->Optional['settings.Settings']:view_handle=NoneifdataisnotNone:view_handle=data.handleload_settings=core.BNGetBinaryViewLoadSettingsForData(self.handle,view_handle)ifload_settingsisNone:returnNonereturnsettings.Settings(handle=load_settings)
[docs]defregister_arch(self,ident:int,endian:Endianness,arch:'architecture.Architecture')->None:core.BNRegisterArchitectureForViewType(self.handle,ident,endian,arch.handle)
[docs]defget_arch(self,ident:int,endian:Endianness)->Optional['architecture.Architecture']:arch=core.BNGetArchitectureForViewType(self.handle,ident,endian)ifarchisNone:returnNonereturnarchitecture.CoreArchitecture._from_cache(arch)
[docs]defregister_platform(self,ident:int,arch:'architecture.Architecture',plat:'_platform.Platform')->None:core.BNRegisterPlatformForViewType(self.handle,ident,arch.handle,plat.handle)
[docs]defregister_default_platform(self,arch:'architecture.Architecture',plat:'_platform.Platform')->None:core.BNRegisterDefaultPlatformForViewType(self.handle,arch.handle,plat.handle)
[docs]defregister_platform_recognizer(self,ident,endian,cb):defcallback(cb,view,meta):try:file_metadata=filemetadata.FileMetadata(handle=core.BNGetFileForView(view))view_obj=BinaryView(file_metadata=file_metadata,handle=core.BNNewViewReference(view))meta_obj=metadata.Metadata(handle=core.BNNewMetadataReference(meta))plat=cb(view_obj,meta_obj)ifplat:handle=core.BNNewPlatformReference(plat.handle)asserthandleisnotNone,"core.BNNewPlatformReference returned None"returnctypes.cast(handle,ctypes.c_void_p).valueexcept:binaryninja.log_error_for_exception("Unhandled Python exception in BinaryViewType.register_platform_recognizer")returnNonecallback_obj=ctypes.CFUNCTYPE(ctypes.c_void_p,ctypes.c_void_p,ctypes.POINTER(core.BNBinaryView),ctypes.POINTER(core.BNMetadata))(lambdactxt,view,meta:callback(cb,view,meta))core.BNRegisterPlatformRecognizerForViewType(self.handle,ident,endian,callback_obj,None)self.__class__._platform_recognizers[len(self.__class__._platform_recognizers)]=callback_obj
[docs]defget_platform(self,ident:int,arch:'architecture.Architecture')->Optional['_platform.Platform']:plat=core.BNGetPlatformForViewType(self.handle,ident,arch.handle)ifplatisNone:returnNonereturn_platform.CorePlatform._from_cache(handle=plat)
[docs]defrecognize_platform(self,ident,endian:Endianness,view:'BinaryView',metadata):plat=core.BNRecognizePlatformForViewType(self.handle,ident,endian,view.handle,metadata.handle)ifplatisNone:returnNonereturn_platform.CorePlatform._from_cache(handle=plat)
[docs]@staticmethoddefadd_binaryview_finalized_event(callback:BinaryViewEvent.BinaryViewEventCallback)->None:"""`add_binaryview_finalized_event` adds a callback that gets executedwhen new binaryview is finalized.For more details, please refer to the documentation of BinaryViewEvent... warning:: The callback provided **must** stay in scope for the lifetime of the process, deletion or \garbage collection of the callback will result in a crash."""BinaryViewEvent.register(BinaryViewEventType.BinaryViewFinalizationEvent,callback)
[docs]@staticmethoddefadd_binaryview_initial_analysis_completion_event(callback:BinaryViewEvent.BinaryViewEventCallback)->None:"""`add_binaryview_initial_analysis_completion_event` adds a callbackthat gets executed after the initial analysis, as well as linearsweep and signature matcher (if they are configured to run) completed.For more details, please refer to the documentation of BinaryViewEvent... warning:: The callback provided **must** stay in scope for the lifetime of the process, deletion or \garbage collection of the callback will result in a crash."""BinaryViewEvent.register(BinaryViewEventType.BinaryViewInitialAnalysisCompletionEvent,callback)
[docs]classSegment:"""The ``Segment`` object is returned during BinaryView creation and should not be directly instantiated."""
[docs]def__init__(self,handle:core.BNSegmentHandle):self.handle=handle
def__del__(self):ifcoreisnotNone:core.BNFreeSegment(self.handle)def__repr__(self):r="r"ifself.readableelse"-"w="w"ifself.writableelse"-"x="x"ifself.executableelse"-"returnf"<segment:{self.start:#x}-{self.end:#x},{r}{w}{x}>"
[docs]@classmethod@deprecation.deprecated(deprecated_in="4.3.6653",details="Use `SegmentDescriptorList` instead.")defserialize(cls,image_base:int,start:int,length:int,data_offset:int=0,data_length:int=0,flags:'SegmentFlag'=SegmentFlag.SegmentReadable,auto_defined=True,segments:str="[]"):"""Serialize segment parameters into a JSON string. This is useful for generating a properly formatted segment description as options when using `load`.:param int image_base: The base address of the image.:param int start: The start address of the segment.:param int length: The length of the segment.:param int data_offset: The offset of the data within the segment.:param int data_length: The length of the data within the segment.:param SegmentFlag flags: The flags of the segment.:param bool auto_defined: Whether the segment is auto-defined.:param str segments: An optional, existing array of segments to append to.:return: A JSON string representing the segment.:rtype: str:Example::>>> base = 0x400000>>> rom_base = 0xffff0000>>> segments = SegmentDescriptorList(base)>>> segments.append(start=base, length=0x1000, data_offset=0, data_length=0x1000, flags=SegmentFlag.SegmentReadable|SegmentFlag.SegmentExecutable)>>> segments.append(start=rom_base, length=0x1000, flags=SegmentFlag.SegmentReadable)>>> view = load(bytes.fromhex('5054ebfe'), options={'loader.imageBase': base, 'loader.platform': 'x86', 'loader.segments': json.dumps(segments)})"""segments_list=json.loads(segments)segment_info={"auto_defined":auto_defined,"data_length":data_length,"data_offset":data_offset,"flags":flags,"length":length,"start":start-image_base}segments_list.append(segment_info)returnjson.dumps(segments_list)
@propertydeflength(self):returnint(core.BNSegmentGetLength(self.handle))def__bool__(self):returnTruedef__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnctypes.addressof(self.handle.contents)==ctypes.addressof(other.handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):returnhash(ctypes.addressof(self.handle.contents))def__contains__(self,i:int):returni>=self.startandi<self.end@propertydefstart(self)->int:returncore.BNSegmentGetStart(self.handle)@propertydefend(self)->int:returncore.BNSegmentGetEnd(self.handle)@propertydefexecutable(self)->bool:return(core.BNSegmentGetFlags(self.handle)&SegmentFlag.SegmentExecutable)!=0@propertydefwritable(self)->bool:return(core.BNSegmentGetFlags(self.handle)&SegmentFlag.SegmentWritable)!=0@propertydefreadable(self)->bool:return(core.BNSegmentGetFlags(self.handle)&SegmentFlag.SegmentReadable)!=0@propertydefdata_length(self)->int:returncore.BNSegmentGetDataLength(self.handle)@propertydefdata_offset(self)->int:returncore.BNSegmentGetDataOffset(self.handle)@propertydefdata_end(self)->int:returncore.BNSegmentGetDataEnd(self.handle)@propertydefauto_defined(self)->bool:returncore.BNSegmentIsAutoDefined(self.handle)
[docs]classSegmentDescriptorList(list):
[docs]def__init__(self,image_base:int):"""Initialize the SegmentDescriptorList with a base image address.:param int image_base: The base address of the image."""super().__init__()self.image_base=image_base
[docs]defappend(self,start:int,length:int,data_offset:int=0,data_length:int=0,flags:'SegmentFlag'=SegmentFlag.SegmentReadable,auto_defined:bool=True):"""Append a segment descriptor to the list.:param int start: The start address of the segment.:param int length: The length of the segment.:param int data_offset: The offset of the data within the segment.:param int data_length: The length of the data within the segment.:param SegmentFlag flags: The flags of the segment.:param bool auto_defined: Whether the segment is auto-defined."""segment_info={"start":start-self.image_base,"length":length,"data_offset":data_offset,"data_length":data_length,"flags":flags,"auto_defined":auto_defined}super().append(segment_info)
[docs]classSection:"""The ``Section`` object is returned during BinaryView creation and should not be directly instantiated."""
[docs]def__init__(self,handle:core.BNSectionHandle):self.handle=handle
def__del__(self):ifcoreisnotNone:core.BNFreeSection(self.handle)def__repr__(self):returnf"<section{self.name}:{self.start:#x}-{self.end:#x}>"def__bool__(self):returnTruedef__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnctypes.addressof(self.handle.contents)==ctypes.addressof(other.handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):returnhash(ctypes.addressof(self.handle.contents))def__contains__(self,i:int):returni>=self.startandi<self.end
[docs]@classmethod@deprecation.deprecated(deprecated_in="4.3.6653",details="Use `SectionDescriptorList` instead.")defserialize(cls,image_base:int,name:str,start:int,length:int,semantics:SectionSemantics=SectionSemantics.DefaultSectionSemantics,type:str="",align:int=1,entry_size:int=0,link:str="",info_section:str="",info_data:int=0,auto_defined:bool=True,sections:str="[]"):"""Serialize section parameters into a JSON string. This is useful for generating a properly formatted section description as options when using `load`.:param int image_base: The base address of the image.:param str name: The name of the section.:param int start: The start address of the section.:param int length: The length of the section.:param SectionSemantics semantics: The semantics of the section.:param str type: The type of the section.:param int align: The alignment of the section.:param int entry_size: The entry size of the section.:param str link: The linked section of the section.:param str info_section: The info section of the section.:param int info_data: The info data of the section.:param bool auto_defined: Whether the section is auto-defined.:param str sections: An optional, existing array of sections to append to.:return: A JSON string representing the section.:rtype: str"""sections_list=json.loads(sections)section_info={"align":align,"auto_defined":auto_defined,"entry_size":entry_size,"info_data":info_data,"info_section":info_section,"length":length,"link":link,"name":name,"semantics":semantics,"start":start-image_base,"type":type}sections_list.append(section_info)returnjson.dumps(sections_list)
@propertydefname(self)->str:returncore.BNSectionGetName(self.handle)@propertydeftype(self)->str:returncore.BNSectionGetType(self.handle)@propertydefstart(self)->int:returncore.BNSectionGetStart(self.handle)@propertydeflinked_section(self)->str:returncore.BNSectionGetLinkedSection(self.handle)@propertydefinfo_section(self)->str:returncore.BNSectionGetInfoSection(self.handle)@propertydefinfo_data(self)->int:returncore.BNSectionGetInfoData(self.handle)@propertydefalign(self)->int:returncore.BNSectionGetAlign(self.handle)@propertydefentry_size(self)->int:returncore.BNSectionGetEntrySize(self.handle)@propertydefsemantics(self)->SectionSemantics:returnSectionSemantics(core.BNSectionGetSemantics(self.handle))@propertydefauto_defined(self)->bool:returncore.BNSectionIsAutoDefined(self.handle)@propertydeflength(self):returnint(core.BNSectionGetLength(self.handle))@propertydefend(self)->int:returnself.start+self.length
[docs]classSectionDescriptorList(list):
[docs]def__init__(self,image_base:int):"""Initialize the SectionDescriptorList with a base image address.:param int image_base: The base address of the image."""super().__init__()self.image_base=image_base
[docs]defappend(self,name:str,start:int,length:int,semantics:'SectionSemantics'=SectionSemantics.DefaultSectionSemantics,type:str="",align:int=1,entry_size:int=0,link:str="",info_section:str="",info_data:int=0,auto_defined:bool=True):"""Append a section descriptor to the list.:param str name: The name of the section.:param int start: The start address of the section.:param int length: The length of the section.:param SectionSemantics semantics: The semantics of the section.:param str type: The type of the section.:param int align: The alignment of the section.:param int entry_size: The size of each entry in the section.:param str link: An optional link field.:param str info_section: An optional info_section field.:param int info_data: An optional info_data field.:param bool auto_defined: Whether the section is auto-defined."""section_info={"name":name,"start":start-self.image_base,"length":length,"semantics":semantics,"type":type,"align":align,"entry_size":entry_size,"link":link,"info_section":info_section,"info_data":info_data,"auto_defined":auto_defined}super().append(section_info)
[docs]classTagType:"""The ``TagType`` object is created by the create_tag_type API and should not be directly instantiated."""
[docs]def__init__(self,handle:core.BNTagTypeHandle):self.handle=handle
def__del__(self):ifcoreisnotNone:core.BNFreeTagType(self.handle)def__repr__(self):returnf"<tag type{self.name}:{self.icon}>"def__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnctypes.addressof(self.handle.contents)==ctypes.addressof(other.handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):returnhash(ctypes.addressof(self.handle.contents))@propertydefid(self)->str:"""Unique id of the TagType"""returncore.BNTagTypeGetId(self.handle)@propertydefname(self)->str:"""Name of the TagType"""returncore.BNTagTypeGetName(self.handle)@name.setterdefname(self,value:str)->None:core.BNTagTypeSetName(self.handle,value)@propertydeficon(self)->str:"""Unicode str containing an emoji to be used as an icon"""returncore.BNTagTypeGetIcon(self.handle)@icon.setterdeficon(self,value:str)->None:core.BNTagTypeSetIcon(self.handle,value)@propertydefvisible(self)->bool:"""Boolean for whether the tags of this type are visible"""returncore.BNTagTypeGetVisible(self.handle)@visible.setterdefvisible(self,value:bool)->None:core.BNTagTypeSetVisible(self.handle,value)@propertydeftype(self)->TagTypeType:"""Type from enums.TagTypeType"""returnTagTypeType(core.BNTagTypeGetType(self.handle))@type.setterdeftype(self,value:TagTypeType)->None:core.BNTagTypeSetType(self.handle,value)
[docs]classTag:"""The ``Tag`` object is created by other APIs (create_*_tag) and should not be directly instantiated."""
[docs]def__init__(self,handle:core.BNTagHandle):self.handle=handle
def__del__(self):ifcoreisnotNone:core.BNFreeTag(self.handle)def__repr__(self):returnf"<tag{self.type.icon}{self.type.name}:{self.data}>"def__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnctypes.addressof(self.handle.contents)==ctypes.addressof(other.handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):returnhash(ctypes.addressof(self.handle.contents))@propertydefid(self)->str:returncore.BNTagGetId(self.handle)@propertydeftype(self)->TagType:core_tag_type=core.BNTagGetType(self.handle)assertcore_tag_typeisnotNone,"core.BNTagGetType returned None"returnTagType(core_tag_type)@propertydefdata(self)->str:returncore.BNTagGetData(self.handle)@data.setterdefdata(self,value:str)->None:core.BNTagSetData(self.handle,value)
[docs]@dataclassclassRelocationInfo:type:RelocationTypepc_relative:boolbase_relative:boolbase:intsize:inttruncate_size:intnative_type:intaddend:inthas_sign:boolimplicit_addend:boolexternal:boolsymbol_index:intsection_index:intaddress:inttarget:intdata_relocation:bool
[docs]def__init__(self,info:core.BNRelocationInfo):self.type=RelocationType(info.type)self.pc_relative=info.pcRelativeself.base_relative=info.baseRelativeself.base=info.baseself.size=info.sizeself.truncate_size=info.truncateSizeself.native_type=info.nativeTypeself.addend=info.addendself.has_sign=info.hasSignself.implicit_addend=info.implicitAddendself.external=info.externalself.symbol_index=info.symbolIndexself.section_index=info.sectionIndexself.address=info.addressself.target=info.targetself.data_relocation=info.dataRelocation
[docs]classRelocation:
[docs]def__init__(self,handle:core.BNRelocationHandle):self.handle=handle
def__del__(self):ifcoreisnotNone:core.BNFreeRelocation(self.handle)def__repr__(self):ifself.symbolisNone:returnf"<Relocation:{self.target:#x}>"try:returnf"<Relocation:\"{self.symbol.full_name}\" @{self.target:#x}>"exceptUnicodeDecodeError:returnf"<Relocation:\"{self.symbol.raw_bytes}\" @{self.target:#x}>"def__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnctypes.addressof(self.handle.contents)==ctypes.addressof(other.handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):returnhash(ctypes.addressof(self.handle.contents))@propertydefinfo(self)->RelocationInfo:returnRelocationInfo(core.BNRelocationGetInfo(self.handle))@propertydefarch(self)->Optional['architecture.Architecture']:"""The architecture associated with the :py:class:`Relocation` (read/write)"""core_arch=core.BNRelocationGetArchitecture(self.handle)returnarchitecture.CoreArchitecture._from_cache(handle=core_arch)@propertydeftarget(self)->int:"""Where the reloc needs to point to"""returncore.BNRelocationGetTarget(self.handle)@propertydefreloc(self)->int:"""The actual pointer that needs to be relocated"""returncore.BNRelocationGetReloc(self.handle)@propertydefsymbol(self)->Optional['_types.CoreSymbol']:core_symbol=core.BNRelocationGetSymbol(self.handle)ifcore_symbolisNone:returnNonereturn_types.CoreSymbol(core_symbol)
class_BinaryViewAssociatedDataStore(associateddatastore._AssociatedDataStore):_defaults={}
[docs]classSymbolMapping(collections.abc.Mapping):# type: ignore"""SymbolMapping object is used to improve performance of the `bv.symbols` API.This allows pythonic code like this to have reasonable performance characteristics>>> my_symbols = get_my_symbols()>>> for symbol in my_symbols:>>>  if bv.symbols[symbol].address == 0x41414141:>>>    print("Found")"""
[docs]def__init__(self,view:'BinaryView'):self._symbol_list=Noneself._count=Noneself._symbol_cache:Optional[Mapping[str,List[_types.CoreSymbol]]]=Noneself._view=viewself._n=0self._keys=None
def__repr__(self):returnf"<SymbolMapping{len(self)} symbols:{self._symbol_cache}>"def__del__(self):ifcoreisnotNoneandself._symbol_listisnotNone:core.BNFreeSymbolList(self._symbol_list,len(self))def__getitem__(self,key:str)->Optional[List['_types.CoreSymbol']]:ifself._symbol_cacheisNone:sym=self._view.get_symbols_by_raw_name(key)iflen(sym)==0:raiseKeyError(f"'{key}': symbol not found")returnsymelse:returnself._symbol_cache[key]def_build_symbol_cache(self):count=ctypes.c_ulonglong(0)self._symbol_list=core.BNGetSymbols(self._view.handle,count,None)assertself._symbol_listisnotNone,"core.BNGetSymbols returned None"self._symbol_cache={}self._count=count.valueforiinrange(len(self)):_handle=core.BNNewSymbolReference(self._symbol_list[i])assert_handleisnotNone,"core.BNNewSymbolReference returned None"sym=_types.CoreSymbol(_handle)try:ifsym.raw_nameinself._symbol_cache:self._symbol_cache[sym.raw_name].append(sym)else:self._symbol_cache[sym.raw_name]=[sym]exceptUnicodeDecodeError:mapped_str=sym.raw_bytes.decode('charmap')ifmapped_strinself._symbol_cache:self._symbol_cache[mapped_str].append(sym)else:self._symbol_cache[mapped_str]=[sym]def__iter__(self)->Iterator[str]:ifself._symbol_cacheisNone:self._build_symbol_cache()assertself._symbol_cacheisnotNoneyield fromself._symbol_cachedef__next__(self)->List['_types.CoreSymbol']:ifself._symbol_cacheisNone:self._build_symbol_cache()assertself._symbol_cacheisnotNoneifself._keysisNone:self._keys=list(self._symbol_cache.keys())self._n+=1returnself._symbol_cache[self._keys[self._n-1]]def__len__(self):ifself._symbol_cacheisNone:self._build_symbol_cache()returnself._countdef__contains__(self,value:str):try:_=self[value]returnTrueexceptKeyError:returnFalse
[docs]defkeys(self)->KeysView[str]:ifself._symbol_cacheisNone:self._build_symbol_cache()assertself._symbol_cacheisnotNonereturnself._symbol_cache.keys()
[docs]defitems(self)->ItemsView[str,List['_types.CoreSymbol']]:ifself._symbol_cacheisNone:self._build_symbol_cache()assertself._symbol_cacheisnotNonereturnself._symbol_cache.items()
[docs]defvalues(self)->ValuesView[List['_types.CoreSymbol']]:ifself._symbol_cacheisNone:self._build_symbol_cache()assertself._symbol_cacheisnotNonereturnself._symbol_cache.values()
[docs]defget(self,key:str,default:Optional[List['_types.CoreSymbol']]=None)->Optional[List['_types.CoreSymbol']]:try:returnself[key]exceptKeyError:returndefault
[docs]classTypeMapping(collections.abc.Mapping):# type: ignore"""TypeMapping object is used to improve performance of the `bv.types` API.This allows pythonic code like this to have reasonable performance characteristics>>> my_types = get_my_types()>>> for type_name in my_types:>>>  if bv.types[type_name].width == 4:>>>    print("Found")"""
[docs]def__init__(self,view:'BinaryView',get_list_fn=core.BNGetAnalysisTypeList):self._type_list=Noneself._count=Noneself._type_cache:Optional[Mapping[_types.QualifiedName,_types.Type]]=Noneself._view=viewself._get_list_fn=get_list_fn
def__repr__(self):returnf"<TypeMapping{len(self)} symbols:{self._type_cache}>"def__del__(self):ifcoreisnotNoneandself._type_listisnotNone:core.BNFreeTypeAndNameList(self._type_list,len(self))def__getitem__(self,key):ifself._type_cacheisNone:result=self._view.get_type_by_name(key)ifresultisNone:raiseKeyError(key)returnresultelse:returnself._type_cache[key]def__iter__(self):ifself._type_cacheisnotNone:yield fromself._type_cachecount=ctypes.c_ulonglong(0)type_list=self._get_list_fn(self._view.handle,count)asserttype_listisnotNone,"core.BNGetAnalysisTypeList returned None"self._type_list=type_listself._type_cache={}self._count=count.valueforiinrange(len(self)):name=_types.QualifiedName._from_core_struct(self._type_list[i].name)type=_types.Type.create(core.BNNewTypeReference(self._type_list[i].type),platform=self._view.platform)self._type_cache[name]=typeyieldname,typedef_build_type_cache(self):for_,_inself:passdef__len__(self):ifself._type_cacheisNone:self._build_type_cache()returnself._countdef__contains__(self,value):try:self[value]returnTrueexceptKeyError:returnFalsedef__eq__(self,other):returnself._view==other._viewdef__ne__(self,other):returnnot(self==other)
[docs]defkeys(self):ifself._type_cacheisNone:self._build_type_cache()assertself._type_cacheisnotNonereturnself._type_cache.keys()
[docs]defitems(self):ifself._type_cacheisNone:self._build_type_cache()assertself._type_cacheisnotNonereturnself._type_cache.items()
[docs]defvalues(self):ifself._type_cacheisNone:self._build_type_cache()assertself._type_cacheisnotNonereturnself._type_cache.values()
[docs]defget(self,value,default=None):try:returnself[value]exceptKeyError:returndefault
[docs]classFunctionList:
[docs]def__init__(self,view:'BinaryView'):count=ctypes.c_ulonglong(0)_funcs=core.BNGetAnalysisFunctionList(view.handle,count)assert_funcsisnotNone,"core.BNGetAnalysisFunctionList returned None"self._funcs=_funcsself._count=count.valueself._view=viewself._n=0
def__iter__(self):foriinrange(0,len(self)):yield_function.Function(self._view,core.BNNewFunctionReference(self._funcs[i]))def__next__(self):ifself._n>=len(self):raiseStopIterationfunc=core.BNNewFunctionReference(self._funcs[self._n])assertfuncisnotNone,"core.BNNewFunctionReference returned None"self._n+=1return_function.Function(self._view,func)@overloaddef__getitem__(self,i:int)->'_function.Function':...@overloaddef__getitem__(self,i:slice)->List['_function.Function']:...def__getitem__(self,i:Union[int,slice])->Union['_function.Function',List['_function.Function']]:ifisinstance(i,int):ifi<0:i=len(self)+iifi>=len(self):raiseIndexError(f"Index{i} out of bounds for FunctionList of size{len(self)}")return_function.Function(self._view,core.BNNewFunctionReference(self._funcs[i]))elifisinstance(i,slice):result=[]ifi.start<0ori.start>=len(self)ori.stop<0ori.stop>=len(self):raiseIndexError(f"Slice{i} out of bounds for FunctionList of size{len(self)}")forjinrange(i.start,i.stop,i.stepifi.stepisnotNoneelse1):result.append(_function.Function(self._view,core.BNNewFunctionReference(self._funcs[j])))returnresultraiseValueError("FunctionList.__getitem__ supports argument of type integer or slice")def__del__(self):ifcoreisnotNone:core.BNFreeFunctionList(self._funcs,len(self))def__len__(self)->int:returnself._count
[docs]classAdvancedILFunctionList:"""The purpose of this class is to generate IL functions IL function in the backgroundimproving the performance of iterating MediumLevelIL and HighLevelILFunctions.Using this class or the associated helper methods BinaryView.mlil_functions / BinaryView.hlil_functionscan improve the performance of ILFunction iteration significantlyThe prefetch_limit property is configurable and should be modified based upon your machines hardware and RAM limitations... warning:: Setting the prefetch_limit excessively high can result in high memory utilization.:Example:>>> import timeit>>> len(bv.functions)4817>>> # Calculate the average time to generate hlil for all functions withing 'bv':>>> timeit.timeit(lambda:[f.hlil for f in bv.functions], number=1)21.761621682000168>>> t1 = _>>> # Now try again with the advanced analysis iterator>>> timeit.timeit(lambda:[f for f in bv.hlil_functions(128)], number=1)6.3147709989998475>>> t1/_3.4461458199270947>>> # This particular binary can iterate hlil functions 3.4x faster>>> # If you don't need IL then its still much faster to just use `bv.functions`>>> timeit.timeit(lambda:[f for f in bv.functions], number=1)0.02230275600004461"""
[docs]def__init__(self,view:'BinaryView',preload_limit:int=mainthread.get_worker_thread_count(),functions:Optional[Iterable]=None):self._view=viewself._func_queue=deque()self._preload_limit=preload_limitiffunctionsisNone:self._functions=FunctionList(self._view)else:self._functions=iter(functions)
def__iter__(self):whileTrue:whilelen(self._func_queue)<self._preload_limit:try:self._func_queue.append(_function.AdvancedFunctionAnalysisDataRequestor(next(self._functions)))exceptStopIteration:breakifnotself._func_queue:breakyieldself._func_queue.popleft().function
[docs]classMemoryMap:r"""The MemoryMap object describes a system-level memory map into which a BinaryView is loaded. Each BinaryViewexposes its portion of the MemoryMap through the Segments defined within that view.A MemoryMap can contain multiple, arbitrarily overlapping memory regions. When modified, address spacesegmentation is automatically managed. If multiple regions overlap, the most recently added region takesprecedence by default.All MemoryMap APIs support undo and redo operations. During BinaryView::Init, these APIs should be used conditionally:* Initial load: Use the MemoryMap APIs to define the memory regions that compose the system.* Database load: Do not use the MemoryMap APIs, as the regions are already persisted and will be restored automatically.This conditional usage prevents redundant operations and ensures database consistency. Using these APIs when loadingfrom a database will also mark the analysis as modified, which is undesirable.:Example:.. code-block:: python>>> base = 0x10000>>> rom_base = 0xc0000000>>> segments = SegmentDescriptorList(base)>>> segments.append(start=base, length=0x1000, data_offset=0, data_length=0x1000, flags=SegmentFlag.SegmentReadable|SegmentFlag.SegmentExecutable)>>> segments.append(start=rom_base, length=0x1000, flags=SegmentFlag.SegmentReadable)>>> view = load(bytes.fromhex('5054ebfe'), options={'loader.imageBase': base, 'loader.platform': 'x86', 'loader.segments': json.dumps(segments)})>>> view.memory_map<region: 0x10000 - 0x10004>size: 0x4objects:'origin<Mapped>@0x0' | Mapped<Absolute> | <r-x><region: 0xc0000000 - 0xc0001000>size: 0x1000objects:'origin<Mapped>@0xbfff0000' | Unmapped | <r--> | FILL<0x0><region: 0xc0001000 - 0xc0001014>size: 0x14objects:'origin<Mapped>@0xbfff1000' | Unmapped | <---> | FILL<0x0>>>> view.memory_map.add_memory_region("rom", rom_base, b'\x90' * 4096, SegmentFlag.SegmentReadable | SegmentFlag.SegmentExecutable)True>>> view.memory_map<region: 0x10000 - 0x10004>size: 0x4objects:'origin<Mapped>@0x0' | Mapped<Absolute> | <r-x><region: 0xc0000000 - 0xc0001000>size: 0x1000objects:'rom' | Mapped<Relative> | <r-x>'origin<Mapped>@0xbfff0000' | Unmapped | <r--> | FILL<0x0><region: 0xc0001000 - 0xc0001014>size: 0x14objects:'origin<Mapped>@0xbfff1000' | Unmapped | <---> | FILL<0x0>>>> view.read(rom_base, 16)b'\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90'>>> view.memory_map.add_memory_region("pad", rom_base, b'\xa5' * 8)True>>> view.read(rom_base, 16)b'\xa5\xa5\xa5\xa5\xa5\xa5\xa5\xa5\x90\x90\x90\x90\x90\x90\x90\x90'>>> view.memory_map<region: 0x10000 - 0x10004>size: 0x4objects:'origin<Mapped>@0x0' | Mapped<Absolute> | <r-x><region: 0xc0000000 - 0xc0000008>size: 0x8objects:'pad' | Mapped<Relative> | <--->'rom' | Mapped<Relative> | <r-x>'origin<Mapped>@0xbfff0000' | Unmapped | <r--> | FILL<0x0><region: 0xc0000008 - 0xc0001000>size: 0xff8objects:'rom' | Mapped<Relative> | <r-x>'origin<Mapped>@0xbfff0000' | Unmapped | <r--> | FILL<0x0><region: 0xc0001000 - 0xc0001014>size: 0x14objects:'origin<Mapped>@0xbfff1000' | Unmapped | <---> | FILL<0x0>"""def__repr__(self):returnself.__str__()def__str__(self):description=self.description()returnself.format_description(description)def__len__(self):mm_json=self.description()if'MemoryMap'inmm_json:returnlen(mm_json['MemoryMap'])else:return0
[docs]def__init__(self,handle:'BinaryView'):self.handle=handle
[docs]defformat_description(self,description:dict)->str:formatted_description=""forentryindescription['MemoryMap']:formatted_description+=f"<region:{hex(entry['address'])} -{hex(entry['address']+entry['length'])}>\n"formatted_description+=f"\tsize:{hex(entry['length'])}\n"formatted_description+="\tobjects:\n"forobjinentry['objects']:ifobj['target']:mapped_state=f"Mapped<{'Absolute'ifobj['absolute_address_mode']else'Relative'}>"else:mapped_state="Unmapped"formatted_description+=f"\t\t'{obj['name']}' |{mapped_state}"r="r"ifobj['flags']&SegmentFlag.SegmentReadableelse"-"w="w"ifobj['flags']&SegmentFlag.SegmentWritableelse"-"x="x"ifobj['flags']&SegmentFlag.SegmentExecutableelse"-"formatted_description+=f" | <{r}{w}{x}>"ifnotobj['target']:formatted_description+=f" | FILL<{hex(obj['fill'])}>"ifnotobj['enabled']:formatted_description+=f" | <DISABLED>"formatted_description+="\n"formatted_description+="\n"returnformatted_description
[docs]defdescription(self,base:bool=False)->dict:ifbase:returnjson.loads(core.BNGetBaseMemoryMapDescription(self.handle))returnjson.loads(core.BNGetMemoryMapDescription(self.handle))
@propertydefbase(self):"""Formatted string of the base memory map, consisting of unresolved auto and user segments (read-only)."""returnself.format_description(self.description(base=True))
[docs]defset_logical_memory_map_enabled(self,enabled:bool)->None:"""Enable or disable the logical memory map.When enabled, the memory map will present a simplified, logical view that merges and abstracts virtual memoryregions based on criteria such as contiguity and flag consistency. This view is designed to provide a higher-levelrepresentation for user analysis, hiding underlying mapping details.When disabled, the memory map will revert to displaying the virtual view, which corresponds directly to the individualsegments mapped from the raw file without any merging or abstraction.:param enabled: True to enable the logical view, False to revert to the virtual view."""core.BNSetLogicalMemoryMapEnabled(self.handle,enabled)
@propertydefis_activated(self):"""Whether the memory map is activated for the associated view."""returncore.BNIsMemoryMapActivated(self.handle)
[docs]defadd_memory_region(self,name:str,start:int,source:Optional[Union['os.PathLike',str,bytes,bytearray,'BinaryView','databuffer.DataBuffer','fileaccessor.FileAccessor']]=None,flags:SegmentFlag=0,fill:int=0,length:Optional[int]=None)->bool:"""Adds a memory region to the memory map. Depending on the source parameter, the memory region is created as one of the following types:- **BinaryMemoryRegion** (***Unimplemented***): Represents a memory region loaded from a binary format.- **DataMemoryRegion**: Region backed by flat file or raw data (str, bytes, DataBuffer).- **RemoteMemoryRegion**: Ephemeral memory region via FileAccessor.- **UnbackedMemoryRegion**: Region not backed by any data source (requires `length` to be set).The `source` parameter determines the type:- `os.PathLike` or `str`: File path to be loaded into memory as a `DataMemoryRegion`.- `bytes` or `bytearray`: Directly loaded into memory as a `DataMemoryRegion`.- `databuffer.DataBuffer`: Loaded as a `DataMemoryRegion`.- `fileaccessor.FileAccessor`: Remote proxy source.- `BinaryView`: (Reserved for future).- `None`: Creates an unbacked memory region (must specify `length`)... note:: If no flags are specified and the new memory region overlaps with one or more existing regions, the overlapping portions of the new region will inherit the flags of the respective underlying regions.Parameters:name (str): A unique name for the memory region.start (int): Starting address.source (Optional[Union[os.PathLike, str, bytes, bytearray, BinaryView, databuffer.DataBuffer, fileaccessor.FileAccessor]]): Source of data or `None` for unbacked.length (Optional[int]): Required if source is None (unbacked).flags (SegmentFlag): Flags to apply to the memory region. Defaults to 0 (no flags).fill (int): Fill byte for unbacked regions. Defaults to 0.Returns:bool: `True` if the memory region was successfully added, `False` otherwise.Raises:NotImplementedError: If source type is unsupported.ValueError: If source is None and length is not specified."""ifsourceisNone:iflengthisNone:raiseValueError("Must specify `length` when `source` is None for unbacked memory region")returncore.BNAddUnbackedMemoryRegion(self.handle,name,start,length,flags,fill)ifisinstance(source,os.PathLike):source=str(source)ifisinstance(source,bytes)orisinstance(source,bytearray):source=databuffer.DataBuffer(source)ifisinstance(source,str):withopen(source,"rb")asf:source=databuffer.DataBuffer(f.read())ifnameisNone:name=""ifisinstance(source,BinaryView):returncore.BNAddBinaryMemoryRegion(self.handle,name,start,source.handle,flags)elifisinstance(source,databuffer.DataBuffer):returncore.BNAddDataMemoryRegion(self.handle,name,start,source.handle,flags)elifisinstance(source,fileaccessor.FileAccessor):returncore.BNAddRemoteMemoryRegion(self.handle,name,start,source._cb,flags)else:raiseNotImplementedError(f"Unsupported memory region source type:{type(source)}")
[docs]defremove_memory_region(self,name:str)->bool:returncore.BNRemoveMemoryRegion(self.handle,name)
[docs]defget_active_memory_region_at(self,addr:int)->str:returncore.BNGetActiveMemoryRegionAt(self.handle,addr)
[docs]defget_memory_region_flags(self,name:str)->set:flags=core.BNGetMemoryRegionFlags(self.handle,name)return{flagforflaginSegmentFlagifflags&flag}
[docs]defset_memory_region_flags(self,name:str,flags:SegmentFlag)->bool:returncore.BNSetMemoryRegionFlags(self.handle,name,flags)
[docs]defis_memory_region_enabled(self,name:str)->bool:returncore.BNIsMemoryRegionEnabled(self.handle,name)
[docs]defset_memory_region_enabled(self,name:str,enabled:bool=True)->bool:returncore.BNSetMemoryRegionEnabled(self.handle,name,enabled)
[docs]defis_memory_region_rebaseable(self,name:str)->bool:returncore.BNIsMemoryRegionRebaseable(self.handle,name)
[docs]defset_memory_region_rebaseable(self,name:str,rebaseable:bool=True)->bool:returncore.BNSetMemoryRegionRebaseable(self.handle,name,rebaseable)
[docs]defget_memory_region_fill(self,name:str)->int:returncore.BNGetMemoryRegionFill(self.handle,name)
[docs]defset_memory_region_fill(self,name:str,fill:int)->bool:returncore.BNSetMemoryRegionFill(self.handle,name,fill)
[docs]defget_memory_region_display_name(self,name:str)->str:returncore.BNGetMemoryRegionDisplayName(self.handle,name)
[docs]defset_memory_region_display_name(self,name:str,display_name:str)->bool:returncore.BNSetMemoryRegionDisplayName(self.handle,name,display_name)
[docs]defis_memory_region_local(self,name:str)->bool:returncore.BNIsMemoryRegionLocal(self.handle,name)
[docs]defreset(self):core.BNResetMemoryMap(self.handle)
[docs]classBinaryView:"""``class BinaryView`` implements a view on binary data, and presents a queryable interface of a binary file. One keyjob of BinaryView is file format parsing which allows Binary Ninja to read, write, insert, remove portionsof the file given a virtual address. For the purposes of this documentation we define a virtual address as thememory address that the various pieces of the physical file will be loaded at.A binary file does not have to have just one BinaryView, thus much of the interface to manipulate disassembly existswithin or is accessed through a BinaryView. All files are guaranteed to have at least the ``Raw`` BinaryView. The``Raw`` BinaryView is simply a hex editor, but is helpful for manipulating binary files via their absolute addresses.BinaryViews are plugins and thus registered with Binary Ninja at startup, and thus should **never** be instantiateddirectly as this is already done. The list of available BinaryViews can be seen in the BinaryViewType class whichprovides an iterator and map of the various installed BinaryViews::>>> list(BinaryViewType)[<view type: 'Raw'>, <view type: 'ELF'>, <view type: 'Mach-O'>, <view type: 'PE'>]>>> BinaryViewType['ELF']<view type: 'ELF'>To open a file with a given BinaryView the following code is recommended:>>> with load("/bin/ls") as bv:...   bv<BinaryView: '/bin/ls', start 0x100000000, len 0x142c8>`By convention in the rest of this document we will use bv to mean an open and, analyzed, BinaryView of an executable file.`When a BinaryView is open on an executable view analysis is automatically run unless specific named parameters are usedto disable updates. If such a parameter is used, updates can be triggered using the :py:func:`update_analysis_and_wait` methodwhich disassembles the executable and returns when all disassembly and analysis is complete::>>> bv.update_analysis_and_wait()>>>Since BinaryNinja's analysis is multi-threaded (depending on version) this can also be done in the backgroundby using the :py:func:`update_analysis` method instead.By standard python convention methods which start with '_' should be considered private and should notbe called externally. Additionally, methods which begin with ``perform_`` should not be called directlyeither and are used explicitly for subclassing a BinaryView... note:: An important note on the ``*_user_*()`` methods. Binary Ninja makes a distinction between edits \performed by the user and actions performed by auto analysis. Auto analysis actions that can quickly be recalculated \are not saved to the database. Auto analysis actions that take a long time and all user edits are stored in the \database (e.g. :py:func:`remove_user_function` rather than :py:func:`remove_function`). Thus use ``_user_`` methods if saving \to the database is desired."""name:Optional[str]=Nonelong_name:Optional[str]=None_registered=False_registered_cb=Noneregistered_view_type=None_associated_data={}_registered_instances=[]_cached_instances={}@classmethoddef_cache_insert(cls,instance):key=ctypes.addressof(instance.handle.contents)ifkeynotincls._cached_instances:cls._cached_instances[ctypes.addressof(instance.handle.contents)]=instance@classmethoddef_cache_remove(cls,handle):key=ctypes.addressof(handle.contents)ifkeyincls._cached_instances:cls._cached_instances.pop(key)@classmethoddef_cache_contains(cls,handle):returnctypes.addressof(handle.contents)incls._cached_instances
[docs]def__new__(cls,file_metadata=None,parent_view=None,handle=None):ifhandle:key=ctypes.addressof(handle.contents)ifkeyincls._cached_instances:core.BNFreeBinaryView(handle)# release the already taken reference since we are pulling from the cachereturncls._cached_instances[key]returnsuper().__new__(cls)
[docs]def__init__(self,file_metadata:Optional['filemetadata.FileMetadata']=None,parent_view:Optional['BinaryView']=None,handle:Optional[core.BNBinaryViewHandle]=None):ifhandleisnotNone:ifself.__class__._cache_contains(handle):return_handle=handleiffile_metadataisNone:self._file=filemetadata.FileMetadata(handle=core.BNGetFileForView(handle))else:self._file=file_metadataelifself.__class__isBinaryView:binaryninja._init_plugins()iffile_metadataisNone:file_metadata=filemetadata.FileMetadata()_handle=core.BNCreateBinaryDataView(file_metadata.handle)self._file=filemetadata.FileMetadata(handle=core.BNNewFileReference(file_metadata.handle))else:binaryninja._init_plugins()ifnotself.__class__._registered:raiseTypeError("view type not registered")self._cb=core.BNCustomBinaryView()self._cb.context=0self._cb.init=self._cb.init.__class__(self._init)self._cb.externalRefTaken=self._cb.externalRefTaken.__class__(self._external_ref_taken)self._cb.externalRefReleased=self._cb.externalRefReleased.__class__(self._external_ref_released)self._cb.read=self._cb.read.__class__(self._read)self._cb.write=self._cb.write.__class__(self._write)self._cb.insert=self._cb.insert.__class__(self._insert)self._cb.remove=self._cb.remove.__class__(self._remove)self._cb.getModification=self._cb.getModification.__class__(self._get_modification)self._cb.isValidOffset=self._cb.isValidOffset.__class__(self._is_valid_offset)self._cb.isOffsetReadable=self._cb.isOffsetReadable.__class__(self._is_offset_readable)self._cb.isOffsetWritable=self._cb.isOffsetWritable.__class__(self._is_offset_writable)self._cb.isOffsetExecutable=self._cb.isOffsetExecutable.__class__(self._is_offset_executable)self._cb.getNextValidOffset=self._cb.getNextValidOffset.__class__(self._get_next_valid_offset)self._cb.getStart=self._cb.getStart.__class__(self._get_start)self._cb.getLength=self._cb.getLength.__class__(self._get_length)self._cb.getEntryPoint=self._cb.getEntryPoint.__class__(self._get_entry_point)self._cb.isExecutable=self._cb.isExecutable.__class__(self._is_executable)self._cb.getDefaultEndianness=self._cb.getDefaultEndianness.__class__(self._get_default_endianness)self._cb.isRelocatable=self._cb.isRelocatable.__class__(self._is_relocatable)self._cb.getAddressSize=self._cb.getAddressSize.__class__(self._get_address_size)self._cb.save=self._cb.save.__class__(self._save)iffile_metadataisNone:raiseException("Attempting to create a BinaryView with FileMetadata which is None")self._file=file_metadata_parent_view=Noneifparent_viewisnotNone:_parent_view=parent_view.handle_handle=core.BNCreateCustomBinaryView(self.__class__.name,file_metadata.handle,_parent_view,self._cb)assert_handleisnotNoneself.handle=_handleself._notifications={}self._parse_only=Falseself._preload_limit=5self._platform=Noneself._endianness=None
def_cleanup(self):ifcoreisNone:returnforiinself._notifications.values():i._unregister()self._notifications.clear()ifself.handleisnotNone:core.BNFreeBinaryView(self.handle)self.handle=Nonedef__enter__(self)->'BinaryView':returnselfdef__exit__(self,type,value,traceback):self._cleanup()self.file.close()def__del__(self):self._cleanup()def__repr__(self):start=self.startlength=self.lengthifstart!=0:size=f"start{start:#x}, len{length:#x}"else:size=f"len{length:#x}"filename=self._file.filenameiflen(filename)>0:returnf"<BinaryView: '{filename}',{size}>"returnf"<BinaryView:{size}>"@propertydeflength(self):returnint(core.BNGetViewLength(self.handle))def__bool__(self):returnTruedef__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnctypes.addressof(self.handle.contents)==ctypes.addressof(other.handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):returnhash(ctypes.addressof(self.handle.contents))def__iter__(self)->Generator['_function.Function',None,None]:yield fromself.functionsdef__getitem__(self,i)->bytes:ifisinstance(i,tuple):result=bytes()forsini:result+=self.__getitem__(s)returnresultelifisinstance(i,slice):ifi.stepisnotNone:raiseIndexError("step not implemented")i=i.indices(self.end)start=i[0]stop=i[1]ifstop<=start:returnb""returnself.read(start,stop-start)elifi<0:ifi>=-self.length:value=self.read(self.start+int(self.length+i),1)iflen(value)==0:raiseIndexError("index not readable")returnvalueraiseIndexError("index out of range")elif(i>=self.start)and(i<self.end):value=self.read(int(i),1)iflen(value)==0:raiseIndexError("index not readable")returnvalueelse:raiseIndexError("index out of range")def__setitem__(self,i,value):ifisinstance(i,slice):ifi.stepisnotNone:raiseIndexError("step not supported on assignment")i=i.indices(self.end)start=i[0]stop=i[1]ifstop<start:stop=startiflen(value)!=(stop-start):self.remove(start,stop-start)self.insert(start,value)else:self.write(start,value)elifi<0:ifi>=-self.length:iflen(value)!=1:raiseValueError("expected single byte for assignment")ifself.write(self.start+int(self.length+i),value)!=1:raiseIndexError("index not writable")else:raiseIndexError("index out of range")elif(i>=self.start)and(i<self.end):iflen(value)!=1:raiseValueError("expected single byte for assignment")ifself.write(int(i),value)!=1:raiseIndexError("index not writable")else:raiseIndexError("index out of range")def__contains__(self,i:int):forsinself.segments:ifiins:returnTruereturnFalse
[docs]@classmethoddefregister(cls)->None:binaryninja._init_plugins()ifcls.nameisNone:raiseValueError("view 'name' not defined")ifcls.long_nameisNone:cls.long_name=cls.namecls._registered_cb=core.BNCustomBinaryViewType()cls._registered_cb.context=0cls._registered_cb.create=cls._registered_cb.create.__class__(cls._create)cls._registered_cb.parse=cls._registered_cb.parse.__class__(cls._parse)cls._registered_cb.isValidForData=cls._registered_cb.isValidForData.__class__(cls._is_valid_for_data)cls._registered_cb.isDeprecated=cls._registered_cb.isDeprecated.__class__(cls._is_deprecated)cls._registered_cb.isForceLoadable=cls._registered_cb.isForceLoadable.__class__(cls._is_force_loadable)cls._registered_cb.getLoadSettingsForData=cls._registered_cb.getLoadSettingsForData.__class__(cls._get_load_settings_for_data)view_handle=core.BNRegisterBinaryViewType(cls.name,cls.long_name,cls._registered_cb)assertview_handleisnotNone,"core.BNRegisterBinaryViewType returned None"cls.registered_view_type=BinaryViewType(view_handle)cls._registered=True
@propertydefparse_only(self)->bool:returnself._parse_only@parse_only.setterdefparse_only(self,value:bool)->None:self._parse_only=value@classmethoddef_create(cls,ctxt,data:core.BNBinaryView):try:file_metadata=filemetadata.FileMetadata(handle=core.BNGetFileForView(data))view=cls(BinaryView(file_metadata=file_metadata,handle=core.BNNewViewReference(data)))# type: ignoreifviewisNone:returnNoneview.parse_only=Falseview_handle=core.BNNewViewReference(view.handle)assertview_handleisnotNone,"core.BNNewViewReference returned None"returnctypes.cast(view_handle,ctypes.c_void_p).valueexcept:log_error_for_exception("Unhandled Python exception in BinaryView._create")returnNone@classmethoddef_parse(cls,ctxt,data:core.BNBinaryView):try:file_metadata=filemetadata.FileMetadata(handle=core.BNGetFileForView(data))view=cls(BinaryView(file_metadata=file_metadata,handle=core.BNNewViewReference(data)))# type: ignoreifviewisNone:returnNoneview.parse_only=Trueview_handle=core.BNNewViewReference(view.handle)assertview_handleisnotNone,"core.BNNewViewReference returned None"returnctypes.cast(view_handle,ctypes.c_void_p).valueexcept:log_error_for_exception("Unhandled Python exception in BinaryView._parse")returnNone@classmethoddef_is_valid_for_data(cls,ctxt,data):try:# I'm not sure whats going on here even so I've suppressed the linter warningreturncls.is_valid_for_data(BinaryView(handle=core.BNNewViewReference(data)))# type: ignoreexcept:log_error_for_exception("Unhandled Python exception in BinaryView._is_valid_for_data")returnFalse@classmethoddef_is_deprecated(cls,ctxt):# Since the is_deprecated() method is newly added, existing code may not have it at all# So here we do not consider it as an errorifnotcallable(getattr(cls,'is_deprecated',None)):returnFalsetry:returncls.is_deprecated()# type: ignoreexcept:log_error_for_exception("Unhandled Python exception in BinaryView._is_deprecated")returnFalse@classmethoddef_is_force_loadable(cls,ctxt):ifnotcallable(getattr(cls,'is_force_loadable',None)):returnFalsetry:returncls.is_force_loadable()# type: ignoreexcept:log_error_for_exception("Unhandled Python exception in BinaryView._is_force_loadable")returnFalse@classmethoddef_get_load_settings_for_data(cls,ctxt,data):try:attr=getattr(cls,"get_load_settings_for_data",None)ifcallable(attr):result=cls.get_load_settings_for_data(BinaryView(handle=core.BNNewViewReference(data)))# type: ignoresettings_handle=core.BNNewSettingsReference(result.handle)assertsettings_handleisnotNone,"core.BNNewSettingsReference returned None"returnctypes.cast(settings_handle,ctypes.c_void_p).valueelse:returnNoneexcept:log_error_for_exception("Unhandled Python exception in BinaryView._get_load_settings_for_data")returnNone
[docs]@staticmethoddefopen(src,file_metadata=None)->Optional['BinaryView']:binaryninja._init_plugins()ifisinstance(src,fileaccessor.FileAccessor):iffile_metadataisNone:file_metadata=filemetadata.FileMetadata()view=core.BNCreateBinaryDataViewFromFile(file_metadata.handle,src._cb)else:iffile_metadataisNone:file_metadata=filemetadata.FileMetadata(str(src))view=core.BNCreateBinaryDataViewFromFilename(file_metadata.handle,str(src))ifviewisNone:returnNonereturnBinaryView(file_metadata=file_metadata,handle=view)
[docs]@staticmethoddefnew(data:Optional[Union[bytes,bytearray,'databuffer.DataBuffer']]=None,file_metadata:Optional['filemetadata.FileMetadata']=None)->Optional['BinaryView']:"""``new`` creates a new, Raw :py:class:`BinaryView` for the provided data.:param data: path to file/bndb, raw bytes, or raw view to load:type data: Union[:py:class:`str`, :py:class:`bytes`, :py:class:`bytearray`, :py:class:`~binaryninja.databuffer.DataBuffer`, :py:class:`os.PathLike`, :py:class:`BinaryView`]:param file_metadata: Optional FileMetadata object for this new view:type file_metadata: :py:class:`~binaryninja.filemetadata.FileMetadata`:return: returns a :py:class:`BinaryView` object for the given filename or ``None``:rtype: :py:class:`BinaryView` or ``None``:Example:>>> binaryninja.load('/bin/ls', options={'loader.imageBase': 0xfffffff0000, 'loader.macho.processFunctionStarts' : False})<BinaryView: '/bin/ls', start 0xfffffff0000, len 0xa290>>>>"""binaryninja._init_plugins()iffile_metadataisNone:file_metadata=filemetadata.FileMetadata()ifdataisNone:view=core.BNCreateBinaryDataView(file_metadata.handle)elifisinstance(data,databuffer.DataBuffer):view=core.BNCreateBinaryDataViewFromBuffer(file_metadata.handle,data.handle)else:buf=databuffer.DataBuffer(data)view=core.BNCreateBinaryDataViewFromBuffer(file_metadata.handle,buf.handle)ifviewisNone:returnNonereturnBinaryView(file_metadata=file_metadata,handle=view)
[docs]@staticmethoddefload(source:Union[str,bytes,bytearray,'databuffer.DataBuffer','os.PathLike','BinaryView','project.ProjectFile'],update_analysis:bool=True,progress_func:Optional[ProgressFuncType]=None,options:Mapping[str,Any]={})->Optional['BinaryView']:"""``load`` opens, generates default load options (which are overridable), and returns the first available \:py:class:`BinaryView`. If no :py:class:`BinaryViewType` is available, then a ``Mapped`` :py:class:`BinaryViewType` is used to load \the :py:class:`BinaryView` with the specified load options. The ``Mapped`` view type attempts to auto-detect the architecture of the \file during initialization. If no architecture is detected or specified in the load options, then the ``Mapped`` view type fails to \initialize and returns ``None``... note:: Although general container file support is not complete, support for Universal archives exists. It's possible to control the architecture preference \with the **'files.universal.architecturePreference'** setting. This setting is scoped to SettingsUserScope and can be modified as follows ::>>> Settings().set_string_list("files.universal.architecturePreference", ["arm64"])It's also possible to override the **'files.universal.architecturePreference'** user setting by specifying it directly with :py:func:`load`.This specific usage of this setting is experimental and may change in the future ::>>> bv = binaryninja.load('/bin/ls', options={'files.universal.architecturePreference': ['arm64']}).. warning:: The recommended code pattern for opening a BinaryView is to use the \:py:func:`~binaryninja.load` API as a context manager like ``with load('/bin/ls') as bv:`` \which will automatically clean up when done with the view. If using this API directly \you will need to call `bv.file.close()` before the BinaryView leaves scope to ensure the \reference is properly removed and prevents memory leaks.:param Union[str, bytes, bytearray, 'databuffer.DataBuffer', 'os.PathLike', 'BinaryView'] source: path to file/bndb, raw bytes, or raw view to load:param bool update_analysis: whether or not to run :py:func:`~BinaryView.update_analysis_and_wait` after opening a :py:class:`BinaryView`, defaults to ``True``:param callback progress_func: optional function to be called with the current progress and total count:param dict options: a dictionary in the form {setting identifier string : object value}:return: returns a :py:class:`BinaryView` object for the given filename or ``None``:rtype: :py:class:`BinaryView` or ``None``:Example:>>> binaryninja.load('/bin/ls', options={'loader.imageBase': 0xfffffff0000, 'loader.macho.processFunctionStarts' : False})<BinaryView: '/bin/ls', start 0xfffffff0000, len 0xa290>>>>"""binaryninja._init_plugins()ifprogress_funcisNone:progress_cfunc=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:True)else:progress_cfunc=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:progress_func(cur,total))ifisinstance(source,os.PathLike):source=str(source)ifisinstance(source,BinaryView):handle=core.BNLoadBinaryView(source.handle,update_analysis,json.dumps(options),progress_cfunc,None)elifisinstance(source,project.ProjectFile):handle=core.BNLoadProjectFile(source._handle,update_analysis,json.dumps(options),progress_cfunc,None)elifisinstance(source,str):handle=core.BNLoadFilename(source,update_analysis,json.dumps(options),progress_cfunc,None)elifisinstance(source,bytes)orisinstance(source,bytearray)orisinstance(source,databuffer.DataBuffer):raw_view=BinaryView.new(source)handle=core.BNLoadBinaryView(raw_view.handle,update_analysis,json.dumps(options),progress_cfunc,None)else:raiseNotImplementedErrorreturnBinaryView(handle=handle)ifhandleelseNone
@classmethoddef_unregister(cls,view:core.BNBinaryView)->None:handle=ctypes.cast(view,ctypes.c_void_p)ifhandle.valueincls._associated_data:delcls._associated_data[handle.value]
[docs]@staticmethoddefset_default_session_data(name:str,value:str)->None:"""``set_default_session_data`` saves a variable to the BinaryView. Session data is ephemeral not saved to a database. Consider using :py:func:`store_metadata` if permanence is needed.:param str name: name of the variable to be saved:param str value: value of the variable to be saved:Example:>>> BinaryView.set_default_session_data("variable_name", "value")>>> bv.session_data.variable_name'value'"""_BinaryViewAssociatedDataStore.set_default(name,value)
@propertydefpreload_limit(self)->int:returnself._preload_limit@preload_limit.setterdefpreload_limit(self,value:int)->None:self._preload_limit=value@propertydefbasic_blocks(self)->Generator['basicblock.BasicBlock',None,None]:"""A generator of all BasicBlock objects in the BinaryView"""forfuncinself:yield fromfunc.basic_blocks@propertydefllil_basic_blocks(self)->Generator['lowlevelil.LowLevelILBasicBlock',None,None]:"""A generator of all LowLevelILBasicBlock objects in the BinaryView"""forfuncinself:llil=func.low_level_ilifllilisnotNone:yield fromllil.basic_blocks@propertydefmlil_basic_blocks(self)->Generator['mediumlevelil.MediumLevelILBasicBlock',None,None]:"""A generator of all MediumLevelILBasicBlock objects in the BinaryView"""forfuncinself.mlil_functions():yield fromfunc.basic_blocks@propertydefhlil_basic_blocks(self)->Generator['highlevelil.HighLevelILBasicBlock',None,None]:"""A generator of all HighLevelILBasicBlock objects in the BinaryView"""forfuncinself.hlil_functions():yield fromfunc.basic_blocks@propertydefinstructions(self)->InstructionsType:"""A generator of instruction tokens and their start addresses"""forblockinself.basic_blocks:start=block.startforiinblock:yield(i[0],start)start+=i[1]@propertydefllil_instructions(self)->'lowlevelil.LLILInstructionsType':"""A generator of llil instructions"""forblockinself.llil_basic_blocks:yield fromblock@propertydefmlil_instructions(self)->Generator['mediumlevelil.MediumLevelILInstruction',None,None]:"""A generator of mlil instructions"""forblockinself.mlil_basic_blocks:yield fromblock@propertydefhlil_instructions(self)->'highlevelil.HLILInstructionsType':"""A generator of hlil instructions"""forblockinself.hlil_basic_blocks:yield fromblock@propertydefparent_view(self)->Optional['BinaryView']:"""View that contains the raw data used by this view (read-only)"""result=core.BNGetParentView(self.handle)ifresultisNone:returnNonereturnBinaryView(handle=result)@propertydefmodified(self)->bool:"""boolean modification state of the BinaryView (read/write)"""returnself._file.modified@modified.setterdefmodified(self,value:bool)->None:self._file.modified=value@propertydefanalysis_changed(self)->bool:"""boolean analysis state changed of the currently running analysis (read-only)"""returnself._file.analysis_changed@propertydefhas_database(self)->bool:"""boolean has a database been written to disk (read-only)"""returnself._file.has_database@propertydefview(self)->'str':returnself._file.view@view.setterdefview(self,value:str)->None:self._file.view=value@propertydefoffset(self)->int:returnself._file.offset@offset.setterdefoffset(self,value:int)->None:self._file.offset=value@propertydeffile(self)->'filemetadata.FileMetadata':""":py:class:`~binaryninja.filemetadata.FileMetadata` backing the BinaryView """returnself._file@propertydefimage_base(self)->int:"""Image base of the binary"""returncore.BNGetImageBase(self.handle)@propertydeforiginal_image_base(self)->int:"""Original image base of the binary"""returncore.BNGetOriginalImageBase(self.handle)@original_image_base.setterdeforiginal_image_base(self,image_base:int)->None:"""Set original image base of the binary. Only intended for binary view implementations"""returncore.BNSetOriginalImageBase(self.handle,image_base)@propertydeforiginal_base(self)->int:"""Original image base of the binary. Deprecated: 4.1.5902 Use `original_image_base` instead."""returncore.BNGetOriginalImageBase(self.handle)@original_base.setterdeforiginal_base(self,base:int)->None:"""Set original image base of the binary. Only intended for binary view implementations. Deprecated: 4.1.5902 Use `original_image_base` instead."""returncore.BNSetOriginalImageBase(self.handle,base)@propertydefstart(self)->int:"""Start offset of the binary (read-only)"""returncore.BNGetStartOffset(self.handle)@propertydefend(self)->int:"""End offset of the binary (read-only)"""returncore.BNGetEndOffset(self.handle)@propertydefentry_point(self)->int:"""Entry point of the binary (read-only)"""returncore.BNGetEntryPoint(self.handle)@propertydefarch(self)->Optional['architecture.Architecture']:"""The architecture associated with the current :py:class:`BinaryView` (read/write)"""arch=core.BNGetDefaultArchitecture(self.handle)ifarchisNone:returnNonereturnarchitecture.CoreArchitecture._from_cache(handle=arch)@arch.setterdefarch(self,value:'architecture.Architecture')->None:ifvalueisNone:core.BNSetDefaultArchitecture(self.handle,None)else:core.BNSetDefaultArchitecture(self.handle,value.handle)@propertydefplatform(self)->Optional['_platform.Platform']:"""The platform associated with the current BinaryView (read/write)"""ifself._platformisnotNone:returnself._platformplat=core.BNGetDefaultPlatform(self.handle)ifplatisNone:returnNoneself._platform=_platform.CorePlatform._from_cache(handle=plat)returnself._platform@platform.setterdefplatform(self,value:Optional['_platform.Platform'])->None:ifvalueisNone:core.BNSetDefaultPlatform(self.handle,None)else:core.BNSetDefaultPlatform(self.handle,value.handle)self._platform=None@propertydefendianness(self)->Endianness:"""Endianness of the binary (read-only)"""ifself._endiannessisNone:self._endianness=Endianness(core.BNGetDefaultEndianness(self.handle))returnself._endianness@propertydefrelocatable(self)->bool:"""Boolean - is the binary relocatable (read-only)"""returncore.BNIsRelocatable(self.handle)@propertydefaddress_size(self)->int:"""Address size of the binary (read-only)"""returncore.BNGetViewAddressSize(self.handle)@propertydefexecutable(self)->bool:"""Whether the binary is an executable (read-only)"""returncore.BNIsExecutableView(self.handle)@propertydeffunctions(self)->FunctionList:"""returns a FunctionList object (read-only)"""returnFunctionList(self)
[docs]defmlil_functions(self,preload_limit:Optional[int]=None,function_generator:Optional[Generator['_function.Function',None,None]]=None)->Generator['mediumlevelil.MediumLevelILFunction',None,None]:"""Generates a list of il functions. This method should be used instead of 'functions' property ifMLIL is needed and performance is a concern."""forfuncinAdvancedILFunctionList(self,self.preload_limitifpreload_limitisNoneelsepreload_limit,function_generator):mlil=func.mlilifmlilisnotNone:yieldmlil
[docs]defhlil_functions(self,preload_limit:Optional[int]=None,function_generator:Optional[Generator['_function.Function',None,None]]=None)->Generator['highlevelil.HighLevelILFunction',None,None]:"""Generates a list of il functions. This method should be used instead of 'functions' property ifHLIL is needed and performance is a concern."""forfuncinAdvancedILFunctionList(self,self.preload_limitifpreload_limitisNoneelsepreload_limit,function_generator):hlil=func.hlilifhlilisnotNone:yieldhlil
@propertydefhas_functions(self)->bool:"""Boolean whether the binary has functions (read-only)"""returncore.BNHasFunctions(self.handle)@propertydefhas_symbols(self)->bool:"""Boolean whether the binary has symbols (read-only)"""returncore.BNHasSymbols(self.handle)@propertydefhas_data_variables(self)->bool:"""Boolean whether the binary has data variables (read-only)"""returncore.BNHasDataVariables(self.handle)@propertydefentry_function(self)->Optional['_function.Function']:"""Entry function (read-only)"""func=core.BNGetAnalysisEntryPoint(self.handle)iffuncisNone:returnNonereturn_function.Function(self,func)@propertydefentry_functions(self)->FunctionList:"""A List of entry functions (read-only)This list contains vanilla entry function, and functions like init_array, fini_array, and TLS callbacks etc.User-added entry functions(via `add_entry_point`) are also included.We see `entry_functions` as good starting points for analysis, these functions normally don't have internal references.However, note that exported functions in a dll/so file are not included.Note the difference with `entry_function`:Example:>>> bv.entry_function<func: x86@0x4014c8>>>> bv.entry_functions[<func: x86@0x4014c8>, <func: x86@0x401618>]:return: a list of functions, containing the vanilla entry and other platform-specific entry functions:rtype: list(Function)"""count=ctypes.c_ulonglong(0)funcs=core.BNGetAllEntryFunctions(self.handle,count)assertfuncsisnotNone,"core.BNGetAllEntryFunctions returned None"result=[]try:foriinrange(0,count.value):result.append(_function.Function(self,core.BNNewFunctionReference(funcs[i])))returnresultfinally:core.BNFreeFunctionList(funcs,count.value)@propertydefsymbols(self)->SymbolMapping:"""Dict of symbols (read-only)Items in the dict are lists of all symbols matching that name.:Example:>>> bv.symbols['_main'][<FunctionSymbol: "_main" @ 0x1dd0>]>>> list(bv.symbols)['_start', '_main', '_printf', '_scanf', ...]>>> bv.symbols['foo']KeyError: "'foo': symbol not found":return: a dict-like generator of symbol names and values:rtype: Generator[str, None, None]"""returnSymbolMapping(self)
[docs]@staticmethoddefinternal_namespace()->'_types.NameSpace':"""Internal namespace for the current BinaryView"""ns=core.BNGetInternalNameSpace()try:return_types.NameSpace._from_core_struct(ns)finally:core.BNFreeNameSpace(ns)
[docs]@staticmethoddefexternal_namespace()->'_types.NameSpace':"""External namespace for the current BinaryView"""ns=core.BNGetExternalNameSpace()try:return_types.NameSpace._from_core_struct(ns)finally:core.BNFreeNameSpace(ns)
@propertydefnamespaces(self)->List['_types.NameSpace']:"""Returns a list of namespaces for the current BinaryView"""count=ctypes.c_ulonglong(0)nameSpaceList=core.BNGetNameSpaces(self.handle,count)assertnameSpaceListisnotNone,"core.BNGetNameSpaces returned None"result=[]try:foriinrange(count.value):result.append(_types.NameSpace._from_core_struct(nameSpaceList[i]))returnresultfinally:core.BNFreeNameSpaceList(nameSpaceList,count.value)@propertydefview_type(self)->str:"""View type (read-only)"""returncore.BNGetViewType(self.handle)@propertydefavailable_view_types(self)->List[BinaryViewType]:"""Available view types (read-only)"""count=ctypes.c_ulonglong(0)types=core.BNGetBinaryViewTypesForData(self.handle,count)result=[]iftypesisNone:returnresulttry:foriinrange(0,count.value):result.append(BinaryViewType(types[i]))returnresultfinally:core.BNFreeBinaryViewTypeList(types)@propertydefstrings(self)->List['StringReference']:"""List of strings (read-only)"""returnself.get_strings()@propertydefderived_strings(self)->List['DerivedString']:count=ctypes.c_ulonglong(0)strings=core.BNGetDerivedStrings(self.handle,count)assertstringsisnotNone,"core.BNGetDerivedStrings returned None"try:result=[]foriinrange(0,count.value):result.append(DerivedString._from_core_struct(strings[i],False))returnresultfinally:core.BNFreeDerivedStringList(strings,count.value)@propertydefsaved(self)->bool:"""boolean state of whether or not the file has been saved (read/write)"""returnself._file.saved@saved.setterdefsaved(self,value:bool)->None:self._file.saved=value@propertydefanalysis_info(self)->AnalysisInfo:"""Provides instantaneous analysis state information and a list of current functions under analysis (read-only).All times are given in units of milliseconds (ms). Per-function `analysis_time` is the aggregation of time spentperforming incremental updates and is reset on a full function update. Per-function `update_count` tracks thecurrent number of incremental updates and is reset on a full function update. Per-function `submit_count` tracks thecurrent number of full updates that have completed... note:: `submit_count` is currently not reset across analysis updates."""info_ref=core.BNGetAnalysisInfo(self.handle)assertinfo_refisnotNone,"core.BNGetAnalysisInfo returned None"info=info_ref[0]active_info_list:List[ActiveAnalysisInfo]=[]try:foriinrange(0,info.count):func=_function.Function(self,core.BNNewFunctionReference(info.activeInfo[i].func))active_info=ActiveAnalysisInfo(func,info.activeInfo[i].analysisTime,info.activeInfo[i].updateCount,info.activeInfo[i].submitCount)active_info_list.append(active_info)returnAnalysisInfo(info.state,info.analysisTime,active_info_list)finally:core.BNFreeAnalysisInfo(info_ref)@propertydefanalysis_progress(self)->AnalysisProgress:"""Status of current analysis (read-only)"""result=core.BNGetAnalysisProgress(self.handle)returnAnalysisProgress(AnalysisState(result.state),result.count,result.total)@propertydefanalysis_state(self)->AnalysisState:"""State of current analysis (read-only)"""returnAnalysisState(core.BNGetAnalysisState(self.handle))@propertydeflinear_disassembly(self)->Iterator['lineardisassembly.LinearDisassemblyLine']:"""Iterator for all lines in the linear disassembly of the view"""returnself.get_linear_disassembly(None)@propertydefdata_vars(self)->Mapping[int,'DataVariable']:"""List of data variables (read-only)"""count=ctypes.c_ulonglong(0)var_list=core.BNGetDataVariables(self.handle,count)assertvar_listisnotNone,"core.BNGetDataVariables returned None"result={}try:foriinrange(0,count.value):result[var_list[i].address]=DataVariable.from_core_struct(var_list[i],self)returnresultfinally:core.BNFreeDataVariables(var_list,count.value)@propertydeftypes(self)->TypeMapping:returnTypeMapping(self)@propertydefdependency_sorted_types(self)->TypeMapping:"""List of all types, sorted such that types are after all types on which they depend (read-only)Order is guaranteed for any collection of types with no cycles. If you have cycles \in type dependencies, order for types in a cycle is not guaranteed... note:: Dependency order is based on named type references for all non-structure types, i.e. \``struct Foo m_foo`` will induce a dependency, whereas ``struct Foo* m_pFoo`` will not.:return: sorted types as defined above"""returnTypeMapping(self,core.BNGetAnalysisDependencySortedTypeList)@propertydeftype_names(self)->List['_types.QualifiedName']:"""List of defined type names (read-only).. note:: Sort order is not guaranteed in 5.2 and later."""count=ctypes.c_ulonglong(0)name_list=core.BNGetAnalysisTypeNames(self.handle,count,"")assertname_listisnotNone,"core.BNGetAnalysisTypeNames returned None"result=[]try:foriinrange(0,count.value):result.append(_types.QualifiedName._from_core_struct(name_list[i]))returnresultfinally:core.BNFreeTypeNameList(name_list,count.value)@propertydeftype_libraries(self)->List['typelibrary.TypeLibrary']:"""List of imported type libraries (read-only)"""count=ctypes.c_ulonglong(0)libraries=core.BNGetBinaryViewTypeLibraries(self.handle,count)assertlibrariesisnotNone,"core.BNGetBinaryViewTypeLibraries returned None"result=[]try:foriinrange(0,count.value):result.append(typelibrary.TypeLibrary(core.BNNewTypeLibraryReference(libraries[i])))returnresultfinally:core.BNFreeTypeLibraryList(libraries,count.value)@propertydefattached_type_archives(self)->Mapping['str','str']:"""All attached type archive ids and paths (read-only)"""ids=ctypes.POINTER(ctypes.c_char_p)()paths=ctypes.POINTER(ctypes.c_char_p)()count=core.BNBinaryViewGetTypeArchives(self.handle,ids,paths)result={}try:foriinrange(0,count):result[core.pyNativeStr(ids[i])]=core.pyNativeStr(paths[i])returnresultfinally:core.BNFreeStringList(ids,count)core.BNFreeStringList(paths,count)@propertydefconnected_type_archives(self)->List['typearchive.TypeArchive']:"""All connected type archive objects (read-only)"""result=[]for(id,path)inself.attached_type_archives.items():archive=self.get_type_archive(id)ifarchiveisnotNone:result.append(archive)returnresult@propertydefsegments(self)->List['Segment']:"""List of resolved segments (read-only)"""count=ctypes.c_ulonglong(0)segment_list=core.BNGetSegments(self.handle,count)assertsegment_listisnotNone,"core.BNGetSegments returned None"result=[]try:foriinrange(0,count.value):segment_handle=core.BNNewSegmentReference(segment_list[i])assertsegment_handleisnotNone,"core.BNNewSegmentReference returned None"result.append(Segment(segment_handle))returnresultfinally:core.BNFreeSegmentList(segment_list,count.value)@propertydefsections(self)->Mapping[str,'Section']:"""Dictionary of sections (read-only)"""count=ctypes.c_ulonglong(0)section_list=core.BNGetSections(self.handle,count)assertsection_listisnotNone,"core.BNGetSections returned None"result={}try:foriinrange(0,count.value):section_handle=core.BNNewSectionReference(section_list[i])assertsection_handleisnotNone,"core.BNNewSectionReference returned None"result[core.BNSectionGetName(section_list[i])]=Section(section_handle)returnresultfinally:core.BNFreeSectionList(section_list,count.value)@propertydefallocated_ranges(self)->List['variable.AddressRange']:"""List of valid address ranges for this view (read-only) Deprecated: 4.1.5902 Use mapped_address_ranges instead."""count=ctypes.c_ulonglong(0)range_list=core.BNGetAllocatedRanges(self.handle,count)assertrange_listisnotNone,"core.BNGetAllocatedRanges returned None"result=[]try:foriinrange(0,count.value):result.append(variable.AddressRange(range_list[i].start,range_list[i].end))returnresultfinally:core.BNFreeAddressRanges(range_list)@propertydefmapped_address_ranges(self)->List['variable.AddressRange']:"""List of mapped address ranges for this view (read-only)"""count=ctypes.c_ulonglong(0)range_list=core.BNGetMappedAddressRanges(self.handle,count)assertrange_listisnotNone,"core.BNGetMappedAddressRanges returned None"result=[]try:foriinrange(0,count.value):result.append(variable.AddressRange(range_list[i].start,range_list[i].end))returnresultfinally:core.BNFreeAddressRanges(range_list)@propertydefbacked_address_ranges(self)->List['variable.AddressRange']:"""List of backed address ranges for this view (read-only)"""count=ctypes.c_ulonglong(0)range_list=core.BNGetBackedAddressRanges(self.handle,count)assertrange_listisnotNone,"core.BNGetBackedAddressRanges returned None"result=[]try:foriinrange(0,count.value):result.append(variable.AddressRange(range_list[i].start,range_list[i].end))returnresultfinally:core.BNFreeAddressRanges(range_list)@propertydefsession_data(self):# TODO add type hint"""Dictionary object where plugins can store arbitrary data associated with the view. This data is ephemeral and not saved to a database. Consider using :py:func:`store_metadata` if permanence is needed."""handle=ctypes.cast(self.handle,ctypes.c_void_p)ifhandle.valuenotinBinaryView._associated_data:obj=_BinaryViewAssociatedDataStore()BinaryView._associated_data[handle.value]=objreturnobjelse:returnBinaryView._associated_data[handle.value]@propertydefglobal_pointer_value(self)->'variable.RegisterValue':"""Discovered value of the global pointer register, if the binary uses one (read-only)"""result=core.BNGetGlobalPointerValue(self.handle)returnvariable.RegisterValue.from_BNRegisterValue(result,self.arch)@propertydefuser_global_pointer_value_set(self)->bool:"""Check whether a user global pointer value has been set"""returncore.BNUserGlobalPointerValueSet(self.handle)
[docs]defclear_user_global_pointer_value(self):"""Clear a previously set user global pointer value, so the auto-analysis can calculate a new value"""core.BNClearUserGlobalPointerValue(self.handle)
[docs]defset_user_global_pointer_value(self,value:variable.RegisterValue,confidence=255):"""Set a user global pointer value. This is useful when the auto analysis fails to find out the value of the globalpointer, or the value is wrong. In this case, we can call ``set_user_global_pointer_value`` with a``ConstantRegisterValue`` or ``ConstantPointerRegisterValue`` to provide a user global pointer value to assist theanalysis.On the other hand, if the auto analysis figures out a global pointer value, but there should not be one, we cancall ``set_user_global_pointer_value`` with an `Undetermined` value to override it.Whenever a user global pointer value is set/cleared, an analysis update must occur for it to take effect andall functions using the global pointer to be updated.We can use ``user_global_pointer_value_set`` to query whether a user global pointer value is set, and use``clear_user_global_pointer_value`` to clear a user global pointer value. Note, ``clear_user_global_pointer_value``is different from calling ``set_user_global_pointer_value`` with an ``Undetermined`` value. The former clears theuser global pointer value and let the analysis decide the global pointer value, whereas the latte forces theglobal pointer value to become undetermined.:param variable.RegisterValue value: the user global pointer value to be set:param int confidence: the confidence value of the user global pointer value. In most cases this should be \set to 255. Setting a value lower than the confidence of the global pointer value from the auto analysis \will cause undesired effect.:return: None:rtype: None:Example:>>> bv.global_pointer_value<const ptr 0x3fd4>>>> bv.set_user_global_pointer_value(ConstantPointerRegisterValue(0x12345678))>>> bv.global_pointer_value<const ptr 0x12345678>>>> bv.user_global_pointer_value_setTrue>>> bv.clear_user_global_pointer_value()>>> bv.global_pointer_value<const ptr 0x3fd4>>>> bv.set_user_global_pointer_value(Undetermined())>>> bv.global_pointer_value<undetermined>"""val=core.BNRegisterValueWithConfidence()val.value=value._to_core_struct()val.confidence=confidencecore.BNSetUserGlobalPointerValue(self.handle,val)
@propertydefparameters_for_analysis(self):returncore.BNGetParametersForAnalysis(self.handle)@parameters_for_analysis.setterdefparameters_for_analysis(self,params):core.BNSetParametersForAnalysis(self.handle,params)@propertydefmax_function_size_for_analysis(self)->int:"""Maximum size of function (sum of basic block sizes in bytes) for auto analysis"""returncore.BNGetMaxFunctionSizeForAnalysis(self.handle)@max_function_size_for_analysis.setterdefmax_function_size_for_analysis(self,size:int)->None:core.BNSetMaxFunctionSizeForAnalysis(self.handle,size)
[docs]defrelocations_at(self,addr:int)->List[Relocation]:"""List of relocations for a given address"""count=ctypes.c_ulonglong()relocs=core.BNGetRelocationsAt(self.handle,addr,count)assertrelocsisnotNone,"core.BNGetRelocationRanges returned None"result=[]try:foriinrange(0,count.value):reloc_handle=core.BNNewRelocationReference(relocs[i])assertreloc_handleisnotNone,"core.BNNewRelocationReference is not None"result.append(Relocation(reloc_handle))returnresultfinally:core.BNFreeRelocationList(relocs,count)
@propertydefrelocation_ranges(self)->List[Tuple[int,int]]:"""List of relocation range tuples (read-only)"""count=ctypes.c_ulonglong()ranges=core.BNGetRelocationRanges(self.handle,count)assertrangesisnotNone,"core.BNGetRelocationRanges returned None"try:return[(ranges[i].start,ranges[i].end)foriinrange(count.value)]finally:core.BNFreeRelocationRanges(ranges)
[docs]defrelocation_ranges_at(self,addr:int)->List[Tuple[int,int]]:"""List of relocation range tuples for a given address"""count=ctypes.c_ulonglong()ranges=core.BNGetRelocationRangesAtAddress(self.handle,addr,count)assertrangesisnotNone,"core.BNGetRelocationRangesAtAddress returned None"try:return[(ranges[i].start,ranges[i].end)foriinrange(count.value)]finally:core.BNFreeRelocationRanges(ranges)
[docs]defrelocation_ranges_in_range(self,addr:int,size:int)->List[Tuple[int,int]]:"""List of relocation range tuples for a given range"""count=ctypes.c_ulonglong()ranges=core.BNGetRelocationRangesInRange(self.handle,addr,size,count)assertrangesisnotNone,"core.BNGetRelocationRangesInRange returned None"try:return[(ranges[i].start,ranges[i].end)foriinrange(count.value)]finally:core.BNFreeRelocationRanges(ranges)
[docs]deffinalize_new_segments(self)->bool:"""Performs "finalization" on segments added after initial Finalization (performed after an Init() has completed).Finalizing a segment involves optimizing the relocation info stored in that segment, so if a segment is addedand relocations are defined for that segment by some automated process, this function should be called afterwards.An example of this can be seen in the KernelCache plugin, in `KernelCache::LoadImageWithInstallName`.After we load an image, map new segments, and define relocations for all of them, we call this functionto let core know it is now safe to finalize the new segments:return: Whether finalization was successful"""returncore.BNBinaryViewFinalizeNewSegments(self.handle)
[docs]defrange_contains_relocation(self,addr:int,size:int)->bool:"""Checks if the specified range overlaps with a relocation"""returncore.BNRangeContainsRelocation(self.handle,addr,size)
@propertydefnew_auto_function_analysis_suppressed(self)->bool:"""Whether or not automatically discovered functions will be analyzed"""returncore.BNGetNewAutoFunctionAnalysisSuppressed(self.handle)@new_auto_function_analysis_suppressed.setterdefnew_auto_function_analysis_suppressed(self,suppress:bool)->None:core.BNSetNewAutoFunctionAnalysisSuppressed(self.handle,suppress)@propertydefproject(self)->Optional['project.Project']:returnself.file.project@propertydefproject_file(self)->Optional['project.ProjectFile']:returnself.file.project_filedef_init(self,ctxt):try:returnself.init()except:log_error_for_exception("Unhandled Python exception in BinaryView._init")returnFalsedef_external_ref_taken(self,ctxt):try:self.__class__._registered_instances.append(self)except:log_error_for_exception("Unhandled Python exception in BinaryView._external_ref_taken")def_external_ref_released(self,ctxt):try:self.__class__._registered_instances.remove(self)except:log_error_for_exception("Unhandled Python exception in BinaryView._external_ref_released")def_read(self,ctxt,dest,offset,length):try:data=self.perform_read(offset,length)ifdataisNone:return0iflen(data)>length:data=data[0:length]ctypes.memmove(dest,data,len(data))returnlen(data)except:log_error_for_exception("Unhandled Python exception in BinaryView._read")return0def_write(self,ctxt,offset,src,length):try:data=ctypes.create_string_buffer(length)ctypes.memmove(data,src,length)returnself.perform_write(offset,data.raw)except:log_error_for_exception("Unhandled Python exception in BinaryView._write")return0def_insert(self,ctxt,offset,src,length):try:data=ctypes.create_string_buffer(length)ctypes.memmove(data,src,length)returnself.perform_insert(offset,data.raw)except:log_error_for_exception("Unhandled Python exception in BinaryView._insert")return0def_remove(self,ctxt,offset,length):try:returnself.perform_remove(offset,length)except:log_error_for_exception("Unhandled Python exception in BinaryView._remove")return0def_get_modification(self,ctxt,offset):try:returnself.perform_get_modification(offset)except:log_error_for_exception("Unhandled Python exception in BinaryView._get_modification")returnModificationStatus.Originaldef_is_valid_offset(self,ctxt,offset):try:returnself.perform_is_valid_offset(offset)except:log_error_for_exception("Unhandled Python exception in BinaryView._is_valid_offset")returnFalsedef_is_offset_readable(self,ctxt,offset):try:returnself.perform_is_offset_readable(offset)except:log_error_for_exception("Unhandled Python exception in BinaryView._is_offset_readable")returnFalsedef_is_offset_writable(self,ctxt,offset):try:returnself.perform_is_offset_writable(offset)except:log_error_for_exception("Unhandled Python exception in BinaryView._is_offset_writable")returnFalsedef_is_offset_executable(self,ctxt,offset):try:returnself.perform_is_offset_executable(offset)except:log_error_for_exception("Unhandled Python exception in BinaryView._is_offset_executable")returnFalsedef_get_next_valid_offset(self,ctxt,offset):try:returnself.perform_get_next_valid_offset(offset)except:log_error_for_exception("Unhandled Python exception in BinaryView._get_next_valid_offset")returnoffsetdef_get_start(self,ctxt):try:returnself.perform_get_start()except:log_error_for_exception("Unhandled Python exception in BinaryView._get_start")return0def_get_length(self,ctxt):try:returnself.perform_get_length()except:log_error_for_exception("Unhandled Python exception in BinaryView._get_length")return0def_get_entry_point(self,ctxt):try:returnself.perform_get_entry_point()except:log_error_for_exception("Unhandled Python exception in BinaryView._get_entry_point")return0def_is_executable(self,ctxt):try:returnself.perform_is_executable()except:log_error_for_exception("Unhandled Python exception in BinaryView._is_executable")returnFalsedef_get_default_endianness(self,ctxt):try:returnself.perform_get_default_endianness()except:log_error_for_exception("Unhandled Python exception in BinaryView._get_default_endianness")returnEndianness.LittleEndiandef_is_relocatable(self,ctxt):try:returnself.perform_is_relocatable()except:log_error_for_exception("Unhandled Python exception in BinaryView._is_relocatable")returnFalsedef_get_address_size(self,ctxt):try:returnself.perform_get_address_size()except:log_error_for_exception("Unhandled Python exception in BinaryView._get_address_size")return8def_save(self,ctxt,file_accessor):try:returnself.perform_save(fileaccessor.CoreFileAccessor(file_accessor))except:log_error_for_exception("Unhandled Python exception in BinaryView._save")returnFalse
[docs]definit(self)->bool:returnTrue
[docs]defdisassembly_tokens(self,addr:int,arch:Optional['architecture.Architecture']=None)->Generator[Tuple[List['_function.InstructionTextToken'],int],None,None]:ifarchisNone:ifself.archisNone:raiseException("Can not call method disassembly with no Architecture specified")arch=self.archsize=1whilesize!=0:tokens,size=arch.get_instruction_text(self.read(addr,arch.max_instr_length),addr)addr+=sizeifsize==0ortokensisNone:breakyield(tokens,size)
[docs]defdisassembly_text(self,addr:int,arch:Optional['architecture.Architecture']=None)->Generator[Tuple[str,int],None,None]:"""``disassembly_text`` helper function for getting disassembly of a given address:param int addr: virtual address of instruction:param Architecture arch: optional Architecture, ``self.arch`` is used if this parameter is None:return: a str representation of the instruction at virtual address ``addr`` or None:rtype: str or None:Example:>>> next(bv.disassembly_text(bv.entry_point))'push    ebp', 1>>>"""ifarchisNone:ifself.archisNone:raiseException("Can not call method disassembly with no Architecture specified")arch=self.archsize=1whilesize!=0:tokens,size=arch.get_instruction_text(self.read(addr,arch.max_instr_length),addr)addr+=sizeifsize==0ortokensisNone:breakyield(''.join(str(a)foraintokens).strip(),size)
[docs]defget_disassembly(self,addr:int,arch:Optional['architecture.Architecture']=None)->Optional[str]:"""``get_disassembly`` simple helper function for printing disassembly of a given address:param int addr: virtual address of instruction:param Architecture arch: optional Architecture, ``self.arch`` is used if this parameter is None:return: a str representation of the instruction at virtual address ``addr`` or None:rtype: str or None:Example:>>> bv.get_disassembly(bv.entry_point)'push    ebp'>>>.. note:: This API is very simplistic and only returns text. See :py:func:`disassembly_text` and \ `instructions` for more capable APIs."""ifarchisNone:ifself.archisNone:raiseException("Can not call method disassembly with no Architecture specified")arch=self.archtxt,_=arch.get_instruction_text(self.read(addr,arch.max_instr_length),addr)iftxtisNone:returnNonereturn''.join(str(a)foraintxt).strip()
[docs]defperform_save(self,accessor)->bool:ifself.parent_viewisnotNone:returnself.parent_view.save(accessor)returnFalse
[docs]@abc.abstractmethoddefperform_get_address_size(self)->int:raiseNotImplementedError
[docs]defperform_get_length(self)->int:"""``perform_get_length`` implements a query for the size of the virtual address range used bythe BinaryView... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:return: returns the size of the virtual address range used by the BinaryView:rtype: int"""return0
[docs]defperform_read(self,addr:int,length:int)->bytes:"""``perform_read`` implements a mapping between a virtual address and an absolute file offset, reading``length`` bytes from the rebased address ``addr``... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:param int addr: a virtual address to attempt to read from:param int length: the number of bytes to be read:return: length bytes read from addr, should return empty string on error:rtype: bytes"""returnb""
[docs]defperform_write(self,addr:int,data:bytes)->int:"""``perform_write`` implements a mapping between a virtual address and an absolute file offset, writingthe bytes ``data`` to rebased address ``addr``... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:param int addr: a virtual address:param bytes data: the data to be written:return: length of data written, should return 0 on error:rtype: int"""return0
[docs]defperform_insert(self,addr:int,data:bytes)->int:"""``perform_insert`` implements a mapping between a virtual address and an absolute file offset, insertingthe bytes ``data`` to rebased address ``addr``... note:: This method **may** be overridden by custom BinaryViews. If not overridden, inserting is disallowed.. warning:: This method **must not** be called directly.:param int addr: a virtual address:param bytes data: the data to be inserted:return: length of data inserted, should return 0 on error:rtype: int"""return0
[docs]defperform_remove(self,addr:int,length:int)->int:"""``perform_remove`` implements a mapping between a virtual address and an absolute file offset, removing``length`` bytes from the rebased address ``addr``... note:: This method **may** be overridden by custom BinaryViews. If not overridden, removing data is disallowed.. warning:: This method **must not** be called directly.:param int addr: a virtual address:param int length: the number of bytes to be removed:return: length of data removed, should return 0 on error:rtype: int"""return0
[docs]defperform_get_modification(self,addr:int)->ModificationStatus:"""``perform_get_modification`` implements query to the whether the virtual address ``addr`` is modified... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:param int addr: a virtual address to be checked:return: one of the following: Original = 0, Changed = 1, Inserted = 2:rtype: ModificationStatus"""returnModificationStatus.Original
[docs]defperform_is_valid_offset(self,addr:int)->bool:"""``perform_is_valid_offset`` implements a check if a virtual address ``addr`` is valid... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:param int addr: a virtual address to be checked:return: true if the virtual address is valid, false if the virtual address is invalid or error:rtype: bool"""data=self.read(addr,1)return(dataisnotNone)and(len(data)==1)
[docs]defperform_is_offset_readable(self,offset:int)->bool:"""``perform_is_offset_readable`` implements a check if a virtual address is readable... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:param int offset: a virtual address to be checked:return: true if the virtual address is readable, false if the virtual address is not readable or error:rtype: bool"""returnself.is_valid_offset(offset)
[docs]defperform_is_offset_writable(self,addr:int)->bool:"""``perform_is_offset_writable`` implements a check if a virtual address ``addr`` is writable... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:param int addr: a virtual address to be checked:return: true if the virtual address is writable, false if the virtual address is not writable or error:rtype: bool"""returnself.is_valid_offset(addr)
[docs]defperform_is_offset_executable(self,addr:int)->bool:"""``perform_is_offset_executable`` implements a check if a virtual address ``addr`` is executable... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:param int addr: a virtual address to be checked:return: true if the virtual address is executable, false if the virtual address is not executable or error:rtype: bool"""returnself.is_valid_offset(addr)
[docs]defperform_get_next_valid_offset(self,addr:int)->int:"""``perform_get_next_valid_offset`` implements a query for the next valid readable, writable, or executable virtualmemory address... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:param int addr: a virtual address to start checking from.:return: the next readable, writable, or executable virtual memory address:rtype: int"""ifaddr<self.perform_get_start():returnself.perform_get_start()returnaddr
[docs]defperform_get_start(self)->int:"""``perform_get_start`` implements a query for the first readable, writable, or executable virtual address inthe BinaryView... note:: This method **may** be overridden by custom BinaryViews. Use :py:func:`add_auto_segment` to provide \data without overriding this method... warning:: This method **must not** be called directly.:return: returns the first virtual address in the BinaryView:rtype: int"""return0
[docs]defperform_get_entry_point(self)->int:"""``perform_get_entry_point`` implements a query for the initial entry point for code execution... note:: This method **should** be implemented for custom BinaryViews that are executable... warning:: This method **must not** be called directly.:return: the virtual address of the entry point:rtype: int"""return0
[docs]defperform_is_executable(self)->bool:"""``perform_is_executable`` implements a check which returns true if the BinaryView is executable... note:: This method **must** be implemented for custom BinaryViews that are executable... warning:: This method **must not** be called directly.:return: true if the current BinaryView is executable, false if it is not executable or on error:rtype: bool"""returnFalse
[docs]defperform_get_default_endianness(self)->Endianness:"""``perform_get_default_endianness`` implements a check which returns the Endianness of the BinaryView.. note:: This method **may** be implemented for custom BinaryViews that are not LittleEndian... warning:: This method **must not** be called directly.:return: either :const:`Endianness.LittleEndian <binaryninja.enums.Endianness.LittleEndian>` or :const:`Endianness.BigEndian <binaryninja.enums.Endianness.BigEndian>`:rtype: Endianness"""returnEndianness.LittleEndian
[docs]defperform_is_relocatable(self)->bool:"""``perform_is_relocatable`` implements a check which returns true if the BinaryView is relocatable. Defaults to False.. note:: This method **may** be implemented for custom BinaryViews that are relocatable... warning:: This method **must not** be called directly.:return: True if the BinaryView is relocatable, False otherwise:rtype: boolean"""returnFalse
[docs]defcreate_database(self,filename:str,progress_func:Optional[ProgressFuncType]=None,settings:Optional['filemetadata.SaveSettings']=None)->bool:"""``create_database`` writes the current database (.bndb) out to the specified file... warning:: This API will only save a database, NOT the original file from a view. To save the original file, use :py:func:`save`. To update a database, use :py:func:`save_auto_snapshot`:param str filename: path and filename to write the bndb to, this string `should` have ".bndb" appended to it.:param callback progress_func: optional function to be called with the current progress and total count.:param SaveSettings settings: optional argument for special save options.:return: True on success, False on failure:rtype: bool.. warning:: The calling thread must not hold a lock on the BinaryView instance as this action is run on the main thread which requires the lock.:Example:>>> settings = SaveSettings()>>> bv.create_database(f"{bv.file.filename}.bndb", None, settings)True"""returnself._file.create_database(filename,progress_func,settings)
[docs]defsave_auto_snapshot(self,progress_func:Optional[ProgressFuncType]=None,settings:Optional['filemetadata.SaveSettings']=None)->bool:"""``save_auto_snapshot`` saves the current database to the already created file... note:: :py:func:`create_database` should have been called prior to executing this method:param callback progress_func: optional function to be called with the current progress and total count.:param SaveSettings settings: optional argument for special save options.:return: True if it successfully saved the snapshot, False otherwise:rtype: bool"""returnself._file.save_auto_snapshot(progress_func,settings)
[docs]defget_view_of_type(self,name:str)->Optional['BinaryView']:"""``get_view_of_type`` returns the BinaryView associated with the provided name if it exists.:param str name: Name of the view to be retrieved:return: BinaryView object associated with the provided name or None on failure:rtype: BinaryView or None"""returnself._file.get_view_of_type(name)
[docs]defundoable_transaction(self)->Generator:"""``undoable_transaction`` gives you a context in which you can make changes to analysis,and creates an Undo state containing those actions. If an exception is thrown, anychanges made to the analysis inside the transaction are reverted.:return: Transaction context manager, which will commit/revert actions depending on if an exception         is thrown when it goes out of scope.:rtype: Generator:Example:>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> # Actions inside the transaction will be committed to the undo state upon exit>>> with bv.undoable_transaction():>>>     bv.convert_to_nop(0x100012f1)True>>> bv.get_disassembly(0x100012f1)'nop'>>> bv.undo()>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> # A thrown exception inside the transaction will undo all changes made inside it>>> with bv.undoable_transaction():>>>     bv.convert_to_nop(0x100012f1)  # Reverted on thrown exception>>>     raise RuntimeError("oh no")RuntimeError: oh no>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'"""returnself._file.undoable_transaction()
[docs]defbegin_undo_actions(self,anonymous_allowed:bool=True)->str:"""``begin_undo_actions`` starts recording actions taken so they can be undone at some point.:param bool anonymous_allowed: Legacy interop: prevent empty calls to :py:func:`commit_undo_actions`` from                               affecting this undo state. Specifically for :py:func:`undoable_transaction``:return: Id of undo state, for passing to :py:func:`commit_undo_actions`` or :py:func:`revert_undo_actions`.:rtype: str:Example:>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> state = bv.begin_undo_actions()>>> bv.convert_to_nop(0x100012f1)True>>> bv.commit_undo_actions(state)>>> bv.get_disassembly(0x100012f1)'nop'>>> bv.undo()>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>>"""returnself._file.begin_undo_actions(anonymous_allowed)
[docs]defcommit_undo_actions(self,id:Optional[str]=None)->None:"""``commit_undo_actions`` commits the actions taken since a call to :py:func:`begin_undo_actions`Pass as `id` the value returned by :py:func:`begin_undo_actions`. Empty values of`id` will commit all changes since the last call to :py:func:`begin_undo_actions`.:param Optional[str] id: id of undo state, from :py:func:`begin_undo_actions`:rtype: None:Example:>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> state = bv.begin_undo_actions()>>> bv.convert_to_nop(0x100012f1)True>>> bv.commit_undo_actions(state)>>> bv.get_disassembly(0x100012f1)'nop'>>> bv.undo()>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>>"""self._file.commit_undo_actions(id)
[docs]defforget_undo_actions(self,id:Optional[str]=None)->None:"""``forget_undo_actions`` removes the actions taken since a call to :py:func:`begin_undo_actions`Pass as `id` the value returned by :py:func:`begin_undo_actions`. Empty values of`id` will remove all changes since the last call to :py:func:`begin_undo_actions`.:param Optional[str] id: id of undo state, from :py:func:`begin_undo_actions`:rtype: None:Example:>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> state = bv.begin_undo_actions()>>> bv.convert_to_nop(0x100012f1)True>>> bv.forget_undo_actions(state)>>> bv.get_disassembly(0x100012f1)'nop'>>> bv.undo()>>> bv.get_disassembly(0x100012f1)'nop'>>>"""self._file.forget_undo_actions(id)
[docs]defrevert_undo_actions(self,id:Optional[str]=None)->None:"""``revert_undo_actions`` reverts the actions taken since a call to :py:func:`begin_undo_actions`Pass as `id` the value returned by :py:func:`begin_undo_actions`. Empty values of`id` will revert all changes since the last call to :py:func:`begin_undo_actions`.:param Optional[str] id: id of undo state, from :py:func:`begin_undo_actions`:rtype: None:Example:>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> state = bv.begin_undo_actions()>>> bv.convert_to_nop(0x100012f1)True>>> bv.revert_undo_actions(state)>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>>"""self._file.revert_undo_actions(id)
[docs]defundo(self)->None:"""``undo`` undo the last committed transaction in the undo database.:rtype: None:Example:>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> with bv.undoable_transaction():>>>     bv.convert_to_nop(0x100012f1)True>>> bv.get_disassembly(0x100012f1)'nop'>>> bv.undo()>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> bv.redo()>>> bv.get_disassembly(0x100012f1)'nop'>>>"""self._file.undo()
[docs]defredo(self)->None:"""``redo`` redo the last committed transaction in the undo database.:rtype: None:Example:>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> with bv.undoable_transaction():>>>     bv.convert_to_nop(0x100012f1)True>>> bv.get_disassembly(0x100012f1)'nop'>>> bv.undo()>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> bv.redo()>>> bv.get_disassembly(0x100012f1)'nop'>>>"""self._file.redo()
[docs]defnavigate(self,view_name:str,offset:int)->bool:"""``navigate`` navigates the UI to the specified virtual address in the specified ViewThe View name is created by combining a View type (e.g. "Graph") with a BinaryView type (e.g. "Mach-O"),separated by a colon, resulting in something like "Graph:Mach-O".:param str view_name: view name:param int offset: address to navigate to:return: whether navigation succeeded:rtype: bool:Example:>>> bv.navigate(bv.view, bv.start)True>>> bv.file.existing_views['Mach-O', 'Raw']>>> import binaryninjaui>>> [i.getName() for i in binaryninjaui.ViewType.getTypes()]['Graph', 'Hex', 'Linear', 'Strings', 'Types', 'Triage', 'Bytes']>>> bv.navigate('Graph:Mach-O', bv.entry_point)True"""returnself._file.navigate(view_name,offset)
[docs]defread(self,addr:int,length:int)->bytes:r"""``read`` returns the data reads at most ``length`` bytes from virtual address ``addr``.:param int addr: virtual address to read from.:param int length: number of bytes to read.:return: at most ``length`` bytes from the virtual address ``addr``, empty string on error or no data:rtype: bytes:Example:>>> #Opening a x86_64 Mach-O binary>>> bv = BinaryView.new("/bin/ls") # note that we are using `new` instead of `load` to get the raw view>>> bv.read(0,4)b'\xcf\xfa\xed\xfe'"""if(addr<0)or(length<0):raiseValueError("length and address must both be positive")buf=databuffer.DataBuffer(handle=core.BNReadViewBuffer(self.handle,addr,length))returnbytes(buf)
[docs]defread_int(self,address:int,size:int,sign:bool=True,endian:Optional[Endianness]=None)->int:_endian=self.endiannessifendianisnotNone:_endian=endiandata=self.read(address,size)iflen(data)!=size:raiseValueError(f"Couldn't read{size} bytes from address:{address:#x}")returnTypedDataAccessor.int_from_bytes(data,size,sign,_endian)
[docs]defread_pointer(self,address:int,size:Optional[int]=None)->int:ifsizeisNone:ifself.archisNone:raiseValueError("Can't read pointer for BinaryView without an architecture")size=self.arch.address_sizereturnself.read_int(address,size,False,self.endianness)
[docs]defread_uuid(self,address:int,ms_format:bool=True)->uuid.UUID:"""Reads a UUID from the specified address in the binary view.:param address: The address to read the UUID from.:param ms_format: Whether to return the UUID in Microsoft format (True) or standard format (False).:return: A UUID object:raises ValueError: If 16 bytes couldn't be read from the specified address."""data=self.read(address,16)iflen(data)!=16:raiseValueError(f"Couldn't read 16 bytes from address:{address:#x}")ifms_format:reordered=data[3::-1]+data[5:3:-1]+data[7:5:-1]+data[8:]returnuuid.UUID(bytes=reordered)else:returnuuid.UUID(bytes=data)
[docs]defwrite(self,addr:int,data:bytes,except_on_relocation:bool=True)->int:"""``write`` writes the bytes in ``data`` to the virtual address ``addr``.:param int addr: virtual address to write to.:param bytes data: data to be written at addr.:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: number of bytes written to virtual address ``addr``:rtype: int:Example:>>> bv.read(0,4)b'BBBB'>>> bv.write(0, b"AAAA")4>>> bv.read(0,4)b'AAAA'"""ifnot(isinstance(data,bytes)orisinstance(data,bytearray)orisinstance(data,str)):raiseTypeError("Must be bytes, bytearray, or str")buf=databuffer.DataBuffer(data)ifexcept_on_relocationandself.range_contains_relocation(addr,len(data)):raiseRelocationWriteException("Attempting to write to a location which has a relocation")returncore.BNWriteViewBuffer(self.handle,addr,buf.handle)
[docs]definsert(self,addr:int,data:bytes)->int:"""``insert`` inserts the bytes in ``data`` to the virtual address ``addr``.:param int addr: virtual address to write to.:param bytes data: data to be inserted at addr.:return: number of bytes inserted to virtual address ``addr``:rtype: int:Example:>>> bv.insert(0,"BBBB")4>>> bv.read(0,8)'BBBBAAAA'"""ifnot(isinstance(data,bytes)orisinstance(data,bytearray)orisinstance(data,str)):raiseTypeError("Must be bytes, bytearray, or str")else:buf=databuffer.DataBuffer(data)returncore.BNInsertViewBuffer(self.handle,addr,buf.handle)
[docs]defremove(self,addr:int,length:int)->int:"""``remove`` removes at most ``length`` bytes from virtual address ``addr``.:param int addr: virtual address to remove from.:param int length: number of bytes to remove.:return: number of bytes removed from virtual address ``addr``:rtype: int:Example:>>> bv.read(0,8)'BBBBAAAA'>>> bv.remove(0,4)4>>> bv.read(0,4)'AAAA'"""returncore.BNRemoveViewData(self.handle,addr,length)
[docs]defget_entropy(self,addr:int,length:int,block_size:int=0)->List[float]:"""``get_entropy`` returns the shannon entropy given the start ``addr``, ``length`` in bytes, and optionally in``block_size`` chunks.:param int addr: virtual address:param int length: total length in bytes:param int block_size: optional block size:return: list of entropy values for each chunk:rtype: list(float)"""result=[]iflength==0:returnresultifblock_size==0:block_size=lengthdata=(ctypes.c_float*((length//block_size)+1))()length=core.BNGetEntropy(self.handle,addr,length,block_size,data)foriinrange(0,length):result.append(float(data[i]))returnresult
[docs]defget_modification(self,addr:int,length:Optional[int]=None)->List[ModificationStatus]:"""``get_modification`` returns the modified bytes of up to ``length`` bytes from virtual address ``addr``, or if``length`` is None returns the ModificationStatus.:param int addr: virtual address to get modification from:param int length: optional length of modification:return: List of ModificationStatus values for each byte in range:rtype: List[ModificationStatus]"""iflengthisNone:return[ModificationStatus(core.BNGetModification(self.handle,addr))]data=(ctypes.c_int*length)()length=core.BNGetModificationArray(self.handle,addr,data,length)return[ModificationStatus(a)foraindata[:length]]
[docs]defget_next_valid_offset(self,addr:int)->int:"""``get_next_valid_offset`` returns the next valid offset in the BinaryView starting from the given virtual address ``addr``.:param int addr: a virtual address to start checking from.:return: The minimum of the next valid offset in the BinaryView and the end address of the BinaryView:rtype: int"""returncore.BNGetNextValidOffset(self.handle,addr)
[docs]defis_valid_offset(self,addr:int)->bool:"""``is_valid_offset`` checks if a virtual address ``addr`` is valid .:param int addr: a virtual address to be checked:return: True if the virtual address is valid, False if the virtual address is invalid or error:rtype: bool"""returncore.BNIsValidOffset(self.handle,addr)
[docs]defis_offset_readable(self,addr:int)->bool:"""``is_offset_readable`` checks if a virtual address ``addr`` is valid for reading.:param int addr: a virtual address to be checked:return: True if the virtual address is valid for reading, False if the virtual address is invalid or error:rtype: bool"""returncore.BNIsOffsetReadable(self.handle,addr)
[docs]defis_offset_writable(self,addr:int)->bool:"""``is_offset_writable`` checks if a virtual address ``addr`` is valid for writing.:param int addr: a virtual address to be checked:return: True if the virtual address is valid for writing, False if the virtual address is invalid or error:rtype: bool"""returncore.BNIsOffsetWritable(self.handle,addr)
[docs]defis_offset_executable(self,addr:int)->bool:"""``is_offset_executable`` checks if a virtual address ``addr`` is valid for executing.:param int addr: a virtual address to be checked:return: True if the virtual address is valid for executing, False if the virtual address is invalid or error:rtype: bool"""returncore.BNIsOffsetExecutable(self.handle,addr)
[docs]defis_offset_code_semantics(self,addr:int)->bool:"""``is_offset_code_semantics`` checks if a virtual address ``addr`` is semantically valid for code.:param int addr: a virtual address to be checked:return: True if the virtual address is valid for code semantics, False if the virtual address is invalid or error:rtype: bool"""returncore.BNIsOffsetCodeSemantics(self.handle,addr)
[docs]defis_offset_extern_semantics(self,addr:int)->bool:"""``is_offset_extern_semantics`` checks if a virtual address ``addr`` is semantically valid for external references.:param int addr: a virtual address to be checked:return: true if the virtual address is valid for external references, false if the virtual address is invalid or error:rtype: bool"""returncore.BNIsOffsetExternSemantics(self.handle,addr)
[docs]defis_offset_writable_semantics(self,addr:int)->bool:"""``is_offset_writable_semantics`` checks if a virtual address ``addr`` is semantically writable. Some sectionsmay have writable permissions for linking purposes but can be treated as read-only for the purposes ofanalysis.:param int addr: a virtual address to be checked:return: True if the virtual address is valid for writing, False if the virtual address is invalid or error:rtype: bool"""returncore.BNIsOffsetWritableSemantics(self.handle,addr)
[docs]defsave(self,dest:Union['fileaccessor.FileAccessor',str])->bool:"""``save`` saves the original binary file to the provided destination ``dest`` along with any modifications... warning:: This API will only save the original file from a view. To save a database, use :py:func:`create_database`.:param str dest: destination path and filename of file to be written:return: True on success, False on failure:rtype: bool"""ifisinstance(dest,fileaccessor.FileAccessor):returncore.BNSaveToFile(self.handle,dest._cb)returncore.BNSaveToFilename(self.handle,str(dest))
[docs]defregister_notification(self,notify:BinaryDataNotification)->None:"""`register_notification` enables the receipt of callbacks for various analysis events. A fulllist of callbacks is available in the :py:class:`BinaryDataNotification` class. If the`notification_barrier` is enabled, then it is triggered upon the initial call to`register_notification`. Subsequent calls for an already registered ``notify`` instancealso trigger a `notification_barrier` callback.:param BinaryDataNotification notify: notify is a subclassed instance of :py:class:`BinaryDataNotification`.:rtype: None"""ifnotifyinself._notifications:self._notifications[notify]._register()returncb=BinaryDataNotificationCallbacks(self,notify)cb._register()self._notifications[notify]=cb
[docs]defunregister_notification(self,notify:BinaryDataNotification)->None:"""`unregister_notification` unregisters the :py:class:`BinaryDataNotification` object passed to`register_notification`:param BinaryDataNotification notify: notify is a subclassed instance of :py:class:`BinaryDataNotification`.:rtype: None"""ifnotifyinself._notifications:self._notifications[notify]._unregister()delself._notifications[notify]
[docs]defadd_function(self,addr:int,plat:Optional['_platform.Platform']=None,auto_discovered:bool=False,func_type:Optional['_function.Function']=None)->Optional['_function.Function']:"""``add_function`` add a new function of the given ``plat`` at the virtual address ``addr``.. warning:: This function is used to create auto functions, often used when writing loaders, etc. Most users will want to use :py:func:`create_user_function` in their scripts.:param int addr: virtual address of the function to be added:param Platform plat: Platform for the function to be added:param auto_discovered: True if function was automatically discovered, False if created by user:param func_type: optional function type:rtype: None:Example:>>> bv.add_function(1)>>> bv.functions[<func: x86_64@0x1>]"""ifself.platformisNoneandplatisNone:raiseException("Default platform not set in BinaryView")ifplatisNone:plat=self.platformifnotisinstance(plat,_platform.Platform):raiseValueError("Provided platform is not of type `Platform`")ifisinstance(func_type,_types.Type):func_type=func_type.handleeliffunc_typeisnotNone:raiseValueError("Provided type is not of type `binaryninja.Type`")result=core.BNAddFunctionForAnalysis(self.handle,plat.handle,addr,auto_discovered,func_type)ifresult:return_function.Function(self,result)returnNone
[docs]defadd_entry_point(self,addr:int,plat:Optional['_platform.Platform']=None)->None:"""``add_entry_point`` adds a virtual address to start analysis from for a given plat.:param int addr: virtual address to start analysis from:param Platform plat: Platform for the entry point analysis:rtype: None:Example:>>> bv.add_entry_point(0xdeadbeef)>>>"""ifself.platformisNoneandplatisNone:raiseException("Default platform not set in BinaryView")ifplatisNone:plat=self.platformifnotisinstance(plat,_platform.Platform):raiseValueError("Provided platform is not of type `Platform`")core.BNAddEntryPointForAnalysis(self.handle,plat.handle,addr)
[docs]defadd_to_entry_functions(self,func:'_function.Function')->None:"""``add_to_entry_functions`` adds a function to the `entry_functions` list.:param Function func: a Function object:rtype: None:Example:>>> bv.entry_functions[<func: x86@0x4014c8>, <func: x86@0x401618>]>>> bv.add_to_entry_functions(bv.get_function_at(0x4014da))>>> bv.entry_functions[<func: x86@0x4014c8>, <func: x86@0x401618>, <func: x86@0x4014da>]"""core.BNAddToEntryFunctions(self.handle,func.handle)
[docs]defremove_function(self,func:'_function.Function',update_refs=False)->None:"""``remove_function`` removes the function ``func`` from the list of functions.. warning:: This method should only be used when the function that is removed is expected to re-appear after any other analysis executes that could re-add it. Most users will want to use :py:func:`remove_user_function` in their scripts.:param Function func: a Function object.:param bool update_refs: automatically update other functions that were referenced:rtype: None:Example:>>> bv.functions[<func: x86_64@0x1>]>>> bv.remove_function(next(bv.functions))>>> bv.functions[]"""core.BNRemoveAnalysisFunction(self.handle,func.handle,update_refs)
[docs]defcreate_user_function(self,addr:int,plat:Optional['_platform.Platform']=None) \->Optional['_function.Function']:"""``create_user_function`` add a new *user* function of the given ``plat`` at the virtual address ``addr``:param int addr: virtual address of the *user* function to be added:param Platform plat: Platform for the function to be added:rtype: None:Example:>>> bv.create_user_function(1)>>> bv.functions[<func: x86_64@0x1>]"""ifplatisNone:ifself.platformisNone:raiseException("Attempting to call create_user_function with no specified platform")plat=self.platformfunc=core.BNCreateUserFunction(self.handle,plat.handle,addr)iffuncisNone:returnNonereturn_function.Function(self,func)
[docs]defremove_user_function(self,func:'_function.Function')->None:"""``remove_user_function`` removes the function ``func`` from the list of functions as a user action... note:: This API will prevent the function from being re-created if any analysis later triggers that would re-add it, unlike :py:func:`remove_function`.:param Function func: a Function object.:rtype: None:Example:>>> bv.functions[<func: x86_64@0x1>]>>> bv.remove_user_function(next(bv.functions))>>> bv.functions[]"""core.BNRemoveUserFunction(self.handle,func.handle)
[docs]defadd_analysis_option(self,name:str)->None:"""``add_analysis_option`` adds an analysis option. Analysis options elaborate the analysis phase. The user muststart analysis by calling either :py:func:`update_analysis` or :py:func:`update_analysis_and_wait`.:param str name: name of the analysis option. Available options are: "linearsweep", and "signaturematcher".:rtype: None:Example:>>> bv.add_analysis_option("linearsweep")>>> bv.update_analysis_and_wait()"""core.BNAddAnalysisOption(self.handle,name)
[docs]defhas_initial_analysis(self)->bool:"""``has_initial_analysis`` check for the presence of an initial analysis in this BinaryView.:return: True if the BinaryView has a valid initial analysis, False otherwise:rtype: bool"""returncore.BNHasInitialAnalysis(self.handle)
[docs]defset_analysis_hold(self,enable:bool)->None:"""``set_analysis_hold`` control the analysis hold for this BinaryView. Enabling analysis hold defers all futureanalysis updates, therefore causing :py:func:`update_analysis` or :py:func:`update_analysis_and_wait` to take no action.:rtype: None"""core.BNSetAnalysisHold(self.handle,enable)
[docs]defget_function_analysis_update_disabled(self)->bool:"""Returns True when functions are prevented from being marked as updates required, False otherwise.:return:"""returncore.BNGetFunctionAnalysisUpdateDisabled(self.handle)
[docs]defset_function_analysis_update_disabled(self,disabled:bool)->None:"""``set_function_analysis_update_disabled`` prevents any function from being marked as updates required, so thatthey would NOT be re-analyzed when the analysis is updated. The main difference between this API and``set_analysis_hold`` is that ``set_analysis_hold`` only temporarily holds the analysis, and the functionsare still arranged to be updated when the hold is turned off. However, with``set_function_analysis_update_disabled``, functions would not be put into the analysis queue at all.Use with caution -- in most cases, this is NOT what you want, and you should use ``set_analysis_hold`` instead.:param disabled::return:"""core.BNSetFunctionAnalysisUpdateDisabled(self.handle,disabled)
[docs]defupdate_analysis(self)->None:"""``update_analysis`` asynchronously starts the analysis process and returns immediately.**Usage**:Call ``update_analysis`` after making changes that could affect the analysis results, such as adding or modifyingfunctions. This ensures that the analysis is updated to reflect the latest changes. The analysis runs in the background,allowing other operations to continue.:rtype: None"""core.BNUpdateAnalysis(self.handle)
[docs]defupdate_analysis_and_wait(self)->None:"""``update_analysis_and_wait`` starts the analysis process and blocks until it is complete. This method should beused when it is necessary to ensure that analysis results are fully updated before proceeding with further operations.If an update is already in progress, this method chains a new update request to ensure that the update processesall pending changes before the call was made.**Usage**:Call ``update_analysis_and_wait`` after making changes that could affect the analysis results, such as adding or modifyingfunctions, to ensure that the analysis reflects the latest changes. Unlike ``update_analysis``, this method waits for theanalysis to finish before returning.**Thread Restrictions**:- **Worker Threads**: This function cannot be called from a worker thread. If called from a worker thread, an error will be  logged, and the function will return immediately.- **UI Threads**: This function cannot be called from a UI thread. If called from a UI thread, an error will be logged, and  the function will return immediately.:rtype: None"""core.BNUpdateAnalysisAndWait(self.handle)
[docs]defabort_analysis(self)->None:"""``abort_analysis`` aborts analysis and suspends the workflow machine. This operation is recoverable, and the workflow machinecan be re-enabled via the ``enable`` API on WorkflowMachine.:rtype: None"""core.BNAbortAnalysis(self.handle)
@propertydefanalysis_is_aborted(self)->bool:"""``analysis_is_aborted`` checks if the analysis has been aborted... note:: This property is intended for use by architecture plugins only.:return: True if the analysis has been aborted, False otherwise:rtype: bool"""returncore.BNAnalysisIsAborted(self.handle)
[docs]defshould_skip_target_analysis(self,source_location:'_function.ArchAndAddr',source_function:'_function.Function',end:int,target_location:'_function.ArchAndAddr')->bool:"""``should_skip_target_analysis`` checks if target analysis should be skipped... note:: This method is intended for use by architecture plugins only.:param _function.ArchAndAddr source_location: The source location.:param _function.Function source_function: The source function.:param int end: The end address of the source branch instruction.:param _function.ArchAndAddr target_location: The target location.:return: True if the target analysis should be skipped, False otherwise:rtype: bool"""bn_src_arch_and_addr=core.BNArchitectureAndAddress()bn_src_arch_and_addr.arch=source_location.arch.handlebn_src_arch_and_addr.address=source_location.addrbn_target_arch_and_addr=core.BNArchitectureAndAddress()bn_target_arch_and_addr.arch=target_location.arch.handlebn_target_arch_and_addr.address=target_location.addrreturncore.BNShouldSkipTargetAnalysis(self.handle,bn_src_arch_and_addr,source_function.handle,end,bn_target_arch_and_addr)
[docs]defdefine_data_var(self,addr:int,var_type:StringOrType,name:Optional[Union[str,'_types.CoreSymbol']]=None)->None:"""``define_data_var`` defines a non-user data variable ``var_type`` at the virtual address ``addr``.:param int addr: virtual address to define the given data variable:param StringOrType var_type: type to be defined at the given virtual address:param Optional[Union[str, '_types.CoreSymbol']] name: Optionally additionally define a symbol at this location:rtype: None:Example:>>> t = bv.parse_type_string("int foo")>>> t(<type: int32_t>, 'foo')>>> bv.define_data_var(bv.entry_point, t[0])>>> bv.define_data_var(bv.entry_point + 4, "int", "foo")>>> bv.get_symbol_at(bv.entry_point + 4)<DataSymbol: "foo" @ 0x23950>>>> bv.get_data_var_at(bv.entry_point + 4)<var 0x23950: int32_t>"""ifisinstance(var_type,str):(var_type,_)=self.parse_type_string(var_type)tc=var_type._to_core_struct()core.BNDefineDataVariable(self.handle,addr,tc)ifnameisnotNone:ifisinstance(name,str):name=_types.Symbol(SymbolType.DataSymbol,addr,name)self.define_auto_symbol(name)
[docs]defdefine_user_data_var(self,addr:int,var_type:StringOrType,name:Optional[Union[str,'_types.CoreSymbol']]=None)->Optional['DataVariable']:"""``define_user_data_var`` defines a user data variable ``var_type`` at the virtual address ``addr``.:param int addr: virtual address to define the given data variable:param binaryninja.Type var_type: type to be defined at the given virtual address:param Optional[Union[str, _types.CoreSymbol]] name: Optionally, additionally define a symbol at this same address:rtype: Optional[DataVariable]:Example:>>> t = bv.parse_type_string("int foo")>>> t(<type: int32_t>, 'foo')>>> bv.define_user_data_var(bv.entry_point, t[0])<var 0x2394c: int32_t>>>> bv.define_user_data_var(bv.entry_point + 4, "int", "foo")<var 0x23950: int32_t>>>> bv.get_symbol_at(bv.entry_point + 4)<DataSymbol: "foo" @ 0x23950>>>> bv.get_data_var_at(bv.entry_point + 4)<var 0x23950: int32_t>"""ifisinstance(var_type,str):(var_type,_)=self.parse_type_string(var_type)tc=var_type._to_core_struct()core.BNDefineUserDataVariable(self.handle,addr,tc)ifnameisnotNone:ifisinstance(name,str):name=_types.Symbol(SymbolType.DataSymbol,addr,name)self.define_user_symbol(name)returnself.get_data_var_at(addr)
[docs]defundefine_data_var(self,addr:int,blacklist:bool=True)->None:"""``undefine_data_var`` removes the non-user data variable at the virtual address ``addr``.:param int addr: virtual address to define the data variable to be removed:param bool blacklist: whether to add the address to the data variable black list so that the auto analysiswould not recreat the variable on re-analysis:rtype: None:Example:>>> bv.undefine_data_var(bv.entry_point)>>>"""core.BNUndefineDataVariable(self.handle,addr,blacklist)
[docs]defundefine_user_data_var(self,addr:int)->None:"""``undefine_user_data_var`` removes the user data variable at the virtual address ``addr``.:param int addr: virtual address to define the data variable to be removed:rtype: None:Example:>>> bv.undefine_user_data_var(bv.entry_point)>>>"""core.BNUndefineUserDataVariable(self.handle,addr)
[docs]defget_data_var_at(self,addr:int)->Optional['DataVariable']:"""``get_data_var_at`` returns the data type at a given virtual address.:param int addr: virtual address to get the data type from:return: returns the DataVariable at the given virtual address, None on error:rtype: DataVariable:Example:>>> t = bv.parse_type_string("int foo")>>> bv.define_data_var(bv.entry_point, t[0])>>> bv.get_data_var_at(bv.entry_point)<var 0x100001174: int32_t>"""var=core.BNDataVariable()ifnotcore.BNGetDataVariableAtAddress(self.handle,addr,var):returnNoneresult=DataVariable.from_core_struct(var,self)core.BNFreeDataVariable(var)returnresult
[docs]defget_functions_containing(self,addr:int,plat:Optional['_platform.Platform']=None)->List['_function.Function']:"""``get_functions_containing`` returns a list of :py:class:`~binaryninja.function.Function` objects which contain the given address.:param int addr: virtual address to query.:rtype: list of :py:class:`~binaryninja.function.Function` objects"""count=ctypes.c_ulonglong(0)funcs=core.BNGetAnalysisFunctionsContainingAddress(self.handle,addr,count)assertfuncsisnotNone,"core.BNGetAnalysisFunctionsContainingAddress returned None"result=[]try:foriinrange(0,count.value):result.append(_function.Function(self,core.BNNewFunctionReference(funcs[i])))ifplatisnotNone:result=[funcforfuncinresultiffunc.platform==plat]returnresultfinally:core.BNFreeFunctionList(funcs,count.value)
[docs]defget_functions_by_name(self,name:str,plat:Optional['_platform.Platform']=None,ordered_filter:Optional[List[SymbolType]]=None)->List['_function.Function']:"""``get_functions_by_name`` returns a list of :py:class:`~binaryninja.function.Function` objectsfunction with a :py:class:`~binaryninja.types.Symbol` of ``name``.:param str name: name of the functions:param Platform plat: (optional) platform:param list(SymbolType) ordered_filter: (optional) an ordered filter based on SymbolType:return: returns a list of :py:class:`~binaryninja.function.Function` objects or an empty list:rtype: list(Function):Example:>>> bv.get_functions_by_name("main")[<func: x86_64@0x1587>]>>>"""ifordered_filterisNone:ordered_filter=[SymbolType.FunctionSymbol,SymbolType.ImportedFunctionSymbol,SymbolType.LibraryFunctionSymbol]fns=[]addresses=list(dict.fromkeys(sym.addressforsyminself.get_symbols_by_name(name,ordered_filter=ordered_filter)))iflen(addresses)==0andname.startswith("sub_"):try:addresses=[int(name[4:],16)]except:addresses=[]foraddressinaddresses:forfninself.get_functions_at(address):iffn.start==address:ifplatisnotNoneandfn.platform!=plat:continuefns.append(fn)returnfns
[docs]defget_function_at(self,addr:int,plat:Optional['_platform.Platform']=None)->Optional['_function.Function']:"""``get_function_at`` gets a Function object for the function that starts at virtual address ``addr``::param int addr: starting virtual address of the desired function:param Platform plat: platform of the desired function:return: returns a Function object or None for the function at the virtual address provided:rtype: Function:Example:>>> bv.get_function_at(bv.entry_point)<func: x86_64@0x100001174>>>>"""ifplatisNone:funcs=self.get_functions_at(addr)ifnotfuncs:returnNoneresult=[funcforfuncinfuncsif(func.platform==self.platform)]ifnotresult:result=funcsreturnresult[0]else:func=core.BNGetAnalysisFunction(self.handle,plat.handle,addr)iffuncisNone:returnNonereturn_function.Function(self,func)
[docs]defget_functions_at(self,addr:int)->List['_function.Function']:"""``get_functions_at`` get a list of :py:class:`~binaryninja.function.Function` objects (one for each valid platform) that start at thegiven virtual address. Binary Ninja does not limit the number of platforms in a given file thus there may bemultiple functions defined from different architectures at the same location. This API allows you to query allof valid platforms.You may also be interested in :py:func:`get_functions_containing` which is useful for requesting all functionthat contain a given address:param int addr: virtual address of the desired Function object list.:return: a list of :py:class:`~binaryninja.function.Function` objects defined at the provided virtual address:rtype: list(Function)"""count=ctypes.c_ulonglong(0)funcs=core.BNGetAnalysisFunctionsForAddress(self.handle,addr,count)assertfuncsisnotNone,"core.BNGetAnalysisFunctionsForAddress returned None"result=[]try:foriinrange(0,count.value):result.append(_function.Function(self,core.BNNewFunctionReference(funcs[i])))returnresultfinally:core.BNFreeFunctionList(funcs,count.value)
[docs]defget_recent_function_at(self,addr:int)->Optional['_function.Function']:func=core.BNGetRecentAnalysisFunctionForAddress(self.handle,addr)iffuncisNone:returnNonereturn_function.Function(self,func)
[docs]defget_basic_blocks_at(self,addr:int)->List['basicblock.BasicBlock']:"""``get_basic_blocks_at`` get a list of :py:class:`~binaryninja.basicblock.BasicBlock` objects which exist at the provided virtual address.:param int addr: virtual address of BasicBlock desired:return: a list of :py:class:`~binaryninja.basicblock.BasicBlock` objects:rtype: list(BasicBlock)"""count=ctypes.c_ulonglong(0)blocks=core.BNGetBasicBlocksForAddress(self.handle,addr,count)assertblocksisnotNone,"core.BNGetBasicBlocksForAddress returned None"result=[]try:foriinrange(0,count.value):block_handle=core.BNNewBasicBlockReference(blocks[i])assertblock_handleisnotNone,"core.BNNewBasicBlockReference is None"result.append(basicblock.BasicBlock(block_handle,self))returnresultfinally:core.BNFreeBasicBlockList(blocks,count.value)
[docs]defget_basic_blocks_starting_at(self,addr:int)->List['basicblock.BasicBlock']:"""``get_basic_blocks_starting_at`` get a list of :py:class:`~binaryninja.basicblock.BasicBlock` objects which start at the provided virtual address.:param int addr: virtual address of BasicBlock desired:return: a list of :py:class:`~binaryninja.basicblock.BasicBlock` objects:rtype: list(BasicBlock)"""count=ctypes.c_ulonglong(0)blocks=core.BNGetBasicBlocksStartingAtAddress(self.handle,addr,count)assertblocksisnotNone,"core.BNGetBasicBlocksStartingAtAddress returned None"result=[]try:foriinrange(0,count.value):block_handle=core.BNNewBasicBlockReference(blocks[i])assertblock_handleisnotNone,"core.BNNewBasicBlockReference returned None"result.append(basicblock.BasicBlock(block_handle,self))returnresultfinally:core.BNFreeBasicBlockList(blocks,count.value)
[docs]defget_recent_basic_block_at(self,addr:int)->Optional['basicblock.BasicBlock']:block=core.BNGetRecentBasicBlockForAddress(self.handle,addr)ifblockisNone:returnNonereturnbasicblock.BasicBlock(block,self)
[docs]defget_code_refs(self,addr:int,length:Optional[int]=None,max_items:Optional[int]=None)->Generator['ReferenceSource',None,None]:"""``get_code_refs`` returns a generator of :py:class:`~binaryninja.binaryview.ReferenceSource` objects (xrefs or cross-references) that point to the provided virtual address.This function returns both autoanalysis ("auto") and user-specified ("user") xrefs.To add a user-specified reference, see :py:func:`~binaryninja.function.Function.add_user_code_ref`.The related :py:func:`get_data_refs` is used to find data references to an address unlike this API which returns references that exist in code... note:: Note that `get_code_refs` returns xrefs to code that references the address being queried. \`get_data_refs` on the other hand returns references that exist in data (pointers in global variables for example). \The related :py:func:`get_code_refs_from` looks for references that are outgoing from the queried address to other locations.:param int addr: virtual address to query for references:param int length: optional length of query:param int max_items: optional maximum number of references to fetch:return: A generator of References for the given virtual address:rtype: Generator[ReferenceSource, None, None]:Example:>>> bv.get_code_refs(here)[<ref: x86@0x4165ff>]>>>"""count=ctypes.c_ulonglong(0)has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0iflengthisNone:refs=core.BNGetCodeReferences(self.handle,addr,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetCodeReferences returned None"else:refs=core.BNGetCodeReferencesInRange(self.handle,addr,length,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetCodeReferencesInRange returned None"try:foriinrange(0,count.value):yieldReferenceSource._from_core_struct(self,refs[i])finally:core.BNFreeCodeReferences(refs,count.value)
[docs]defget_code_refs_from(self,addr:int,func:Optional['_function.Function']=None,arch:Optional['architecture.Architecture']=None,length:Optional[int]=None)->List[int]:"""``get_code_refs_from`` returns a list of virtual addresses referenced by code in the function ``func``,of the architecture ``arch``, and at the address ``addr``. If no function is specified, references fromall functions and containing the address will be returned. If no architecture is specified, thearchitecture of the function will be used.This function returns both autoanalysis ("auto") and user-specified ("user") xrefs.To add a user-specified reference, see :py:func:`~binaryninja.function.Function.add_user_code_ref`.:param int addr: virtual address to query for references:param int length: optional length of query:param Architecture arch: optional architecture of query:return: list of integers:rtype: list(integer)"""result=[]funcs=self.get_functions_containing(addr)iffuncisNoneelse[func]ifnotfuncs:return[]forsrc_funcinfuncs:src_arch=src_func.archifarchisNoneelsearchassertsrc_archisnotNoneref_src=core.BNReferenceSource(src_func.handle,src_arch.handle,addr)count=ctypes.c_ulonglong(0)iflengthisNone:refs=core.BNGetCodeReferencesFrom(self.handle,ref_src,count)assertrefsisnotNone,"core.BNGetCodeReferencesFrom returned None"else:refs=core.BNGetCodeReferencesFromInRange(self.handle,ref_src,length,count)assertrefsisnotNone,"core.BNGetCodeReferencesFromInRange returned None"foriinrange(0,count.value):result.append(refs[i])core.BNFreeAddressList(refs)returnresult
[docs]defget_data_refs(self,addr:int,length:Optional[int]=None,max_items:Optional[int]=None)->Generator[int,None,None]:"""``get_data_refs`` returns a list of virtual addresses of _data_ (not code) which references ``addr``, optionally specifyinga length. When ``length`` is set ``get_data_refs`` returns the data which references in the range ``addr``-``addr``+``length``.This function returns both autoanalysis ("auto") and user-specified ("user") xrefs. To add a user-specifiedreference, see :py:func:`add_user_data_ref`... warning:: If you're looking at this API, please double check that you don't mean to use :py:func:`get_code_refs` instead. \`get_code_refs` returns references from code to the specified address while this API returns references from data \(pointers in global variables for example). Also, note there exists :py:func:`get_data_refs_from`.:param int addr: virtual address to query for references:param int length: optional length of query:return: list of integers:rtype: list(integer):Example:>>> bv.get_data_refs(here)[4203812]>>>"""count=ctypes.c_ulonglong(0)has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0iflengthisNone:refs=core.BNGetDataReferences(self.handle,addr,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetDataReferences returned None"else:refs=core.BNGetDataReferencesInRange(self.handle,addr,length,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetDataReferencesInRange returned None"try:foriinrange(0,count.value):yieldrefs[i]finally:core.BNFreeDataReferences(refs)
[docs]defget_data_refs_from(self,addr:int,length:Optional[int]=None)->Generator[int,None,None]:"""``get_data_refs_from`` returns a list of virtual addresses referenced by the address ``addr``. Optionally specifyinga length. When ``length`` is set ``get_data_refs_from`` returns the data referenced in the range ``addr``-``addr``+``length``.This function returns both autoanalysis ("auto") and user-specified ("user") xrefs. To add a user-specifiedreference, see :py:func:`add_user_data_ref`. Also, note there exists :py:func:`get_data_refs`.:param int addr: virtual address to query for references:param int length: optional length of query:return: list of integers:rtype: list(integer):Example:>>> bv.get_data_refs_from(here)[4200327]>>>"""count=ctypes.c_ulonglong(0)iflengthisNone:refs=core.BNGetDataReferencesFrom(self.handle,addr,count)assertrefsisnotNone,"core.BNGetDataReferencesFrom returned None"else:refs=core.BNGetDataReferencesFromInRange(self.handle,addr,length,count)assertrefsisnotNone,"core.BNGetDataReferencesFromInRange returned None"try:foriinrange(0,count.value):yieldrefs[i]finally:core.BNFreeDataReferences(refs)
[docs]defget_code_refs_for_type(self,name:str,max_items:Optional[int]=None)->Generator[ReferenceSource,None,None]:"""``get_code_refs_for_type`` returns a Generator[ReferenceSource] objects (xrefs or cross-references) that reference the provided QualifiedName.:param QualifiedName name: name of type to query for references:param int max_items: optional maximum number of references to fetch:return: List of References for the given type:rtype: list(ReferenceSource):Example:>>> bv.get_code_refs_for_type('A')[<ref: x86@0x4165ff>]>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0refs=core.BNGetCodeReferencesForType(self.handle,_name,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetCodeReferencesForType returned None"try:foriinrange(0,count.value):yieldReferenceSource._from_core_struct(self,refs[i])finally:core.BNFreeCodeReferences(refs,count.value)
[docs]defget_code_refs_for_type_field(self,name:str,offset:int,max_items:Optional[int]=None)->Generator['_types.TypeFieldReference',None,None]:"""``get_code_refs_for_type`` returns a Generator[TypeFieldReference] objects (xrefs or cross-references) that reference the provided type field.:param QualifiedName name: name of type to query for references:param int offset: offset of the field, relative to the type:param int max_items: optional maximum number of references to fetch:return: Generator of References for the given type:rtype: Generator[TypeFieldReference]:Example:>>> bv.get_code_refs_for_type_field('A', 0x8)[<ref: x86@0x4165ff>]>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0refs=core.BNGetCodeReferencesForTypeField(self.handle,_name,offset,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetCodeReferencesForTypeField returned None"try:foriinrange(0,count.value):ifrefs[i].func:func=_function.Function(self,core.BNNewFunctionReference(refs[i].func))else:func=Noneifrefs[i].arch:arch=architecture.CoreArchitecture._from_cache(refs[i].arch)else:arch=Noneaddr=refs[i].addrsize=refs[i].sizetypeObj=Noneifrefs[i].incomingType.type:typeObj=_types.Type.create(core.BNNewTypeReference(refs[i].incomingType.type),confidence=refs[i].incomingType.confidence)yield_types.TypeFieldReference(func,arch,addr,size,typeObj)finally:core.BNFreeTypeFieldReferences(refs,count.value)
[docs]defget_data_refs_for_type(self,name:str,max_items:Optional[int]=None)->Generator[int,None,None]:"""``get_data_refs_for_type`` returns a list of virtual addresses of data which references the type ``name``.Note, the returned addresses are the actual start of the queried type. For example, suppose there is a DataVariableat 0x1000 that has type A, and type A contains type B at offset 0x10. Then `get_data_refs_for_type('B')` willreturn 0x1010 for it.:param QualifiedName name: name of type to query for references:param int max_items: optional maximum number of references to fetch:return: list of integers:rtype: list(integer):Example:>>> bv.get_data_refs_for_type('A')[4203812]>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0refs=core.BNGetDataReferencesForType(self.handle,_name,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetDataReferencesForType returned None"try:foriinrange(0,count.value):yieldrefs[i]finally:core.BNFreeDataReferences(refs)
[docs]defget_data_refs_for_type_field(self,name:'_types.QualifiedNameType',offset:int,max_items:Optional[int]=None)->List[int]:"""``get_data_refs_for_type_field`` returns a list of virtual addresses of data which references the type ``name``.Note, the returned addresses are the actual start of the queried type field. For example, suppose there is aDataVariable at 0x1000 that has type A, and type A contains type B at offset 0x10.Then `get_data_refs_for_type_field('B', 0x8)` will return 0x1018 for it.:param QualifiedName name: name of type to query for references:param int offset: offset of the field, relative to the type:param int max_items: optional maximum number of references to fetch:return: list of integers:rtype: list(integer):Example:>>> bv.get_data_refs_for_type_field('A', 0x8)[4203812]>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0refs=core.BNGetDataReferencesForTypeField(self.handle,_name,offset,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetDataReferencesForTypeField returned None"result=[]try:foriinrange(0,count.value):result.append(refs[i])returnresultfinally:core.BNFreeDataReferences(refs)
[docs]defget_data_refs_from_for_type_field(self,name:'_types.QualifiedNameType',offset:int,max_items:Optional[int]=None)->List[int]:"""``get_data_refs_from_for_type_field`` returns a list of virtual addresses of data which are referenced by the type ``name``.Only data referenced by structures with the ``__data_var_refs`` attribute are included.:param QualifiedName name: name of type to query for references:param int offset: offset of the field, relative to the type:param int max_items: optional maximum number of references to fetch:return: list of integers:rtype: list(integer):Example:>>> bv.get_data_refs_from_for_type_field('A', 0x8)[4203812]>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0refs=core.BNGetDataReferencesFromForTypeField(self.handle,_name,offset,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetDataReferencesFromForTypeField returned None"result=[]try:foriinrange(0,count.value):result.append(refs[i])returnresultfinally:core.BNFreeDataReferences(refs)
[docs]defget_type_refs_for_type(self,name:'_types.QualifiedNameType',max_items:Optional[int]=None)->List['_types.TypeReferenceSource']:"""``get_type_refs_for_type`` returns a list of TypeReferenceSource objects (xrefs or cross-references) that reference the provided QualifiedName.:param QualifiedName name: name of type to query for references:param int max_items: optional maximum number of references to fetch:return: List of references for the given type:rtype: list(TypeReferenceSource):Example:>>> bv.get_type_refs_for_type('A')['<type D, offset 0x8, direct>', '<type C, offset 0x10, indirect>']>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0refs=core.BNGetTypeReferencesForType(self.handle,_name,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetTypeReferencesForType returned None"result=[]try:foriinrange(0,count.value):type_field=_types.TypeReferenceSource(_types.QualifiedName._from_core_struct(refs[i].name),refs[i].offset,refs[i].type)result.append(type_field)returnresultfinally:core.BNFreeTypeReferences(refs,count.value)
[docs]defget_type_refs_for_type_field(self,name:'_types.QualifiedNameType',offset:int,max_items:Optional[int]=None)->List['_types.TypeReferenceSource']:"""``get_type_refs_for_type`` returns a list of TypeReferenceSource objects (xrefs or cross-references) that reference the provided type field.:param QualifiedName name: name of type to query for references:param int offset: offset of the field, relative to the type:param int max_items: optional maximum number of references to fetch:return: List of references for the given type:rtype: list(TypeReferenceSource):Example:>>> bv.get_type_refs_for_type_field('A', 0x8)['<type D, offset 0x8, direct>', '<type C, offset 0x10, indirect>']>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0refs=core.BNGetTypeReferencesForTypeField(self.handle,_name,offset,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetTypeReferencesForTypeField returned None"result=[]try:foriinrange(0,count.value):type_field=_types.TypeReferenceSource(_types.QualifiedName._from_core_struct(refs[i].name),refs[i].offset,refs[i].type)result.append(type_field)returnresultfinally:core.BNFreeTypeReferences(refs,count.value)
[docs]defget_code_refs_for_type_from(self,addr:int,func:Optional['_function.Function']=None,arch:Optional['architecture.Architecture']=None,length:Optional[int]=None)->List['_types.TypeReferenceSource']:"""``get_code_refs_for_type_from`` returns a list of types referenced by code in the function ``func``,of the architecture ``arch``, and at the address ``addr``. If no function is specified, references fromall functions and containing the address will be returned. If no architecture is specified, thearchitecture of the function will be used.:param int addr: virtual address to query for references:param int length: optional length of query:return: list of references:rtype: list(TypeReferenceSource)"""result=[]funcs=self.get_functions_containing(addr)iffuncisNoneelse[func]ifnotfuncs:return[]forsrc_funcinfuncs:src_arch=src_func.archifarchisNoneelsearchassertsrc_archisnotNoneref_src=core.BNReferenceSource(src_func.handle,src_arch.handle,addr)count=ctypes.c_ulonglong(0)iflengthisNone:refs=core.BNGetCodeReferencesForTypeFrom(self.handle,ref_src,count)assertrefsisnotNone,"core.BNGetCodeReferencesForTypeFrom returned None"else:refs=core.BNGetCodeReferencesForTypeFromInRange(self.handle,ref_src,length,count)assertrefsisnotNone,"core.BNGetCodeReferencesForTypeFromInRange returned None"try:foriinrange(0,count.value):type_field=_types.TypeReferenceSource(_types.QualifiedName._from_core_struct(refs[i].name),refs[i].offset,refs[i].type)result.append(type_field)finally:core.BNFreeTypeReferences(refs,count.value)returnresult
[docs]defget_code_refs_for_type_fields_from(self,addr:int,func:Optional['_function.Function']=None,arch:Optional['architecture.Architecture']=None,length:Optional[int]=None)->List['_types.TypeReferenceSource']:"""``get_code_refs_for_type_fields_from`` returns a list of type fields referenced by code in the function ``func``,of the architecture ``arch``, and at the address ``addr``. If no function is specified, references fromall functions and containing the address will be returned. If no architecture is specified, thearchitecture of the function will be used.:param int addr: virtual address to query for references:param int length: optional length of query:return: list of references:rtype: list(TypeReferenceSource)"""result=[]funcs=self.get_functions_containing(addr)iffuncisNoneelse[func]ifnotfuncs:return[]forsrc_funcinfuncs:src_arch=src_func.archifarchisNoneelsearchassertsrc_archisnotNoneref_src=core.BNReferenceSource(src_func.handle,src_arch.handle,addr)count=ctypes.c_ulonglong(0)iflengthisNone:refs=core.BNGetCodeReferencesForTypeFieldsFrom(self.handle,ref_src,count)assertrefsisnotNone,"core.BNGetCodeReferencesForTypeFieldsFrom returned None"else:refs=core.BNGetCodeReferencesForTypeFieldsFromInRange(self.handle,ref_src,length,count)assertrefsisnotNone,"core.BNGetCodeReferencesForTypeFieldsFromInRange returned None"try:foriinrange(0,count.value):type_field=_types.TypeReferenceSource(_types.QualifiedName._from_core_struct(refs[i].name),refs[i].offset,refs[i].type)result.append(type_field)finally:core.BNFreeTypeReferences(refs,count.value)returnresult
[docs]defget_derived_string_code_refs(self,str:'DerivedString',max_items:Optional[int]=None)->Generator['ReferenceSource',None,None]:count=ctypes.c_ulonglong(0)has_max_items=max_itemsisnotNonemax_items_value=max_itemsifhas_max_itemselse0core_str=str._to_core_struct(False)refs=core.BNGetDerivedStringCodeReferences(self.handle,core_str,count,has_max_items,max_items_value)assertrefsisnotNone,"core.BNGetDerivedStringCodeReferences returned None"try:foriinrange(0,count.value):yieldReferenceSource._from_core_struct(self,refs[i])finally:core.BNFreeCodeReferences(refs,count.value)
[docs]defadd_data_ref(self,from_addr:int,to_addr:int)->None:"""``add_data_ref`` adds an auto data cross-reference (xref) from the address ``from_addr`` to the address ``to_addr``.:param int from_addr: the reference's source virtual address.:param int to_addr: the reference's destination virtual address.:rtype: None.. note:: It is intended to be used from within workflows or binary view initialization."""core.BNAddUserDataReference(self.handle,from_addr,to_addr)
[docs]defremove_data_ref(self,from_addr:int,to_addr:int)->None:"""``remove_data_ref`` removes an  auto data cross-reference (xref) from the address ``from_addr`` to the address ``to_addr``.This function will only remove ones generated during autoanalysis.If the reference does not exist, no action is performed.:param int from_addr: the reference's source virtual address.:param int to_addr: the reference's destination virtual address.:rtype: None.. note:: It is intended to be used from within workflows or other reoccurring analysis tasks. Removed \  references will be re-created whenever auto analysis is re-run for the"""core.BNRemoveDataReference(self.handle,from_addr,to_addr)
[docs]defadd_user_data_ref(self,from_addr:int,to_addr:int)->None:"""``add_user_data_ref`` adds a user-specified data cross-reference (xref) from the address ``from_addr`` to the address ``to_addr``.If the reference already exists, no action is performed. To remove the reference, use :py:func:`remove_user_data_ref`.:param int from_addr: the reference's source virtual address.:param int to_addr: the reference's destination virtual address.:rtype: None"""core.BNAddUserDataReference(self.handle,from_addr,to_addr)
[docs]defremove_user_data_ref(self,from_addr:int,to_addr:int)->None:"""``remove_user_data_ref`` removes a user-specified data cross-reference (xref) from the address ``from_addr`` to the address ``to_addr``.This function will only remove user-specified references, not ones generated during autoanalysis.If the reference does not exist, no action is performed.:param int from_addr: the reference's source virtual address.:param int to_addr: the reference's destination virtual address.:rtype: None"""core.BNRemoveUserDataReference(self.handle,from_addr,to_addr)
[docs]defget_all_fields_referenced(self,name:'_types.QualifiedNameType')->List[int]:"""``get_all_fields_referenced`` returns a list of offsets in the QualifiedNamespecified by name, which are referenced by code.:param QualifiedName name: name of type to query for references:return: List of offsets:rtype: list(integer):Example:>>> bv.get_all_fields_referenced('A')[0, 8, 16, 24, 32, 40]>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()refs=core.BNGetAllFieldsReferenced(self.handle,_name,count)assertrefsisnotNone,"core.BNGetAllFieldsReferenced returned None"result=[]try:foriinrange(0,count.value):result.append(refs[i])returnresultfinally:core.BNFreeDataReferences(refs)
[docs]defget_all_sizes_referenced(self,name:'_types.QualifiedNameType')->Mapping[int,List[int]]:"""``get_all_sizes_referenced`` returns a map from field offset to a list of sizes ofthe accesses to it.:param QualifiedName name: name of type to query for references:return: A map from field offset to thesize of the code accesses to it:rtype: map:Example:>>> bv.get_all_sizes_referenced('B'){0: [1, 8], 8: [8], 16: [1, 8]}>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()refs=core.BNGetAllSizesReferenced(self.handle,_name,count)assertrefsisnotNone,"core.BNGetAllSizesReferenced returned None"result:Mapping[int,List[int]]={}try:foriinrange(0,count.value):result[refs[i].offset]=[]forjinrange(0,refs[i].count):result[refs[i].offset].append(refs[i].sizes[j])returnresultfinally:core.BNFreeTypeFieldReferenceSizeInfo(refs,count.value)
[docs]defget_all_types_referenced(self,name:'_types.QualifiedNameType')->Mapping[int,List['_types.Type']]:"""``get_all_types_referenced`` returns a map from field offset to a list of incoming types written to the specified type.:param QualifiedName name: name of type to query for references:return: A map from field offset to a list of incoming types written to it:rtype: map:Example:>>> bv.get_all_types_referenced('B'){0: [<type: char, 0% confidence>], 8: [<type: int64_t, 0% confidence>],16: [<type: char, 0% confidence>, <type: bool>]}>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()refs=core.BNGetAllTypesReferenced(self.handle,_name,count)assertrefsisnotNone,"core.BNGetAllTypesReferenced returned None"result:Mapping[int,List['_types.Type']]={}try:foriinrange(0,count.value):result[refs[i].offset]=[]forjinrange(0,refs[i].count):typeObj=_types.Type.create(core.BNNewTypeReference(refs[i].types[j].type),self.platform,refs[i].types[j].confidence)result[refs[i].offset].append(typeObj)returnresultfinally:core.BNFreeTypeFieldReferenceTypeInfo(refs,count.value)
[docs]defget_sizes_referenced(self,name:'_types.QualifiedNameType',offset:int)->List[int]:"""``get_sizes_referenced`` returns a list of access sizes to the specified type.:param QualifiedName name: name of type to query for references:param int offset: offset of the field:return: a list of sizes of the accesses to it.:rtype: list:Example:>>> bv.get_sizes_referenced('B', 16)[1, 8]>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()refs=core.BNGetSizesReferenced(self.handle,_name,offset,count)assertrefsisnotNone,"core.BNGetSizesReferenced returned None"result=[]try:foriinrange(0,count.value):result.append(refs[i])returnresultfinally:core.BNFreeTypeFieldReferenceSizes(refs,count.value)
[docs]defget_types_referenced(self,name:'_types.QualifiedName',offset:int)->List['_types.Type']:"""``get_types_referenced`` returns a list of types related to the type field access.:param QualifiedName name: name of type to query for references:param int offset: offset of the field:return: a list of types related to the type field access.:rtype: list:Example:>>> bv.get_types_referenced('B', 0x10)[<type: bool>, <type: char, 0% confidence>]>>>"""count=ctypes.c_ulonglong(0)_name=_types.QualifiedName(name)._to_core_struct()refs=core.BNGetTypesReferenced(self.handle,_name,offset,count)assertrefsisnotNone,"core.BNGetTypesReferenced returned None"try:result=[]foriinrange(0,count.value):typeObj=_types.Type.create(core.BNNewTypeReference(refs[i].type),confidence=refs[i].confidence)result.append(typeObj)returnresultfinally:core.BNFreeTypeFieldReferenceTypes(refs,count.value)
[docs]defget_outgoing_direct_type_references(self,name:'_types.QualifiedNameType')->List['_types.QualifiedName']:qname=_types.QualifiedName(name)_qname=qname._to_core_struct()count=ctypes.c_ulonglong(0)_result=core.BNGetOutgoingDirectTypeReferences(self.handle,_qname,count)assert_resultisnotNone,"core.BNGetOutgoingDirectTypeReferences returned None"try:result=[]foriinrange(0,count.value):result_name=_types.QualifiedName._from_core_struct(_result[i])result.append(result_name)returnresultfinally:core.BNFreeTypeNameList(_result,count.value)
[docs]defget_outgoing_recursive_type_references(self,names:Union['_types.QualifiedNameType',List['_types.QualifiedNameType']])->List['_types.QualifiedName']:qnames=[]ifisinstance(names,list):fornameinnames:qnames.append(_types.QualifiedName(name))else:qnames.append(_types.QualifiedName(names))_qnames=(core.BNQualifiedName*len(qnames))()fori,qnameinenumerate(qnames):_qnames[i]=qname._to_core_struct()count=ctypes.c_ulonglong(0)_result=core.BNGetOutgoingRecursiveTypeReferences(self.handle,_qnames,len(qnames),count)assert_resultisnotNone,"core.BNGetOutgoingRecursiveTypeReferences returned None"try:result=[]foriinrange(0,count.value):result_name=_types.QualifiedName._from_core_struct(_result[i])result.append(result_name)returnresultfinally:core.BNFreeTypeNameList(_result,count.value)
[docs]defget_incoming_direct_type_references(self,name:'_types.QualifiedNameType')->List['_types.QualifiedName']:qname=_types.QualifiedName(name)_qname=qname._to_core_struct()count=ctypes.c_ulonglong(0)_result=core.BNGetIncomingDirectTypeReferences(self.handle,_qname,count)assert_resultisnotNone,"core.BNGetIncomingDirectTypeReferences returned None"try:result=[]foriinrange(0,count.value):result_name=_types.QualifiedName._from_core_struct(_result[i])result.append(result_name)returnresultfinally:core.BNFreeTypeNameList(_result,count.value)
[docs]defget_incoming_recursive_type_references(self,names:Union['_types.QualifiedNameType',List['_types.QualifiedNameType']])->List['_types.QualifiedName']:qnames=[]ifisinstance(names,list):fornameinnames:qnames.append(_types.QualifiedName(name))else:qnames.append(_types.QualifiedName(names))_qnames=(core.BNQualifiedName*len(qnames))()fori,qnameinenumerate(qnames):_qnames[i]=qname._to_core_struct()count=ctypes.c_ulonglong(0)_result=core.BNGetIncomingRecursiveTypeReferences(self.handle,_qnames,len(qnames),count)assert_resultisnotNone,"core.BNGetIncomingRecursiveTypeReferences returned None"try:result=[]foriinrange(0,count.value):result_name=_types.QualifiedName._from_core_struct(_result[i])result.append(result_name)returnresultfinally:core.BNFreeTypeNameList(_result,count.value)
[docs]defcreate_structure_from_offset_access(self,name:'_types.QualifiedName')->'_types.StructureType':newMemberAdded=ctypes.c_bool(False)_name=_types.QualifiedName(name)._to_core_struct()struct=core.BNCreateStructureFromOffsetAccess(self.handle,_name,newMemberAdded)ifstructisNone:raiseException("BNCreateStructureFromOffsetAccess failed to create struct from offsets")return_types.StructureType.from_core_struct(struct)
[docs]defcreate_structure_member_from_access(self,name:'_types.QualifiedName',offset:int)->'_types.Type':_name=_types.QualifiedName(name)._to_core_struct()result=core.BNCreateStructureMemberFromAccess(self.handle,_name,offset)ifnotresult.type:raiseException("BNCreateStructureMemberFromAccess failed to create struct member offsets")return_types.Type.create(result.type,confidence=result.confidence)
[docs]defadd_expression_parser_magic_value(self,name:str,value:int)->None:"""Add a magic value to the expression parser.If the magic value already exists, its value gets updated.The magic value can be used in the expression by a `$` followed by its name, e.g., `$foobar`.It is optional to include the `$` when calling this function, i.e., calling with `foobar` and `$foobar`has the same effect.:param str name: name for the magic value to add or update:param int value: value for the magic value:return:"""core.BNAddExpressionParserMagicValue(self.handle,name,value)
[docs]defremove_expression_parser_magic_value(self,name:str)->None:"""Remove a magic value from the expression parser.If the magic value gets referenced after removal, an error will occur during the parsing.:param str name: name for the magic value to remove:return:"""core.BNRemoveExpressionParserMagicValue(self.handle,name)
[docs]defadd_expression_parser_magic_values(self,names:List[str],values:List[int])->None:"""Add a list of magic value to the expression parser.The list `names` and `values` must have the same size. The ith name in the `names` will correspond tothe ith value in the `values`.If a magic value already exists, its value gets updated.The magic value can be used in the expression by a `$` followed by its name, e.g., `$foobar`.It is optional to include the `$` when calling this function, i.e., calling with `foobar` and `$foobar`has the same effect.:param list(str) names: names for the magic values to add or update:param list(int) values: value for the magic values:return:"""iflen(names)==0orlen(values)==0or(notlen(names)==len(values)):returnnames_buf=(ctypes.c_char_p*len(names))()foriinrange(0,len(names)):names_buf[i]=names[i].encode('charmap')values_buf=(ctypes.c_ulonglong*len(values))()foriinrange(0,len(values)):values_buf[i]=values[i]core.BNAddExpressionParserMagicValues(self.handle,names_buf,values_buf,len(names))
[docs]defremove_expression_parser_magic_values(self,names:List[str])->None:"""Remove a list of magic value from the expression parserIf any of the magic values gets referenced after removal, an error will occur during the parsing.:param list(str) names: names for the magic value to remove:return:"""iflen(names)==0:returnnames_buf=(ctypes.c_char_p*len(names))()foriinrange(0,len(names)):names_buf[i]=names[i].encode('charmap')core.BNRemoveExpressionParserMagicValues(self.handle,names_buf,len(names))
[docs]defget_expression_parser_magic_value(self,name:str)->Optional[int]:"""Get the value of an expression parser magic valueIf the queried magic value exists, the function returns true and the magic value is returned in `value`.If the queried magic value does not exist, the function returns None.:param name: name for the magic value to query:return:"""result=ctypes.c_ulonglong()ifnotcore.BNGetExpressionParserMagicValue(self.handle,name,result):returnNonereturnresult.value
[docs]defget_callers(self,addr:int)->Generator[ReferenceSource,None,None]:"""``get_callers`` returns a list of ReferenceSource objects (xrefs or cross-references) that call the provided virtual address.In this case, tail calls, jumps, and ordinary calls are considered.:param int addr: virtual address of callee to query for callers:return: List of References that call the given virtual address:rtype: list(ReferenceSource):Example:>>> bv.get_callers(here)[<ref: x86@0x4165ff>]>>>"""count=ctypes.c_ulonglong(0)refs=core.BNGetCallers(self.handle,addr,count)assertrefsisnotNone,"core.BNGetCallers returned None"try:foriinrange(0,count.value):yieldReferenceSource._from_core_struct(self,refs[i])finally:core.BNFreeCodeReferences(refs,count.value)
[docs]defget_callees(self,addr:int,func:Optional['_function.Function']=None,arch:Optional['architecture.Architecture']=None)->List[int]:"""``get_callees`` returns a list of virtual addresses called by the call site in the function ``func``,of the architecture ``arch``, and at the address ``addr``. If no function is specified, call sites fromall functions and containing the address will be considered. If no architecture is specified, thearchitecture of the function will be used.:param int addr: virtual address of the call site to query for callees:param Function func: (optional) the function that the call site belongs to:param Architecture func: (optional) the architecture of the call site:return: list of integers:rtype: list(integer)"""result=[]funcs=self.get_functions_containing(addr)iffuncisNoneelse[func]ifnotfuncs:return[]forsrc_funcinfuncs:src_arch=src_func.archifarchisNoneelsearchassertsrc_archisnotNoneref_src=core.BNReferenceSource(src_func.handle,src_arch.handle,addr)count=ctypes.c_ulonglong(0)refs=core.BNGetCallees(self.handle,ref_src,count)assertrefsisnotNone,"core.BNGetCallees returned None"try:foriinrange(0,count.value):result.append(refs[i])finally:core.BNFreeAddressList(refs)returnresult
[docs]defget_symbol_at(self,addr:int,namespace:'_types.NameSpaceType'=None)->Optional['_types.CoreSymbol']:"""``get_symbol_at`` returns the Symbol at the provided virtual address.:param addr: virtual address to query for symbol:param namespace: (optional) the namespace of the symbols to retrieve:return: CoreSymbol for the given virtual address:rtype: CoreSymbol:Example:>>> bv.get_symbol_at(bv.entry_point)<FunctionSymbol: "_start" @ 0x100001174>>>>"""_namespace=_types.NameSpace.get_core_struct(namespace)sym=core.BNGetSymbolByAddress(self.handle,addr,_namespace)ifsymisNone:returnNonereturn_types.CoreSymbol(sym)
[docs]defget_symbols_by_raw_name(self,name:str,namespace:'_types.NameSpaceType'=None)->List['_types.CoreSymbol']:_namespace=_types.NameSpace.get_core_struct(namespace)count=ctypes.c_ulonglong(0)syms=core.BNGetSymbolsByRawName(self.handle,name,count,_namespace)assertsymsisnotNone,"core.BNGetSymbolsByRawName returned None"result=[]try:foriinrange(0,count.value):handle=core.BNNewSymbolReference(syms[i])asserthandleisnotNone,"core.BNNewSymbolReference returned None"result.append(_types.CoreSymbol(handle))returnresultfinally:core.BNFreeSymbolList(syms,count.value)
[docs]defget_symbol_by_raw_name(self,name:str,namespace:'_types.NameSpaceType'=None)->Optional['_types.CoreSymbol']:"""``get_symbol_by_raw_name`` retrieves a Symbol object for the given raw (mangled) name.:param name: raw (mangled) name of Symbol to be retrieved:param namespace: (optional) the namespace to search for the given symbol:return: CoreSymbol object corresponding to the provided raw name:rtype: CoreSymbol:Example:>>> bv.get_symbol_by_raw_name('?testf@Foobar@@SA?AW4foo@1@W421@@Z')<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>>>>"""_namespace=_types.NameSpace.get_core_struct(namespace)sym=core.BNGetSymbolByRawName(self.handle,name,_namespace)ifsymisNone:returnNonereturn_types.CoreSymbol(sym)
[docs]defget_symbols_by_name(self,name:str,namespace:'_types.NameSpaceType'=None,ordered_filter:Optional[List[SymbolType]]=None)->List['_types.CoreSymbol']:"""``get_symbols_by_name`` retrieves a list of Symbol objects for the given symbol name and ordered filter:param name: name of Symbol object to be retrieved:param namespace: (optional) the namespace to search for the given symbol:param namespace: (optional) the namespace to search for the given symbol:param ordered_filter: (optional) an ordered filter based on SymbolType:return: Symbol object corresponding to the provided name:rtype: Symbol:Example:>>> bv.get_symbols_by_name('?testf@Foobar@@SA?AW4foo@1@W421@@Z')[<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>]>>>"""ifordered_filterisNone:ordered_filter=[SymbolType.FunctionSymbol,SymbolType.ImportedFunctionSymbol,SymbolType.LibraryFunctionSymbol,SymbolType.SymbolicFunctionSymbol,SymbolType.DataSymbol,SymbolType.ImportedDataSymbol,SymbolType.ImportAddressSymbol,SymbolType.ExternalSymbol,SymbolType.LocalLabelSymbol]_namespace=_types.NameSpace.get_core_struct(namespace)count=ctypes.c_ulonglong(0)syms=core.BNGetSymbolsByName(self.handle,name,count,_namespace)assertsymsisnotNone,"core.BNGetSymbolsByName returned None"result=[]try:foriinrange(0,count.value):handle=core.BNNewSymbolReference(syms[i])asserthandleisnotNone,"core.BNNewSymbolReference returned None"result.append(_types.CoreSymbol(handle))result=sorted(filter(lambdasym:sym.typeinordered_filter,result),key=lambdasym:ordered_filter.index(sym.type))returnresultfinally:core.BNFreeSymbolList(syms,count.value)
[docs]defget_symbols(self,start:Optional[int]=None,length:Optional[int]=None,namespace:'_types.NameSpaceType'=None)->List['_types.CoreSymbol']:"""``get_symbols`` retrieves the list of all Symbol objects in the optionally provided range.:param start: optional start virtual address:param length: optional length:return: list of all Symbol objects, or those Symbol objects in the range of ``start``-``start+length``:rtype: list(Symbol):Example:>>> bv.get_symbols(0x1000200c, 1)[<ImportAddressSymbol: "KERNEL32!IsProcessorFeaturePresent" @ 0x1000200c>]>>>"""count=ctypes.c_ulonglong(0)_namespace=_types.NameSpace.get_core_struct(namespace)ifstartisNone:syms=core.BNGetSymbols(self.handle,count,_namespace)assertsymsisnotNone,"core.BNGetSymbols returned None"else:iflengthisNone:length=1syms=core.BNGetSymbolsInRange(self.handle,start,length,count,namespace)assertsymsisnotNone,"core.BNGetSymbolsInRange returned None"result=[]try:foriinrange(0,count.value):sym_handle=core.BNNewSymbolReference(syms[i])assertsym_handleisnotNone,"core.BNNewSymbolReference returned None"result.append(_types.CoreSymbol(sym_handle))returnresultfinally:core.BNFreeSymbolList(syms,count.value)
[docs]defget_symbols_of_type(self,sym_type:SymbolType,start:Optional[int]=None,length:Optional[int]=None,namespace:'_types.NameSpaceType'=None)->List['_types.CoreSymbol']:"""``get_symbols_of_type`` retrieves a list of all :py:class:`~binaryninja.types.Symbol` objects of the provided symbol type in the optionally provided range.:param sym_type: A Symbol type: :py:class:`~binaryninja.enums.SymbolType`:param start: optional start virtual address:param length: optional length:return: list of all :py:class:`~binaryninja.types.Symbol` objects of type ``sym_type``, or those :py:class:`~binaryninja.types.Symbol` objects in the range of ``start``-``start+length``:rtype: list(CoreSymbol):Example:>>> bv.get_symbols_of_type(SymbolType.ImportAddressSymbol, 0x10002028, 1)[<ImportAddressSymbol: "KERNEL32!GetCurrentThreadId" @ 0x10002028>]>>>"""ifisinstance(sym_type,str):sym_type=SymbolType[sym_type]_namespace=_types.NameSpace.get_core_struct(namespace)count=ctypes.c_ulonglong(0)ifstartisNone:syms=core.BNGetSymbolsOfType(self.handle,sym_type,count,_namespace)assertsymsisnotNone,"core.BNGetSymbolsOfType returned None"else:iflengthisNone:raiseException("Length must be provided if start is present")syms=core.BNGetSymbolsOfTypeInRange(self.handle,sym_type,start,length,count,_namespace)assertsymsisnotNone,"core.BNGetSymbolsOfTypeInRange returned None"result=[]try:foriinrange(0,count.value):sym_handle=core.BNNewSymbolReference(syms[i])assertsym_handleisnotNone,"core.BNNewSymbolReference returned None"result.append(_types.CoreSymbol(sym_handle))returnresultfinally:core.BNFreeSymbolList(syms,count.value)
[docs]defdefine_auto_symbol(self,sym:'_types.CoreSymbol')->None:"""``define_auto_symbol`` adds a symbol to the internal list of automatically discovered Symbol objects in a givennamespace... warning:: If multiple symbols for the same address are defined, the symbol with the highest confidence and  lowest SymbolType value will be used. Ties are broken by symbol name.:param sym: the symbol to define:rtype: None"""core.BNDefineAutoSymbol(self.handle,sym.handle)
[docs]defdefine_auto_symbol_and_var_or_function(self,sym:'_types.CoreSymbol',type:Optional['_types.Type']=None,plat:Optional['_platform.Platform']=None,type_confidence:Optional[int]=0)->Optional['_types.CoreSymbol']:"""``define_auto_symbol_and_var_or_function`` Defines an "Auto" symbol, and a Variable/Function alongside it... warning:: If multiple symbols for the same address are defined, the symbol with the highest confidence and  lowest SymbolType value will be used. Ties are broken by symbol name.:param sym: Symbol to define:param type: Type for the function/variable being defined (can be None):param plat: Platform (optional):param type_confidence: Optional confidence value for the type:rtype: Optional[CoreSymbol]"""ifplatisNone:ifself.platformisNone:raiseException("Attempting to call define_auto_symbol_and_var_or_function without Platform specified")plat=self.platformelifnotisinstance(plat,_platform.Platform):raiseValueError("Provided platform is not of type `Platform`")tc=core.BNTypeWithConfidence()tc.type=Nonetc.confidence=0ifisinstance(type,_types.Type):tc.type=type.handletc.confidence=type_confidenceeliftypeisnotNone:raiseValueError("Provided type is not of type `binaryninja.Type`")_sym=core.BNDefineAutoSymbolAndVariableOrFunction(self.handle,plat.handle,sym.handle,tc)if_symisNone:returnNonereturn_types.CoreSymbol(_sym)
[docs]defundefine_auto_symbol(self,sym:'_types.CoreSymbol')->None:"""``undefine_auto_symbol`` removes a symbol from the internal list of automatically discovered Symbol objects.:param Symbol sym: the symbol to undefine:rtype: None"""core.BNUndefineAutoSymbol(self.handle,sym.handle)
[docs]defdefine_user_symbol(self,sym:'_types.CoreSymbol')->None:"""``define_user_symbol`` adds a symbol to the internal list of user added Symbol objects... warning:: If multiple symbols for the same address are defined, the symbol with the highest confidence and  lowest SymbolType value will be used. Ties are broken by symbol name.:param Symbol sym: the symbol to define:rtype: None"""core.BNDefineUserSymbol(self.handle,sym.handle)
[docs]defundefine_user_symbol(self,sym:'_types.CoreSymbol')->None:"""``undefine_user_symbol`` removes a symbol from the internal list of user added Symbol objects.:param sym: the symbol to undefine:rtype: None"""core.BNUndefineUserSymbol(self.handle,sym.handle)
[docs]defdefine_imported_function(self,import_addr_sym:'_types.CoreSymbol',func:'_function.Function',type:Optional['_types.Type']=None)->None:"""``define_imported_function`` defines an imported Function ``func`` with a ImportedFunctionSymbol type.:param import_addr_sym: A Symbol object with type ImportedFunctionSymbol:param func: A Function object to define as an imported function:param type: Optional type for the function:rtype: None"""core.BNDefineImportedFunction(self.handle,import_addr_sym.handle,func.handle,NoneiftypeisNoneelsetype.handle)
[docs]defbulk_modify_symbols(self):"""``bulk_modify_symbols`` returns a context manager that improves performance when adding orremoving a large number of symbols. Symbols added within the Python `with` keyword willdefer processing until the end of the block. Many symbol getter APIs will return staleresults inside the `with` block, so this function should only be used when symbolqueries are not needed at the same time as the modifications."""classBulkModify:def__init__(self,view:'BinaryView'):self._view=viewdef__enter__(self)->None:core.BNBeginBulkModifySymbols(self._view.handle)def__exit__(self,type,value,traceback):core.BNEndBulkModifySymbols(self._view.handle)returnBulkModify(self)
[docs]defcreate_tag_type(self,name:str,icon:str)->'TagType':"""``create_tag_type`` creates a new :py:class:`TagType` and adds it to the view:param str name: The name for the tag:param str icon: The icon (recommended 1 emoji or 2 chars) for the tag:return: The created tag type:rtype: TagType:Example:>>> bv.create_tag_type("Crabby Functions", "🦀")>>>"""tag_handle=core.BNCreateTagType(self.handle)asserttag_handleisnotNone,"core.BNCreateTagType returned None"tag_type=TagType(tag_handle)tag_type.name=nametag_type.icon=iconcore.BNAddTagType(self.handle,tag_type.handle)returntag_type
[docs]defremove_tag_type(self,tag_type:str):"""``remove_tag_type`` removes a :py:class:`TagType` and all tags that use it:param str tag_type: The name of the tag type to remove:rtype: None"""tag_type=self.get_tag_type(tag_type)iftag_typeisnotNone:core.BNRemoveTagType(self.handle,tag_type.handle)
@propertydeftag_types(self)->Mapping[str,Union['TagType',List['TagType']]]:"""``tag_types`` gets a dictionary of all Tag Types present for the view,structured as {Tag Type Name => Tag Type}... warning:: This method inconsistently returns a list of :py:class:`TagType` objects or a single \ :py:class:`TagType` this behavior will change in future revisions:rtype: dict of (str, TagType)"""count=ctypes.c_ulonglong(0)types=core.BNGetTagTypes(self.handle,count)asserttypesisnotNone,"core.BNGetTagTypes returned None"result:Mapping[str,Union['TagType',List['TagType']]]={}try:foriinrange(0,count.value):tag_handle=core.BNNewTagTypeReference(types[i])asserttag_handleisnotNone,"core.BNNewTagTypeReference returned None"tag=TagType(tag_handle)iftag.nameinresult:cur_item=result[tag.name]ifisinstance(cur_item,list):cur_item.append(tag)result[tag.name]=cur_itemelse:result[tag.name]=[cur_item,tag]else:result[tag.name]=tagreturnresultfinally:core.BNFreeTagTypeList(types,count.value)
[docs]defget_tag_type(self,name:str)->Optional['TagType']:"""Get a tag type by its name.:param name: Name of the tag type:return: The relevant tag type, if it exists:rtype: TagType"""ifisinstance(name,TagType):log_warn("Accessing tag types by type is deprecated. Please use the name instead.")returnnameelse:tag_type=core.BNGetTagType(self.handle,name)iftag_typeisnotNone:returnTagType(tag_type)else:returnNone
[docs]defadd_tag(self,addr:int,tag_type_name:str,data:str,user:bool=True):"""``add_tag`` creates and adds a :py:class:`Tag` object at a data address.This API is appropriate for generic data tags. For functions,consider using :py:func:`~binaryninja.function.Function.add_tag`.:param int addr: address at which to add the tag:param str tag_type_name: The name of the tag type for this Tag:param str data: additional data for the Tag:param bool user: Whether or not a user tag:Example:>>> bv.add_tag(here, "Crashes", "Null pointer dereference")>>>"""tag_type=self.get_tag_type(tag_type_name)iftag_typeisNone:returntag_handle=core.BNCreateTag(tag_type.handle,data)asserttag_handleisnotNone,"core.BNCreateTag returned None"tag=Tag(tag_handle)core.BNAddTag(self.handle,tag.handle,user)core.BNAddUserDataTag(self.handle,addr,tag.handle)
def_fetch_tags(self,c_api_func,*args)->List[Tuple[int,'Tag']]:"""Internal helper to fetch tags using the specified core API function.:param c_api_func: The C API function to call.:param args: Arguments for the C API function.:return: List of (address, Tag) pairs."""count=ctypes.c_ulonglong()tags=c_api_func(self.handle,*args,count)asserttagsisnotNone,f"{c_api_func.__name__} returned None"result=[]try:foriinrange(count.value):tag_handle=core.BNNewTagReference(tags[i].tag)asserttag_handleisnotNone,"core.BNNewTagReference returned None"tag=Tag(tag_handle)result.append((tags[i].addr,tag))returnresultfinally:core.BNFreeTagReferences(tags,count.value)@propertydeftags_all_scopes(self)->List[Tuple[int,'Tag']]:"""``tags_all_scopes`` fetches all tags in all scopes."""returnself._fetch_tags(core.BNGetAllTagReferences)@propertydeftags_for_address(self)->List[Tuple[int,'Tag']]:"""``tags_for_address`` fetches all address-specific tags."""returnself._fetch_tags(core.BNGetAllAddressTagReferences)@propertydeftags_for_function(self)->List[Tuple[int,'Tag']]:"""``tags_for_function`` fetches all function-specific tags."""returnself._fetch_tags(core.BNGetAllFunctionTagReferences)@propertydeftags_for_data(self)->List[Tuple[int,'Tag']]:"""``tags_for_data`` fetches all data-specific tags."""returnself._fetch_tags(core.BNGetDataTagReferences)
[docs]deftags_by_type(self,tag_type:'TagType')->List[Tuple[int,'Tag']]:"""``tags_by_type`` fetches tags of a specific type.:param tag_type: The type of tags to fetch."""returnself._fetch_tags(core.BNGetAllTagReferencesOfType,tag_type.handle)
[docs]deftags_for_data_by_type(self,tag_type:'TagType')->List[Tuple[int,'Tag']]:"""``tags_for_data_by_type`` fetches data-specific tags of a specific type.:param tag_type: The type of tags to filter by.:rtype: list(int, Tag)"""returnself._fetch_tags(core.BNGetTagReferencesOfType,tag_type.handle)
[docs]deftags_for_data_with_source(self,auto:bool=True)->List[Tuple[int,'Tag']]:"""``tags_for_data_with_source`` fetches data-specific tags filtered by source.:param auto: If True, fetch auto tags. If False, fetch user tags.:rtype: list(int, Tag)"""ifauto:returnself._fetch_tags(core.BNGetAutoDataTagReferences)else:returnself._fetch_tags(core.BNGetUserDataTagReferences)
# Note: The 'Tags' APIs above have been added to expose the ability to fetch tags for various scopes in a# in an efficient manner. By default, the 'tags' property on both `BinaryView` and `Function` objects returns# all tags scoped to the object.@propertydeftags(self)->List[Tuple[int,'Tag']]:"""``tags`` gets a list of all data :py:class:`Tag` objects in the view.Tags are returned as a list of (address, :py:class:`Tag`) pairs.:rtype: list(int, Tag)"""returnself.get_tags()
[docs]defget_tags(self,auto:Optional[bool]=None)->List[Tuple[int,'Tag']]:"""``tags`` gets a list of all data :py:class:`Tag` objects in the view.Tags are returned as a list of (address, :py:class:`Tag`) pairs.:rtype: list(int, Tag)"""count=ctypes.c_ulonglong()ifautoisNone:tags=core.BNGetDataTagReferences(self.handle,count)asserttagsisnotNone,"core.BNGetDataTagReferences returned None"elifauto:tags=core.BNGetAutoDataTagReferences(self.handle,count)asserttagsisnotNone,"core.BNGetAutoDataTagReferences return None"else:tags=core.BNGetUserDataTagReferences(self.handle,count)asserttagsisnotNone,"core.BNGetUserDataTagReferences returned None"result=[]try:foriinrange(0,count.value):tag_handle=core.BNNewTagReference(tags[i].tag)asserttag_handleisnotNone,"core.BNNewTagReference is not None"tag=Tag(tag_handle)result.append((tags[i].addr,tag))returnresultfinally:core.BNFreeTagReferences(tags,count.value)
[docs]defget_tags_at(self,addr:int,auto:Optional[bool]=None)->List['Tag']:"""``get_data_tags_at`` gets a list of :py:class:`Tag` objects for a data address.:param int addr: address to get tags at:param bool auto: If None, gets all tags, if True, gets auto tags, if False, gets user tags:return: A list of data :py:class:`Tag` objects:rtype: list(Tag)"""count=ctypes.c_ulonglong()ifautoisNone:tags=core.BNGetDataTags(self.handle,addr,count)asserttagsisnotNone,"core.BNGetDataTags returned None"elifauto:tags=core.BNGetAutoDataTags(self.handle,addr,count)asserttagsisnotNone,"core.BNGetAutoDataTags returned None"else:tags=core.BNGetUserDataTags(self.handle,addr,count)asserttagsisnotNone,"core.BNGetUserDataTags returned None"result=[]try:foriinrange(0,count.value):tag_handle=core.BNNewTagReference(tags[i])asserttag_handleisnotNone,"core.BNNewTagReference is not None"result.append(Tag(tag_handle))returnresultfinally:core.BNFreeTagList(tags,count.value)
[docs]defget_tags_in_range(self,address_range:'variable.AddressRange',auto:Optional[bool]=None)->List[Tuple[int,'Tag']]:"""``get_data_tags_in_range`` gets a list of all data :py:class:`Tag` objects in a given range.Range is inclusive at the start, exclusive at the end.:param AddressRange address_range: address range from which to get tags:param bool auto: If None, gets all tags, if True, gets auto tags, if False, gets auto tags:return: A list of (address, data tag) tuples:rtype: list((int, Tag))"""count=ctypes.c_ulonglong()ifautoisNone:refs=core.BNGetDataTagsInRange(self.handle,address_range.start,address_range.end,count)assertrefsisnotNone,"BNGetDataTagsInRange returned None"elifauto:refs=core.BNGetAutoDataTagsInRange(self.handle,address_range.start,address_range.end,count)assertrefsisnotNone,"BNGetAutoDataTagsInRange returned None"else:refs=core.BNGetUserDataTagsInRange(self.handle,address_range.start,address_range.end,count)assertrefsisnotNone,"BNGetUserDataTagsInRange returned None"result=[]try:foriinrange(0,count.value):tag_ref=core.BNNewTagReference(refs[i].tag)asserttag_refisnotNone,"BNNewTagReference returned None"tag=Tag(tag_ref)result.append((refs[i].addr,tag))returnresultfinally:core.BNFreeTagReferences(refs,count.value)
[docs]defremove_user_data_tag(self,addr:int,tag:Tag):"""``remove_user_data_tag`` removes a :py:class:`Tag` object at a data address.Since this removes a user tag, it will be added to the current undo buffer.:param int addr: address at which to remove the tag:param Tag tag: :py:class:`Tag` object to be removed:rtype: None"""core.BNRemoveUserDataTag(self.handle,addr,tag.handle)
[docs]defremove_user_data_tags_of_type(self,addr:int,tag_type:str):"""``remove_user_data_tags_of_type`` removes all data tags at the given address of the given type.Since this removes user tags, it will be added to the current undo buffer.:param int addr: address at which to add the tags:param str tag_type: Tag type name to match for removing:rtype: None"""tag_type=self.get_tag_type(tag_type)iftag_typeisnotNone:core.BNRemoveUserDataTagsOfType(self.handle,addr,tag_type.handle)
[docs]defremove_auto_data_tag(self,addr:int,tag:'Tag'):"""``remove_auto_data_tag`` removes a Tag object at a data address.:param int addr: address at which to remove the tag:param Tag tag: Tag object to be removed:rtype: None"""core.BNRemoveAutoDataTag(self.handle,addr,tag.handle)
[docs]defremove_auto_data_tags_of_type(self,addr:int,tag_type:str):"""``remove_auto_data_tags_of_type`` removes all data tags at the given address of the given type.:param int addr: address at which to add the tags:param str tag_type: Tag type name to match for removing:rtype: None"""tag_type=self.get_tag_type(tag_type)iftag_typeisnotNone:core.BNRemoveAutoDataTagsOfType(self.handle,addr,tag_type.handle)
[docs]defcheck_for_string_annotation_type(self,addr:int,allow_short_strings:bool=False,allow_large_strings:bool=False,child_width:int=0)->Optional[Tuple[str,StringType]]:"""Check for string annotation at a given address. This returns the string (and type of the string) as annotated in the UI at a given address. If there's no annotation, this function returns `None`.:param int addr: address at which to check for string annotation:param bool allow_short_strings: Allow string shorter than the `analysis.limits.minStringLength` setting:param bool allow_large_strings: Allow strings longer than the `rendering.strings.maxAnnotationLength` setting (up to `analysis.limits.maxStringLength`):param int child_width: What width of strings to look for, 1 for ASCII/UTF8, 2 for UTF16, 4 for UTF32, 0 to check for all:rtype: None"""value=ctypes.c_char_p()string_type=ctypes.c_int()result=core.BNCheckForStringAnnotationType(self.handle,addr,value,string_type,allow_short_strings,allow_large_strings,child_width)ifresult:result=value.value.decode("utf-8")core.free_string(value)return(result,StringType(string_type.value))returnNone
[docs]defcan_assemble(self,arch:Optional['architecture.Architecture']=None)->bool:"""``can_assemble`` queries the architecture plugin to determine if the architecture can assemble instructions.:return: True if the architecture can assemble, False otherwise:rtype: bool:Example:>>> bv.can_assemble()True>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNCanAssemble(self.handle,arch.handle)
[docs]defis_never_branch_patch_available(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``is_never_branch_patch_available`` queries the architecture plugin to determine if the instruction at theinstruction at ``addr`` can be made to **never branch**. The actual logic of which is implemented in the``perform_is_never_branch_patch_available`` in the corresponding architecture.:param int addr: the virtual address of the instruction to be patched:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True if the instruction can be patched, False otherwise:rtype: bool:Example:>>> bv.get_disassembly(0x100012ed)'test    eax, eax'>>> bv.is_never_branch_patch_available(0x100012ed)False>>> bv.get_disassembly(0x100012ef)'jg      0x100012f5'>>> bv.is_never_branch_patch_available(0x100012ef)True>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNIsNeverBranchPatchAvailable(self.handle,arch.handle,addr)
[docs]defis_always_branch_patch_available(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``is_always_branch_patch_available`` queries the architecture plugin to determine if theinstruction at ``addr`` can be made to **always branch**. The actual logic of which is implemented in the``perform_is_always_branch_patch_available`` in the corresponding architecture.:param int addr: the virtual address of the instruction to be patched:param Architecture arch: (optional) the architecture for the current view:return: True if the instruction can be patched, False otherwise:rtype: bool:Example:>>> bv.get_disassembly(0x100012ed)'test    eax, eax'>>> bv.is_always_branch_patch_available(0x100012ed)False>>> bv.get_disassembly(0x100012ef)'jg      0x100012f5'>>> bv.is_always_branch_patch_available(0x100012ef)True>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNIsAlwaysBranchPatchAvailable(self.handle,arch.handle,addr)
[docs]defis_invert_branch_patch_available(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``is_invert_branch_patch_available`` queries the architecture plugin to determine if the instruction at ``addr``is a branch that can be inverted. The actual logic of which is implemented in the``perform_is_invert_branch_patch_available`` in the corresponding architecture.:param int addr: the virtual address of the instruction to be patched:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True if the instruction can be patched, False otherwise:rtype: bool:Example:>>> bv.get_disassembly(0x100012ed)'test    eax, eax'>>> bv.is_invert_branch_patch_available(0x100012ed)False>>> bv.get_disassembly(0x100012ef)'jg      0x100012f5'>>> bv.is_invert_branch_patch_available(0x100012ef)True>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNIsInvertBranchPatchAvailable(self.handle,arch.handle,addr)
[docs]defis_skip_and_return_zero_patch_available(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``is_skip_and_return_zero_patch_available`` queries the architecture plugin to determine if theinstruction at ``addr`` is similar to an x86 "call" instruction which can be made to return zero. The actuallogic of which is implemented in the ``perform_is_skip_and_return_zero_patch_available`` in the correspondingarchitecture.:param int addr: the virtual address of the instruction to be patched:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True if the instruction can be patched, False otherwise:rtype: bool:Example:>>> bv.get_disassembly(0x100012f6)'mov     dword [0x10003020], eax'>>> bv.is_skip_and_return_zero_patch_available(0x100012f6)False>>> bv.get_disassembly(0x100012fb)'call    0x10001629'>>> bv.is_skip_and_return_zero_patch_available(0x100012fb)True>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNIsSkipAndReturnZeroPatchAvailable(self.handle,arch.handle,addr)
[docs]defis_skip_and_return_value_patch_available(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``is_skip_and_return_value_patch_available`` queries the architecture plugin to determine if theinstruction at ``addr`` is similar to an x86 "call" instruction which can be made to return a value. The actuallogic of which is implemented in the ``perform_is_skip_and_return_value_patch_available`` in the correspondingarchitecture.:param int addr: the virtual address of the instruction to be patched:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True if the instruction can be patched, False otherwise:rtype: bool:Example:>>> bv.get_disassembly(0x100012f6)'mov     dword [0x10003020], eax'>>> bv.is_skip_and_return_value_patch_available(0x100012f6)False>>> bv.get_disassembly(0x100012fb)'call    0x10001629'>>> bv.is_skip_and_return_value_patch_available(0x100012fb)True>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNIsSkipAndReturnValuePatchAvailable(self.handle,arch.handle,addr)
[docs]defconvert_to_nop(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``convert_to_nop`` converts the instruction at virtual address ``addr`` to a nop of the provided architecture... note:: This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary \file must be saved in order to preserve the changes made.:param int addr: virtual address of the instruction to convert to nops:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True on success, False on failure.:rtype: bool:Example:>>> bv.get_disassembly(0x100012fb)'call    0x10001629'>>> bv.convert_to_nop(0x100012fb)True>>> #The above 'call' instruction is 5 bytes, a nop in x86 is 1 byte,>>> # thus 5 nops are used:>>> bv.get_disassembly(0x100012fb)'nop'>>> bv.get_disassembly(0x100012fb + 1)'nop'>>> bv.get_disassembly(0x100012fb + 2)'nop'>>> bv.get_disassembly(0x100012fb + 3)'nop'>>> bv.get_disassembly(0x100012fb + 4)'nop'>>> bv.get_disassembly(0x100012fb + 5)'mov     byte [ebp-0x1c], al'"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNConvertToNop(self.handle,arch.handle,addr)
[docs]defalways_branch(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``always_branch`` convert the instruction of architecture ``arch`` at the virtual address ``addr`` to anunconditional branch... note:: This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary \file must be saved in order to preserve the changes made.:param int addr: virtual address of the instruction to be modified:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True on success, False on failure.:rtype: bool:Example:>>> bv.get_disassembly(0x100012ef)'jg      0x100012f5'>>> bv.always_branch(0x100012ef)True>>> bv.get_disassembly(0x100012ef)'jmp     0x100012f5'>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNAlwaysBranch(self.handle,arch.handle,addr)
[docs]defnever_branch(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``never_branch`` convert the branch instruction of architecture ``arch`` at the virtual address ``addr`` toa fall through... note:: This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary\file must be saved in order to preserve the changes made.:param int addr: virtual address of the instruction to be modified:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True on success, False on failure.:rtype: bool:Example:>>> bv.get_disassembly(0x1000130e)'jne     0x10001317'>>> bv.never_branch(0x1000130e)True>>> bv.get_disassembly(0x1000130e)'nop'>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNConvertToNop(self.handle,arch.handle,addr)
[docs]definvert_branch(self,addr:int,arch:Optional['architecture.Architecture']=None)->bool:"""``invert_branch`` convert the branch instruction of architecture ``arch`` at the virtual address ``addr`` to theinverse branch... note:: This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary \file must be saved in order to preserve the changes made.:param int addr: virtual address of the instruction to be modified:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True on success, False on failure.:rtype: bool:Example:>>> bv.get_disassembly(0x1000130e)'je      0x10001317'>>> bv.invert_branch(0x1000130e)True>>>>>> bv.get_disassembly(0x1000130e)'jne     0x10001317'>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNInvertBranch(self.handle,arch.handle,addr)
[docs]defskip_and_return_value(self,addr:int,value:int,arch:Optional['architecture.Architecture']=None)->bool:"""``skip_and_return_value`` convert the ``call`` instruction of architecture ``arch`` at the virtual address``addr`` to the equivalent of returning a value.:param int addr: virtual address of the instruction to be modified:param int value: value to make the instruction *return*:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: True on success, False on failure.:rtype: bool:Example:>>> bv.get_disassembly(0x1000132a)'call    0x1000134a'>>> bv.skip_and_return_value(0x1000132a, 42)True>>> #The return value from x86 functions is stored in eax thus:>>> bv.get_disassembly(0x1000132a)'mov     eax, 0x2a'>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNSkipAndReturnValue(self.handle,arch.handle,addr,value)
[docs]defget_instruction_length(self,addr:int,arch:Optional['architecture.Architecture']=None)->int:"""``get_instruction_length`` returns the number of bytes in the instruction of Architecture ``arch`` at the virtualaddress ``addr``:param int addr: virtual address of the instruction query:param Architecture arch: (optional) the architecture of the instructions if different from the default:return: Number of bytes in instruction:rtype: int:Example:>>> bv.get_disassembly(0x100012f1)'xor     eax, eax'>>> bv.get_instruction_length(0x100012f1)2L>>>"""ifarchisNone:ifself.archisNone:raiseException("Attempting to call can_assemble without an Architecture specified")arch=self.archreturncore.BNGetInstructionLength(self.handle,arch.handle,addr)
[docs]defnotify_data_written(self,offset:int,length:int)->None:core.BNNotifyDataWritten(self.handle,offset,length)
[docs]defnotify_data_inserted(self,offset:int,length:int)->None:core.BNNotifyDataInserted(self.handle,offset,length)
[docs]defnotify_data_removed(self,offset:int,length:int)->None:core.BNNotifyDataRemoved(self.handle,offset,length)
[docs]defget_component(self,guid:str)->Optional[component.Component]:"""Lookup a Component by its GUID:param guid: GUID of the component to look up:return: The Component with that Guid"""bn_component=core.BNGetComponentByGuid(self.handle,guid)ifbn_componentisNone:returnNonereturncomponent.Component(bn_component)
[docs]defget_component_by_path(self,path:str)->Optional[component.Component]:"""Lookup a Component by its pathname:note: This is a convenience method, and for performance-sensitive lookups, GetComponentByGuid is very highly recommended.Lookups are done based on the .display_name of the Component.All lookups are absolute from the root component, and are case-sensitive. Pathnames are delimited with "/":param path: Pathname of the desired Component:return: The Component at that pathname:Example:>>> c = bv.create_component(name="MyComponent")>>> c2 = bv.create_component(name="MySubComponent", parent=c)>>> bv.get_component_by_path("/MyComponent/MySubComponent") == c2True>>> c3 = bv.create_component(name="MySubComponent", parent=c)>>> c3<Component "MySubComponent (1)" "(20712aff...")>>>> bv.get_component_by_path("/MyComponent/MySubComponent (1)") == c3True"""ifnotisinstance(path,str):raiseTypeError("Pathname must be a string")bn_component=core.BNGetComponentByPath(self.handle,path)ifbn_componentisNone:returnNonereturncomponent.Component(bn_component)
@propertydefroot_component(self)->component.Component:"""The root component for the BinaryView (read-only)This Component cannot be removed, and houses all unparented Components.:return: The root component"""returncomponent.Component(core.BNGetRootComponent(self.handle))
[docs]defcreate_component(self,name:Optional[str]=None,parent:Union[component.Component,str,None]=None)->component.Component:"""Create a new component with an optional name and parent.The `parent` argument can be either a Component or the Guid of a component to which the created componentwill be added as a child:param name: Optional name to create the component with:param parent: Optional parent to which the component will be added:return: The created component"""ifparent:ifisinstance(parent,component.Component):ifname:returncomponent.Component(core.BNCreateComponentWithParentAndName(self.handle,parent.guid,name))else:returncomponent.Component(core.BNCreateComponentWithParent(self.handle,parent.guid))elifisinstance(parent,str):ifname:returncomponent.Component(core.BNCreateComponentWithParentAndName(self.handle,parent,name))else:returncomponent.Component(core.BNCreateComponentWithParent(self.handle,parent))else:raiseTypeError("parent can only be a Component object or string GUID representing one")else:ifname:returncomponent.Component(core.BNCreateComponentWithName(self.handle,name))else:returncomponent.Component(core.BNCreateComponent(self.handle))
[docs]defremove_component(self,_component:Union[component.Component,str])->bool:"""Remove a component from the tree entirely.:param _component: Component to remove:return: Whether the removal was successful"""ifisinstance(_component,component.Component):returncore.BNRemoveComponent(self.handle,_component.handle)elifisinstance(_component,str):returncore.BNRemoveComponentByGuid(self.handle,_component)raiseTypeError("Removal is only supported with a Component or string representing its Guid")
[docs]defget_function_parent_components(self,function:'_function.Function')->List['component.Component']:_components=[]count=ctypes.c_ulonglong(0)bn_components=core.BNGetFunctionParentComponents(self.handle,function.handle,count)try:foriinrange(count.value):_components.append(component.Component(core.BNNewComponentReference(bn_components[i])))finally:core.BNFreeComponents(bn_components,count.value)return_components
[docs]defget_data_variable_parent_components(self,data_variable:'DataVariable')->List['component.Component']:_components=[]count=ctypes.c_ulonglong(0)bn_components=core.BNGetDataVariableParentComponents(self.handle,data_variable.address,count)try:foriinrange(count.value):_components.append(component.Component(core.BNNewComponentReference(bn_components[i])))finally:core.BNFreeComponents(bn_components,count.value)return_components
[docs]defget_strings(self,start:Optional[int]=None,length:Optional[int]=None)->List['StringReference']:"""``get_strings`` returns a list of strings defined in the binary in the optional virtual address range:``start-(start+length)``Note that this API will only return strings that have been identified by the string-analysis and thus governed by the minimum and maximum length settings and unrelated to the type system.:param int start: optional virtual address to start the string list from, defaults to start of the binary:param int length: optional length range to return strings from, defaults to length of the binary:return: a list of all strings or a list of strings defined between ``start`` and ``start+length``:rtype: list(StringReference):Example:>>> bv.get_strings(0x1000004d, 1)[<AsciiString: 0x1000004d, len 0x2c>]>>>"""count=ctypes.c_ulonglong(0)ifstartisNone:strings=core.BNGetStrings(self.handle,count)assertstringsisnotNone,"core.BNGetStrings returned None"else:iflengthisNone:length=self.end-startstrings=core.BNGetStringsInRange(self.handle,start,length,count)assertstringsisnotNone,"core.BNGetStringsInRange returned None"result=[]try:foriinrange(0,count.value):result.append(StringReference(self,StringType(strings[i].type),strings[i].start,strings[i].length))returnresultfinally:core.BNFreeStringReferenceList(strings)
[docs]defget_string_at(self,addr:int,partial:bool=False)->Optional['StringReference']:"""``get_string_at`` returns the string that falls on given virtual address... note:: This returns discovered strings and is therefore governed by `analysis.limits.minStringLength` and other settings. For an alternative API that simply returns any potential c-string at a given location, use :py:func:`get_ascii_string_at`.:param int addr: virtual address to get the string from:param bool partial: whether to return a partial string reference or not:return: returns the StringReference at the given virtual address, otherwise None.:rtype: StringReference:Example:>>> bv.get_string_at(0x40302f)<StringType.AsciiString: 0x403028, len 0x12>"""str_ref=core.BNStringReference()ifnotcore.BNGetStringAtAddress(self.handle,addr,str_ref):returnNoneifpartialand(addr!=str_ref.start)and(str_ref.type!=StringType.AsciiString):partial=Falselog_warn("Partial string not supported at{}".format(hex(addr)))start=addrifpartialelsestr_ref.startlength=str_ref.length-(addr-str_ref.start)ifpartialelsestr_ref.lengthreturnStringReference(self,StringType(str_ref.type),start,length)
[docs]defget_ascii_string_at(self,addr:int,min_length:int=4,max_length:Optional[int]=None,require_cstring:bool=True)->Optional['StringReference']:"""``get_ascii_string_at`` returns an ascii string found at ``addr``... note:: This returns an ascii string irrespective of whether the core analysis identified a string at that location. For an alternative API that uses existing identified strings, use :py:func:`get_string_at`.:param int addr: virtual address to start the string:param int min_length: minimum length to define a string:param int max_length: max length string to return:param bool require_cstring: only return 0x0-terminated strings:return: the string found at ``addr`` or None if a string does not exist:rtype: StringReference or None:Example:>>> s1 = bv.get_ascii_string_at(0x70d0)>>> s1<AsciiString: 0x70d0, len 0xb>>>> s1.value'AWAVAUATUSH'>>> s2 = bv.get_ascii_string_at(0x70d1)>>> s2<AsciiString: 0x70d1, len 0xa>>>> s2.value'WAVAUATUSH'"""ifnotisinstance(addr,int):raiseValueError("Input address ("+str(addr)+") is not a number.")ifaddr<self.startoraddr>=self.end:returnNonebr=BinaryReader(self)br.seek(addr)length=0c=br.read8()whilecisnotNoneandc>0andc<=0x7f:iflength==max_length:breaklength+=1c=br.read8()iflength<min_length:returnNoneifrequire_cstringandc!=0:returnNonereturnStringReference(self,StringType.AsciiString,addr,length)
[docs]defadd_analysis_completion_event(self,callback:Callable[[],None])->'AnalysisCompletionEvent':"""``add_analysis_completion_event`` sets up a call back function to be called when analysis has been completed.This is helpful when using :py:func:`update_analysis` which does not wait for analysis completion before returning.The callee of this function is not responsible for maintaining the lifetime of the returned AnalysisCompletionEvent object... note:: The lock held by the callback thread on the BinaryView instance ensures that other BinaryView actions can be safely performed in the callback thread... warning:: The built-in python console automatically updates analysis after every command is run, which means this call back may not behave as expected if entered interactively.:param callback callback: A function to be called with no parameters when analysis has completed.:return: An initialized AnalysisCompletionEvent object:rtype: AnalysisCompletionEvent:Example:>>> def completionEvent():...   print("done")...>>> bv.add_analysis_completion_event(completionEvent)<binaryninja.AnalysisCompletionEvent object at 0x10a2c9f10>>>> bv.update_analysis()done>>>"""returnAnalysisCompletionEvent(self,callback)
[docs]defget_next_function_start_after(self,addr:int)->int:"""``get_next_function_start_after`` returns the virtual address of the Function that occurs after the virtual address``addr``:param int addr: the virtual address to start looking from.:return: the virtual address of the next Function:rtype: int:Example:>>> bv.get_next_function_start_after(bv.entry_point)268441061L>>> hex(bv.get_next_function_start_after(bv.entry_point))'0x100015e5L'>>> hex(bv.get_next_function_start_after(0x100015e5))'0x10001629L'>>> hex(bv.get_next_function_start_after(0x10001629))'0x1000165eL'>>>"""returncore.BNGetNextFunctionStartAfterAddress(self.handle,addr)
[docs]defget_next_basic_block_start_after(self,addr:int)->int:"""``get_next_basic_block_start_after`` returns the virtual address of the BasicBlock that occurs after the virtual address ``addr``:param int addr: the virtual address to start looking from.:return: the virtual address of the next BasicBlock:rtype: int:Example:>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))'0x100014a8L'>>> hex(bv.get_next_basic_block_start_after(0x100014a8))'0x100014adL'>>>"""returncore.BNGetNextBasicBlockStartAfterAddress(self.handle,addr)
[docs]defget_next_data_after(self,addr:int)->int:"""``get_next_data_after`` retrieves the virtual address of the next non-code byte.:param int addr: the virtual address to start looking from.:return: the virtual address of the next data byte which is data, not code:rtype: int:Example:>>> hex(bv.get_next_data_after(0x10000000))'0x10000001L'"""returncore.BNGetNextDataAfterAddress(self.handle,addr)
[docs]defget_next_data_var_after(self,addr:int)->Optional['DataVariable']:"""``get_next_data_var_after`` retrieves the next :py:class:`DataVariable`, or None.:param int addr: the virtual address to start looking from.:return: the next :py:class:`DataVariable`:rtype: DataVariable:Example:>>> bv.get_next_data_var_after(0x10000000)<var 0x1000003c: int32_t>>>>"""whileTrue:next_data_var_start=core.BNGetNextDataVariableStartAfterAddress(self.handle,addr)ifnext_data_var_start==self.end:returnNonevar=core.BNDataVariable()ifnotcore.BNGetDataVariableAtAddress(self.handle,next_data_var_start,var):returnNoneifvar.address<next_data_var_start:addr=var.address+core.BNGetTypeWidth(var.type)continuebreakresult=DataVariable.from_core_struct(var,self)core.BNFreeDataVariable(var)returnresult
[docs]defget_next_data_var_start_after(self,addr:int)->int:"""``get_next_data_var_start_after`` retrieves the next virtual address of the next :py:class:`DataVariable`:param int addr: the virtual address to start looking from.:return: the virtual address of the next :py:class:`DataVariable`:rtype: int:Example:>>> hex(bv.get_next_data_var_start_after(0x10000000))'0x1000003cL'>>> bv.get_data_var_at(0x1000003c)<var 0x1000003c: int32_t>>>>"""returncore.BNGetNextDataVariableStartAfterAddress(self.handle,addr)
[docs]defget_previous_function_start_before(self,addr:int)->int:"""``get_previous_function_start_before`` returns the virtual address of the Function that occurs prior to thevirtual address provided:param int addr: the virtual address to start looking from.:return: the virtual address of the previous Function:rtype: int:Example:>>> hex(bv.entry_point)'0x1000149fL'>>> hex(bv.get_next_function_start_after(bv.entry_point))'0x100015e5L'>>> hex(bv.get_previous_function_start_before(0x100015e5))'0x1000149fL'>>>"""returncore.BNGetPreviousFunctionStartBeforeAddress(self.handle,addr)
[docs]defget_previous_basic_block_start_before(self,addr:int)->int:"""``get_previous_basic_block_start_before`` returns the virtual address of the BasicBlock that occurs prior to theprovided virtual address:param int addr: the virtual address to start looking from.:return: the virtual address of the previous BasicBlock:rtype: int:Example:>>> hex(bv.entry_point)'0x1000149fL'>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))'0x100014a8L'>>> hex(bv.get_previous_basic_block_start_before(0x100014a8))'0x1000149fL'>>>"""returncore.BNGetPreviousBasicBlockStartBeforeAddress(self.handle,addr)
[docs]defget_previous_basic_block_end_before(self,addr:int)->int:"""``get_previous_basic_block_end_before``:param int addr: the virtual address to start looking from.:return: the virtual address of the previous BasicBlock end:rtype: int:Example:>>> hex(bv.entry_point)'0x1000149fL'>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))'0x100014a8L'>>> hex(bv.get_previous_basic_block_end_before(0x100014a8))'0x100014a8L'"""returncore.BNGetPreviousBasicBlockEndBeforeAddress(self.handle,addr)
[docs]defget_previous_data_before(self,addr:int)->int:"""``get_previous_data_before``:param int addr: the virtual address to start looking from.:return: the virtual address of the previous data (non-code) byte:rtype: int:Example:>>> hex(bv.get_previous_data_before(0x1000001))'0x1000000L'>>>"""returncore.BNGetPreviousDataBeforeAddress(self.handle,addr)
[docs]defget_previous_data_var_before(self,addr:int)->Optional['DataVariable']:"""``get_previous_data_var_before`` retrieves the previous :py:class:`DataVariable`, or None.:param int addr: the virtual address to start looking from.:return: the previous :py:class:`DataVariable`:rtype: DataVariable:Example:>>> bv.get_previous_data_var_before(0x1000003c)<var 0x10000000: int16_t>>>>"""prev_data_var_start=core.BNGetPreviousDataVariableStartBeforeAddress(self.handle,addr)ifprev_data_var_start==addr:returnNonevar=core.BNDataVariable()ifnotcore.BNGetDataVariableAtAddress(self.handle,prev_data_var_start,var):returnNoneresult=DataVariable.from_core_struct(var,self)core.BNFreeDataVariable(var)returnresult
[docs]defget_previous_data_var_start_before(self,addr:int)->int:"""``get_previous_data_var_start_before``:param int addr: the virtual address to start looking from.:return: the virtual address of the previous :py:class:`DataVariable`:rtype: int:Example:>>> hex(bv.get_previous_data_var_start_before(0x1000003c))'0x10000000L'>>> bv.get_data_var_at(0x10000000)<var 0x10000000: int16_t>>>>"""returncore.BNGetPreviousDataVariableStartBeforeAddress(self.handle,addr)
[docs]defget_linear_disassembly_position_at(self,addr:int,settings:Optional['_function.DisassemblySettings']=None)->'lineardisassembly.LinearViewCursor':"""``get_linear_disassembly_position_at`` instantiates a :py:class:`~binaryninja.lineardisassembly.LinearViewCursor` object for use in:py:func:`get_previous_linear_disassembly_lines` or :py:func:`get_next_linear_disassembly_lines`.:param int addr: virtual address of linear disassembly position:param DisassemblySettings settings: an instantiated :py:class:`~binaryninja.function.DisassemblySettings` object, defaults to None which will use default settings:return: An instantiated :py:class:`~binaryninja.lineardisassembly.LinearViewCursor` object for the provided virtual address:rtype: LinearViewCursor:Example:>>> settings = DisassemblySettings()>>> pos = bv.get_linear_disassembly_position_at(0x1000149f, settings)>>> lines = bv.get_previous_linear_disassembly_lines(pos)>>> lines[<0x1000149a: pop     esi>, <0x1000149b: pop     ebp>,<0x1000149c: retn    0xc>, <0x1000149f: >]"""pos=lineardisassembly.LinearViewCursor(lineardisassembly.LinearViewObject.disassembly(self,settings))pos.seek_to_address(addr)returnpos
[docs]defget_previous_linear_disassembly_lines(self,pos:'lineardisassembly.LinearViewCursor')->List['lineardisassembly.LinearDisassemblyLine']:"""``get_previous_linear_disassembly_lines`` retrieves a list of :py:class:`~binaryninja.lineardisassembly.LinearDisassemblyLine` objects for theprevious disassembly lines, and updates the LinearViewCursor passed in. This function can be calledrepeatedly to get more lines of linear disassembly.:param LinearViewCursor pos: Position to start retrieving linear disassembly lines from:return: a list of :py:class:`~binaryninja.lineardisassembly.LinearDisassemblyLine` objects for the previous lines.:Example:>>> settings = DisassemblySettings()>>> pos = bv.get_linear_disassembly_position_at(0x1000149a, settings)>>> bv.get_previous_linear_disassembly_lines(pos)[<0x10001488: push    dword [ebp+0x10 {arg_c}]>, ... , <0x1000149a: >]>>> bv.get_previous_linear_disassembly_lines(pos)[<0x10001483: xor     eax, eax  {0x0}>, ... , <0x10001488: >]"""result=[]whilelen(result)==0:ifnotpos.previous():returnresultresult=pos.linesreturnresult
[docs]defget_next_linear_disassembly_lines(self,pos:'lineardisassembly.LinearViewCursor')->List['lineardisassembly.LinearDisassemblyLine']:"""``get_next_linear_disassembly_lines`` retrieves a list of :py:class:`~binaryninja.lineardisassembly.LinearDisassemblyLine` objects for thenext disassembly lines, and updates the LinearViewCursor passed in. This function can be calledrepeatedly to get more lines of linear disassembly.:param LinearViewCursor pos: Position to start retrieving linear disassembly lines from:return: a list of :py:class:`~binaryninja.lineardisassembly.LinearDisassemblyLine` objects for the next lines.:Example:>>> settings = DisassemblySettings()>>> pos = bv.get_linear_disassembly_position_at(0x10001483, settings)>>> bv.get_next_linear_disassembly_lines(pos)[<0x10001483: xor     eax, eax  {0x0}>, <0x10001485: inc     eax  {0x1}>, ... , <0x10001488: >]>>> bv.get_next_linear_disassembly_lines(pos)[<0x10001488: push    dword [ebp+0x10 {arg_c}]>, ... , <0x1000149a: >]>>>"""result=[]whilelen(result)==0:result=pos.linesifnotpos.next():returnresultreturnresult
[docs]defget_linear_disassembly(self,settings:Optional['_function.DisassemblySettings']=None)->Iterator['lineardisassembly.LinearDisassemblyLine']:"""``get_linear_disassembly`` gets an iterator for all lines in the linear disassembly of the view for the givendisassembly settings... note::- linear_disassembly doesn't just return disassembly; it will return a single line from the linear view,\and thus will contain both data views, and disassembly.- **Warning:** In order to get deterministic output, the WaitForIL `DisassemblyOption` should be set to True.:param DisassemblySettings settings: instance specifying the desired output formatting. Defaults to None which will use default settings.:return: An iterator containing formatted disassembly lines.:rtype: LinearDisassemblyIterator:Example:>>> settings = DisassemblySettings()>>> lines = bv.get_linear_disassembly(settings)>>> for line in lines:...  print(line)...  break...cf fa ed fe 07 00 00 01  ........"""@dataclassclassLinearDisassemblyIterator:view:'BinaryView'settings:Optional['_function.DisassemblySettings']=Nonedef__iter__(self):pos=lineardisassembly.LinearViewCursor(lineardisassembly.LinearViewObject.disassembly(self.view,self.settings))whileTrue:lines=self.view.get_next_linear_disassembly_lines(pos)iflen(lines)==0:breakforlineinlines:yieldlinereturniter(LinearDisassemblyIterator(self,settings))
[docs]defparse_type_string(self,text:str,import_dependencies:bool=True)->Tuple['_types.Type','_types.QualifiedName']:"""``parse_type_string`` parses string containing C into a single type :py:class:`Type`.In contrast to the :py:func:`~binaryninja.platform.Platform.parse_types_from_source` or :py:func:`~binaryninja.platform.Platform.parse_types_from_source_file`, ``parse_type_string``can only load a single type, though it can take advantage of existing type information in the binaryview, while those two APIs do not.:param str text: C source code string of type to create:param import_dependencies: If Type Library types should be imported during parsing:return: A tuple of a :py:class:`Type` and type name:rtype: tuple(Type, QualifiedName):Example:>>> bv.parse_type_string("int foo")(<type: int32_t>, 'foo')>>>"""ifnotisinstance(text,str):raiseValueError("Source must be a string")result=core.BNQualifiedNameAndType()assertresultisnotNone,"core.BNQualifiedNameAndType returned None"try:errors=ctypes.c_char_p()type_list=core.BNQualifiedNameList()type_list.count=0ifnotcore.BNParseTypeString(self.handle,text,result,errors,type_list,import_dependencies):asserterrors.valueisnotNone,"core.BNParseTypeString returned 'errors' set to None"error_str=errors.value.decode("utf-8")core.free_string(errors)raiseSyntaxError(error_str)type_obj=_types.Type.create(core.BNNewTypeReference(result.type),platform=self.platform)name=_types.QualifiedName._from_core_struct(result.name)returntype_obj,namefinally:core.BNFreeQualifiedNameAndType(result)
[docs]defparse_types_from_string(self,text:str,options:Optional[List[str]]=None,include_dirs:Optional[List[str]]=None,import_dependencies:bool=True)->'_types.BasicTypeParserResult':"""``parse_types_from_string`` parses string containing C into a :py:class:`BasicTypeParserResult` objects. This APIunlike the :py:func:`~binaryninja.platform.Platform.parse_types_from_source` allows the reference of types already definedin the BinaryView.:param str text: C source code string of types, variables, and function types, to create:param options: Optional list of string options to be passed into the type parser:param include_dirs: Optional list of header search directories:param import_dependencies: If Type Library types should be imported during parsing:return: :py:class:`~binaryninja.typeparser.BasicTypeParserResult` (a SyntaxError is thrown on parse error):rtype: BasicTypeParserResult:Example:>>> bv.parse_types_from_string('int foo;\\nint bar(int x);\\nstruct bas{int x,y;};\\n')({types: {'bas': <type: struct bas>}, variables: {'foo': <type: int32_t>}, functions:{'bar':<type: int32_t(int32_t x)>}}, '')>>>"""ifnotisinstance(text,str):raiseValueError("Source must be a string")ifoptionsisNone:options=[]ifinclude_dirsisNone:include_dirs=[]parse=core.BNTypeParserResult()try:options_cpp=(ctypes.c_char_p*len(options))()for(i,s)inenumerate(options):options_cpp[i]=core.cstr(s)include_dirs_cpp=(ctypes.c_char_p*len(include_dirs))()for(i,s)inenumerate(include_dirs):include_dirs_cpp[i]=core.cstr(s)errors=ctypes.c_char_p()type_list=core.BNQualifiedNameList()type_list.count=0ifnotcore.BNParseTypesString(self.handle,text,options_cpp,len(options),include_dirs_cpp,len(include_dirs),parse,errors,type_list,import_dependencies):asserterrors.valueisnotNone,"core.BNParseTypesString returned errors set to None"error_str=errors.value.decode("utf-8")core.free_string(errors)raiseSyntaxError(error_str)type_dict:Mapping[_types.QualifiedName,_types.Type]={}variables:Mapping[_types.QualifiedName,_types.Type]={}functions:Mapping[_types.QualifiedName,_types.Type]={}foriinrange(0,parse.typeCount):name=_types.QualifiedName._from_core_struct(parse.types[i].name)type_dict[name]=_types.Type.create(core.BNNewTypeReference(parse.types[i].type),platform=self.platform)foriinrange(0,parse.variableCount):name=_types.QualifiedName._from_core_struct(parse.variables[i].name)variables[name]=_types.Type.create(core.BNNewTypeReference(parse.variables[i].type),platform=self.platform)foriinrange(0,parse.functionCount):name=_types.QualifiedName._from_core_struct(parse.functions[i].name)functions[name]=_types.Type.create(core.BNNewTypeReference(parse.functions[i].type),platform=self.platform)return_types.BasicTypeParserResult(type_dict,variables,functions)finally:core.BNFreeTypeParserResult(parse)
[docs]defparse_possiblevalueset(self,value:str,state:RegisterValueType,here:int=0)->'variable.PossibleValueSet':"""Evaluates a string representation of a PossibleValueSet into an instance of the ``PossibleValueSet`` value... note:: Values are evaluated based on the rules as specified for :py:func:`parse_expression` API. This implies that a ``ConstantValue [0x4000].d`` can be provided given that 4 bytes can be read at ``0x4000``. All constants are considered to be in hexadecimal form by default.The parser uses the following rules:- ConstantValue - ``<value>``- ConstantPointerValue - ``<value>``- StackFrameOffset - ``<value>``- SignedRangeValue - ``<value>:<value>:<value>{,<value>:<value>:<value>}*`` (Multiple ValueRanges can be provided by separating them by commas)- UnsignedRangeValue - ``<value>:<value>:<value>{,<value>:<value>:<value>}*`` (Multiple ValueRanges can be provided by separating them by commas)- InSetOfValues - ``<value>{,<value>}*``- NotInSetOfValues - ``<value>{,<value>}*``:param str value: PossibleValueSet value to be parsed:param RegisterValueType state: State for which the value is to be parsed:param int here: (optional) Base address for relative expressions, defaults to zero:rtype: PossibleValueSet:Example:>>> psv_c = bv.parse_possiblevalueset("400", RegisterValueType.ConstantValue)>>> psv_c<const 0x400>>>> psv_ur = bv.parse_possiblevalueset("1:10:1", RegisterValueType.UnsignedRangeValue)>>> psv_ur<unsigned ranges: [<range: 0x1 to 0x10>]>>>> psv_is = bv.parse_possiblevalueset("1,2,3", RegisterValueType.InSetOfValues)>>> psv_is<in set([0x1, 0x2, 0x3])>>>>"""result=core.BNPossibleValueSet()errors=ctypes.c_char_p()ifvalue==None:value=''ifnotcore.BNParsePossibleValueSet(self.handle,value,state,result,here,errors):iferrors:asserterrors.valueisnotNone,"core.BNParsePossibleValueSet returned errors set to None"error_str=errors.value.decode("utf-8")else:error_str="Error parsing specified PossibleValueSet"core.BNFreePossibleValueSet(result)core.free_string(errors)raiseValueError(error_str)returnvariable.PossibleValueSet(self.arch,result)
@propertydeftype_container(self)->'typecontainer.TypeContainer':"""Type Container for all types (user and auto) in the BinaryView. Any auto typesmodified through the Type Container will be converted into user types.:return: Full view Type Container"""container=core.BNGetAnalysisTypeContainer(self.handle)returntypecontainer.TypeContainer(handle=container)@propertydefauto_type_container(self)->'typecontainer.TypeContainer':"""Type Container for ONLY auto types in the BinaryView. Any changes to types willNOT promote auto types to user types.:return: Auto types only Type Container"""container=core.BNGetAnalysisAutoTypeContainer(self.handle)returntypecontainer.TypeContainer(handle=container)@propertydefuser_type_container(self)->'typecontainer.TypeContainer':"""Type Container for ONLY user types in the BinaryView.:return: User types only Type Container"""container=core.BNGetAnalysisUserTypeContainer(self.handle)returntypecontainer.TypeContainer(handle=container)
[docs]defget_type_by_name(self,name:'_types.QualifiedNameType')->Optional['_types.Type']:"""``get_type_by_name`` returns the defined type whose name corresponds with the provided ``name``:param QualifiedName name: Type name to lookup:return: A :py:class:`Type` or None if the type does not exist:rtype: Type or None:Example:>>> type, name = bv.parse_type_string("int foo")>>> bv.define_user_type(name, type)>>> bv.get_type_by_name(name)<type: int32_t>>>>"""_name=_types.QualifiedName(name)._to_core_struct()obj=core.BNGetAnalysisTypeByName(self.handle,_name)ifnotobj:returnNonereturn_types.Type.create(obj,platform=self.platform)
[docs]defget_type_by_id(self,id:str)->Optional['_types.Type']:"""``get_type_by_id`` returns the defined type whose unique identifier corresponds with the provided ``id``:param str id: Unique identifier to lookup:return: A :py:class:`Type` or None if the type does not exist:rtype: Type or None:Example:>>> type, name = bv.parse_type_string("int foo")>>> type_id = Type.generate_auto_type_id("source", name)>>> bv.define_type(type_id, name, type)>>> bv.get_type_by_id(type_id)<type: int32_t>>>>"""obj=core.BNGetAnalysisTypeById(self.handle,id)ifnotobj:returnNonereturn_types.Type.create(obj,platform=self.platform)
[docs]defget_type_name_by_id(self,id:str)->Optional['_types.QualifiedName']:"""``get_type_name_by_id`` returns the defined type name whose unique identifier corresponds with the provided ``id``:param str id: Unique identifier to lookup:return: A QualifiedName or None if the type does not exist:rtype: QualifiedName or None:Example:>>> type, name = bv.parse_type_string("int foo")>>> type_id = Type.generate_auto_type_id("source", name)>>> bv.define_type(type_id, name, type)'foo'>>> bv.get_type_name_by_id(type_id)'foo'>>>"""name=core.BNGetAnalysisTypeNameById(self.handle,id)result=_types.QualifiedName._from_core_struct(name)core.BNFreeQualifiedName(name)iflen(result)==0:returnNonereturnresult
[docs]defget_type_id(self,name:'_types.QualifiedNameType')->str:"""``get_type_id`` returns the unique identifier of the defined type whose name corresponds with theprovided ``name``:param QualifiedName name: Type name to lookup:return: The unique identifier of the type:rtype: str:Example:>>> type, name = bv.parse_type_string("int foo")>>> type_id = Type.generate_auto_type_id("source", name)>>> registered_name = bv.define_type(type_id, name, type)>>> bv.get_type_id(registered_name) == type_idTrue>>>"""_name=_types.QualifiedName(name)._to_core_struct()returncore.BNGetAnalysisTypeId(self.handle,_name)
[docs]defadd_type_library(self,lib:'typelibrary.TypeLibrary')->None:"""``add_type_library`` make the contents of a type library available for type/import resolution:param TypeLibrary lib: library to register with the view:rtype: None"""ifnotisinstance(lib,typelibrary.TypeLibrary):raiseValueError("must pass in a TypeLibrary object")core.BNAddBinaryViewTypeLibrary(self.handle,lib.handle)
[docs]defget_type_library(self,name:str)->Optional['typelibrary.TypeLibrary']:"""``get_type_library`` returns the TypeLibrary:param str name: Library name to lookup:return: The Type Library object, if any:rtype: TypeLibrary or None:Example:"""handle=core.BNGetBinaryViewTypeLibrary(self.handle,name)ifhandleisNone:returnNonereturntypelibrary.TypeLibrary(handle)
[docs]defis_type_auto_defined(self,name:'_types.QualifiedNameType')->bool:"""``is_type_auto_defined`` queries the user type list of name. If name is not in the *user* type list then the nameis considered an *auto* type.:param QualifiedName name: Name of type to query:return: True if the type is not a *user* type. False if the type is a *user* type.:Example:>>> bv.is_type_auto_defined("foo")True>>> bv.define_user_type("foo", bv.parse_type_string("struct {int x,y;}")[0])>>> bv.is_type_auto_defined("foo")False>>>"""_name=_types.QualifiedName(name)._to_core_struct()returncore.BNIsAnalysisTypeAutoDefined(self.handle,_name)
[docs]defdefine_type(self,type_id:str,default_name:Optional['_types.QualifiedNameType'],type_obj:StringOrType)->'_types.QualifiedName':"""``define_type`` registers a :py:class:`Type` ``type_obj`` of the given ``name`` in the global list of types forthe current :py:class:`BinaryView`. This method should only be used for automatically generated types.:param str type_id: Unique identifier for the automatically generated type:param QualifiedName default_name: Name of the type to be registered:param StringOrType type_obj: Type object to be registered:return: Registered name of the type. May not be the same as the requested name if the user has renamed types.:rtype: QualifiedName:Example:>>> type, name = bv.parse_type_string("int foo")>>> registered_name = bv.define_type(Type.generate_auto_type_id("source", name), name, type)>>> bv.get_type_by_name(registered_name)<type: int32_t>>>> registered_name = bv.define_type("mytypeid", None, "int bar")>>> bv.get_type_by_name(registered_name)<type: int32_t>"""ifisinstance(type_obj,str):(type_obj,new_name)=self.parse_type_string(type_obj)ifdefault_nameisNone:default_name=new_nameassertdefault_nameisnotNone,"default_name can only be None if named type is derived from string passed to type_obj"name=_types.QualifiedName(default_name)._to_core_struct()reg_name=core.BNDefineAnalysisType(self.handle,type_id,name,type_obj.handle)result=_types.QualifiedName._from_core_struct(reg_name)core.BNFreeQualifiedName(reg_name)returnresult
[docs]defdefine_user_type(self,name:Optional['_types.QualifiedNameType'],type_obj:StringOrType)->None:"""``define_user_type`` registers a :py:class:`Type` ``type_obj`` of the given ``name`` in the global list of usertypes for the current :py:class:`BinaryView`.:param QualifiedName name: Name of the user type to be registered:param StringOrType type_obj: Type object to be registered:rtype: None:Example:>>> type, name = bv.parse_type_string("int foo")>>> bv.define_user_type(name, type)>>> bv.get_type_by_name(name)<type: int32_t>>>> bv.define_user_type(None, "int bas")>>> bv.get_type_by_name("bas")<type: int32_t>"""ifisinstance(type_obj,str):(type_obj,new_name)=self.parse_type_string(type_obj)ifnameisNone:name=new_nameifnameisNone:raiseValueError("name can only be None if named type is derived from string passed to type_obj")_name=_types.QualifiedName(name)._to_core_struct()core.BNDefineUserAnalysisType(self.handle,_name,type_obj.handle)
[docs]defdefine_types(self,types:List[Tuple[str,Optional['_types.QualifiedNameType'],StringOrType]],progress_func:Optional[ProgressFuncType])->Mapping[str,'_types.QualifiedName']:"""``define_types`` registers multiple types as though calling :py:func:`define_type` multiple times.The difference with this plural version is that it is optimized for adding many typesat the same time, using knowledge of all types at add-time to improve runtime.There is an optional ``progress_func`` callback function in case you want updates for a long-running call... warning:: This method should only be used for automatically generated types, see :py:func:`define_user_types` for interactive plugin uses.The return values of this function provide a map of each type id and which name was chosen for that type(which may be different from the requested name).:param types: List of type ids/names/definitions for the new types. Check :py:func:`define_type` for more details.:param progress: Function to call for progress updates:return: A map of all the chosen names for the defined types with their ids."""api_types=(core.BNQualifiedNameTypeAndId*len(types))()fori,(type_id,default_name,type_obj)inenumerate(types):ifisinstance(type_obj,str):(type_obj,new_name)=self.parse_type_string(type_obj)ifdefault_nameisNone:default_name=new_nameassertdefault_nameisnotNone,"default_name can only be None if named type is derived from string passed to type_obj"api_types[i].name=_types.QualifiedName(default_name)._to_core_struct()api_types[i].id=core.cstr(type_id)api_types[i].type=type_obj.handleifprogress_func:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:progress_func(cur,total))else:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:True)result_ids=ctypes.POINTER(ctypes.c_char_p)()result_names=ctypes.POINTER(core.BNQualifiedName)()result_count=core.BNDefineAnalysisTypes(self.handle,api_types,len(types),progress_func_obj,None,result_ids,result_names)try:result={}foriinrange(result_count):id=core.pyNativeStr(result_ids[i])name=_types.QualifiedName._from_core_struct(result_names[i])result[id]=namereturnresultfinally:core.BNFreeStringList(result_ids,result_count)core.BNFreeTypeNameList(result_names,result_count)
[docs]defdefine_user_types(self,types:List[Tuple[Optional['_types.QualifiedNameType'],StringOrType]],progress_func:Optional[ProgressFuncType]):"""``define_user_types`` registers multiple types as though calling :py:func:`define_user_type` multiple times.The difference with this plural version is that it is optimized for adding many typesat the same time, using knowledge of all types at add-time to improve runtime.There is an optional ``progress_func`` callback function in case you want updates for a long-running call.:param types: List of type names/definitions for the new types. Check :py:func:`define_user_type` for more details.:param progress: Function to call for progress updates"""api_types=(core.BNQualifiedNameAndType*len(types))()fori,(default_name,type_obj)inenumerate(types):ifisinstance(type_obj,str):(type_obj,new_name)=self.parse_type_string(type_obj)ifdefault_nameisNone:default_name=new_nameassertdefault_nameisnotNone,"default_name can only be None if named type is derived from string passed to type_obj"api_types[i].name=_types.QualifiedName(default_name)._to_core_struct()api_types[i].type=type_obj.handleifprogress_func:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:progress_func(cur,total))else:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:True)core.BNDefineUserAnalysisTypes(self.handle,api_types,len(types),progress_func_obj,None)
[docs]defundefine_type(self,type_id:str)->None:"""``undefine_type`` removes a :py:class:`Type` from the global list of types for the current :py:class:`BinaryView`:param str type_id: Unique identifier of type to be undefined:rtype: None:Example:>>> type, name = bv.parse_type_string("int foo")>>> type_id = Type.generate_auto_type_id("source", name)>>> bv.define_type(type_id, name, type)>>> bv.get_type_by_name(name)<type: int32_t>>>> bv.undefine_type(type_id)>>> bv.get_type_by_name(name)>>>"""core.BNUndefineAnalysisType(self.handle,type_id)
[docs]defundefine_user_type(self,name:'_types.QualifiedNameType')->None:"""``undefine_user_type`` removes a :py:class:`Type` from the global list of user types for the current:py:class:`BinaryView`:param QualifiedName name: Name of user type to be undefined:rtype: None:Example:>>> type, name = bv.parse_type_string("int foo")>>> bv.define_user_type(name, type)>>> bv.get_type_by_name(name)<type: int32_t>>>> bv.undefine_user_type(name)>>> bv.get_type_by_name(name)>>>"""_name=_types.QualifiedName(name)._to_core_struct()core.BNUndefineUserAnalysisType(self.handle,_name)
[docs]defrename_type(self,old_name:'_types.QualifiedNameType',new_name:'_types.QualifiedNameType')->None:"""``rename_type`` renames a type in the global list of types for the current :py:class:`BinaryView`:param QualifiedName old_name: Existing name of type to be renamed:param QualifiedName new_name: New name of type to be renamed:rtype: None:Example:>>> type, name = bv.parse_type_string("int foo")>>> bv.define_user_type(name, type)>>> bv.get_type_by_name("foo")<type: int32_t>>>> bv.rename_type("foo", "bar")>>> bv.get_type_by_name("bar")<type: int32_t>>>>"""_old_name=_types.QualifiedName(old_name)._to_core_struct()_new_name=_types.QualifiedName(new_name)._to_core_struct()core.BNRenameAnalysisType(self.handle,_old_name,_new_name)
[docs]defget_system_call_type(self,id:int,platform:Optional['_platform.Platform']=None)->Optional['_types.Type']:ifplatformisNone:platform=self.platformifplatformisNone:raiseException("Unable to retrieve system call type without a platform")handle=core.BNGetAnalysisSystemCallType(self.handle,platform.handle,id)ifhandleisNone:returnNonereturn_types.Type.create(handle,platform=platform)
[docs]defget_system_call_name(self,id:int,platform:Optional['_platform.Platform']=None)->Optional[str]:ifplatformisNone:platform=self.platformifplatformisNone:raiseException("Unable to retrieve system call type without a platform")result=core.BNGetAnalysisSystemCallName(self.handle,platform.handle,id)ifresultisNone:returnNonereturnresult
[docs]defimport_library_type(self,name:str,lib:Optional[typelibrary.TypeLibrary]=None)->Optional['_types.Type']:"""``import_library_type`` recursively imports a type from the specified type library, or, ifno library was explicitly provided, the first type library associated with the current :py:class:`BinaryView`that provides the name requested.This may have the impact of loading other type libraries as dependencies on other type libraries are lazily resolvedwhen references to types provided by them are first encountered.Note that the name actually inserted into the view may not match the name as it exists in the type library inthe event of a name conflict. To aid in this, the :py:class:`Type` object returned is a `NamedTypeReference` tothe deconflicted name used.:param QualifiedName name::param TypeLibrary lib::return: a `NamedTypeReference` to the type, taking into account any renaming performed:rtype: Type"""_name=_types.QualifiedName(name)_lib=ctypes.POINTER(ctypes.POINTER(core.BNTypeLibrary))()iflibisnotNone:_lib.contents=lib.handleelse:_lib.contents=ctypes.POINTER(core.BNTypeLibrary)()handle=core.BNBinaryViewImportTypeLibraryType(self.handle,_lib,_name._to_core_struct())ifhandleisNone:returnNonereturn_types.Type.create(handle,platform=self.platform)
[docs]defimport_type_by_guid(self,guid:Union[str,uuid.UUID])->Optional['_types.Type']:"""``import_type_by_guid`` recursively imports a type interface given its GUID... note:: To support this type of lookup a type library must havecontain a metadata key called "type_guids" which is a mapDict[string_guid, string_type_name] orDict[string_guid, Tuple[string_type_name, type_library_name]]:param str guid: GUID of the COM interface to import:return: the object type, with any interior `NamedTypeReferences` renamed as necessary to be appropriate for the current view:rtype: Type"""ifnotisinstance(guid,str):guid=str(guid)ifself.archisNone:returnNoneiftype_handle:=core.BNBinaryViewImportTypeLibraryTypeByGuid(self.handle,guid):return_types.Type.create(type_handle,platform=self.platform)returnNone
[docs]defimport_library_object(self,name:str,lib:Optional[typelibrary.TypeLibrary]=None)->Optional[Tuple['typelibrary.TypeLibrary','_types.Type']]:"""``import_library_object`` recursively imports an object from the specified type library, or, if \no library was explicitly provided, the first type library associated with the current :py:class:`BinaryView` \that provides the name requested.This may have the impact of loading other type libraries as dependencies on other type libraries are lazily resolved \when references to types provided by them are first encountered... note:: If you are implementing a custom BinaryView and use this method to import object types, \you should then call ``record_imported_object`` with the details of where the object is located.:param QualifiedName name::param TypeLibrary lib::return: the object type, with any interior `NamedTypeReferences` renamed as necessary to be appropriate for the current view:rtype: Type"""_name=_types.QualifiedName(name)_lib=ctypes.POINTER(ctypes.POINTER(core.BNTypeLibrary))()iflibisnotNone:_lib.contents=lib.handleelse:_lib.contents=ctypes.POINTER(core.BNTypeLibrary)()handle=core.BNBinaryViewImportTypeLibraryObject(self.handle,_lib,_name._to_core_struct())ifhandleisNone:returnNonereturn_types.Type.create(handle,platform=self.platform)
[docs]defexport_type_to_library(self,lib:typelibrary.TypeLibrary,name:Optional[str],type_obj:StringOrType)->None:"""Recursively exports ``type_obj`` into ``lib`` as a type with a ``name``.This should be used to store type definitions with no symbol information. For example, `color` might be a typeof `enum {RED=0, ORANGE=1, YELLOW=2, ...}` used by this library. If you have a function, variable, or otherobject that is exported, you probably want :py:meth:`export_object_to_library` instead.As other referenced types are encountered, they are either copied into the destination type library orelse the type library that provided the referenced type is added as a dependency for the destination library.:param TypeLibrary lib::param QualifiedName name::param StringOrType type_obj::rtype: None"""_name=NoneifnameisnotNone:_name=_types.QualifiedName(name)ifnotisinstance(lib,typelibrary.TypeLibrary):raiseTypeError("lib must be a TypeLibrary object")ifisinstance(type_obj,str):(type_obj,new_name)=self.parse_type_string(type_obj)ifnameisNone:_name=new_nameifnotisinstance(type_obj,(_types.Type,_types.TypeBuilder)):raiseTypeError("type_obj must be a Type object")if_nameisNone:raiseValueError("name can only be None if named type is derived from string passed to type_obj")core.BNBinaryViewExportTypeToTypeLibrary(self.handle,lib.handle,_name._to_core_struct(),type_obj.handle)
[docs]defexport_object_to_library(self,lib:typelibrary.TypeLibrary,name:Optional[str],type_obj:StringOrType)->None:"""Recursively exports ``type_obj`` into ``lib`` as an object with a ``name``.This should be used to store definitions for functions, variables, and other things that are named symbols.For example, `MessageBoxA` might be the name of a function with the type `int ()(HWND, LPCSTR, LPCSTR, UINT)`.If you just want to store a type definition, you probably want :py:meth:`export_type_to_library`.As other referenced types are encountered, they are either copied into the destination type library orelse the type library that provided the referenced type is added as a dependency for the destination library.:param TypeLibrary lib::param QualifiedName name::param StringOrType type_obj::rtype: None"""_name=NoneifnameisnotNone:_name=_types.QualifiedName(name)ifnotisinstance(lib,typelibrary.TypeLibrary):raiseTypeError("lib must be a TypeLibrary object")ifisinstance(type_obj,str):(type_obj,new_name)=self.parse_type_string(type_obj)ifnameisNone:_name=new_nameifnotisinstance(type_obj,(_types.Type,_types.TypeBuilder)):raiseTypeError("type_obj must be a Type object")if_nameisNone:raiseValueError("name can only be None if named type is derived from string passed to type_obj")core.BNBinaryViewExportObjectToTypeLibrary(self.handle,lib.handle,_name._to_core_struct(),type_obj.handle)
[docs]defset_manual_type_source_override(self,entries:Mapping['_types.QualifiedName',Tuple['_types.QualifiedName',str]]):"""This allows for fine-grained control over how types from this BinaryView are exported to a TypeLibraryby `export_type_to_library` and `export_object_to_library`. Types identified by the keys of the dictwill NOT be exported to the destination TypeLibrary, but will instead be treated as a type that hadcome from the string component of the value tuple. This results in the destination TypeLibrary gaininga new dependency.This is useful if a BinaryView was automatically marked up with a lot of debug information but youwant to export only a subset of that information into a new TypeLibrary. By creating a description ofwhich local types correspond to types in other already extant libraries, those types will be avoidedduring the recursive export.This data is not persisted and does not impact analysis.For example, if a BinaryView contains the following types:.. code-block:: cstruct RECT { ... }; // omittedstruct ContrivedExample { RECT rect; };Then the following python:.. code-block:: pythonoverrides = {"RECT": ("tagRECT", "winX64common")}bv.set_manual_type_source_override(overrides)bv.export_type_to_library(dest_new_typelib, "ContrivedExample", bv.get_type_by_name("ContrivedExample"))Results in dest_new_typelib only having ContrivedExample added, and "RECT" being inserted as a dependencyto a the type "tagRECT" found in the typelibrary "winX64common""""count=len(entries)src_names=(core.BNQualifiedName*count)()dst_names=(core.BNQualifiedName*count)()lib_names=(ctypes.c_char_p*count)()for(i,src,(dst,lib))inenumerate(entries.items()):src_names[i]=src._to_core_struct()dst_names[i]=dst._to_core_struct()lib_names[i]=lib.encode("utf-8")core.BNBinaryViewSetManualDependencies(self.handle,src_names,dst_names,lib_names,count)
[docs]defrecord_imported_object_library(self,lib:typelibrary.TypeLibrary,name:str,addr:int,platform:Optional['_platform.Platform']=None)->None:"""``record_imported_object_library`` should be called by custom py:py:class:`BinaryView` implementationswhen they have successfully imported an object from a type library (e.g. a symbol's type).Values recorded with this function will then be queryable via ``lookup_imported_object_library``.:param lib: Type Library containing the imported type:param name: Name of the object in the type library:param addr: address of symbol at import site:param platform: Platform of symbol at import site:rtype: None"""ifplatformisNone:platform=self.platformifplatformisNone:raiseException("Unable to record imported object library without a platform")core.BNBinaryViewRecordImportedObjectLibrary(self.handle,platform.handle,addr,lib.handle,_types.QualifiedName(name)._to_core_struct())
[docs]deflookup_imported_object_library(self,addr:int,platform:Optional['_platform.Platform']=None)->Optional[Tuple[typelibrary.TypeLibrary,'_types.QualifiedName']]:"""``lookup_imported_object_library`` gives you details of which type library and name was used to determinethe type of a symbol at a given address:param addr: address of symbol at import site:param platform: Platform of symbol at import site:return: A tuple of [TypeLibrary, QualifiedName] with the library and name used, or None if it was not imported:rtype: Tuple[TypeLibrary, QualifiedName]"""ifplatformisNone:platform=self.platformresult_lib=(ctypes.POINTER(core.BNTypeLibrary)*1)()result_name=(core.BNQualifiedName*1)()ifnotcore.BNBinaryViewLookupImportedObjectLibrary(self.handle,platform.handle,addr,result_lib,result_name):returnNonelib=typelibrary.TypeLibrary(result_lib[0])name=_types.QualifiedName._from_core_struct(result_name[0])core.BNFreeQualifiedName(result_name)returnlib,name
[docs]deflookup_imported_type_library(self,name:'_types.QualifiedNameType')->Optional[Tuple[typelibrary.TypeLibrary,'_types.QualifiedName']]:"""``lookup_imported_type_library`` gives you details of from which type library and namea given type in the analysis was imported.:param name: Name of type in analysis:return: A tuple of [TypeLibrary, QualifiedName] with the library and name used, or None if it was not imported:rtype: Optional[Tuple[TypeLibrary, QualifiedName]]"""name=_types.QualifiedName(name)result_lib=(ctypes.POINTER(core.BNTypeLibrary)*1)()result_name=(core.BNQualifiedName*1)()ifnotcore.BNBinaryViewLookupImportedTypeLibrary(self.handle,name._to_core_struct(),result_lib,result_name):returnNonelib=typelibrary.TypeLibrary(result_lib[0])name=_types.QualifiedName._from_core_struct(result_name[0])core.BNFreeQualifiedName(result_name)returnlib,name
[docs]defattach_type_archive(self,archive:'typearchive.TypeArchive'):"""Attach a given type archive to the analysis and try to connect to it.If attaching was successful, names from that archive will become available to pull,but no types will actually be associated by calling this.:param archive: New archive"""attached=self.attach_type_archive_by_id(archive.id,archive.path)assertattached==archive
[docs]defattach_type_archive_by_id(self,id:str,path:str)->Optional['typearchive.TypeArchive']:"""Attach a type archive to the owned analysis and try to connect to it.If attaching was successful, names from that archive will become available to pull,but no types will actually be associated by calling this.The behavior of this function is rather complicated, in an attempt to enable theability to have attached, but disconnected Type Archives.Normal operation:If there was no previously connected Type Archive whose id matches `id`, and thefile at `path` contains a Type Archive whose id matches `id`, it will beattached and connected.Edge-cases:If there was a previously connected Type Archive whose id matches `id`, nothingwill happen, and it will simply be returned.If the file at `path` does not exist, nothing will happen and None will be returned.If the file at `path` exists but does not contain a Type Archive whose id matches `id`,nothing will happen and None will be returned.If there was a previously attached but disconnected Type Archive whose id matches `id`,and the file at `path` contains a Type Archive whose id matches `id`, thepreviously attached Type Archive will have its saved path updated to pointto `path`. The Type Archive at `path` will be connected and returned.:param id: Id of Type Archive to attach:param path: Path to file of Type Archive to attach:return: Attached archive object, if it could be connected."""archive=core.BNBinaryViewAttachTypeArchive(self.handle,id,path)ifnotarchive:returnNonereturntypearchive.TypeArchive(handle=archive)
[docs]defdetach_type_archive(self,archive:'typearchive.TypeArchive'):"""Detach from a type archive, breaking all associations to types within the archive:param archive: Type archive to detach"""self.detach_type_archive_by_id(archive.id)
[docs]defdetach_type_archive_by_id(self,id:str):"""Detach from a type archive, breaking all associations to types within the archive:param id: Id of archive to detach"""ifnotcore.BNBinaryViewDetachTypeArchive(self.handle,id):raiseRuntimeError("BNBinaryViewDetachTypeArchive")
[docs]defget_type_archive(self,id:str)->Optional['typearchive.TypeArchive']:"""Look up a connected archive by its id:param id: Id of archive:return: Archive, if one exists with that id. Otherwise None"""result=core.BNBinaryViewGetTypeArchive(self.handle,id)ifresultisNone:returnNonereturntypearchive.TypeArchive(result)
[docs]defget_type_archive_path(self,id:str)->Optional[str]:"""Look up the path for an attached (but not necessarily connected) type archive by its id:param id: Id of archive:return: Archive path, if it is attached. Otherwise None."""result=core.BNBinaryViewGetTypeArchivePath(self.handle,id)ifresultisNone:returnNonereturnresult
@propertydeftype_archive_type_names(self)->Mapping['_types.QualifiedName',List[Tuple['typearchive.TypeArchive',str]]]:"""Get a list of all available type names in all connected archives, and their archive/type id pair:return: name <-> [(archive, archive type id)] for all type names"""result={}archives=self.connected_type_archivesforarchiveinarchives:for(id,name)inarchive.type_names_and_ids.items():ifnameinresult:result[name].append((archive,id))else:result[name]=[(archive,id)]returnresult
[docs]defget_type_archives_for_type_name(self,name:'_types.QualifiedNameType')->List[Tuple['typearchive.TypeArchive',str]]:"""Get a list of all connected type archives that have a given type name:return: (archive, archive type id) for all archives"""name=_types.QualifiedName(name)archive_ids=ctypes.POINTER(ctypes.c_char_p)()type_ids=ctypes.POINTER(ctypes.c_char_p)()id_count=core.BNBinaryViewGetTypeArchiveTypeNames(self.handle,name._to_core_struct(),archive_ids,type_ids)ids=[]type_archives=self.connected_type_archivestype_archives_by_id={}forarchiveintype_archives:type_archives_by_id[archive.id]=archivetry:forjinrange(0,id_count):ids.append((type_archives_by_id[core.pyNativeStr(archive_ids[j])],core.pyNativeStr(type_ids[j])))returnidsfinally:core.BNFreeStringList(archive_ids,id_count)core.BNFreeStringList(type_ids,id_count)
@propertydefassociated_type_archive_types(self)->Mapping['_types.QualifiedName',Tuple[Optional['typearchive.TypeArchive'],str]]:"""Get a list of all types in the analysis that are associated with attached type archives:return: Map of all analysis types to their corresponding archive / id. If a type is associated with a disconnected type archive, the archive will be None."""result={}type_archives=self.attached_type_archivestype_archives_by_id={}for(archive_id,_)intype_archives.items():type_archives_by_id[archive_id]=self.get_type_archive(archive_id)fortype_id,(archive_id,archive_type_id)inself.associated_type_archive_type_ids.items():name=self.get_type_name_by_id(type_id)ifnameisNone:continueresult[name]=(type_archives_by_id.get(archive_id,None),archive_type_id)returnresult@propertydefassociated_type_archive_type_ids(self)->Mapping[str,Tuple[str,str]]:"""Get a list of all types in the analysis that are associated with type archives:return: Map of all analysis types to their corresponding archive / id"""type_ids=ctypes.POINTER(ctypes.c_char_p)()archive_ids=ctypes.POINTER(ctypes.c_char_p)()archive_type_ids=ctypes.POINTER(ctypes.c_char_p)()count=core.BNBinaryViewGetAssociatedTypeArchiveTypes(self.handle,type_ids,archive_ids,archive_type_ids)result={}try:foriinrange(0,count):type_id=core.pyNativeStr(type_ids[i])archive_id=core.pyNativeStr(archive_ids[i])archive_type_id=core.pyNativeStr(archive_type_ids[i])result[type_id]=(archive_id,archive_type_id)returnresultfinally:core.BNFreeStringList(type_ids,count)core.BNFreeStringList(archive_ids,count)core.BNFreeStringList(archive_type_ids,count)
[docs]defget_associated_types_from_archive(self,archive:'typearchive.TypeArchive')->Mapping['_types.QualifiedName',str]:"""Get a list of all types in the analysis that are associated with a specific type archive:return: Map of all analysis types to their corresponding archive id"""result={}fortype_id,archive_type_idinself.get_associated_types_from_archive_by_id(archive.id).items():name=self.get_type_name_by_id(type_id)ifnameisNone:continueresult[name]=archive_type_idreturnresult
[docs]defget_associated_types_from_archive_by_id(self,archive_id:str)->Mapping[str,str]:"""Get a list of all types in the analysis that are associated with a specific type archive:return: Map of all analysis types to their corresponding archive id"""type_ids=ctypes.POINTER(ctypes.c_char_p)()archive_type_ids=ctypes.POINTER(ctypes.c_char_p)()count=core.BNBinaryViewGetAssociatedTypesFromArchive(self.handle,archive_id,type_ids,archive_type_ids)result={}try:foriinrange(0,count):type_id=core.pyNativeStr(type_ids[i])archive_type_id=core.pyNativeStr(archive_type_ids[i])result[type_id]=archive_type_idreturnresultfinally:core.BNFreeStringList(type_ids,count)core.BNFreeStringList(archive_type_ids,count)
[docs]defget_associated_type_archive_type_target(self,name:'_types.QualifiedNameType')->Optional[Tuple[Optional['typearchive.TypeArchive'],str]]:"""Determine the target archive / type id of a given analysis type:param name: Analysis type:return: (archive, archive type id) if the type is associated. None otherwise."""type_id=self.get_type_id(name)iftype_id=='':returnNoneresult=self.get_associated_type_archive_type_target_by_id(type_id)ifresultisNone:returnNonearchive_id,type_id=resultarchive=self.get_type_archive(archive_id)returnarchive,type_id
[docs]defget_associated_type_archive_type_target_by_id(self,type_id:str)->Optional[Tuple[str,str]]:"""Determine the target archive / type id of a given analysis type:param type_id: Analysis type id:return: (archive id, archive type id) if the type is associated. None otherwise."""archive_id=ctypes.c_char_p()archive_type_id=ctypes.c_char_p()ifnotcore.BNBinaryViewGetAssociatedTypeArchiveTypeTarget(self.handle,type_id,archive_id,archive_type_id):returnNoneresult=(core.pyNativeStr(archive_id.value),core.pyNativeStr(archive_type_id.value))core.free_string(archive_id)core.free_string(archive_type_id)returnresult
[docs]defget_associated_type_archive_type_source(self,archive:'typearchive.TypeArchive',archive_type:'_types.QualifiedNameType')->Optional['_types.QualifiedName']:"""Determine the local source type name for a given archive type:param archive: Target type archive:param archive_type: Name of target archive type:return: Name of source analysis type, if this type is associated. None otherwise."""archive_type_id=archive.get_type_id(archive_type)ifarchive_type_idisNone:returnNoneresult=self.get_associated_type_archive_type_source_by_id(archive.id,archive_type_id)ifresultisNone:returnNonereturnself.get_type_name_by_id(result)
[docs]defget_associated_type_archive_type_source_by_id(self,archive_id:str,archive_type_id:str)->Optional[str]:"""Determine the local source type id for a given archive type:param archive_id: Id of target type archive:param archive_type_id: Id of target archive type:return: Id of source analysis type, if this type is associated. None otherwise."""type_id=ctypes.c_char_p()ifnotcore.BNBinaryViewGetAssociatedTypeArchiveTypeSource(self.handle,archive_id,archive_type_id,type_id):returnNoneresult=core.pyNativeStr(type_id.value)core.free_string(type_id)returnresult
[docs]defdisassociate_type_archive_type(self,type:'_types.QualifiedNameType')->bool:"""Disassociate an associated type, so that it will no longer receive updates from its connected type archive:param type: Name of type in analysis:return: True if successful"""type_id=self.get_type_id(type)iftype_id=='':returnFalsereturnself.disassociate_type_archive_type_by_id(type_id)
[docs]defdisassociate_type_archive_type_by_id(self,type_id:str)->bool:"""Disassociate an associated type id, so that it will no longer receive updates from its connected type archive:param type_id: Id of type in analysis:return: True if successful"""returncore.BNBinaryViewDisassociateTypeArchiveType(self.handle,type_id)
[docs]defpull_types_from_archive(self,archive:'typearchive.TypeArchive',names:List['_types.QualifiedNameType']) \->Optional[Mapping['_types.QualifiedName',Tuple['_types.QualifiedName','_types.Type']]]:"""Pull types from a type archive, updating them and any dependencies:param archive: Target type archive:param names: Names of desired types in type archive:return: { name: (name, type) } Mapping from archive name to (analysis name, definition), None on error"""archive_type_ids=[]fornameinnames:archive_type_id=archive.get_type_id(name)ifarchive_type_idisNone:returnNonearchive_type_ids.append(archive_type_id)result=self.pull_types_from_archive_by_id(archive.id,archive_type_ids)ifresultisNone:returnNoneresults={}for(archive_type_id,analysis_type_id)inresult.items():results[archive.get_type_name_by_id(archive_type_id)]=(self.get_type_name_by_id(analysis_type_id),self.get_type_by_id(analysis_type_id))returnresults
[docs]defpull_types_from_archive_by_id(self,archive_id:str,archive_type_ids:List[str]) \->Optional[Mapping[str,str]]:"""Pull types from a type archive by id, updating them and any dependencies:param archive_id: Target type archive id:param archive_type_ids: Ids of desired types in type archive:return: { id: id } Mapping from archive type id to analysis type id, None on error"""api_ids=(ctypes.c_char_p*len(archive_type_ids))()fori,idinenumerate(archive_type_ids):api_ids[i]=core.cstr(id)updated_archive_type_strs=ctypes.POINTER(ctypes.c_char_p)()updated_analysis_type_strs=ctypes.POINTER(ctypes.c_char_p)()updated_type_count=ctypes.c_size_t(0)try:ifnotcore.BNBinaryViewPullTypeArchiveTypes(self.handle,archive_id,api_ids,len(archive_type_ids),updated_archive_type_strs,updated_analysis_type_strs,updated_type_count):returnNoneresults={}foriinrange(0,updated_type_count.value):results[core.pyNativeStr(updated_archive_type_strs[i])]=core.pyNativeStr(updated_analysis_type_strs[i])returnresultsfinally:core.BNFreeStringList(updated_archive_type_strs,updated_type_count.value)core.BNFreeStringList(updated_analysis_type_strs,updated_type_count.value)
[docs]defpush_types_to_archive(self,archive:'typearchive.TypeArchive',names:List['_types.QualifiedNameType']) \->Optional[Mapping['_types.QualifiedName',Tuple['_types.QualifiedName','_types.Type']]]:"""Push a collection of types, and all their dependencies, into a type archive:param archive: Target type archive:param names: Names of types in analysis:return: { name: (name, type) } Mapping from analysis name to (archive name, definition), None on error"""analysis_type_ids=[]fornameinnames:analysis_type_id=self.get_type_id(name)ifanalysis_type_idisNone:returnNoneanalysis_type_ids.append(analysis_type_id)result=self.push_types_to_archive_by_id(archive.id,analysis_type_ids)ifresultisNone:returnNoneresults={}for(analysis_type_id,archive_type_id)inresult.items():results[self.get_type_name_by_id(analysis_type_id)]=(archive.get_type_name_by_id(archive_type_id),archive.get_type_by_id(archive_type_id))returnresults
[docs]defpush_types_to_archive_by_id(self,archive_id:str,type_ids:List[str]) \->Optional[Mapping[str,str]]:"""Push a collection of types, and all their dependencies, into a type archive:param archive_id: Id of target type archive:param type_ids: Ids of types in analysis:return: True if successful"""api_ids=(ctypes.c_char_p*len(type_ids))()fori,idinenumerate(type_ids):api_ids[i]=core.cstr(id)updated_analysis_type_strs=ctypes.POINTER(ctypes.c_char_p)()updated_archive_type_strs=ctypes.POINTER(ctypes.c_char_p)()updated_type_count=ctypes.c_size_t(0)try:ifnotcore.BNBinaryViewPushTypeArchiveTypes(self.handle,archive_id,api_ids,len(type_ids),updated_analysis_type_strs,updated_archive_type_strs,updated_type_count):returnNoneresults={}foriinrange(0,updated_type_count.value):results[core.pyNativeStr(updated_analysis_type_strs[i])]=core.pyNativeStr(updated_archive_type_strs[i])returnresultsfinally:core.BNFreeStringList(updated_analysis_type_strs,updated_type_count.value)core.BNFreeStringList(updated_archive_type_strs,updated_type_count.value)
[docs]defregister_platform_types(self,platform:'_platform.Platform')->None:"""``register_platform_types`` ensures that the platform-specific types for a :py:class:`Platform` are availablefor the current :py:class:`BinaryView`. This is automatically performed when adding a new function or settingthe default platform.:param Platform platform: Platform containing types to be registered:rtype: None:Example:>>> platform = Platform["linux-x86"]>>> bv.register_platform_types(platform)>>>"""core.BNRegisterPlatformTypes(self.handle,platform.handle)
[docs]deflookup_imported_type_platform(self,name:'_types.QualifiedNameType')->Optional[Tuple['_platform.Platform','_types.QualifiedName']]:"""``lookup_imported_type_platform`` gives you details of from which platform and namea given type in the analysis was imported.:param name: Name of type in analysis:return: A tuple of [Platform, QualifiedName] with the platform and name used, or None if it was not imported:rtype: Optional[Tuple[Platform, QualifiedName]]"""name=_types.QualifiedName(name)result_platform=(ctypes.POINTER(core.BNPlatform)*1)()result_name=(core.BNQualifiedName*1)()ifnotcore.BNLookupImportedTypePlatform(self.handle,name._to_core_struct(),result_platform,result_name):returnNoneplatform=_platform.CorePlatform._from_cache(handle=result_platform[0])name=_types.QualifiedName._from_core_struct(result_name[0])core.BNFreeQualifiedName(result_name)returnplatform,name
[docs]deffind_next_data(self,start:int,data:bytes,flags:FindFlag=FindFlag.FindCaseSensitive)->Optional[int]:"""``find_next_data`` searches for the bytes ``data`` starting at the virtual address ``start`` until the end of the BinaryView.:param int start: virtual address to start searching from.:param Union[bytes, bytearray, str] data: data to search for:param FindFlag flags: (optional) defaults to case-insensitive data search==================== ============================FindFlag             Description==================== ============================FindCaseSensitive    Case-sensitive searchFindCaseInsensitive  Case-insensitive search==================== ============================"""ifnotisinstance(data,bytes):raiseTypeError("Must be bytes, bytearray, or str")else:buf=databuffer.DataBuffer(data)result=ctypes.c_ulonglong()ifnotcore.BNFindNextData(self.handle,start,buf.handle,result,flags):returnNonereturnresult.value
[docs]deffind_next_text(self,start:int,text:str,settings:Optional[_function.DisassemblySettings]=None,flags:int=FindFlag.FindCaseSensitive,graph_type:_function.FunctionViewTypeOrName=FunctionGraphType.NormalFunctionGraph)->Optional[int]:"""``find_next_text`` searches for string ``text`` occurring in the linear view output starting at the virtualaddress ``start`` until the end of the BinaryView.:param int start: virtual address to start searching from.:param str text: text to search for:param DisassemblySettings settings: disassembly settings:param FindFlag flags: (optional) bit-flags list of options, defaults to case-insensitive data search==================== ============================FindFlag             Description==================== ============================FindCaseSensitive    Case-sensitive searchFindCaseInsensitive  Case-insensitive searchFindIgnoreWhitespace Ignore whitespace characters==================== ============================:param FunctionViewType graph_type: the IL to search within"""ifnotisinstance(text,str):raiseTypeError("text parameter is not str type")ifsettingsisNone:settings=_function.DisassemblySettings()ifnotisinstance(settings,_function.DisassemblySettings):raiseTypeError("settings parameter is not DisassemblySettings type")result=ctypes.c_ulonglong()graph_type=_function.FunctionViewType(graph_type)._to_core_struct()ifnotcore.BNFindNextText(self.handle,start,text,result,settings.handle,flags,graph_type):returnNonereturnresult.value
[docs]deffind_next_constant(self,start:int,constant:int,settings:Optional[_function.DisassemblySettings]=None,graph_type:_function.FunctionViewTypeOrName=FunctionGraphType.NormalFunctionGraph)->Optional[int]:"""``find_next_constant`` searches for integer constant ``constant`` occurring in the linear view output starting at the virtualaddress ``start`` until the end of the BinaryView.:param int start: virtual address to start searching from.:param int constant: constant to search for:param DisassemblySettings settings: disassembly settings:param FunctionViewType graph_type: the IL to search within"""ifnotisinstance(constant,int):raiseTypeError("constant parameter is not integral type")ifsettingsisNone:settings=_function.DisassemblySettings()ifnotisinstance(settings,_function.DisassemblySettings):raiseTypeError("settings parameter is not DisassemblySettings type")result=ctypes.c_ulonglong()graph_type=_function.FunctionViewType(graph_type)._to_core_struct()ifnotcore.BNFindNextConstant(self.handle,start,constant,result,settings.handle,graph_type):returnNonereturnresult.value
[docs]classQueueGenerator:
[docs]def__init__(self,t,results):self.thread=tself.results=resultst.start()
def__iter__(self):returnselfdef__next__(self):whileTrue:ifnotself.results.empty():returnself.results.get()if(notself.thread.is_alive())andself.results.empty():raiseStopIteration
[docs]deffind_all_data(self,start:int,end:int,data:bytes,flags:FindFlag=FindFlag.FindCaseSensitive,progress_func:Optional[ProgressFuncType]=None,match_callback:Optional[DataMatchCallbackType]=None)->QueueGenerator:"""``find_all_data`` searches for the bytes ``data`` starting at the virtual address ``start``until the virtual address ``end``. Once a match is found, the ``match_callback`` is called.:param int start: virtual address to start searching from.:param int end: virtual address to end the search.:param Union[bytes, bytearray, str] data: data to search for:param FindFlag flags: (optional) defaults to case-insensitive data search==================== ============================FindFlag             Description==================== ============================FindCaseSensitive    Case-sensitive searchFindCaseInsensitive  Case-insensitive search==================== ============================:param callback progress_func: optional function to be called with the current progress \and total count. This function should return a boolean value that decides whether the \search should continue or stop:param callback match_callback: function that gets called when a match is found. The \callback takes two parameters, i.e., the address of the match, and the actual DataBuffer \that satisfies the search. If this parameter is None, this function becomes a generator \and yields a tuple of the matching address and the matched DataBuffer. This function \can return a boolean value that decides whether the search should continue or stop.:rtype QueueGenerator: A generator object that will yield all the found results"""ifnotisinstance(data,bytes):raiseTypeError("data parameter must be bytes, bytearray, or str")buf=databuffer.DataBuffer(data)ifnotisinstance(flags,FindFlag):raiseTypeError('flag parameter must have type FindFlag')ifprogress_func:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:progress_func(cur,total))else:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:True)ifmatch_callback:# the `not match_callback(...) is False` tolerates the users who forget to return# `True` from inside the callbackmatch_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.POINTER(core.BNDataBuffer))(lambdactxt,addr,match:notmatch_callback(addr,databuffer.DataBuffer(handle=match))isFalse)returncore.BNFindAllDataWithProgress(self.handle,start,end,buf.handle,flags,None,progress_func_obj,None,match_callback_obj)else:results=queue.Queue()match_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.POINTER(core.BNDataBuffer))(lambdactxt,addr,match:results.put((addr,databuffer.DataBuffer(handle=match)))orTrue)t=threading.Thread(target=lambda:core.BNFindAllDataWithProgress(self.handle,start,end,buf.handle,flags,None,progress_func_obj,None,match_callback_obj))returnself.QueueGenerator(t,results)
def_LinearDisassemblyLine_convertor(self,lines:core.BNLinearDisassemblyLineHandle)->'lineardisassembly.LinearDisassemblyLine':line=lineardisassembly.LinearDisassemblyLine._from_core_struct(lines[0])core.BNFreeLinearDisassemblyLines(lines,1)returnline
[docs]deffind_all_text(self,start:int,end:int,text:str,settings:Optional[_function.DisassemblySettings]=None,flags=FindFlag.FindCaseSensitive,graph_type:_function.FunctionViewTypeOrName=FunctionGraphType.NormalFunctionGraph,progress_func=None,match_callback=None)->QueueGenerator:"""``find_all_text`` searches for string ``text`` occurring in the linear view output startingat the virtual address ``start`` until the virtual address ``end``. Once a match is found,the ``match_callback`` is called.:param int start: virtual address to start searching from.:param int end: virtual address to end the search.:param str text: text to search for:param DisassemblySettings settings: DisassemblySettings object used to render the text \to be searched:param FindFlag flags: (optional) bit-flags list of options, defaults to case-insensitive data search==================== ============================FindFlag             Description==================== ============================FindCaseSensitive    Case-sensitive searchFindCaseInsensitive  Case-insensitive searchFindIgnoreWhitespace Ignore whitespace characters==================== ============================:param FunctionViewType graph_type: the IL to search within:param callback progress_func: optional function to be called with the current progress \and total count. This function should return a boolean value that decides whether the \search should continue or stop:param callback match_callback: function that gets called when a match is found. The \callback takes three parameters, i.e., the address of the match, and the actual string \that satisfies the search, and the LinearDisassemblyLine that contains the matching \line. If this parameter is None, this function becomes a generator \and yields a tuple of the matching address, the matched string, and the matching \LinearDisassemblyLine. This function can return a boolean value that decides whether \the search should continue or stop:rtype QueueGenerator: A generator object that will yield all the found results"""ifnotisinstance(text,str):raiseTypeError("text parameter is not str type")ifsettingsisNone:settings=_function.DisassemblySettings()settings.set_option(DisassemblyOption.ShowAddress,False)settings.set_option(DisassemblyOption.ShowOpcode,False)settings.set_option(DisassemblyOption.ShowVariableTypesWhenAssigned,True)settings.set_option(DisassemblyOption.WaitForIL,True)ifnotisinstance(settings,_function.DisassemblySettings):raiseTypeError("settings parameter is not DisassemblySettings type")ifnotisinstance(flags,FindFlag):raiseTypeError('flag parameter must have type FindFlag')graph_type=_function.FunctionViewType(graph_type)._to_core_struct()ifprogress_func:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:progress_func(cur,total))else:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:True)ifmatch_callback:# The reason we use `not match_callback(...) is False` is the user tends to happily# deal with the returned data, but forget to return True at the end of the callback.# Then only the first result will be returned.match_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_char_p,ctypes.POINTER(core.BNLinearDisassemblyLine))(lambdactxt,addr,match,line:notmatch_callback(addr,match,self._LinearDisassemblyLine_convertor(line))isFalse)returncore.BNFindAllTextWithProgress(self.handle,start,end,text,settings.handle,flags,graph_type,None,progress_func_obj,None,match_callback_obj)else:results=queue.Queue()match_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_char_p,ctypes.POINTER(core.BNLinearDisassemblyLine))(lambdactxt,addr,match,line:results.put((addr,match,self._LinearDisassemblyLine_convertor(line)))orTrue)t=threading.Thread(target=lambda:core.BNFindAllTextWithProgress(self.handle,start,end,text,settings.handle,flags,graph_type,None,progress_func_obj,None,match_callback_obj))returnself.QueueGenerator(t,results)
[docs]deffind_all_constant(self,start:int,end:int,constant:int,settings:Optional[_function.DisassemblySettings]=None,graph_type:_function.FunctionViewTypeOrName=FunctionGraphType.NormalFunctionGraph,progress_func:Optional[ProgressFuncType]=None,match_callback:Optional[LineMatchCallbackType]=None)->QueueGenerator:"""``find_all_constant`` searches for the integer constant ``constant`` starting at thevirtual address ``start`` until the virtual address ``end``. Once a match is found,the ``match_callback`` is called... note:: A ``constant`` is considered used if a line in the linear view expansion of the given \function graph type contains a token with a value that matches that constant. \This does not search for raw bytes/data in the binary, for that you want to use \:py:func:`find_all_data`.:param int start: virtual address to start searching from.:param int end: virtual address to end the search.:param int constant: constant to search for:param DisassemblySettings settings: DisassemblySettings object used to render the text \to be searched:param FunctionViewType graph_type: the IL to search within:param callback progress_func: optional function to be called with the current progress \and total count. This function should return a boolean value that decides whether the \search should continue or stop:param callback match_callback: function that gets called when a match is found. The \callback takes two parameters, i.e., the address of the match, and the \LinearDisassemblyLine that contains the matching line. If this parameter is None, \this function becomes a generator and yields the matching address and the \matching LinearDisassemblyLine. This function can return a boolean value that \decides whether the search should continue or stop:rtype QueueGenerator: A generator object that will yield all the found results"""ifnotisinstance(constant,int):raiseTypeError("constant parameter is not integral type")ifsettingsisNone:settings=_function.DisassemblySettings()settings.set_option(DisassemblyOption.ShowAddress,False)settings.set_option(DisassemblyOption.ShowOpcode,False)settings.set_option(DisassemblyOption.ShowVariableTypesWhenAssigned,True)settings.set_option(DisassemblyOption.WaitForIL,True)ifnotisinstance(settings,_function.DisassemblySettings):raiseTypeError("settings parameter is not DisassemblySettings type")graph_type=_function.FunctionViewType(graph_type)._to_core_struct()ifprogress_func:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:progress_func(cur,total))else:progress_func_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:True)ifmatch_callback:match_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.POINTER(core.BNLinearDisassemblyLine))(lambdactxt,addr,line:notmatch_callback(addr,self._LinearDisassemblyLine_convertor(line))isFalse)returncore.BNFindAllConstantWithProgress(self.handle,start,end,constant,settings.handle,graph_type,None,progress_func_obj,None,match_callback_obj)else:results=queue.Queue()match_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.POINTER(core.BNLinearDisassemblyLine))(lambdactxt,addr,line:results.put((addr,self._LinearDisassemblyLine_convertor(line)))orTrue)t=threading.Thread(target=lambda:core.BNFindAllConstantWithProgress(self.handle,start,end,constant,settings.handle,graph_type,None,progress_func_obj,None,match_callback_obj))returnself.QueueGenerator(t,results)
[docs]defsearch(self,pattern:str,start:int=None,end:int=None,raw:bool=False,ignore_case:bool=False,overlap:bool=False,align:int=1,limit:int=None,progress_callback:Optional[ProgressFuncType]=None,match_callback:Optional[DataMatchCallbackType]=None)->QueueGenerator:r"""Searches for matches of the specified ``pattern`` within this BinaryView with an optionally provided address range specified by ``start`` and ``end``.This is the API used by the advanced binary search UI option. The search pattern can be interpreted in various ways:- specified as a string of hexadecimal digits where whitespace is ignored, and the '?' character acts as a wildcard- a regular expression suitable for working with bytes- or if the ``raw`` option is enabled, the pattern is interpreted as a raw string, and any special characters are escaped and interpreted literally:param pattern: The pattern to search for.:type pattern: :py:class:`str`:param start: The address to start the search from. (default: None):type start: :py:class:`int`:param end: The address to end the search (inclusive). (default: None):type end: :py:class:`int`:param bool raw: Whether to interpret the pattern as a raw string (default: False).:param bool ignore_case: Whether to perform case-insensitive matching (default: False).:param bool overlap: Whether to allow matches to overlap (default: False).:param int align: The alignment of matches, must be a power of 2 (default: 1).:param int limit: The maximum number of matches to return (default: None).:param callback progress_callback: An optional function to be called with the current progress and total count. \This function should return a boolean value that decides whether the search should continue or stop.:param callback match_callback: A function that gets called when a match is found. The callback takes two parameters: \the address of the match, and the actual DataBuffer that satisfies the search. This function can return a boolean \value that decides whether the search should continue or stop.:return: A generator object that yields the offset and matched DataBuffer for each match found.:rtype: QueueGenerator:Example:>>> from binaryninja import load>>> bv = load('/bin/ls')>>> print(bv)<BinaryView: '/bin/ls', start 0x100000000, len 0x182f8>>>> bytes(list(bv.search("50 ?4"))[0][1]).hex()'5004'>>> bytes(list(bv.search("[\x20-\x25][\x60-\x67]"))[0][1]).hex()'2062'"""ifstartisNone:start=self.startifendisNone:end=self.endifend!=0xffffffffffffffff:end=end-1ifstart>end:raiseValueError("The start address must be less than or equal to end address!")query={"pattern":pattern,"start":start,"end":end,"raw":raw,"ignoreCase":ignore_case,"overlap":overlap,"align":align}ifprogress_callback:progress_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:progress_callback(cur,total))else:progress_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:True)match_count=0definternal_match_callback(ctxt,offset,match):nonlocalmatch_countmatch_count+=1data_buffer=databuffer.DataBuffer(handle=match)results.put((offset,data_buffer))ifmatch_callbackisnotNone:should_continue=match_callback(offset,data_buffer)ifnotshould_continue:returnFalseiflimitisnotNoneandmatch_count>=limit:returnFalsereturnTruematch_callback_obj=ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.POINTER(core.BNDataBuffer))(internal_match_callback)results=queue.Queue()t=threading.Thread(target=lambda:core.BNSearch(self.handle,json.dumps(query),None,progress_callback_obj,None,match_callback_obj))returnself.QueueGenerator(t,results)
[docs]defreanalyze(self)->None:"""``reanalyze`` causes all functions to be reanalyzed. This function does not wait for the analysis to finish.:rtype: None"""core.BNReanalyzeAllFunctions(self.handle)
@propertydefworkflow(self)->Optional['_workflow.Workflow']:handle=core.BNGetWorkflowForBinaryView(self.handle)ifhandleisNone:returnNonereturn_workflow.Workflow(handle=handle,object_handle=self.handle)
[docs]defrebase(self,address:int,force:Optional[bool]=False,progress_func:Optional[ProgressFuncType]=None)->Optional['BinaryView']:"""``rebase`` rebase the existing :py:class:`BinaryView` into a new :py:class:`BinaryView` at the specified virtual address.. note:: This method does not update corresponding UI components. If the `BinaryView` is associated with \UI components then initiate the rebase operation within the UI, e.g. using the command palette or \``binaryninjaui.UIContext.activeContext().rebaseCurrentView()``. If working with views that \are not associated with UI components while the UI is active, then set ``force`` to ``True`` to enable rebasing.:param int address: virtual address of the start of the :py:class:`BinaryView`:param bool force: enable rebasing while the UI is active:return: the new :py:class:`BinaryView` object or ``None`` on failure:rtype: :py:class:`BinaryView` or ``None``:Example:>>> from binaryninja import load>>> bv = load('/bin/ls')>>> print(bv)<BinaryView: '/bin/ls', start 0x100000000, len 0x182f8>>>> newbv = bv.rebase(0x400000)>>> print(newbv)<BinaryView: '/bin/ls', start 0x400000, len 0x182f8>>>>>>> # For rebasing the current view in the UI:>>> import binaryninjaui>>> execute_on_main_thread_and_wait(lambda: binaryninjaui.UIContext.activeContext().rebaseCurrentView(0x800000))"""result=Falseifcore.BNIsUIEnabled()andnotforce:log_warn("The BinaryView rebase API does not update corresponding UI components. If the BinaryView is not associated with the UI rerun with 'force = True'.")returnNoneifprogress_funcisNone:result=core.BNRebase(self.handle,address)else:result=core.BNRebaseWithProgress(self.handle,address,None,ctypes.CFUNCTYPE(ctypes.c_bool,ctypes.c_void_p,ctypes.c_ulonglong,ctypes.c_ulonglong)(lambdactxt,cur,total:progress_func(cur,total)))ifresult:returnself.get_view_of_type(self.view_type)else:returnNone
[docs]defshow_plain_text_report(self,title:str,contents:str)->None:core.BNShowPlainTextReport(self.handle,title,contents)
[docs]defshow_markdown_report(self,title:str,contents:str,plaintext:str="")->None:"""``show_markdown_report`` displays the markdown contents in UI applications and plaintext in command-lineapplications. Markdown reports support hyperlinking into the BinaryView. Hyperlinks can be specified as follows:``binaryninja://?expr=_start`` Where ``expr=`` specifies an expression parsable by the :py:func:`parse_expression` API... note:: This API functions differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \a simple text prompt is used.:param str contents: markdown contents to display:param str plaintext: Plain text version to display (used on the command-line):rtype: None:Example:>>> bv.show_markdown_report("title", "##Contents", "Plain text contents")Plain text contents"""core.BNShowMarkdownReport(self.handle,title,contents,plaintext)
[docs]defshow_html_report(self,title:str,contents:str,plaintext:str="")->None:"""``show_html_report`` displays the HTML contents in UI applications and plaintext in command-lineapplications. HTML reports support hyperlinking into the BinaryView. Hyperlinks can be specified as follows:``binaryninja://?expr=_start`` Where ``expr=`` specifies an expression parsable by the :py:func:`parse_expression` API... note:: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line \a simple text prompt is used.:param str contents: HTML contents to display:param str plaintext: Plain text version to display (used on the command-line):rtype: None:Example:>>> bv.show_html_report("title", "<h1>Contents</h1>", "Plain text contents")Plain text contents"""core.BNShowHTMLReport(self.handle,title,contents,plaintext)
[docs]defshow_graph_report(self,title:str,graph:flowgraph.FlowGraph)->None:"""``show_graph_report`` displays a :py:class:`FlowGraph` object `graph` in a new tab with ``title``.:param title: Title of the graph:type title: Text string title of the tab:param graph: The graph you wish to display:type graph: :py:class:`FlowGraph` object"""core.BNShowGraphReport(self.handle,title,graph.handle)
[docs]defget_address_input(self,prompt:str,title:str,current_address:Optional[int]=None)->Optional[int]:"""``get_address_input`` Gets a virtual address via a prompt displayed to the user:param prompt: Prompt for the dialog:param title: Window title, if used in the UI:param current_address: Optional current address, for relative inputs:return: The value entered by the user, if one was entered"""ifcurrent_addressisNone:current_address=self._file.offsetvalue=ctypes.c_ulonglong()ifnotcore.BNGetAddressInput(value,prompt,title,self.handle,current_address):returnNonereturnvalue.value
[docs]defbegin_bulk_add_segments(self)->None:"""``begin_bulk_add_segments`` Begins a bulk segment addition operation.This function prepares the `BinaryView` for bulk addition of both auto and user-defined segments.During the bulk operation, segments can be added using `add_auto_segment` or similar functionswithout immediately triggering the MemoryMap update process. The queued segments will not takeeffect until `end_bulk_add_segments` is called."""core.BNBeginBulkAddSegments(self.handle)
[docs]defend_bulk_add_segments(self)->None:"""``end_bulk_add_segments`` Finalizes and applies all queued segments (auto and user)added during a bulk segment addition operation.This function commits all segments that were queued since the last call to `begin_bulk_add_segments`.The MemoryMap update process is executed at this point, applying all changes in one batch forimproved performance.Note: This function must be called after `begin_bulk_add_segments` to apply the queued segments."""core.BNEndBulkAddSegments(self.handle)
[docs]defcancel_bulk_add_segments(self)->None:"""``cancel_bulk_add_segments`` Cancels a bulk segment addition operation.This function discards all auto and user segments that were queued since the last call to`begin_bulk_add_segments` without applying them. It allows you to abandon the changes in casethey are no longer needed.Note: If no bulk operation is in progress, calling this function has no effect."""core.BNCancelBulkAddSegments(self.handle)
[docs]defadd_auto_segment(self,start:int,length:int,data_offset:int,data_length:int,flags:SegmentFlag)->None:"""``add_auto_segment`` Adds an analysis segment that specifies how data from the raw file is mapped into a virtual address spaceNote that the segments added may have different size attributes than requested"""core.BNAddAutoSegment(self.handle,start,length,data_offset,data_length,flags)
[docs]defadd_auto_segments(self,segments:List[core.BNSegmentInfo])->None:"""``add_auto_segments`` Adds analysis segments that specify how data from the raw file is mapped into a virtual address space:param List[core.BNSegmentInfo] segments: list of segments to add:rtype: None"""segment_list=(core.BNSegmentInfo*len(segments))(*segments)core.BNAddAutoSegments(self.handle,segment_list,len(segments))
[docs]defremove_auto_segment(self,start:int,length:int=0)->None:"""``remove_auto_segment`` Removes an automatically generated segment from the current segment mapping. This method removes the most recently added 'auto' segment that either matches the specified start address or contains it.:param int start: virtual address of the start of the segment:param int length: length of the segment (unused):rtype: None.. warning:: This action is not persistent across saving of a BNDB and must be re-applied each time a BNDB is loaded."""core.BNRemoveAutoSegment(self.handle,start,length)
[docs]defadd_user_segment(self,start:int,length:int,data_offset:int,data_length:int,flags:SegmentFlag)->None:"""``add_user_segment`` creates a user-defined segment that specifies how data from the raw file is mapped into a virtual address space.:param int start: virtual address of the start of the segment:param int length: length of the segment (may be larger than the source data):param int data_offset: offset from the parent view:param int data_length: length of the data from the parent view:param enums.SegmentFlag flags: SegmentFlags:rtype: None"""core.BNAddUserSegment(self.handle,start,length,data_offset,data_length,flags)
[docs]defadd_user_segments(self,segments:List[core.BNSegmentInfo])->None:"""``add_user_segments`` Adds user-defined segments that specify how data from the raw file is mapped into a virtual address space:param List[core.BNSegmentInfo] segments: list of segments to add:rtype: None"""segment_list=(core.BNSegmentInfo*len(segments))(*segments)core.BNAddUserSegments(self.handle,segment_list,len(segments))
[docs]defremove_user_segment(self,start:int,length:int=0)->None:"""``remove_user_segment`` Removes a user-defined segment from the current segment mapping. This method removes the most recently added 'user' segment that either matches the specified start address or contains it.:param int start: virtual address of the start of the segment:param int length: length of the segment (unused):rtype: None"""core.BNRemoveUserSegment(self.handle,start,length)
[docs]defget_segment_at(self,addr:int)->Optional[Segment]:"""``get_segment_at`` gets the Segment a given virtual address is located in:param addr: A virtual address:return: The segment, if it was found"""seg=core.BNGetSegmentAt(self.handle,addr)ifnotseg:returnNonereturnSegment(seg)
[docs]defget_address_for_data_offset(self,offset:int)->Optional[int]:"""``get_address_for_data_offset`` returns the virtual address that maps to the specific file offset.:param int offset: file offset:return: the virtual address of the first segment that contains that file location:rtype: Int"""address=ctypes.c_ulonglong()ifnotcore.BNGetAddressForDataOffset(self.handle,offset,address):returnNonereturnaddress.value
[docs]defget_data_offset_for_address(self,address:int)->Optional[int]:"""``get_data_offset_for_address`` returns the file offset that maps to the given virtual address, if possible.If `address` falls within a bss segment or an external segment, for example, no mapping is possible, and `None` will be returned.:param int address: virtual address:return: the file location that is mapped to the given virtual address, or None if no such mapping is possible:rtype: Int"""segment=self.get_segment_at(address)ifsegmentisnotNoneandsegment.start<=address<segment.end:offset=address-segment.startifoffset<segment.data_length:returnoffset+segment.data_offsetreturnNone
[docs]defadd_auto_section(self,name:str,start:int,length:int,semantics:SectionSemantics=SectionSemantics.DefaultSectionSemantics,type:str="",align:int=1,entry_size:int=1,linked_section:str="",info_section:str="",info_data:int=0)->None:core.BNAddAutoSection(self.handle,name,start,length,semantics,type,align,entry_size,linked_section,info_section,info_data)
[docs]defremove_auto_section(self,name:str)->None:core.BNRemoveAutoSection(self.handle,name)
[docs]defadd_user_section(self,name:str,start:int,length:int,semantics:SectionSemantics=SectionSemantics.DefaultSectionSemantics,type:str="",align:int=1,entry_size:int=1,linked_section:str="",info_section:str="",info_data:int=0)->None:"""``add_user_section`` creates a user-defined section that can help inform analysis by clarifying what types ofdata exist in what ranges. Note that all data specified must already be mapped by an existing segment.:param str name: name of the section:param int start: virtual address of the start of the section:param int length: length of the section:param enums.SectionSemantics semantics: SectionSemantics of the section:param str type: optional type:param int align: optional byte alignment:param int entry_size: optional entry size:param str linked_section: optional name of a linked section:param str info_section: optional name of an associated informational section:param int info_data: optional info data:rtype: None"""core.BNAddUserSection(self.handle,name,start,length,semantics,type,align,entry_size,linked_section,info_section,info_data)
[docs]defremove_user_section(self,name:str)->None:core.BNRemoveUserSection(self.handle,name)
[docs]defget_sections_at(self,addr:int)->List[Section]:count=ctypes.c_ulonglong(0)section_list=core.BNGetSectionsAt(self.handle,addr,count)assertsection_listisnotNone,"core.BNGetSectionsAt returned None"result=[]try:foriinrange(0,count.value):section_handle=core.BNNewSectionReference(section_list[i])assertsection_handleisnotNone,"core.BNNewSectionReference returned None"result.append(Section(section_handle))returnresultfinally:core.BNFreeSectionList(section_list,count.value)
[docs]defget_section_by_name(self,name:str)->Optional[Section]:section=core.BNGetSectionByName(self.handle,name)ifsectionisNone:returnNoneresult=Section(section)returnresult
[docs]defget_unique_section_names(self,name_list:List[str])->List[str]:incoming_names=(ctypes.c_char_p*len(name_list))()foriinrange(0,len(name_list)):incoming_names[i]=name_list[i].encode("utf-8")outgoing_names=core.BNGetUniqueSectionNames(self.handle,incoming_names,len(name_list))assertoutgoing_namesisnotNone,"core.BNGetUniqueSectionNames returned None"result=[]try:foriinrange(0,len(name_list)):result.append(outgoing_names[i].decode("utf-8"))returnresultfinally:core.BNFreeStringList(outgoing_names,len(name_list))
@propertydefaddress_comments(self)->Mapping[int,str]:"""Returns a read-only dict of the address comments attached to this BinaryViewNote that these are different from function-level comments which are specific to each :py:class:`Function`.For annotating code, it is recommended to use comments attached to functions rather than addresscomments attached to the BinaryView. On the other hand, BinaryView comments can be attached to datawhereas function comments cannot.To create a function-level comment, use :py:func:`~binaryninja.function.Function.set_comment_at`."""count=ctypes.c_ulonglong()addrs=core.BNGetGlobalCommentedAddresses(self.handle,count)assertaddrsisnotNone,"core.BNGetGlobalCommentedAddresses returned None"result={}try:foriinrange(0,count.value):result[addrs[i]]=self.get_comment_at(addrs[i])returnresultfinally:core.BNFreeAddressList(addrs)
[docs]defget_comment_at(self,addr:int)->str:"""``get_comment_at`` returns the address-based comment attached to the given address in this BinaryViewNote that address-based comments are different from function-level comments which are specific to each :py:class:`~binaryninja.function.Function`.For more information, see :py:func:`address_comments`.:param int addr: virtual address within the current BinaryView to apply the comment to:rtype: str"""returncore.BNGetGlobalCommentForAddress(self.handle,addr)
[docs]defset_comment_at(self,addr:int,comment:str)->None:"""``set_comment_at`` sets a comment for the BinaryView at the address specifiedNote that these are different from function-level comments which are specific to each :py:class:`~binaryninja.function.Function`. \For more information, see :py:func:`address_comments`.:param int addr: virtual address within the current BinaryView to apply the comment to:param str comment: string comment to apply:rtype: None:Example:>>> bv.set_comment_at(here, "hi")"""core.BNSetGlobalCommentForAddress(self.handle,addr,comment)
@propertydefdebug_info(self)->"debuginfo.DebugInfo":"""The current debug info object for this binary view"""debug_handle=core.BNGetDebugInfo(self.handle)assertdebug_handleisnotNone,"core.BNGetDebugInfo returned None"returndebuginfo.DebugInfo(debug_handle)@debug_info.setterdefdebug_info(self,value:"debuginfo.DebugInfo")->None:"""Sets the debug info for the current binary view"""ifnotisinstance(value,debuginfo.DebugInfo):raiseValueError("Attempting to set debug_info to something which isn't and instance of 'DebugInfo'")core.BNSetDebugInfo(self.handle,value.handle)
[docs]defapply_debug_info(self,value:"debuginfo.DebugInfo")->None:"""Sets the debug info and applies its contents to the current binary view"""ifnotisinstance(value,debuginfo.DebugInfo):raiseValueError("Attempting to apply_debug_info with something which isn't and instance of 'DebugInfo'")core.BNApplyDebugInfo(self.handle,value.handle)
[docs]defquery_metadata(self,key:str)->'metadata.MetadataValueType':"""`query_metadata` retrieves a metadata associated with the given key stored in the current BinaryView.:param str key: key to query:rtype: metadata associated with the key:Example:>>> bv.store_metadata("integer", 1337)>>> bv.query_metadata("integer")1337L>>> bv.store_metadata("list", [1,2,3])>>> bv.query_metadata("list")[1L, 2L, 3L]>>> bv.store_metadata("string", "my_data")>>> bv.query_metadata("string")'my_data'"""md_handle=core.BNBinaryViewQueryMetadata(self.handle,key)ifmd_handleisNone:raiseKeyError(key)returnmetadata.Metadata(handle=md_handle).value
[docs]defstore_metadata(self,key:str,md:metadata.MetadataValueType,isAuto:bool=False)->None:"""`store_metadata` stores an object for the given key in the current BinaryView. Objects stored using`store_metadata` can be retrieved when the database is reopened. Objects stored are not arbitrary pythonobjects! The values stored must be able to be held in a Metadata object. See :py:class:`~binaryninja.metadata.Metadata`for more information. Python objects could obviously be serialized using pickle but this intentionallya task left to the user since there is the potential security issues.:param str key: key value to associate the Metadata object with:param Varies md: object to store.:param bool isAuto: whether the metadata is an auto metadata. Most metadata should \keep this as False. Only those automatically generated metadata should have this set \to True. Auto metadata is not saved into the database and is presumably re-generated \when re-opening the database.:rtype: None:Example:>>> bv.store_metadata("integer", 1337)>>> bv.query_metadata("integer")1337L>>> bv.store_metadata("list", [1,2,3])>>> bv.query_metadata("list")[1L, 2L, 3L]>>> bv.store_metadata("string", "my_data")>>> bv.query_metadata("string")'my_data'"""_md=mdifnotisinstance(_md,metadata.Metadata):_md=metadata.Metadata(_md)core.BNBinaryViewStoreMetadata(self.handle,key,_md.handle,isAuto)
[docs]defremove_metadata(self,key:str)->None:"""`remove_metadata` removes the metadata associated with key from the current BinaryView.:param str key: key associated with metadata to remove from the BinaryView:rtype: None:Example:>>> bv.store_metadata("integer", 1337)>>> bv.remove_metadata("integer")"""core.BNBinaryViewRemoveMetadata(self.handle,key)
@propertydefmetadata(self)->Dict[str,'metadata.MetadataValueType']:"""`metadata` retrieves the metadata associated with the current BinaryView.:rtype: metadata associated with the BinaryView:Example:>>> bv.metadata<metadata: {}>"""md_handle=core.BNBinaryViewGetMetadata(self.handle)assertmd_handleisnotNone,"core.BNBinaryViewGetMetadata returned None"value=metadata.Metadata(handle=md_handle).valueassertisinstance(value,dict),"core.BNBinaryViewGetMetadata did not return a dict"returnvalue@propertydefauto_metadata(self)->Dict[str,'metadata.MetadataValueType']:"""`metadata` retrieves the metadata associated with the current BinaryView.:rtype: metadata associated with the BinaryView:Example:>>> bv.metadata<metadata: {}>"""md_handle=core.BNBinaryViewGetAutoMetadata(self.handle)assertmd_handleisnotNone,"core.BNBinaryViewGetAutoMetadata returned None"value=metadata.Metadata(handle=md_handle).valueassertisinstance(value,dict),"core.BNBinaryViewGetAutoMetadata did not return a dict"returnvalue
[docs]defget_load_settings_type_names(self)->List[str]:"""``get_load_settings_type_names`` retrieve a list :py:class:`BinaryViewType` names for which load settings exist in \this :py:class:`BinaryView` context:return: list of :py:class:`BinaryViewType` names:rtype: list(str)"""result=[]count=ctypes.c_ulonglong(0)names=core.BNBinaryViewGetLoadSettingsTypeNames(self.handle,count)assertnamesisnotNone,"core.BNBinaryViewGetLoadSettingsTypeNames returned None"try:foriinrange(count.value):result.append(names[i])returnresultfinally:core.BNFreeStringList(names,count.value)
[docs]defget_load_settings(self,type_name:str)->Optional[settings.Settings]:"""``get_load_settings`` retrieve a :py:class:`~binaryninja.settings.Settings` object which defines the load settings for the given :py:class:`BinaryViewType` ``type_name``:param str type_name: the :py:class:`BinaryViewType` name:return: the load settings:rtype: :py:class:`~binaryninja.settings.Settings`, or ``None``"""settings_handle=core.BNBinaryViewGetLoadSettings(self.handle,type_name)ifsettings_handleisNone:returnNonereturnsettings.Settings(handle=settings_handle)
[docs]defset_load_settings(self,type_name:str,settings:Optional[settings.Settings])->None:"""``set_load_settings`` set a :py:class:`~binaryninja.settings.Settings` object which defines the load settings for the given :py:class:`BinaryViewType` ``type_name``:param str type_name: the :py:class:`BinaryViewType` name:param Settings settings: the load settings:rtype: None"""ifsettingsisnotNone:settings=settings.handlecore.BNBinaryViewSetLoadSettings(self.handle,type_name,settings)
[docs]defparse_expression(self,expression:str,here:int=0)->int:r"""Evaluates a string expression to an integer value.The parser uses the following rules:- Symbols are defined by the lexer as ``[A-Za-z0-9_:<>][A-Za-z0-9_:$\-<>]+`` or anything enclosed in either single or double quotes- Symbols are everything in ``bv.symbols``, unnamed DataVariables (i.e. ``data_00005000``), unnamed functions (i.e. ``sub_00005000``), or section names (i.e. ``.text``)- Numbers are defaulted to hexadecimal thus `_printf + 10` is equivalent to `printf + 0x10` If decimal numbers required use the decimal prefix.- Since numbers and symbols can be ambiguous its recommended that you prefix your numbers with the following:- ``0x`` - Hexadecimal- ``0n`` - Decimal- ``0`` - Octal- In the case of an ambiguous number/symbol (one with no prefix) for instance ``12345`` we will first attempt  to look up the string as a symbol, if a symbol is found its address is used, otherwise we attempt to convert  it to a hexadecimal number.- The following operations are valid: ``+, -, \*, /, %, (), &, \|, ^, ~, ==, !=, >, <, >=, <=``- Comparison operators return 1 if the condition is true, 0 otherwise.- In addition to the above operators there are dereference operators similar to BNIL style IL:- ``[<expression>]`` - read the `current address size` at ``<expression>``- ``[<expression>].b`` - read the byte at ``<expression>``- ``[<expression>].w`` - read the word (2 bytes) at ``<expression>``- ``[<expression>].d`` - read the dword (4 bytes) at ``<expression>``- ``[<expression>].q`` - read the quadword (8 bytes) at ``<expression>``- The ``$here`` (or more succinctly: ``$``) keyword can be used in calculations and is defined as the ``here`` parameter, or the currently selected address- The ``$start``/``$end`` keyword represents the address of the first/last bytes in the file respectively- Arbitrary magic values (name-value-pairs) can be added to the expression parser via the  :py:func:`add_expression_parser_magic_value` API. Notably, the debugger adds all register values into the  expression parser so they can be used directly when navigating. The register values can be referenced like  `$rbp`, `$x0`, etc. For more details, refer to the related  `debugger docs <https://docs.binary.ninja/guide/debugger/index.html#navigating-the-binary>`_.:param str expression: Arithmetic expression to be evaluated:param int here: (optional) Base address for relative expressions, defaults to zero:rtype: int"""offset=ctypes.c_ulonglong()errors=ctypes.c_char_p()ifnotcore.BNParseExpression(self.handle,expression,offset,here,errors):asserterrors.valueisnotNone,"core.BNParseExpression returned errors set to None"error_str=errors.value.decode("utf-8")core.free_string(errors)raiseValueError(error_str)returnoffset.value
[docs]defeval(self,expression:str,here:int=0)->int:"""Evaluates a string expression to an integer value. This is a more concise alias for the :py:func:`parse_expression` API"""returnself.parse_expression(expression,here)
[docs]defreader(self,address:Optional[int]=None)->'BinaryReader':returnBinaryReader(self,address=address)
[docs]defwriter(self,address:Optional[int]=None)->'BinaryWriter':returnBinaryWriter(self,address=address)
@propertydeflibraries(self)->List[str]:try:result:List[str]=[]libs=self.query_metadata("Libraries")assertisinstance(libs,list)forsinlibs:assertisinstance(s,str)result.append(s)returnresultexceptKeyError:return[]
[docs]deftyped_data_accessor(self,address:int,type:'_types.Type')->'TypedDataAccessor':returnTypedDataAccessor(type,address,self,self.endianness)
[docs]defcreate_logger(self,logger_name:str)->Logger:returnLogger(self.file.session_id,logger_name)
[docs]defadd_external_library(self,name:str,backing_file:Optional['project.ProjectFile']=None,auto:bool=False)->externallibrary.ExternalLibrary:"""Add an ExternalLibrary to this BinaryView:param name: Name of the external library:param backing_file: Optional ProjectFile that backs the external library:param auto: Whether or not this action is the result of automated analysis:return: The created ExternalLibrary"""file_handle=Noneifbacking_fileisnotNone:file_handle=backing_file._handlehandle=core.BNBinaryViewAddExternalLibrary(self.handle,name,file_handle,auto)asserthandleisnotNone,"core.BNBinaryViewAddExternalLibrary returned None"returnexternallibrary.ExternalLibrary(handle)
[docs]defremove_external_library(self,name:str):"""Remove an ExternalLibrary from this BinaryView by name.Any associated ExternalLocations will be unassociated from the ExternalLibrary:param name: Name of the external library to remove"""core.BNBinaryViewRemoveExternalLibrary(self.handle,name)
[docs]defget_external_library(self,name:str)->Optional[externallibrary.ExternalLibrary]:"""Get an ExternalLibrary in this BinaryView by name:param name: Name of the external library:return: An ExternalLibrary with the given name, or None"""handle=core.BNBinaryViewGetExternalLibrary(self.handle,name)ifhandleisNone:returnNonereturnexternallibrary.ExternalLibrary(handle)
[docs]defget_external_libraries(self)->List[externallibrary.ExternalLibrary]:"""Get a list of all ExternalLibrary in this BinaryView:return: A list of ExternalLibraries in this BinaryView"""count=ctypes.c_ulonglong(0)handles=core.BNBinaryViewGetExternalLibraries(self.handle,count)asserthandlesisnotNone,"core.BNBinaryViewGetExternalLibraries returned None"result=[]try:foriinrange(count.value):new_handle=core.BNNewExternalLibraryReference(handles[i])assertnew_handleisnotNone,"core.BNNewExternalLibraryReference returned None"result.append(externallibrary.ExternalLibrary(new_handle))returnresultfinally:core.BNFreeExternalLibraryList(handles,count.value)
[docs]defadd_external_location(self,source_symbol:'_types.CoreSymbol',library:Optional[externallibrary.ExternalLibrary],target_symbol:Optional[str],target_address:Optional[int],auto:bool=False)->externallibrary.ExternalLocation:"""Add an ExternalLocation with its source in this BinaryView.ExternalLocations must have a target address and/or symbol.:param source_symbol: Symbol that the association is from:param library: Library that the ExternalLocation belongs to:param target_symbol: Symbol that the ExternalLocation points to:param target_address: Address that the ExternalLocation points to:param auto: Whether or not this action is the result of automated analysis:return: The created ExternalLocation"""c_addr=Noneiftarget_addressisnotNone:c_addr=ctypes.c_ulonglong(target_address)eliftarget_symbolisNone:raiseExternalLinkException("External locations must have a target address and/or symbol")handle=core.BNBinaryViewAddExternalLocation(self.handle,source_symbol.handle,library._handleiflibraryelseNone,target_symbol,c_addr,auto)asserthandleisnotNone,"core.BNBinaryViewAddExternalLocation returned None"returnexternallibrary.ExternalLocation(handle)
[docs]defremove_external_location(self,source_symbol:'_types.CoreSymbol'):"""Remove the ExternalLocation with the given source symbol from this BinaryView:param source_symbol: Source symbol that will be used to determine the ExternalLocation to remove"""core.BNBinaryViewRemoveExternalLocation(self.handle,source_symbol._handle)
[docs]defget_external_location(self,source_symbol:'_types.CoreSymbol')->Optional[externallibrary.ExternalLocation]:"""Get the ExternalLocation with the given source symbol in this BinaryView:param source_symbol: The source symbol of the ExternalLocation:return: An ExternalLocation with the given source symbol, or None"""handle=core.BNBinaryViewGetExternalLocation(self.handle,source_symbol.handle)ifhandleisNone:returnNonereturnexternallibrary.ExternalLocation(handle)
[docs]defget_external_locations(self)->List[externallibrary.ExternalLocation]:"""Get a list of ExternalLocations in this BinaryView:return: A list of ExternalLocations in this BinaryView"""count=ctypes.c_ulonglong(0)handles=core.BNBinaryViewGetExternalLocations(self.handle,count)asserthandlesisnotNone,"core.BNBinaryViewGetExternalLocations returned None"result=[]try:foriinrange(count.value):new_handle=core.BNNewExternalLocationReference(handles[i])assertnew_handleisnotNone,"core.BNNewExternalLocationReference returned None"result.append(externallibrary.ExternalLocation(new_handle))returnresultfinally:core.BNFreeExternalLocationList(handles,count.value)
@propertydefmemory_map(self):"""``memory_map`` returns the MemoryMap object for the current BinaryView. The `MemoryMap` object is a proxy objectthat provides a high-level view of the memory map, allowing you to query and manipulate memory regions. This proxyensures that the memory map always reflects the latest state of the core `MemoryMap` object in the underlying `BinaryView`."""returnMemoryMap(handle=self.handle)
[docs]defstringify_unicode_data(self,arch:Optional['architecture.Architecture'],buffer:'databuffer.DataBuffer',null_terminates:bool=True,allow_short_strings:bool=False)->Tuple[Optional[str],Optional[StringType]]:"""``stringify_unicode_data`` converts a buffer of unicode data into a string representation.:param arch: The architecture to use for stringification, or None to use the current architecture of the BinaryView:param buffer: The DataBuffer containing the unicode data to stringify:param null_terminates: If True, stops stringification at the first null character, otherwise continues until the end of the buffer:param allow_short_strings: If True, allows short strings to be returned, otherwise only long strings are returned:return: A tuple containing the string representation and its type, or (None, None) if the stringification fails:rtype: Tuple[Optional[str], Optional[StringType]]"""ifnotisinstance(buffer,databuffer.DataBuffer):raiseTypeError("buffer must be an instance of databuffer.DataBuffer")string=ctypes.c_char_p()string_type=ctypes.c_int()ifarchisnotNone:arch=arch.handleifnotcore.BNStringifyUnicodeData(self.handle,arch,buffer.handle,null_terminates,allow_short_strings,ctypes.byref(string),ctypes.byref(string_type)):returnNone,Noneresult=string.value.decode('utf-8')core.free_string(string)returnresult,StringType(string_type.value)
[docs]classBinaryReader:"""``class BinaryReader`` is a convenience class for reading binary data.BinaryReader can be instantiated as follows and the rest of the document will start from this context ::>>> from binaryninja import *>>> bv = load("/bin/ls")>>> br = BinaryReader(bv)>>> hex(br.read32())'0xfeedfacfL'>>>Or using the optional endian parameter ::>>> from binaryninja import *>>> br = BinaryReader(bv, Endianness.BigEndian)>>> hex(br.read32())'0xcffaedfeL'>>>"""
[docs]def__init__(self,view:'BinaryView',endian:Optional[Endianness]=None,address:Optional[int]=None):_handle=core.BNCreateBinaryReader(view.handle)assert_handleisnotNone,"core.BNCreateBinaryReader returned None"self._handle=_handleifendianisNone:core.BNSetBinaryReaderEndianness(self._handle,view.endianness)else:core.BNSetBinaryReaderEndianness(self._handle,endian)ifaddressisnotNone:self.seek(address)
def__del__(self):ifcoreisnotNone:core.BNFreeBinaryReader(self._handle)def__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnctypes.addressof(self._handle.contents)==ctypes.addressof(other._handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):returnhash(ctypes.addressof(self._handle.contents))@propertydefendianness(self)->Endianness:"""The Endianness to read data. (read/write):getter: returns the endianness of the reader:setter: sets the endianness of the reader (BigEndian or LittleEndian):type: Endianness"""returnEndianness(core.BNGetBinaryReaderEndianness(self._handle))@endianness.setterdefendianness(self,value:Endianness)->None:core.BNSetBinaryReaderEndianness(self._handle,value)@propertydefoffset(self)->int:"""The current read offset (read/write).:getter: returns the current internal offset:setter: sets the internal offset:type: int"""returncore.BNGetReaderPosition(self._handle)@offset.setterdefoffset(self,value:int)->None:core.BNSeekBinaryReader(self._handle,value)@propertydefvirtual_base(self)->int:"""The current virtual base offset for the stream (read/write).:getter: returns the current virtual base:setter: sets the virtual base:type: int"""returncore.BNGetBinaryReaderVirtualBase(self._handle)@virtual_base.setterdefvirtual_base(self,value:int)->None:core.BNSetBinaryReaderVirtualBase(self._handle,value)@propertydefeof(self)->bool:"""Is end of file (read-only):getter: returns boolean, true if end of file, false otherwise:type: bool"""returncore.BNIsEndOfFile(self._handle)
[docs]defread(self,length:int,address:Optional[int]=None)->Optional[bytes]:r"""``read`` returns ``length`` bytes read from the current offset, adding ``length`` to offset.:param int length: number of bytes to read.:param int address: offset to set the internal offset before reading:return: ``length`` bytes from current offset:rtype: str, or None on failure:Example:>>> br.read(8)'\xcf\xfa\xed\xfe\x07\x00\x00\x01'>>>"""ifaddressisnotNone:self.seek(address)dest=ctypes.create_string_buffer(length)ifnotcore.BNReadData(self._handle,dest,length):returnNonereturndest.raw
[docs]defread8(self,address:Optional[int]=None)->Optional[int]:"""``read8`` returns a one byte integer from offset incrementing the offset.:param int address: offset to set the internal offset before reading:return: byte at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> br.read8()207>>>"""ifaddressisnotNone:self.seek(address)result=ctypes.c_ubyte()ifnotcore.BNRead8(self._handle,result):returnNonereturnresult.value
[docs]defread16(self,address:Optional[int]=None)->Optional[int]:"""``read16`` returns a two byte integer from offset incrementing the offset by two, using specified endianness.:param int address: offset to set the internal offset before reading:return: a two byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read16())'0xfacf'>>>"""ifaddressisnotNone:self.seek(address)result=ctypes.c_ushort()ifnotcore.BNRead16(self._handle,result):returnNonereturnresult.value
[docs]defread32(self,address:Optional[int]=None)->Optional[int]:"""``read32`` returns a four byte integer from offset incrementing the offset by four, using specified endianness.:param int address: offset to set the internal offset before reading:return: a four byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read32())'0xfeedfacfL'>>>"""ifaddressisnotNone:self.seek(address)result=ctypes.c_uint()ifnotcore.BNRead32(self._handle,result):returnNonereturnresult.value
[docs]defread64(self,address:Optional[int]=None)->Optional[int]:"""``read64`` returns an eight byte integer from offset incrementing the offset by eight, using specified endianness.:param int address: offset to set the internal offset before reading:return: an eight byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read64())'0x1000007feedfacfL'>>>"""ifaddressisnotNone:self.seek(address)result=ctypes.c_ulonglong()ifnotcore.BNRead64(self._handle,result):returnNonereturnresult.value
[docs]defread16le(self,address:Optional[int]=None)->Optional[int]:"""``read16le`` returns a two byte little endian integer from offset incrementing the offset by two.:param int address: offset to set the internal offset before reading:return: a two byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read16le())'0xfacf'>>>"""ifaddressisnotNone:self.seek(address)result=self.read(2)if(resultisNone)or(len(result)!=2):returnNonereturnstruct.unpack("<H",result)[0]
[docs]defread32le(self,address:Optional[int]=None)->Optional[int]:"""``read32le`` returns a four byte little endian integer from offset incrementing the offset by four.:param int address: offset to set the internal offset before reading:return: a four byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read32le())'0xfeedfacf'>>>"""ifaddressisnotNone:self.seek(address)result=self.read(4)if(resultisNone)or(len(result)!=4):returnNonereturnstruct.unpack("<I",result)[0]
[docs]defread64le(self,address:Optional[int]=None)->Optional[int]:"""``read64le`` returns an eight byte little endian integer from offset incrementing the offset by eight.:param int address: offset to set the internal offset before reading:return: a eight byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read64le())'0x1000007feedfacf'>>>"""ifaddressisnotNone:self.seek(address)result=self.read(8)if(resultisNone)or(len(result)!=8):returnNonereturnstruct.unpack("<Q",result)[0]
[docs]defread16be(self,address:Optional[int]=None)->Optional[int]:"""``read16be`` returns a two byte big endian integer from offset incrementing the offset by two.:param int address: offset to set the internal offset before reading:return: a two byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read16be())'0xcffa'>>>"""ifaddressisnotNone:self.seek(address)result=self.read(2)if(resultisNone)or(len(result)!=2):returnNonereturnstruct.unpack(">H",result)[0]
[docs]defread32be(self,address:Optional[int]=None)->Optional[int]:"""``read32be`` returns a four byte big endian integer from offset incrementing the offset by four.:param int address: offset to set the internal offset before reading:return: a four byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read32be())'0xcffaedfe'"""ifaddressisnotNone:self.seek(address)result=self.read(4)if(resultisNone)or(len(result)!=4):returnNonereturnstruct.unpack(">I",result)[0]
[docs]defread64be(self,address:Optional[int]=None)->Optional[int]:"""``read64be`` returns an eight byte big endian integer from offset incrementing the offset by eight.:param int address: offset to set the internal offset before reading:return: a eight byte integer at offset.:rtype: int, or None on failure:Example:>>> br.seek(0x100000000)>>> hex(br.read64be())'0xcffaedfe07000001L'"""ifaddressisnotNone:self.seek(address)result=self.read(8)if(resultisNone)or(len(result)!=8):returnNonereturnstruct.unpack(">Q",result)[0]
[docs]defseek(self,offset:int,whence:Optional[int]=0)->None:"""``seek`` update internal offset to ``offset``.:param int offset: offset to set the internal offset to:param int whence: optional, defaults to 0 for absolute file positioning, or 1 for relative to current location:rtype: None:Example:>>> hex(br.offset)'0x100000008L'>>> br.seek(0x100000000)>>> hex(br.offset)'0x100000000L'>>>"""ifwhence:self.seek_relative(offset)returncore.BNSeekBinaryReader(self._handle,offset)
[docs]defseek_relative(self,offset:int)->None:"""``seek_relative`` updates the internal offset by ``offset``.:param int offset: offset to add to the internal offset:rtype: None:Example:>>> hex(br.offset)'0x100000008L'>>> br.seek_relative(-8)>>> hex(br.offset)'0x100000000L'>>>"""core.BNSeekBinaryReaderRelative(self._handle,offset)
[docs]classBinaryWriter:"""``class BinaryWriter`` is a convenience class for writing binary data.BinaryWriter can be instantiated as follows and the rest of the document will start from this context ::>>> from binaryninja import *>>> bv = load("/bin/ls")>>> br = BinaryReader(bv)>>> br.offset4294967296>>> bw = BinaryWriter(bv)>>>Or using the optional endian parameter ::>>> from binaryninja import *>>> bv = load("/bin/ls")>>> br = BinaryReader(bv, Endianness.BigEndian)>>> bw = BinaryWriter(bv, Endianness.BigEndian)>>>"""
[docs]def__init__(self,view:BinaryView,endian:Optional[Endianness]=None,address:Optional[int]=None):self._handle=core.BNCreateBinaryWriter(view.handle)assertself._handleisnotNone,"core.BNCreateBinaryWriter returned None"self._view=viewifendianisNone:core.BNSetBinaryWriterEndianness(self._handle,view.endianness)else:core.BNSetBinaryWriterEndianness(self._handle,endian)ifaddressisnotNone:self.seek(address)
def__del__(self):ifcoreisnotNone:core.BNFreeBinaryWriter(self._handle)def__eq__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedassertself._handleisnotNoneassertother._handleisnotNonereturnctypes.addressof(self._handle.contents)==ctypes.addressof(other._handle.contents)def__ne__(self,other):ifnotisinstance(other,self.__class__):returnNotImplementedreturnnot(self==other)def__hash__(self):assertself._handleisnotNonereturnhash(ctypes.addressof(self._handle.contents))@propertydefendianness(self)->Endianness:"""The Endianness to written data. (read/write):getter: returns the endianness of the reader:setter: sets the endianness of the reader (BigEndian or LittleEndian):type: Endianness"""returnEndianness(core.BNGetBinaryWriterEndianness(self._handle))@endianness.setterdefendianness(self,value:Endianness)->None:core.BNSetBinaryWriterEndianness(self._handle,value)@propertydefoffset(self)->int:"""The current write offset (read/write).:getter: returns the current internal offset:setter: sets the internal offset:type: int"""returncore.BNGetWriterPosition(self._handle)@offset.setterdefoffset(self,value:int)->None:core.BNSeekBinaryWriter(self._handle,value)
[docs]defwrite(self,value:bytes,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write`` writes ``len(value)`` bytes to the internal offset, without regard to endianness.:param str bytes: bytes to be written at current offset:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool:Example:>>> bw.write("AAAA")True>>> br.read(4)'AAAA'>>>"""ifaddressisnotNone:self.seek(address)ifexcept_on_relocationandself._view.range_contains_relocation(self.offset,len(value)):raiseRelocationWriteException("Attempting to write to a location which has a relocation")ifisinstance(value,str):value=value.decode("utf-8")buf=ctypes.create_string_buffer(len(value))ctypes.memmove(buf,value,len(value))returncore.BNWriteData(self._handle,buf,len(value))
[docs]defwrite8(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write8`` lowest order byte from the integer ``value`` to the current offset.:param str value: bytes to be written at current offset:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean:rtype: bool:Example:>>> bw.write8(0x42)True>>> br.read(1)'B'>>>"""ifaddressisnotNone:self.seek(address)ifexcept_on_relocationandself._view.range_contains_relocation(self.offset,1):raiseRelocationWriteException("Attempting to write to a location which has a relocation")returncore.BNWrite8(self._handle,value)
[docs]defwrite16(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write16`` writes the lowest order two bytes from the integer ``value`` to the current offset, using internal endianness.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)ifexcept_on_relocationandself._view.range_contains_relocation(self.offset,2):raiseRelocationWriteException("Attempting to write to a location which has a relocation")returncore.BNWrite16(self._handle,value)
[docs]defwrite32(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write32`` writes the lowest order four bytes from the integer ``value`` to the current offset, using internal endianness.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)ifexcept_on_relocationandself._view.range_contains_relocation(self.offset,4):raiseRelocationWriteException("Attempting to write to a location which has a relocation")returncore.BNWrite32(self._handle,value)
[docs]defwrite64(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write64`` writes the lowest order eight bytes from the integer ``value`` to the current offset, using internal endianness.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)ifexcept_on_relocationandself._view.range_contains_relocation(self.offset,8):raiseRelocationWriteException("Attempting to write to a location which has a relocation")returncore.BNWrite64(self._handle,value)
[docs]defwrite16le(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write16le`` writes the lowest order two bytes from the little endian integer ``value`` to the current offset.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)returnself.write(struct.pack("<H",value),except_on_relocation=except_on_relocation)
[docs]defwrite32le(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write32le`` writes the lowest order four bytes from the little endian integer ``value`` to the current offset.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)returnself.write(struct.pack("<I",value),except_on_relocation=except_on_relocation)
[docs]defwrite64le(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write64le`` writes the lowest order eight bytes from the little endian integer ``value`` to the current offset.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)returnself.write(struct.pack("<Q",value),except_on_relocation=except_on_relocation)
[docs]defwrite16be(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write16be`` writes the lowest order two bytes from the big endian integer ``value`` to the current offset.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)returnself.write(struct.pack(">H",value),except_on_relocation=except_on_relocation)
[docs]defwrite32be(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write32be`` writes the lowest order four bytes from the big endian integer ``value`` to the current offset.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)returnself.write(struct.pack(">I",value),except_on_relocation=except_on_relocation)
[docs]defwrite64be(self,value:int,address:Optional[int]=None,except_on_relocation=True)->bool:"""``write64be`` writes the lowest order eight bytes from the big endian integer ``value`` to the current offset.:param int value: integer value to write.:param int address: offset to set the internal offset before writing:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation:return: boolean True on success, False on failure.:rtype: bool"""ifaddressisnotNone:self.seek(address)returnself.write(struct.pack(">Q",value),except_on_relocation=except_on_relocation)
[docs]defseek(self,offset:int)->None:"""``seek`` update internal offset to ``offset``.:param int offset: offset to set the internal offset to:rtype: None:Example:>>> hex(bw.offset)'0x100000008L'>>> bw.seek(0x100000000)>>> hex(bw.offset)'0x100000000L'>>>"""core.BNSeekBinaryWriter(self._handle,offset)
[docs]defseek_relative(self,offset:int)->None:"""``seek_relative`` updates the internal offset by ``offset``.:param int offset: offset to add to the internal offset:rtype: None:Example:>>> hex(bw.offset)'0x100000008L'>>> bw.seek_relative(-8)>>> hex(bw.offset)'0x100000000L'>>>"""core.BNSeekBinaryWriterRelative(self._handle,offset)
[docs]@dataclass(init=False)classStructuredDataValue(object):type:'_types.Type'address:intvalue:bytesendian:Endiannessdef__str__(self):decode_str="{}B".format(self.type.width)return' '.join([f"{x:02x}"forxinstruct.unpack(decode_str,self.value)])def__repr__(self):returnf"<StructuredDataValue type:{self.type} value:{self}>"def__int__(self):ifself.type.width==1:code="B"elifself.type.width==2:code="H"elifself.type.width==4:code="I"elifself.type.width==8:code="Q"else:raiseException("Could not convert to integer with width{}".format(self.type.width))endian="<"ifself.endian==Endianness.LittleEndianelse">"returnstruct.unpack(f"{endian}{code}",self.value)[0]@propertydefstr(self)->str:returnstr(self)@propertydefwidth(self)->int:returnlen(self.type)@propertydefint(self)->int:returnint(self)
[docs]@dataclassclassTypedDataAccessor:type:'_types.Type'address:intview:'BinaryView'endian:Endiannessdef__post_init__(self):ifnotisinstance(self.type,_types.Type):raiseTypeError("Attempting to create TypedDataAccessor with TypeBuilder")def__bytes__(self):returnself.view.read(self.address,len(self))def__repr__(self):returnf"<TypedDataAccessor type:{self.type} value:{self.value}>"def__len__(self):_type=self.typeifisinstance(_type,_types.NamedTypeReferenceType):_type=_type.target(self.view)if_typeisNone:raiseValueError(f"Couldn't get target of type{_type}")returnlen(_type)def__int__(self):_type=self.typeifisinstance(_type,_types.NamedTypeReferenceType):_type=_type.target(self.view)ifisinstance(_type,_types.PointerType):returnself.int_from_bytes(bytes(self),len(self),False,self.endian)elifisinstance(_type,(_types.IntegerType,_types.EnumerationType)):returnself.int_from_bytes(bytes(self),len(self),bool(_type.signed),self.endian)raiseValueError(f"Attempting to coerce non integral type:{type(_type)} to an integer")def__bool__(self):returnbool(self.int_from_bytes(bytes(self),len(self),False))def__iter__(self):_type=self.typeifnotisinstance(_type,_types.ArrayType):raiseValueError("Can't iterate over non-array")foriinrange(_type.count):yieldself[i]def__getitem__(self,key:Union[str,int,slice])->Union['TypedDataAccessor',List['TypedDataAccessor']]:_type=self.typeifisinstance(_type,_types.NamedTypeReferenceType):_type=_type.target(self.view)ifisinstance(_type,_types.ArrayType)andisinstance(key,int):ifkey>=_type.count:raiseValueError(f"Index{key} out of bounds array has{_type.count} elements")returnTypedDataAccessor(_type.element_type,self.address+key*len(_type.element_type),self.view,self.endian)ifisinstance(_type,_types.ArrayType)andisinstance(key,slice):return[self[i]foriinrange(*key.indices(len(self.value)))]ifnotisinstance(_type,_types.StructureType):raiseValueError("Can't get member of non-structure")ifnotisinstance(key,str):raiseValueError("Must use string to get member of structure")m=_type[key]ifmisNone:raiseValueError(f"Member{key} doesn't exist in structure")returnTypedDataAccessor(m.type.immutable_copy(),self.address+m.offset,self.view,self.endian)
[docs]@staticmethoddefbyte_order(endian)->str:# as of python3.8 -> Literal["little", "big"]return"little"ifendian==Endianness.LittleEndianelse"big"
[docs]@staticmethoddefint_from_bytes(data:bytes,width:int,sign:bool,endian:Optional[Endianness]=None)->int:returnint.from_bytes(data[0:width],byteorder=TypedDataAccessor.byte_order(endian),signed=sign)# type: ignore
def__float__(self):ifnotisinstance(self.type,_types.FloatType):raiseException("Attempting to coerce non float type to a float")endian="<"ifself.endian==Endianness.LittleEndianelse">"ifself.type.width==2:code="e"elifself.type.width==4:code="f"elifself.type.width==8:code="d"else:raiseValueError(f"Could not convert to float with width{self.type.width}")returnstruct.unpack(f"{endian}{code}",bytes(self))[0]@propertydefvalue(self)->Any:returnself._value_helper(self.type,self.view.read(self.address,len(self.type)))@value.setterdefvalue(self,data:Union[bytes,int,float])->None:ifisinstance(data,int):integral_types=(_types.IntegerType,_types.IntegerBuilder,_types.BoolType,_types.BoolBuilder,_types.CharType,_types.CharBuilder,_types.WideCharType,_types.WideCharBuilder,_types.PointerType,_types.PointerBuilder,_types.EnumerationType,_types.EnumerationBuilder)ifnotisinstance(self.type,integral_types):raiseTypeError(f"Can't set the value of type{type(self.type)} to int value")signed=Trueifisinstance(self.type,(_types.IntegerType,_types.IntegerBuilder)):signed=bool(self.type.signed)to_write=data.to_bytes(len(self),TypedDataAccessor.byte_order(self.endian),signed=signed)# type: ignoreelifisinstance(data,float)andisinstance(self.type,(_types.FloatType,_types.FloatBuilder)):endian="<"ifself.endian==Endianness.LittleEndianelse">"ifself.type.width==2:code="e"elifself.type.width==4:code="f"elifself.type.width==8:code="d"else:raiseValueError(f"Could not convert to float with width{self.type.width}")to_write=struct.pack(f"{endian}{code}",data)else:to_write=datacount=self.view.write(self.address,to_write)ifcount!=len(to_write):raiseValueError("Unable to write all bytes to the location, segment might not have file backing")def_value_helper(self,_type:'_types.Type',data:bytes)->Any:ifnotisinstance(_type,_types.Type):raiseTypeError(f"Attempting to get value of TypeBuilder of type{type(_type)}")ifisinstance(_type,_types.NamedTypeReferenceType):target=_type.target(self.view)iftargetisNone:raiseValueError("Couldn't find target for type")_type=targetifisinstance(_type,(_types.VoidType,_types.FunctionType)):#, _types.VarArgsType, _types.ValueType)):returnNoneelifisinstance(_type,_types.BoolType):returnbool(self)elifisinstance(_type,_types.EnumerationType):value=int(self)formemberin_type.members:ifint(member)==value:returnmemberreturnvalueelifisinstance(_type,(_types.IntegerType,_types.PointerType)):returnint(self)elifisinstance(_type,_types.FloatType):returnfloat(self)elifisinstance(_type,_types.WideCharType):returndata.decode(f"utf-16-{'le'ifself.endian==Endianness.LittleEndianelse'be'}")elifisinstance(_type,_types.StructureType):result={}formemberin_type.members:result[member.name]=TypedDataAccessor(member.type,self.address+member.offset,self.view,self.endian).valuereturnresultelifisinstance(_type,_types.ArrayType):result=[]if_type.element_typeisNone:raiseValueError("Can not get value for Array type with no element type")if_type.element_type.width==1and_type.element_type.type_class==TypeClass.IntegerTypeClass:returnbytes(self)if_type.element_type.width==2and_type.element_type.type_class==TypeClass.WideCharTypeClass:returnbytes(self).decode(f"utf-16-{'le'ifself.endian==Endianness.LittleEndianelse'be'}")foroffsetinrange(0,len(_type)-1,_type.element_type.width):result.append(TypedDataAccessor(_type.element_type,self.address+offset,self.view,self.endian).value)returnresultelse:raiseTypeError(f"Unhandled `Type`{type(_type)}")
[docs]defas_uuid(self,ms_format:bool=True)->uuid.UUID:"""Converts the object to a UUID object using Microsoft byte ordering.:param ms_format: Flag indicating whether to use Microsoft byte ordering. Default is True.:type ms_format: bool:return: The UUID object representing the byte array.:rtype: uuid.UUID:raises ValueError: If the byte array representation of this data is not exactly 16 bytes long."""# Ensure the byte array is 16 bytes long (128 bits)byte_array=bytes(self)iflen(byte_array)!=16:raiseValueError("Byte array must be exactly 16 bytes long.")# Reorder the bytes to match the UUID format# First 3 components (10 bytes) are little-endian, last 2 components (6 bytes) are big-endianifms_format:reordered=byte_array[3::-1]+byte_array[5:3:-1]+byte_array[7:5:-1]+byte_array[8:]# Create a UUID object and return its string representationreturnuuid.UUID(bytes=reordered)else:returnuuid.UUID(bytes=byte_array)
# for backward compatibilityTypedDataReader=TypedDataAccessor
[docs]@dataclassclassCoreDataVariable:_address:int_type:'_types.Type'_auto_discovered:booldef__len__(self):returnlen(self._type)def__hash__(self):returnhash((self.type,self.address,self.auto_discovered))@propertydeftype(self)->'_types.Type':returnself._type@propertydefaddress(self)->int:returnself._address@propertydefauto_discovered(self)->bool:returnself._auto_discovered
[docs]classDataVariable(CoreDataVariable):
[docs]def__init__(self,view:BinaryView,address:int,type:'_types.Type',auto_discovered:bool):super(DataVariable,self).__init__(address,type,auto_discovered)self.view=viewself._accessor=TypedDataAccessor(self.type,self.address,self.view,self.view.endianness)
[docs]@classmethoddeffrom_core_struct(cls,var:core.BNDataVariable,view:'BinaryView')->'DataVariable':var_type=_types.Type.create(core.BNNewTypeReference(var.type),platform=view.platform,confidence=var.typeConfidence)returncls(view,var.address,var_type,var.autoDiscovered)
@propertydefdata_refs_from(self)->Optional[Generator[int,None,None]]:"""data cross references from this data variable (read-only)"""returnself.view.get_data_refs_from(self.address,max(1,len(self)))@propertydefdata_refs(self)->Optional[Generator[int,None,None]]:"""data cross references to this data variable (read-only)"""returnself.view.get_data_refs(self.address,max(1,len(self)))@propertydefcode_refs(self)->Generator['ReferenceSource',None,None]:"""code references to this data variable (read-only)"""returnself.view.get_code_refs(self.address,max(1,len(self)))def__len__(self):returnlen(self.type)def__repr__(self):returnf"<var{self.address:#x}:{self.type}>"@propertydefvalue(self)->Any:returnself._accessor.value@value.setterdefvalue(self,data:bytes)->None:self._accessor.value=datadef__getitem__(self,item:str):returnself._accessor[item]def__iter__(self):returniter(self._accessor)@propertydeftype(self)->'_types.Type':returnself._type@type.setterdeftype(self,value:Optional['_types.Type'])->None:# type: ignore_type=valueifvalueisnotNoneelse_types.VoidType.create()assertself.view.define_user_data_var(self.address,_type)isnotNone,"Unable to set DataVariable's type"self._type=_typeself._accessor.type=_type@propertydefsymbol(self)->Optional['_types.CoreSymbol']:returnself.view.get_symbol_at(self.address)@symbol.setterdefsymbol(self,value:Optional[Union[str,'_types.CoreSymbol']])->None:# type: ignoreexisting_symbol=self.symbolifvalueisNoneorvalue=="":ifexisting_symbolisnotNone:self.view.undefine_user_symbol(existing_symbol)elifisinstance(value,(str,_types.QualifiedName)):ifexisting_symbolisnotNone:symbol_type=existing_symbol.typeelse:symbol_type=SymbolType.DataSymbolsymbol=_types.Symbol(symbol_type,self.address,str(value))self.view.define_user_symbol(symbol)elifisinstance(value,_types.CoreSymbol):self.view.define_user_symbol(value)else:raiseValueError("Unknown supported for symbol assignment")@propertydefname(self)->Optional[str]:ifself.symbolisNone:returnNonereturnself.symbol.name@name.setterdefname(self,value:str)->None:self.symbol=value@propertydefcomponents(self)->List[component.Component]:returnself.view.get_data_variable_parent_components(self)
[docs]classDataVariableAndName(CoreDataVariable):
[docs]def__init__(self,addr:int,var_type:'_types.Type',var_name:str,auto_discovered:bool)->None:super(DataVariableAndName,self).__init__(addr,var_type,auto_discovered)self.name=var_name
def__repr__(self)->str:returnf"<var{self.address:#x}:{self.type}{self.name}>"