Merge pull request #58 from britive/develop

v0.11.0

Author: twratl

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All changes to the package starting with v0.3.1 will be logged here.
 
+## v0.11.0 [2023-02-07]
+#### What's New
+* The `api` command is now available which exposes all the methods available in the Britive Python SDK.
+
+#### Enhancements
+* None
+
+#### Bug Fixes
+* None
+* 
+#### Dependencies
+* None
+
+#### Other
+* Updated documentation with examples of how to use the new `api` command.
+
 ## v0.10.2 [2023-02-06]
 #### What's New
 * None

docs/index.md

@@ -159,6 +159,37 @@ Example:
 As we construct the checkout command it would generally be `AWS/Dev/Test/Admin` but since the environment has a `/`
 in it, we need to escape that to be `AWS/Dev\/Test/Admin` so the CLI can properly parse out the 3 required parts of the string .
 
+## `api` Command - Use the Britive Python SDK via the CLI
+
+As of v0.11.0 a new command called `api` has been introduced. This command exposes the full capability of the Britive Python SDK
+to users of the `pybritive` CLI.
+
+Documentation on each SDK method can be found inside the Python SDK itself and on Github
+(https://github.com/britive/python-sdk). The Python package `britive` is a dependency of the CLI
+already so the SDK is available without installing any extra packages.
+
+It is left up to the caller to provide the proper `method` and `parameters` based on the documentation
+of the API call being performed. Examples will follow which explain how to do this.
+
+The authenticated identity must have the appropriate permissions to perform the actions being requested.
+General end users of Britive will not have these permissions. This call (and the larger SDK) is generally
+meant for administrative functionality.
+
+Example of use: (`pybritive api method --parameter1 value1 --parameter2 value2 [--parameterX valueX]`)
+
+* `pybritive api users.list` | will list all users in the britive tenant
+* `pybritive api tags.create --name testtag --description "test tag"` | will create a tag
+* `pybritive api users.list --query '[].email'` | will list all users and output just the email address of each user via jmespath query
+* `pybritive api profiles.create --application-id <id> --name testprofile` | will create a profile
+* `pybritive api secrets_manager.secrets.create --name test --vault-id <id> --value '{"Note": {"secret1": "abc"}}'` | creates a secret
+* `pybritive api secrets_manager.secrets.create --name test-file --vault-id <id> --file fileb://test.json --static-secret-template-id <id> --value None` | creates a file secret
+
+
+* The `method` is the same pattern as what would be used when referencing an instance of the `Britive` class.
+* The `parameters` are dynamic based on the method being invoked. Review the documentation for the method in question to understand
+which parameters are expected and which are optional. Parameters with `_` in the name should be translated to `-` when referencing them
+via the CLI.
+
 ## Shell Completion
 
 TODO: Provide more automated scripts here to automatically add the required configs to the profiles. For now the below works just fine though.

requirements.txt

@@ -16,4 +16,5 @@ mkdocs==1.3.1
 mkdocs-click==0.8.0
 twine~=4.0.1
 python-dateutil~=2.8.2
-boto3
+boto3
+jmespath

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = pybritive
-version = 0.10.2
+version = 0.11.0
 author = Britive Inc.
 author_email = support@britive.com
 description = A pure Python CLI for Britive
@@ -27,6 +27,7 @@ install_requires =
     cryptography
     python-dateutil
     britive>=2.14.0
+    jmespath
 
 [options.packages.find]
 where = src

src/pybritive/britive_cli.py

@@ -1,4 +1,5 @@
 import io
+import pathlib
 from britive.britive import Britive
 from .helpers.config import ConfigManager
 from .helpers.credentials import FileCredentialManager, EncryptedFileCredentialManager
@@ -15,6 +16,7 @@
 from datetime import datetime
 import os
 import sys
+import jmespath
 
 
 default_table_format = 'fancy_grid'
@@ -142,9 +144,17 @@ def print(self, data: object, ignore_silent: bool = False):
 
         if self.output_format == 'json':
             click.echo(json.dumps(data, indent=2, default=str))
-        elif self.output_format == 'list':
+        elif self.output_format == 'list-profiles':
             for row in data:
                 click.echo(self.list_separator.join([self.escape_profile_element(x) for x in row.values()]))
+        elif self.output_format == 'list':
+            for row in data:
+                if isinstance(row, dict):
+                    click.echo(self.list_separator.join([json.dumps(x, default=str) for x in row.values()]))
+                elif isinstance(row, list):
+                    click.echo(self.list_separator.join([json.dumps(x, default=str) for x in row]))
+                else:
+                    click.echo(row)
         elif self.output_format == 'csv':
             fields = list(data[0].keys())
             output = io.StringIO()
@@ -202,8 +212,18 @@ def list_profiles(self, checked_out: bool = False):
                     row.pop('Description')
                     row.pop('Type')
                 data.append(row)
+
+        # set special list output if needed
+        if self.output_format == 'list':
+            self.output_format = 'list-profiles'
+
         self.print(data)
 
+        # and set it back
+        if self.output_format == 'list-profiles':
+            self.output_format = 'list'
+
+
     def list_applications(self):
         self.login()
         self._set_available_profiles()
@@ -596,6 +616,61 @@ def request_withdraw(self, profile):
     def clear_gcloud_auth_key_files(self):
         self.config.clear_gcloud_auth_key_files()
 
+    def api(self, method, parameters={}, query=None):
+        self.login()
+
+        # clean up parameters - need to load json as dict if json string is provided and handle file inputs
+        computed_parameters = {}
+        open_file_keys = []
+        for key, value in parameters.items():
+            computed_key = key.replace('-', '_')
+            computed_value = value
+
+            if value.lower() == 'none':
+                computed_value = None
+
+            if value.startswith('file://'):
+                filepath = value.replace('file://', '')
+                path = pathlib.Path(filepath)
+                with open(str(path), 'r') as f:
+                    computed_value = f.read().strip()
+
+            if value.startswith('fileb://'):
+                filepath = value.replace('fileb://', '')
+                path = pathlib.Path(filepath)
+                computed_value = open(str(path), 'rb')
+                open_file_keys.append(computed_key)
+
+            try:
+                computed_parameters[computed_key] = json.loads(computed_value)
+            except json.JSONDecodeError:
+                computed_parameters[computed_key] = computed_value
+            except Exception:  # not sure what else we would do so just default to the value provided
+                computed_parameters[computed_key] = computed_value
+
+        # determine the sdk method we need to execute, starting at the base Britive class
+        func = self.b
+        try:
+            for m in method.split('.'):
+                func = getattr(func, m)
+        except Exception as e:
+            raise click.ClickException(f'invalid method {method} provided.')
+
+        # execute the method with the computed parameters
+        response = func(**computed_parameters)
+
+        # close any files we opened due to fileb:// prefix
+        for key in open_file_keys:
+            try:
+                computed_parameters[key].close()
+            except Exception:
+                pass
+
+        # output the response, optionally filtering based on provided jmespath query/search
+        self.print(jmespath.search(query, response) if query else response)
+
+
+
 
 
 

src/pybritive/cli_interface.py

@@ -11,6 +11,7 @@
 from .commands.cache import cache as group_cache
 from .commands.request import request as group_request
 from .commands.clear import clear as group_clear
+from .commands.api import api as command_api
 import sys
 import os
 
@@ -48,6 +49,7 @@ def cli(version):
 cli.add_command(group_cache)
 cli.add_command(group_request)
 cli.add_command(group_clear)
+cli.add_command(command_api)
 
 
 if __name__ == "__main__":

src/pybritive/commands/api.py

@@ -0,0 +1,47 @@
+import click
+from ..helpers.build_britive import build_britive
+from ..options.britive_options import britive_options
+
+
+@click.command(
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True
+    )
+)
+@build_britive
+@britive_options(names='query,output_format,tenant,token,passphrase,federation_provider')
+@click.argument('method')
+def api(ctx, query, output_format, tenant, token, passphrase, federation_provider, method):
+    """Exposes the Britive Python SDK methods to the CLI.
+
+    Documentation on each SDK method can be found inside the Python SDK itself and on Github
+    (https://github.com/britive/python-sdk). The Python package `britive` is a dependency of the CLI
+    already so the SDK is available without installing any extra packages.
+
+    It is left up to the caller to provide the proper `method` and `parameters` based on the documentation
+    of the API call being performed.
+
+    The authenticated identity must have the appropriate permissions to perform the actions being requested.
+    General end users of Britive will not have these permissions. This call (and the larger SDK) is generally
+    meant for administrative functionality.
+
+    Example of use:
+
+    * generic: pybritive api method --parameter1 value1 --parameter2 value2 [--parameterX valueX]
+
+    * pybritive api users.list
+
+    * pybritive api tags.create --name testtag --description "test tag"
+
+    * pybritive api users.list --query '[].email'
+
+    * pybritive api profiles.create --application-id <id> --name testprofile
+
+    """
+    parameters = {ctx.args[i][2:]: ctx.args[i + 1] for i in range(0, len(ctx.args), 2)}
+    ctx.obj.britive.api(
+        method=method,
+        parameters=parameters,
+        query=query
+    )

src/pybritive/options/britive_options.py

@@ -22,6 +22,7 @@
 from ..options.federation_provider import option as federation_provider
 from ..options.gcloud_key_file import option as gcloud_key_file
 from ..options.verbose import option as verbose
+from ..options.query import option as query
 
 options_map = {
     'tenant': tenant,
@@ -47,7 +48,8 @@
     'aws_credentials_file': aws_credentials_file,
     'federation_provider': federation_provider,
     'gcloud_key_file': gcloud_key_file,
-    'verbose': verbose
+    'verbose': verbose,
+    'query': query
 }
 
 

src/pybritive/options/query.py

@@ -0,0 +1,8 @@
+import click
+
+
+option = click.option(
+    '--query',
+    default=None,
+    help='JMESPath query to apply to the response.'
+)