Import classic bookmarks

Purpose

Import classic bookmarks (created using up to REVEN 2.4) from ".rbm" files to the "server-side" bookmarks system (from REVEN 2.5+).

How to use

usage: import_bookmarks.py [-h] [--host HOST] [-p PORT] [-f FILENAME]
                           [--prepend-symbol]

optional arguments:
  -h, --help            show this help message and exit
  --host HOST           Reven host, as a string (default: "localhost")
  -p PORT, --port PORT  Reven port, as an int (default: 13370)
  -f FILENAME, --filename FILENAME
                        Path to the classic bookmark file (*.rbm).
  --prepend-symbol      If set, prepend the OSSI symbol as stored in the
                        classic symbol file to the description of the bookmark

Known limitations

N/A

Supported versions

REVEN 2.5+

Supported perimeter

Any REVEN scenario for which a .rbm is available.

Dependencies

None.

Source

import argparse
import json

import reven2


"""
# Import classic bookmarks

## Purpose

Import classic bookmarks (created using up to REVEN 2.4) from ".rbm" files to the "server-side" bookmarks system
(from REVEN 2.5+).

## How to use

```bash
usage: import_bookmarks.py [-h] [--host HOST] [-p PORT] [-f FILENAME]
                           [--prepend-symbol]

optional arguments:
  -h, --help            show this help message and exit
  --host HOST           Reven host, as a string (default: "localhost")
  -p PORT, --port PORT  Reven port, as an int (default: 13370)
  -f FILENAME, --filename FILENAME
                        Path to the classic bookmark file (*.rbm).
  --prepend-symbol      If set, prepend the OSSI symbol as stored in the
                        classic symbol file to the description of the bookmark
```

## Known limitations

N/A

## Supported versions

REVEN 2.5+

## Supported perimeter

Any REVEN scenario for which a .rbm is available.

## Dependencies

None.
"""


def import_bookmarks(reven_server, rbm_path, prepend_symbol=False):
    r"""
    This function is a helper to import classic bookmarks from ".rbm" files to the new "server-side" bookmarks system.

    Examples
    ========

    >>> # Import bookmarks
    >>> f = "Reven2/2.5.0-rc2-1-ga1b971b/Scenarios/bksod_ff34e5e1-dfaa-41fe-88b0-fdad14993fe3/UserData/bookmarks.rbm"
    >>> import_bookmarks(reven_server, f)
    >>> for bookmark in reven_server.bookmarks.all():
    ...     print(bookmark)
    #169672818: 'mst120 deallocated by network'
    #8655429: 'mst120 allocated by system'
    #8627412: 'IcaRawInput looks nice to see decrypted data'
    #1231549571: 'ica find channel on this pointer???'
    #1141851788: 'Same pointer reallocated to something else'
    #1231549773: 'crash'

    >>> # Import bookmarks, prepending the known symbol before the description
    >>> import_bookmarks(reven_server, f, prepend_symbol=True)
    >>> for bookmark in reven_server.bookmarks.all():
    ...     print(bookmark)
    #169672818: 'ExFreePoolWithTag+0x0 - ntoskrnl.exe: mst120 deallocated by network'
    #8655429: 'ExAllocatePoolWithTag+0x1df - ntoskrnl.exe: mst120 allocated by system'
    #8627412: 'IcaRawInput+0x0 - termdd.sys: IcaRawInput looks nice to see decrypted data'
    #1231549571: 'IcaFindChannel+0x3d - termdd.sys: ica find channel on this pointer???'
    #1141851788: 'ExAllocatePoolWithTag+0x1df - ntoskrnl.exe: Same pointer reallocated to something else'
    #1231549773: 'ExpCheckForIoPriorityBoost+0xa7 - ntoskrnl.exe: crash'

    Information
    ===========

    @param reven_server: The C{reven2.RevenServer} instance on which you wish to import the bookmarks.
    @param rbm_path: Path to the classic bookmark file.
    @param prepend_symbol: If C{True}, prepend the OSSI symbol as stored in the classic symbol file to the description
                           of the bookmark.
    """
    with open(rbm_path) as f:
        json_bookmarks = json.load(f)
        for json_bookmark in json_bookmarks.values():
            try:
                transition = reven_server.trace.transition(int(json_bookmark["identifier"]))
                description_prefix = (json_bookmark["symbol"] + ": ") if prepend_symbol else ""
                description = description_prefix + json_bookmark["description"]
                reven_server.bookmarks.add(transition, str(description))
            except IndexError:
                print(
                    "Skipping import of bookmark at transition {} which is out of range".format(
                        json_bookmark["identifier"]
                    )
                )


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--host", type=str, default="localhost", help='Reven host, as a string (default: "localhost")')
    parser.add_argument("-p", "--port", type=int, default="13370", help="Reven port, as an int (default: 13370)")
    parser.add_argument("-f", "--filename", type=str, help="Path to the classic bookmark file (*.rbm).")
    parser.add_argument(
        "--prepend-symbol",
        action="store_true",
        help="If set, prepend the OSSI symbol as stored in the classic symbol file to the "
        "description of the bookmark",
    )
    args = parser.parse_args()

    reven_server = reven2.RevenServer(args.host, args.port)
    import_bookmarks(reven_server, args.filename, args.prepend_symbol)
    print("Bookmarks imported!")