New lookup plug-in: Bitwarden Secrets Manager (#6389)

* add Bitwarden Secrets Manager lookup

* fix pep8 and yamllint complaints

* fix version_added, add maintainer and copyright notice

* document BWS_ACCESS_TOKEN env var and declare as required

* avoid returning nested list

* update 'value of a secret' example after f6c4492c

* update copyright notice in bitwarden_secrets_manager plugin

thx felixfontein

Co-authored-by: Felix Fontein <felix@fontein.de>

* rename classes to distinguish from existing bw plugin

* use AnsibleLookupError, formatting

* bump version_added to 7.0.0

Co-authored-by: Felix Fontein <felix@fontein.de>

* ci fix: python style guide calls for excessive blank lines

https://peps.python.org/pep-0008/#blank-lines

* first attempt at unit tests for bws lookup

* ci fix: remove trailing newline

* attempt to fix tests object not callable error

* address formatting, tests and pyright suggestions

* reduce scope of mocked code for more real test coverage

only the actual bws CLI call is mocked now, this should enable the
exception thrown test to succeed if I didn't add new problems

* fix undefined variable 'expected_rc'

* fix mocked _run method to return correct data types

* keep list of one element for test case comparison

* bump version_added to 7.2.0

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: jantari <jantari@github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/lookup/bitwarden_secrets_manager.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2023, jantari (https://github.com/jantari)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+from __future__ import (absolute_import, division, print_function)
+
+__metaclass__ = type
+
+DOCUMENTATION = """
+    name: bitwarden_secrets_manager
+    author:
+      - jantari (@jantari)
+    requirements:
+      - bws (command line utility)
+    short_description: Retrieve secrets from Bitwarden Secrets Manager
+    version_added: 7.2.0
+    description:
+      - Retrieve secrets from Bitwarden Secrets Manager.
+    options:
+      _terms:
+        description: Secret ID(s) to fetch values for.
+        required: true
+        type: list
+        elements: str
+      bws_access_token:
+        description: The BWS access token to use for this lookup.
+        env:
+          - name: BWS_ACCESS_TOKEN
+        required: true
+        type: str
+"""
+
+EXAMPLES = """
+- name: Get a secret relying on the BWS_ACCESS_TOKEN environment variable for authentication
+  ansible.builtin.debug:
+    msg: >-
+      {{ lookup("community.general.bitwarden_secrets_manager", "2bc23e48-4932-40de-a047-5524b7ddc972") }}
+
+- name: Get a secret passing an explicit access token for authentication
+  ansible.builtin.debug:
+    msg: >-
+      {{
+        lookup(
+          "community.general.bitwarden_secrets_manager",
+          "2bc23e48-4932-40de-a047-5524b7ddc972",
+          bws_access_token="9.4f570d14-4b54-42f5-bc07-60f4450b1db5.YmluYXJ5LXNvbWV0aGluZy0xMjMK:d2h5IGhlbGxvIHRoZXJlCg=="
+        )
+      }}
+
+- name: Get two different secrets each using a different access token for authentication
+  ansible.builtin.debug:
+    msg:
+      - '{{ lookup("community.general.bitwarden_secrets_manager", "2bc23e48-4932-40de-a047-5524b7ddc972", bws_access_token=token1) }}'
+      - '{{ lookup("community.general.bitwarden_secrets_manager", "9d89af4c-eb5d-41f5-bb0f-4ae81215c768", bws_access_token=token2) }}'
+  vars:
+    token1: "9.4f570d14-4b54-42f5-bc07-60f4450b1db5.YmluYXJ5LXNvbWV0aGluZy0xMjMK:d2h5IGhlbGxvIHRoZXJlCg=="
+    token2: "1.69b72797-6ea9-4687-a11e-848e41a30ae6.YW5zaWJsZSBpcyBncmVhdD8K:YW5zaWJsZSBpcyBncmVhdAo="
+
+- name: Get just the value of a secret
+  ansible.builtin.debug:
+    msg: >-
+      {{ lookup("community.general.bitwarden_secrets_manager", "2bc23e48-4932-40de-a047-5524b7ddc972").value }}
+"""
+
+RETURN = """
+  _raw:
+    description: List containing one or more secrets.
+    type: list
+    elements: dict
+"""
+
+from subprocess import Popen, PIPE
+
+from ansible.errors import AnsibleLookupError
+from ansible.module_utils.common.text.converters import to_text
+from ansible.parsing.ajson import AnsibleJSONDecoder
+from ansible.plugins.lookup import LookupBase
+
+
+class BitwardenSecretsManagerException(AnsibleLookupError):
+    pass
+
+
+class BitwardenSecretsManager(object):
+    def __init__(self, path='bws'):
+        self._cli_path = path
+
+    @property
+    def cli_path(self):
+        return self._cli_path
+
+    def _run(self, args, stdin=None):
+        p = Popen([self.cli_path] + args, stdout=PIPE, stderr=PIPE, stdin=PIPE)
+        out, err = p.communicate(stdin)
+        rc = p.wait()
+        return to_text(out, errors='surrogate_or_strict'), to_text(err, errors='surrogate_or_strict'), rc
+
+    def get_secret(self, secret_id, bws_access_token):
+        """Get and return the secret with the given secret_id.
+        """
+
+        # Prepare set of params for Bitwarden Secrets Manager CLI
+        # Color output was not always disabled correctly with the default 'auto' setting so explicitly disable it.
+        params = [
+            '--color', 'no',
+            '--access-token', bws_access_token,
+            'get', 'secret', secret_id
+        ]
+
+        out, err, rc = self._run(params)
+        if rc != 0:
+            raise BitwardenSecretsManagerException(to_text(err))
+
+        return AnsibleJSONDecoder().raw_decode(out)[0]
+
+
+class LookupModule(LookupBase):
+    def run(self, terms, variables=None, **kwargs):
+        self.set_options(var_options=variables, direct=kwargs)
+        bws_access_token = self.get_option('bws_access_token')
+
+        return [_bitwarden_secrets_manager.get_secret(term, bws_access_token) for term in terms]
+
+
+_bitwarden_secrets_manager = BitwardenSecretsManager()