5.1. bropkg.manager module

A module defining the main Bro Package Manager interface which supplies methods to interact with and operate on Bro packages.

class bropkg.manager.Manager(state_dir, script_dir, plugin_dir, bro_dist='')

Bases: object

A package manager object performs various operations on packages.

It uses a state directory and a manifest file within it to keep track of package sources, installed packages and their statuses.

sources

dict of str -> source.Source – dictionary package sources keyed by the name given to add_source()

installed_pkgs

dict of str -> package.InstalledPackage – a dictionary of installed packaged keyed on package names (the last component of the package’s git URL)

bro_dist

str – path to the Bro source code distribution. This is needed for packages that contain Bro plugins that need to be built from source code.

state_dir

str – the directory where the package manager will a maintain manifest file, package/source git clones, and other persistent state the manager needs in order to operate

backup_dir

str – a directory where the package manager will store backup files (e.g. locally modified package config files)

log_dir

str – a directory where the package manager will store misc. logs files (e.g. package build logs)

scratch_dir

str – a directory where the package manager performs miscellaneous/temporary file operations

script_dir

str – the directory where the package manager will copy each installed package’s script_dir (as given by its bro-pkg.meta file). Each package gets a subdirectory within script_dir associated with its name.

plugin_dir

str – the directory where the package manager will copy each installed package’s plugin_dir (as given by its bro-pkg.meta file). Each package gets a subdirectory within plugin_dir associated with its name.

source_clonedir

str – the directory where the package manager will clone package sources. Each source gets a subdirectory associated with its name.

package_clonedir

str – the directory where the package manager will clone installed packages. Each package gets a subdirectory associated with its name.

package_testdir

str – the directory where the package manager will run tests. Each package gets a subdirectory associated with its name.

manifest

str – the path to the package manager’s manifest file. This file maintains a list of installed packages and their status.

autoload_script

str – path to a Bro script named packages.bro that the package manager maintains. It is a list of @load for each installed package that is marked as loaded (see load()).

autoload_package

str – path to a Bro __load__.bro script which is just a symlink to autoload_script. It’s always located in a directory named packages, so as long as BROPATH is configured correctly, @load packages will load all installed packages that have been marked as loaded.

add_source(name, git_url)

Add a git repository that acts as a source of packages.

Parameters:
  • name (str) – a short name that will be used to reference the package source.
  • git_url (str) – the git URL of the package source
Returns:

empty string if the source is successfully added, else the reason why it failed.

Return type:

str

backup_modified_files(backup_subdir, modified_files)

Creates backups of modified config files

Parameters:
  • modified_files (list of (str, str)) – the return value of modified_config_files().
  • backup_subdir (str) – the subdir of backup_dir in which
Returns:

paths indicating the backup locations. The order of the returned list corresponds directly to the order of modified_files.

Return type:

list of str

bro_plugin_path()

Return the path where installed package plugins are located.

This path can be added to BRO_PLUGIN_PATH for interoperability with Bro.

bropath()

Return the path where installed package scripts are located.

This path can be added to BROPATH for interoperability with Bro.

bundle(bundle_file, package_list, prefer_existing_clones=False)

Creates a package bundle.

Parameters:
  • bundle_file (str) – filesystem path of the zip file to create.
  • package_list (list of (str, str)) – a list of (git URL, version) string tuples to put in the bundle. If the version string is empty, the latest available version of the package is used.
  • prefer_existing_clones (bool) – if True and the package list contains a package at a version that is already installed, then the existing git clone of that package is put into the bundle instead of cloning from the remote repository.
Returns:

empty string if the bundle is successfully created, else an error string explaining what failed.

Return type:

str

find_installed_package(pkg_path)

Return an package.InstalledPackage if one matches the name.

Parameters:pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.

A package’s name is the last component of it’s git URL.

has_scripts(installed_pkg)

Return whether a package.InstalledPackage installed scripts.

Parameters:installed_pkg (package.InstalledPackage) – the installed package to check for whether it has installed any Bro scripts.
Returns:True if the package has installed Bro scripts.
Return type:bool
info(pkg_path, version='', prefer_installed=True)

Retrieves information about a package.

Parameters:
  • pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
  • version (str) – may be a git version tag, branch name, or commit hash from which metadata will be pulled. If an empty string is given, then the latest git version tag is used (or the “master” branch if no version tags exist).
  • prefer_installed (bool) – if this is set, then the information from any current installation of the package is returned instead of retrieving the latest information from the package’s git repo. The version parameter is also ignored when this is set as it uses whatever version of the package is currently installed.
Returns:

A package.PackageInfo object.

install(pkg_path, version='')

Install a package.

Parameters:
  • pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
  • version (str) – if not given, then the latest git version tag is installed (or if no version tags exist, the “master” branch is installed). If given, it may be either a git version tag or a git branch name.
Returns:

empty string if package installation succeeded else an error string explaining why it failed.

Return type:

str

Raises:

IOError – if the manifest can’t be written

installed_packages()

Return list of package.InstalledPackage.

load(pkg_path)

Mark an installed package as being “loaded”.

The collection of “loaded” packages is a convenient way for Bro to more simply load a whole group of packages installed via the package manager.

Parameters:pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
Returns:empty string if the package is successfully marked as loaded, else an explanation of why it failed.
Return type:str
Raises:IOError – if the loader script or manifest can’t be written
loaded_packages()

