runzero.api.explorers

Management of an Organization’s explorers, which perform scan activity.

Module Contents

Classes

Explorers

Management of runZero Explorers.
class runzero.api.explorers.Explorers(client: runzero.client.Client)[source]

Management of runZero Explorers.

Explorers are deployed to a machine and are assigned to runzero.api.Sites where they perform Scans defined by runzero.api.Tasks.

Explorers are simliar to runzero.api.HostedZones in that both execute tasks. Whereas HostedZones are provided by runZero and do the work of Explorers, an Explorer is a single deployable service which can scan networks which are not publicly accessible.

Parameters:

client (runzero.client.Client) – A handle to the runzero.Client client which manages interactions with the runZero server.

Constructor method

delete(org_id: uuid.UUID, explorer_id: uuid.UUID) → None[source]

Removes and uninstalls an explorer from your Organization.

Parameters:

  • org_id (uuid.UUID) – The ID of the organization to operate against

  • explorer_id (uuid.UUID) – ID of explorer to delete

Returns:

None

Raises:

AuthError, ClientError, ServerError

Return type:

None

get(org_id: uuid.UUID, name: str | None = None, explorer_id: uuid.UUID | None = None) → runzero.types.Explorer | None[source]

Retrieves the runZero Explorer with the provided name or id, if it is active and exists in the Organization.

Parameters:

  • org_id (uuid.UUID) – The ID of the organization to operate against

  • name (Optional[str]) – Optional name of the explorer to retrieve. This is a case-insensitive hostname match. If not provided, must provide explorer_id.

  • explorer_id (Optional[uuid.UUID]) – Optional id of the explorer to retrieve. If not provided, must provide name.

Returns:

explorer requested or None

Raises:

AuthError, ClientError, ServerError, ValueError if neither explorer_id nor name are provided.

Return type:

Optional[runzero.types.Explorer]

get_all(org_id: uuid.UUID) → List[runzero.types.Explorer][source]

Retrieves all active runZero Explorers available within the given Organization.

Parameters:

org_id (uuid.UUID) – The ID of the organization to operate against

Returns:

a list of all Explorers available within the given Organization

Raises:

AuthError, ClientError, ServerError

Return type:

List[runzero.types.Explorer]

move_to_site(org_id: uuid.UUID, explorer_id: uuid.UUID, site_id: uuid.UUID) → runzero.types.Explorer[source]

Moves an explorer to a different site.

Explorers moved to a new site will no longer execute tasks defined in the old site, and will be available to execute tasks defined in the new site.

Parameters:

  • org_id (uuid.UUID) – The ID of the organization to operate against

  • explorer_id (uuid.UUID) – ID of explorer to assign to a new site

  • site_id (uuid.UUID) – ID of the site the explorer will be assigned to

Returns:

The Explorer with the provided ID, assigned to new site site_id

Raises:

AuthError, ClientError, ServerError

Return type:

runzero.types.Explorer

update_to_latest_version(org_id: uuid.UUID, explorer_id: uuid.UUID) → None[source]

Updates an explorer with given explorer id to the latest explorer software version available.

This will force the explorer to upgrade and restart.

Parameters:

  • org_id (uuid.UUID) – The ID of the organization to operate against

  • explorer_id (uuid.UUID) – The ID of the explorer to update

Returns:

None

Raises:

AuthError, ClientError, ServerError

Return type:

None