collaboration.remote module¶

binaryninja.collaboration.remote.Remote(handle)

Class representing a connection to a Collaboration server

class Remote(handle: LP_BNRemote)[source]¶

Bases: object

Class representing a connection to a Collaboration server

Parameters:: handle (LP_BNRemote) –

connect(username: str | None = None, token: str | None = None)[source]¶

Connect to a Remote, loading metadata and optionally acquiring a token.

Note

If no username or token are provided, they will be looked up from the keychain, likely saved there by Enterprise authentication.

Parameters:

username (str | None) – Optional username to connect with
token (str | None) – Optional token to authenticate with

Raises:

RuntimeError – If the connection fails

create_group(name: str, usernames: List[str]) → Group[source]¶

Create a new group on the remote (and pull it)

Note

This function is only available to accounts with admin status on the Remote

Parameters:

name (str) – Group name
usernames (List[str]) – List of usernames of users in the group

Returns:

Reference to the created group

Raises:

RuntimeError if there was an error

Return type:

Group

create_project(name: str, description: str) → RemoteProject[source]¶

Create a new project on the remote (and pull it)

Parameters:

name (str) – Project name
description (str) – Project description

Returns:

Reference to the created project

Raises:

RuntimeError if there was an error

Return type:

RemoteProject

create_user(username: str, email: str, is_active: bool, password: str, group_ids: List[int], user_permission_ids: List[int]) → User[source]¶

Create a new user on the remote (and pull it)

Note

This function is only available to accounts with admin status on the Remote

Parameters:

username (str) – User username
email (str) – User email
is_active (bool) – If the user is enabled
password (str) – User password
group_ids (List[int]) – List of group ids for the user
user_permission_ids (List[int]) – List of permission ids for the user

Returns:

Reference to the created user

Raises:

RuntimeError if there was an error

Return type:

User

delete_group(group: Group)[source]¶

Delete a group from the remote

Note

This function is only available to accounts with admin status on the Remote

Parameters:: group (Group) – Group to delete
Raises:: RuntimeError if there was an error

delete_project(project: RemoteProject)[source]¶

Delete a project from the remote

Parameters:: project (RemoteProject) – Project to delete
Raises:: RuntimeError if there was an error

disconnect()[source]¶

Disconnect from the remote

Raises:: RuntimeError – If there was somehow an error

static get_for_bv(bv: BinaryView) → Remote | None[source]¶

Get the Remote for a Binary View

Parameters:: bv (BinaryView) – Binary view, potentially with collaboration metadata
Returns:: Remote from one of the connected remotes, or None if not found
Raises:: RuntimeError – If there was an error
Return type:: Remote | None

static get_for_local_database(database: Database) → Remote | None[source]¶

Get the Remote for a Database

Parameters:: database (Database) – BN database, potentially with collaboration metadata
Returns:: Remote from one of the connected remotes, or None if not found
Return type:: Optional[Remote]
Raises:: RuntimeError – If there was an error

get_group_by_id(id: int) → Group | None[source]¶

Get a specific group in the Remote by its id

Note

If groups have not been pulled, they will be pulled upon calling this.

Note

This function is only available to accounts with admin status on the Remote

Parameters:: id (int) – Id of Group
Returns:: Group object, if one with that id exists. Else, None
Raises:: RuntimeError if there was an error pulling groups
Return type:: Group | None

get_group_by_name(name: str) → Group | None[source]¶

Get a specific group in the Remote by its name

Note

If groups have not been pulled, they will be pulled upon calling this.

Note

This function is only available to accounts with admin status on the Remote

Parameters:: name (str) – Name of Group
Returns:: Group object, if one with that name exists. Else, None
Raises:: RuntimeError if there was an error pulling groups
Return type:: Group | None

get_project_by_id(id: str) → RemoteProject | None[source]¶

Get a specific project in the Remote by its id

Note

If projects have not been pulled, they will be pulled upon calling this.

Parameters:: id (str) – Id of Project
Returns:: Project object, if one with that id exists. Else, None
Raises:: RuntimeError if there was an error pulling projects
Return type:: RemoteProject | None

get_project_by_name(name: str) → RemoteProject | None[source]¶

Get a specific project in the Remote by its name

Note

If projects have not been pulled, they will be pulled upon calling this.

Parameters:: name (str) – Name of Project
Returns:: Project object, if one with that name exists. Else, None
Raises:: RuntimeError if there was an error pulling projects
Return type:: RemoteProject | None

get_user_by_id(id: str) → User | None[source]¶

Get a specific user in the Remote by their id

Note

If users have not been pulled, they will be pulled upon calling this.

Note

This function is only available to accounts with admin status on the Remote

Parameters:: id (str) – Id of User
Returns:: User object, if one with that id exists. Else, None
Raises:: RuntimeError if there was an error pulling users
Return type:: User | None

get_user_by_username(username: str) → User | None[source]¶

Get a specific user in the Remote by their username

Note

If users have not been pulled, they will be pulled upon calling this.

Note

This function is only available to accounts with admin status on the Remote

Parameters:: username (str) – Username of User
Returns:: User object, if one with that name exists. Else, None
Raises:: RuntimeError if there was an error pulling users
Return type:: User | None

load_metadata()[source]¶

Load metadata from the Remote, including unique id and versions

Raises:: RuntimeError – If there was an error

pull_groups(progress: ~typing.Callable[[int, int], bool] = <function nop>)[source]¶

Pull the list of groups from the Remote.

Note

This function is only available to accounts with admin status on the Remote

