reven2.bookmark.Bookmarks class documentationreven2.bookmark
(View In Hierarchy)
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. |
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. |