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 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 clear_all_bookmarks Attempts to remove all bookmarks from the server.
Method refresh Requests a fresh view of the bookmarks from the server.
Method remove Attempts to remove the passed bookmark from the server.
Method remove_if Attempts to remove all bookmarks that satisfy a condition from the server.
Instance Variable _bookmarks Undocumented
Instance Variable _rvn Undocumented
Instance Variable _trace Undocumented
def __init__(self, _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

Returns
The newly added bookmark, or the existing bookmark if it already existed.
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

Parameters
transitionA reven2.trace.Transition instance at which look for bookmarks
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 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')]
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

Parameters
bookmarkA Bookmark instance obtained from Bookmarks.all or Bookmarks.at_transition.
Returns
True 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.
Raises
RuntimeErrorIf called on a bookmark that is being edited or have been edited, since the last refresh, by another client (e.g. Axion).
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

Parameters
fA function accepting a Bookmark as argument and return True if that bookmark must be removed, False if it must be kept.
_bookmarks =

Undocumented

_rvn =

Undocumented

_trace =

Undocumented