GrimoireLab Toolkit

Toolkit of common functions used across GrimoireLab projects.

This package provides a library composed by functions widely used in other GrimoireLab projects. These function deal with date handling, introspection, URIs/URLs, among other topics.

Requirements

• Python >= 3.8

You will also need some other libraries for running the tool, you can find the whole list of dependencies in pyproject.toml file.

Installation

There are several ways to install GrimoireLab Toolkit on your system: packages or source code using Poetry or pip.

PyPI

GrimoireLab Toolkit can be installed using pip, a tool for installing Python packages. To do it, run the next command:

$ pip install grimoirelab-toolkit

Source code

To install from the source code you will need to clone the repository first:

$ git clone https://github.com/chaoss/grimoirelab-toolkit
$ cd grimoirelab-toolkit

Then use pip or Poetry to install the package along with its dependencies.

Pip

To install the package from local directory run the following command:

$ pip install .

In case you are a developer, you should install GrimoireLab Toolkit in editable mode:

$ pip install -e .

Poetry

We use poetry for dependency management and packaging. You can install it following its documentation. Once you have installed it, you can install GrimoireLab Toolkit and the dependencies in a project isolated environment using:

$ poetry install

To spaw a new shell within the virtual environment use:

$ poetry shell

Credential Manager Library

This is a module made to retrieve credentials from different secrets management systems like Bitwarden. It accesses the secrets management service, looks for the desired credential and returns it in String form.

To use the module in your python code

Bitwarden

from grimoirelab_toolkit.credential_manager import BitwardenManager


# Instantiate the Bitwarden manager using the api credentials for login
bw_manager = BitwardenManager("your_client_id", "your_client_secret", "your_master_password")

# Login
bw_manager.login()

# Retrieve a secret from Bitwarden
username = bw_manager.get_secret("github")
password = bw_manager.get_secret("elasticsearch")

# Logout
bw_manager.logout()

Response format

When calling get_secret(item_name), the method returns a JSON object with the following structure:

NOTE: the parameter "item_name" corresponds with the field "name" of the json. That's the name of the item. (in this case, GitHub)

Example Response

{
  "passwordHistory": [
    {
      "lastUsedDate": "2024-11-05T10:27:18.411Z",
      "password": "previous_password_value_1"
    },
    {
      "lastUsedDate": "2024-11-05T09:20:06.512Z",
      "password": "previous_password_value_2"
    }
  ],
  "revisionDate": "2025-05-11T14:40:19.456Z",
  "creationDate": "2024-10-30T18:56:41.023Z",
  "object": "item",
  "id": "91300380-620f-4707-8de1-b21901383315",
  "organizationId": null,
  "folderId": null,
  "type": 1,
  "reprompt": 0,
  "name": "GitHub",
  "notes": null,
  "favorite": false,
  "fields": [
    {
      "name": "api-token",
      "value": "TOKEN"
      "type": 0,
      "linkedId": null
    },
    {
      "name": "api_key",
      "value": "APIKEY",
      "type": 0,
      "linkedId": null
    }
  ],
  "login": {
    "uris": [],
    "username": "your_username",
    "password": "your_password",
    "totp": null,
    "passwordRevisionDate": "2024-11-05T10:27:18.411Z"
  },
  "collectionIds": [],
  "attachments": []
}

Field Descriptions

• passwordHistory: Array of previously used passwords with timestamps
• revisionDate: Last modification timestamp (ISO 8601 format)
• creationDate: Item creation timestamp (ISO 8601 format)
• object: Always "item" for credential items
• id: Unique identifier for this item
• organizationId: Organization ID if shared, null for personal items
• folderId: Folder ID if organized, null otherwise
• type: Item type (1 = login, 2 = secure note, 3 = card, 4 = identity)
• name: Display name of the credential item (name used as argument in get_secret())
• notes: Optional notes field
• favorite: Boolean indicating if item is favorited
• fields: Array of custom fields with name-value pairs
  • name: Field name
  • value: Field value (can contain secrets)
  • type: Field type (0 = text, 1 = hidden, 2 = boolean)
• login: Login credentials object
  • username: Login username
  • password: Login password
  • totp: TOTP secret for 2FA (if configured)
  • uris: Array of associated URIs/URLs
  • passwordRevisionDate: Last password change timestamp
• collectionIds: Array of collection IDs this item belongs to
• attachments: Array of file attachments

The module uses the Bitwarden CLI to interact with Bitwarden.

License

Licensed under GNU General Public License (GPL), version 3 or later.