reven2.bookmark.Bookmarks

class documentation

class Bookmarks:

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
transition	A `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
bookmark	A `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
`RuntimeError`	If 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

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
f	A 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