class Bookmarks:
A list of the bookmarks saved on the REVEN server for this project.
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 |
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.
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.
>>> # 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
| Returns | The newly added bookmark, or the existing bookmark if it already existed. | |
Attempts to remove the passed bookmark from the server.
>>> # 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!")
| 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). |
Return a generator of all the bookmarks in the trace
>>> # 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')
Return a generator of the bookmarks at the specified transition
>>> # 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')
| Parameters | transition | A reven2.trace.Transition instance at which look for bookmarks |
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.
>>> # 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')]
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.
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.
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.
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.
>>> # 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')]
| Parameters | f | A function accepting a Bookmark as argument and return True if that bookmark must be removed, False if it must be kept. |