class documentation

class Bookmarks:

View In Hierarchy

A list of the bookmarks saved on the REVEN server for this project.

Warnings

This object is not meant to be constructed directly. Use RevenServer.bookmarks instead.

Method __init__ Undocumented
Method add Attempts to add a new bookmark at the specified transition, with the specified description.
Method remove Attempts to remove the passed bookmark from the server.
Method all Return a generator of all the bookmarks in the trace
Method at_transition Return a generator of the bookmarks at the specified transition
Method refresh Requests a fresh view of the bookmarks from the server.
Method clear_all_bookmarks Attempts to remove all bookmarks from the server.
Method remove_if Attempts to remove all bookmarks that satisfy a condition from the server.
Instance Variable _rvn Undocumented
Instance Variable _trace Undocumented
Instance Variable _bookmarks Undocumented
def __init__(self, _trace):

Undocumented

_rvn =

Undocumented

_trace =

Undocumented

def add(self, transition, description):

Attempts to add a new bookmark at the specified transition, with the specified description.

If the bookmarks already contain a bookmark with the same transition and description, then no new bookmark will be added.

Note

Searching for existing bookmarks is done against the local bookmark list. In particular, if the same bookmark was already added by another client since the last call to Bookmarks.refresh, the bookmark will be duplicated.

Examples

>>> # Adding a new bookmark
>>> bookmarks.add(reven_server.trace.transition(42), "Forty-Two")
>>> # Adding a new bookmark with the current location as description
>>> loc = transition.context_before().ossi.location()
>>> bookmarks.add(transition, str(loc))
>>> # Adding all calls to a function as bookmarks:
>>> symbol = next(reven_server.ossi.symbols("^NtCreateFiles$", "ntoskrnl"))
>>> for ctx in reven_server.trace.search(symbol):
...    bookmarks.add(ctx.transition_after(), "auto: {}".format(symbol.name))
>>> # You can check the added bookmarks in Axion

Information

ReturnsThe newly added bookmark, or the existing bookmark if it already existed.
def remove(self, bookmark):

Attempts to remove the passed bookmark from the server.

Examples

>>> # Removing a freshly added bookmark after a typo
>>> bookmark = bookmarks.add(transition, "Very impotant transition!")
>>> bookmarks.remove(bookmark)
>>> bookmark = bookmarks.add(transition, "Very important transition!")

Information

ParametersbookmarkA Bookmark instance obtained from Bookmarks.all or Bookmarks.at_transition.
ReturnsTrue if calling this function resulted in the removal of this bookmark on the server. False if the bookmark was already removed either by a previous call or by another client.
RaisesRuntimeErrorIf called on a bookmark that is being edited or have been edited, since the last refresh, by another client (e.g. Axion).
def all(self):

Return a generator of all the bookmarks in the trace

Examples

>>> # Get a list of all the bookmarks of the trace
>>> list(bookmarks.all())
[Bookmark(id=1, transition=#62888 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=2, transition=#4136301 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=3, transition=#7559593 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=4, transition=#15131085 sub rsp, 0x88, description='auto: NtCreateFile')]
>>> # Get a bookmark
>>> next(bookmarks.all())
Bookmark(id=1, transition=#62888 sub rsp, 0x88, description='auto: NtCreateFile')
def at_transition(self, transition):

Return a generator of the bookmarks at the specified transition

Examples

>>> # Return one bookmark at transition 62888
>>> next(bookmarks.at_transition(reven_server.trace.transition(62888)))
Bookmark(id=1, transition=#62888 sub rsp, 0x88, description='auto: NtCreateFile')

Information

ParameterstransitionA reven2.trace.Transition instance at which look for bookmarks
def refresh(self):

Requests a fresh view of the bookmarks from the server.

This will retrieve changes made by other clients (Axion, or another script). You should call this method when you know other clients modified the bookmarks of this project.

Examples

>>> # Getting changes made by Axion
>>> list(bookmarks.all())
[Bookmark(id=1, transition=#62888 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=2, transition=#4136301 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=3, transition=#7559593 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=4, transition=#15131085 sub rsp, 0x88, description='auto: NtCreateFile')]
>>> # ... Add one bookmark in Axion
>>> bookmarks.refresh()
>>> list(bookmarks.all())
[Bookmark(id=1, transition=#62888 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=2, transition=#4136301 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=3, transition=#7559593 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=4, transition=#15131085 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=5, transition=#10335341 xor ecx, r9d, description='SymCryptSha256AppendBlocks_ul1+0xc6 - ci.dll')]
_bookmarks =

Undocumented

def clear_all_bookmarks(self):

Attempts to remove all bookmarks from the server.

Bookmarks that are being edited or have been edited since, the last refresh, by other clients will not be removed, even using this method.

Note

Removing bookmarks is done against the local bookmark list. In particular, if some other bookmarks were added by another client since the last call to Bookmarks.refresh, the bookmark will not be removed.

def remove_if(self, f):

Attempts to remove all bookmarks that satisfy a condition from the server.

Bookmarks that are being edited or have been edited since the last refresh by other clients will not be removed, even using this method.

Note

Removing bookmarks is done against the local bookmark list. In particular, if some other bookmarks were added by another client since the last call to Bookmarks.refresh, the bookmark will not be removed.

Examples

>>> # Removing all bookmarks that start with the "auto:" prefix
>>> list(bookmarks.all())
[Bookmark(id=1, transition=#62888 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=2, transition=#4136301 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=3, transition=#7559593 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=4, transition=#15131085 sub rsp, 0x88, description='auto: NtCreateFile'),
Bookmark(id=5, transition=#10335341 xor ecx, r9d, description='SymCryptSha256AppendBlocks_ul1+0xc6 - ci.dll')]
>>> bookmarks.remove_if(lambda bookmark: bookmark.description.startswith('auto:'))
>>> list(bookmarks.all())
[Bookmark(id=5, transition=#10335341 xor ecx, r9d, description='SymCryptSha256AppendBlocks_ul1+0xc6 - ci.dll')]

Information

ParametersfA function accepting a Bookmark as argument and return True if that bookmark must be removed, False if it must be kept.
API Documentation for reven2, generated by pydoctor 21.2.2 at 2021-10-01 07:18:12.