Parameters:: progress (Callable[[int, int], bool]) – Function to call for progress updates
Raises:: RuntimeError if there was an error pulling groups

pull_projects(progress: ~typing.Callable[[int, int], bool] = <function nop>)[source]¶

Pull the list of projects from the Remote.

Parameters:: progress (Callable[[int, int], bool]) – Function to call for progress updates
Raises:: RuntimeError if there was an error pulling projects

pull_users(progress: ~typing.Callable[[int, int], bool] = <function nop>)[source]¶

Pull the list of users from the Remote.

Note

This function is only available to accounts with admin status on the Remote. Non-admin accounts attempting to call this function will pull an empty list of users.

Parameters:: progress (Callable[[int, int], bool]) – Function to call for progress updates
Raises:: RuntimeError if there was an error pulling users

push_group(group: Group, extra_fields: Dict[str, str] | None = None)[source]¶

Push an updated Group object to the Remote

Note

This function is only available to accounts with admin status on the Remote

Parameters:

group (Group) – Group object which has been updated
extra_fields (Dict[str, str] | None) – Extra HTTP fields to send with the update

Raises:

RuntimeError if there was an error

push_project(project: RemoteProject, extra_fields: Dict[str, str] | None = None)[source]¶

Push an updated Project object to the Remote

Parameters:

project (RemoteProject) – Project object which has been updated
extra_fields (Dict[str, str] | None) – Extra HTTP fields to send with the update

Raises:

RuntimeError if there was an error

push_user(user: User, extra_fields: Dict[str, str] | None = None)[source]¶

Push an updated User object to the Remote

Note

This function is only available to accounts with admin status on the Remote

Parameters:

group – User object which has been updated
extra_fields (Dict[str, str] | None) – Extra HTTP fields to send with the update
user (User) –

Raises:

RuntimeError if there was an error

request_authentication_token(username: str, password: str) → str | None[source]¶

Request an authentication token using a username and password.

Parameters:

username (str) – Username to authenticate with
password (str) – Password of user

Returns:

Authentication token string, or None if there was an error

Return type:

str | None

search_groups(prefix: str) → List[Tuple[int, str]][source]¶

Search for groups in the Remote with a given prefix

Parameters:: prefix (str) – Prefix of name for groups
Returns:: List of group id <=> group name pairs
Raises:: RuntimeError if there was an error
Return type:: List[Tuple[int, str]]

search_users(prefix: str) → List[Tuple[str, str]][source]¶

Search for users in the Remote with a given prefix

Parameters:: prefix (str) – Prefix of name for users
Returns:: List of user id <=> user name pairs
Raises:: RuntimeError if there was an error
Return type:: List[Tuple[str, str]]

property address: str¶

Base address of the Remote

Returns:: URL string

property auth_backends: List[Tuple[str, str]]¶

List of supported authentication backends on the server. If metadata has not been pulled, it will be pulled upon calling this.

Returns:: List of Backend id <=> backend display name tuples
Raises:: RuntimeError – If there was an error

property current_user: User | None¶

Get the user object for the currently connected user (only if you are an admin)

Note

If users have not been pulled, they will be pulled upon calling this.

Note

This function is only available to accounts with admin status on the Remote

Returns:: User object
Raises:: RuntimeError if there was an error pulling users

property groups: List[Group]¶

Get the list of groups in this project.

Note

If groups have not been pulled, they will be pulled upon calling this.

Note

This function is only available to accounts with admin status on the Remote

Returns:: List of Group objects
Raises:: RuntimeError if there was an error pulling groups

property has_loaded_metadata¶

If the remote has pulled metadata like its id, etc

Returns:: True if it has been pulled

property has_pulled_groups: bool¶

If the project has pulled the groups yet

Returns:: True if they have been pulled

property has_pulled_projects: bool¶

If the project has pulled the projects yet

Returns:: True if they have been pulled

property has_pulled_users: bool¶

If the project has pulled the users yet

Returns:: True if they have been pulled

property is_admin: bool¶

If the currently connected user is an administrator.

Note

If users have not been pulled, they will attempt to be pulled upon calling this.

Returns:: True if the user is an administrator

property is_connected: bool¶

If the Remote is connected (has Remote.connect been called)

Returns:: True if connected

property is_enterprise: bool¶

If this remote is the same as the Enterprise License server

Returns:: True if the same

property name: str¶

Assigned name of the Remote

Returns:: Name string

property projects: List[RemoteProject]¶

Get the list of projects in this project.

Note

If projects have not been pulled, they will be pulled upon calling this.

Returns:: List of Project objects
Raises:: RuntimeError if there was an error pulling projects

property server_build_id: str¶

Build id of software running on the server. If metadata has not been pulled, it will be pulled upon calling this.

Returns:: Server build id string
Raises:: RuntimeError – If there was an error

property server_version: int¶

Version of software running on the server. If metadata has not been pulled, it will be pulled upon calling this.

Returns:: Server version number
Raises:: RuntimeError – If there was an error

property token: str¶

Token used to connect to the remote

Returns:: Token string

property unique_id: str¶

Unique id. If metadata has not been pulled, it will be pulled upon calling this.

Returns:: Id string
Raises:: RuntimeError – If there was an error pulling metadata.

property username: str¶

Username used to connect to the remote

Returns:: Username string

property users: List[User]¶

Get the list of users in this project.

Note

If users have not been pulled, they will be pulled upon calling this.

Note

This function is only available to accounts with admin status on the Remote

Returns:: List of User objects
Raises:: RuntimeError if there was an error pulling users