Return list of loaded package.InstalledPackage.

match_source_packages(pkg_path)

Return a list of package.Package that match a given path.

Parameters:pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
modified_config_files(installed_pkg)

Return a list of package config files that the user has modified.

Parameters:installed_pkg (package.InstalledPackage) – the installed package to check for whether it has installed any Bro scripts.
Returns:tuples that describe the modified config files. The first element is the config file as specified in the package metadata (a file path relative to the package’s root directory). The second element is an absolute file system path to where that config file is currently installed.
Return type:list of (str, str)
package_build_log(pkg_path)

Return the path to the package manager’s build log for a package.

Parameters:pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
package_versions(installed_package)

Returns a list of version number tags available for a package.

Parameters:installed_package (package.InstalledPackage) – the package for which version number tags will be retrieved.
Returns:the version number tags.
Return type:list of str
pin(pkg_path)

Pin a currently installed package to the currently installed version.

Pinned packages are never upgraded when calling upgrade().

Parameters:pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
Returns:None if no matching installed package could be found, else the installed package that was pinned.
Return type:package.InstalledPackage
Raises:IOError – when the manifest file can’t be written
refresh_installed_packages()

Fetch latest git information for installed packages.

This retrieves information about outdated packages, but does not actually upgrade their installations.

Raises:IOError – if the package manifest file can’t be written
refresh_source(name, aggregate=False, push=False)

Pull latest git information from a package source.

This makes the latest pre-aggregated package metadata available or performs the aggregation locally in order to push it to the actual package source. Locally aggregated data also takes precedence over the source’s pre-aggregated data, so it can be useful in the case the operator of the source does not update their pre-aggregated data at a frequent enough interval.

Parameters:
  • name (str) – the name of the package source. E.g. the same name used as a key to add_source().
  • aggregate (bool) – whether to perform a local metadata aggregation by crawling all packages listed in the source’s index files.
  • push (bool) – whether to push local changes to the aggregated metadata to the remote package source. If the aggregate flag is set, the data will be pushed after the aggregation is finished.
Returns:

an empty string if no errors occurred, else a description of what went wrong.

Return type:

str

remove(pkg_path)

Remove an installed package.

Parameters:

pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.

Returns:

True if an installed package was removed, else False.

Return type:

bool

Raises:
  • IOError – if the package manifest file can’t be written
  • OSError – if the installed package’s directory can’t be deleted
save_temporary_config_files(installed_pkg)

Return a list of temporary package config file backups.

Parameters:installed_pkg (package.InstalledPackage) – the installed package to save temporary config file backups for.
Returns:tuples that describe the config files backups. The first element is the config file as specified in the package metadata (a file path relative to the package’s root directory). The second element is an absolute file system path to where that config file has been copied. It should be considered temporary, so make use of it before doing any further operations on packages.
Return type:list of (str, str)
source_packages()

Return a list of package.Package within all sources.

test(pkg_path, version='')

Test a package.

Parameters:
  • pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
  • version (str) – if not given, then the latest git version tag is used (or if no version tags exist, the “master” branch is used). If given, it may be either a git version tag or a git branch name.
Returns:

a tuple containing an error message string, a boolean indicating whether the tests passed, as well as a path to the directory in which the tests were run. In the case where tests failed, the directory can be inspected to figure out what went wrong. In the case where the error message string is not empty, the error message indicates the reason why tests could not be run.

Return type:

(str, bool, str)

unbundle(bundle_file)
unload(pkg_path)

Unmark an installed package as being “loaded”.

The collection of “loaded” packages is a convenient way for Bro to more simply load a whole group of packages installed via the package manager.

Parameters:pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
Returns:True if a package is successfully unmarked as loaded.
Return type:bool
Raises:IOError – if the loader script or manifest can’t be written
unpin(pkg_path)

Unpin a currently installed package and allow it to be upgraded.

Parameters:pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
Returns:None if no matching installed package could be found, else the installed package that was unpinned.
Return type:package.InstalledPackage
Raises:IOError – when the manifest file can’t be written
upgrade(pkg_path)

Upgrade a package to the latest available version.

Parameters:pkg_path (str) – the full git URL of a package or the shortened path/name that refers to it within a package source. E.g. for a package source called “bro” with package named “foo” in alice/bro-pkg.index, the following inputs may refer to the package: “foo”, “alice/foo”, or “bro/alice/foo”.
Returns:an empty string if package upgrade succeeded else an error string explaining why it failed.
Return type:str
Raises:IOError – if the manifest can’t be written
validate_dependencies(requested_packages, ignore_installed_packages=False)

Validates package dependencies.

Parameters:
  • requested_packages (list of (str, str)) – a list of (package name or git URL, version) string tuples validate. If the version string is empty, the latest available version of the package is used.
  • ignore_installed_packages (bool) – whether the dependency analysis should consider installed packages as satisfying dependency requirements.
Returns:

the first element of the tuple is an empty string if dependency graph was successfully validated, else an error string explaining what is invalid. In the case it was validated, the second element is a list of tuples where the first elements are dependency packages that would need to be installed in order to satisfy the dependencies of the requested packages (it will not include any packages that are already installed or that are in the requested_packages argument). The second element of tuples in the list is a version string of the associated package that satisfies dependency requirements.

Return type:

(str, list of (package.PackageInfo, str))