collaboration.remote module

binaryninja.collaboration.remote.Remote([...])

Class representing a connection to a Collaboration server

class Remote(name: str | None = None, address: str | None = None, handle=None)[source]

Bases: object

Class representing a connection to a Collaboration server

Parameters:
  • name (str | None) –

  • address (str | None) –

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

nop(*args, **kwargs)[source]