strongdm.client

   1# Copyright 2020 StrongDM Inc
   2#
   3# Licensed under the Apache License, Version 2.0 (the "License");
   4# you may not use this file except in compliance with the License.
   5# You may obtain a copy of the License at
   6#
   7#     http://www.apache.org/licenses/LICENSE-2.0
   8#
   9# Unless required by applicable law or agreed to in writing, software
  10# distributed under the License is distributed on an "AS IS" BASIS,
  11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12# See the License for the specific language governing permissions and
  13# limitations under the License.
  14#
  15
  16# Code generated by protogen. DO NOT EDIT.
  17
  18import base64
  19import collections
  20import copy
  21import datetime
  22import functools
  23import grpc
  24import hashlib
  25import hmac
  26import random
  27import re
  28import time
  29from . import errors
  30from . import plumbing
  31from . import svc
  32
  33from cryptography.hazmat.primitives.asymmetric import rsa, padding
  34from cryptography.hazmat.primitives import serialization, hashes
  35
  36# These defaults are taken from AWS. Customization of these values
  37# is a future step in the API.
  38DEFAULT_BASE_RETRY_DELAY = 1  # 1 second
  39DEFAULT_MAX_RETRY_DELAY = 120  # 120 seconds
  40DEFAULT_RETRY_FACTOR = 1.6
  41DEFAULT_RETRY_JITTER = 0.2
  42API_VERSION = '2025-04-14'
  43USER_AGENT = 'strongdm-sdk-python/17.4.0'
  44
  45method_regexp = re.compile(r'\W+')
  46
  47
  48class _ClientCallDetails(
  49        collections.namedtuple(
  50            "_ClientCallDetails",
  51            ("method", "timeout", "metadata", "credentials")),
  52        grpc.ClientCallDetails,
  53):
  54    """ _ClientCallDetails is used to override some of the attributes of the client_call_details in the interceptors"""
  55    pass
  56
  57
  58class _EncryptionInterceptor(grpc.UnaryUnaryClientInterceptor):
  59    """ _EncryptionInterceptor is used to add transparent encryption/decryption support for managed secrets"""
  60    def __init__(self, client):
  61        self.client = client
  62        self.public_key_cache = {}
  63
  64    def intercept_unary_unary(self, continuation, client_call_details,
  65                              request):
  66        method = method_regexp.sub("_", client_call_details.method.lower())
  67        callback = getattr(self, method, None)
  68        if callback is not None:
  69            return callback(continuation, client_call_details, request)
  70        return continuation(client_call_details, request)
  71
  72    @functools.cached_property
  73    def private_key(self):
  74        return rsa.generate_private_key(
  75            public_exponent=65537,
  76            key_size=4096,
  77        )
  78
  79    def _encrypt_secret(self, method, continuation, client_call_details,
  80                        request):
  81        secret = request.managed_secret
  82        if len(secret.value) != 0:
  83            if secret.secret_engine_id not in self.public_key_cache:
  84                try:
  85                    # fetch secret engine details to fill up self.public_key_cache
  86                    # if it fails the call to create/update will fail as well
  87                    self.client.secret_engines.get(secret.secret_engine_id)
  88                except errors.RPCError:
  89                    pass
  90            key = self.public_key_cache.get(secret.secret_engine_id)
  91            if key is not None:
  92                encrypted = key.encrypt(
  93                    secret.value,
  94                    padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA256()),
  95                                 algorithm=hashes.SHA256(),
  96                                 label=None))
  97                secret.value = encrypted
  98            client_call_details = _ClientCallDetails(
  99                method=client_call_details.method,
 100                timeout=client_call_details.timeout,
 101                metadata=self.client.get_metadata(method, request),
 102                credentials=client_call_details.credentials)
 103        return continuation(client_call_details, request)
 104
 105    def _v1_managedsecrets_create(self, continuation, client_call_details,
 106                                  request):
 107        return self._encrypt_secret("ManagedSecrets.Create", continuation,
 108                                    client_call_details, request)
 109
 110    def _v1_managedsecrets_update(self, continuation, client_call_details,
 111                                  request):
 112        return self._encrypt_secret("ManagedSecrets.Update", continuation,
 113                                    client_call_details, request)
 114
 115    def _v1_managedsecrets_retrieve(self, continuation, client_call_details,
 116                                    request):
 117        if len(request.public_key) != 0:
 118            return continuation(client_call_details, request)
 119
 120        privKey = self.private_key
 121        request.public_key = privKey.public_key().public_bytes(
 122            serialization.Encoding.PEM,
 123            serialization.PublicFormat.SubjectPublicKeyInfo)
 124        client_call_details = _ClientCallDetails(
 125            method=client_call_details.method,
 126            timeout=client_call_details.timeout,
 127            metadata=self.client.get_metadata("ManagedSecrets.Retrieve",
 128                                              request),
 129            credentials=client_call_details.credentials)
 130        resp = continuation(client_call_details, request)
 131        if resp.code() != grpc.StatusCode.OK:
 132            return resp
 133        result = resp.result()
 134        plaintext = privKey.decrypt(
 135            result.managed_secret.value,
 136            padding.OAEP(
 137                mgf=padding.MGF1(algorithm=hashes.SHA256()),
 138                algorithm=hashes.SHA256(),
 139                label=None,
 140            ))
 141        result.managed_secret.value = plaintext
 142        return resp
 143
 144    def _v1_secretengines_get(self, continuation, client_call_details,
 145                              request):
 146        response = continuation(client_call_details, request)
 147        if response.code() != grpc.StatusCode.OK:
 148            return response
 149        result = response.result()
 150        engine = plumbing.convert_secret_engine_to_porcelain(
 151            result.secret_engine)
 152        engineKey = serialization.load_pem_public_key(engine.public_key)
 153        self.public_key_cache[engine.id] = engineKey
 154        return response
 155
 156    def _v1_secretengines_list(self, continuation, client_call_details,
 157                               request):
 158        response = continuation(client_call_details, request)
 159        if response.code() != grpc.StatusCode.OK:
 160            return response
 161        result = response.result()
 162        for plumbing_engine in result.secret_engines:
 163            engine = plumbing.convert_secret_engine_to_porcelain(
 164                plumbing_engine)
 165            engineKey = serialization.load_pem_public_key(engine.public_key)
 166            self.public_key_cache[engine.id] = engineKey
 167        return response
 168
 169
 170class Client:
 171    '''Client interacts with the strongDM API.'''
 172    def __init__(self,
 173                 api_access_key,
 174                 api_secret,
 175                 host='app.strongdm.com:443',
 176                 insecure=False,
 177                 retry_rate_limit_errors=True,
 178                 page_limit=0):
 179        '''
 180        Create a new Client.
 181
 182        - api_access_key: the access key to authenticate with strongDM
 183        - api_secret: the secret key to authenticate with strongDM
 184        '''
 185        self.api_access_key = api_access_key.strip()
 186        self.api_secret = base64.b64decode(api_secret.strip())
 187        self.base_retry_delay = DEFAULT_BASE_RETRY_DELAY
 188        self.max_retry_delay = DEFAULT_MAX_RETRY_DELAY
 189        self.retry_factor = DEFAULT_RETRY_FACTOR
 190        self.retry_jitter = DEFAULT_RETRY_JITTER
 191        self.retry_rate_limit_errors = retry_rate_limit_errors
 192        self.snapshot_datetime = None
 193        self.page_limit = page_limit
 194
 195        try:
 196            if insecure:
 197                channel = grpc.insecure_channel(host)
 198            else:
 199                creds = grpc.ssl_channel_credentials()
 200                channel = grpc.secure_channel(host, creds)
 201        except Exception as e:
 202            raise plumbing.convert_error_to_porcelain(e) from e
 203        channel = grpc.intercept_channel(channel, _EncryptionInterceptor(self))
 204        self.channel = channel
 205        self.access_requests = svc.AccessRequests(channel, self)
 206        '''
 207         AccessRequests are requests for access to a resource that may match a Workflow.
 208
 209        See `strongdm.svc.AccessRequests`.
 210        '''
 211        self.access_request_events_history = svc.AccessRequestEventsHistory(
 212            channel, self)
 213        '''
 214         AccessRequestEventsHistory provides records of all changes to the state of an AccessRequest.
 215
 216        See `strongdm.svc.AccessRequestEventsHistory`.
 217        '''
 218        self.access_requests_history = svc.AccessRequestsHistory(channel, self)
 219        '''
 220         AccessRequestsHistory provides records of all changes to the state of an AccessRequest.
 221
 222        See `strongdm.svc.AccessRequestsHistory`.
 223        '''
 224        self.account_attachments = svc.AccountAttachments(channel, self)
 225        '''
 226         AccountAttachments assign an account to a role.
 227
 228        See `strongdm.svc.AccountAttachments`.
 229        '''
 230        self.account_attachments_history = svc.AccountAttachmentsHistory(
 231            channel, self)
 232        '''
 233         AccountAttachmentsHistory records all changes to the state of an AccountAttachment.
 234
 235        See `strongdm.svc.AccountAttachmentsHistory`.
 236        '''
 237        self.account_grants = svc.AccountGrants(channel, self)
 238        '''
 239         AccountGrants assign a resource directly to an account, giving the account the permission to connect to that resource.
 240
 241        See `strongdm.svc.AccountGrants`.
 242        '''
 243        self.account_grants_history = svc.AccountGrantsHistory(channel, self)
 244        '''
 245         AccountGrantsHistory records all changes to the state of an AccountGrant.
 246
 247        See `strongdm.svc.AccountGrantsHistory`.
 248        '''
 249        self.account_permissions = svc.AccountPermissions(channel, self)
 250        '''
 251         AccountPermissions records the granular permissions accounts have, allowing them to execute
 252         relevant commands via StrongDM's APIs.
 253
 254        See `strongdm.svc.AccountPermissions`.
 255        '''
 256        self.account_resources = svc.AccountResources(channel, self)
 257        '''
 258         AccountResources enumerates the resources to which accounts have access.
 259         The AccountResources service is read-only.
 260
 261        See `strongdm.svc.AccountResources`.
 262        '''
 263        self.account_resources_history = svc.AccountResourcesHistory(
 264            channel, self)
 265        '''
 266         AccountResourcesHistory records all changes to the state of a AccountResource.
 267
 268        See `strongdm.svc.AccountResourcesHistory`.
 269        '''
 270        self.accounts = svc.Accounts(channel, self)
 271        '''
 272         Accounts are users that have access to strongDM. There are two types of accounts:
 273         1. **Users:** humans who are authenticated through username and password or SSO.
 274         2. **Service Accounts:** machines that are authenticated using a service token.
 275         3. **Tokens** are access keys with permissions that can be used for authentication.
 276
 277        See `strongdm.svc.Accounts`.
 278        '''
 279        self.accounts_groups = svc.AccountsGroups(channel, self)
 280        '''
 281         An AccountGroup links an account and a group.
 282
 283        See `strongdm.svc.AccountsGroups`.
 284        '''
 285        self.accounts_groups_history = svc.AccountsGroupsHistory(channel, self)
 286        '''
 287         AccountsGroupsHistory records all changes to the state of an AccountGroup.
 288
 289        See `strongdm.svc.AccountsGroupsHistory`.
 290        '''
 291        self.accounts_history = svc.AccountsHistory(channel, self)
 292        '''
 293         AccountsHistory records all changes to the state of an Account.
 294
 295        See `strongdm.svc.AccountsHistory`.
 296        '''
 297        self.activities = svc.Activities(channel, self)
 298        '''
 299         An Activity is a record of an action taken against a strongDM deployment, e.g.
 300         a user creation, resource deletion, sso configuration change, etc. The Activities
 301         service is read-only.
 302
 303        See `strongdm.svc.Activities`.
 304        '''
 305        self.approval_workflow_approvers = svc.ApprovalWorkflowApprovers(
 306            channel, self)
 307        '''
 308         ApprovalWorkflowApprovers link approval workflow approvers to an ApprovalWorkflowStep
 309
 310        See `strongdm.svc.ApprovalWorkflowApprovers`.
 311        '''
 312        self.approval_workflow_approvers_history = svc.ApprovalWorkflowApproversHistory(
 313            channel, self)
 314        '''
 315         ApprovalWorkflowApproversHistory records all changes to the state of an ApprovalWorkflowApprover.
 316
 317        See `strongdm.svc.ApprovalWorkflowApproversHistory`.
 318        '''
 319        self.approval_workflow_steps = svc.ApprovalWorkflowSteps(channel, self)
 320        '''
 321         ApprovalWorkflowSteps link approval workflow steps to an ApprovalWorkflow
 322
 323        See `strongdm.svc.ApprovalWorkflowSteps`.
 324        '''
 325        self.approval_workflow_steps_history = svc.ApprovalWorkflowStepsHistory(
 326            channel, self)
 327        '''
 328         ApprovalWorkflowStepsHistory records all changes to the state of an ApprovalWorkflowStep.
 329
 330        See `strongdm.svc.ApprovalWorkflowStepsHistory`.
 331        '''
 332        self.approval_workflows = svc.ApprovalWorkflows(channel, self)
 333        '''
 334         ApprovalWorkflows are the mechanism by which requests for access can be viewed by authorized
 335         approvers and be approved or denied.
 336
 337        See `strongdm.svc.ApprovalWorkflows`.
 338        '''
 339        self.approval_workflows_history = svc.ApprovalWorkflowsHistory(
 340            channel, self)
 341        '''
 342         ApprovalWorkflowsHistory records all changes to the state of an ApprovalWorkflow.
 343
 344        See `strongdm.svc.ApprovalWorkflowsHistory`.
 345        '''
 346        self.control_panel = svc.ControlPanel(channel, self)
 347        '''
 348         ControlPanel contains all administrative controls.
 349
 350        See `strongdm.svc.ControlPanel`.
 351        '''
 352        self.discovery_connectors = svc.DiscoveryConnectors(channel, self)
 353        '''
 354         A Discovery Connector is a configuration object for performing Resource
 355         Scans in remote systems such as AWS, GCP, Azure, and other systems.
 356
 357        See `strongdm.svc.DiscoveryConnectors`.
 358        '''
 359        self.granted_account_entitlements = svc.GrantedAccountEntitlements(
 360            channel, self)
 361        '''
 362         GrantedAccountEntitlements enumerates the resources to which an account has been granted access.
 363         The GrantedAccountEntitlements service is read-only.
 364
 365        See `strongdm.svc.GrantedAccountEntitlements`.
 366        '''
 367        self.granted_resource_entitlements = svc.GrantedResourceEntitlements(
 368            channel, self)
 369        '''
 370         GrantedResourceEntitlements enumerates the accounts that have been granted access to a given resource.
 371         The GrantedResourceEntitlements service is read-only.
 372
 373        See `strongdm.svc.GrantedResourceEntitlements`.
 374        '''
 375        self.granted_role_entitlements = svc.GrantedRoleEntitlements(
 376            channel, self)
 377        '''
 378         GrantedRoleEntitlements enumerates the resources to which a role grants access.
 379         The GrantedRoleEntitlements service is read-only.
 380
 381        See `strongdm.svc.GrantedRoleEntitlements`.
 382        '''
 383        self.roles = svc.Roles(channel, self)
 384        '''
 385         A Role has a list of access rules which determine which Resources the members
 386         of the Role have access to. An Account can be a member of multiple Roles via
 387         AccountAttachments.
 388
 389        See `strongdm.svc.Roles`.
 390        '''
 391        self.groups = svc.Groups(channel, self)
 392        '''
 393         A Group is a set of principals.
 394
 395        See `strongdm.svc.Groups`.
 396        '''
 397        self.groups_history = svc.GroupsHistory(channel, self)
 398        '''
 399         GroupsHistory records all changes to the state of a Group.
 400
 401        See `strongdm.svc.GroupsHistory`.
 402        '''
 403        self.groups_roles = svc.GroupsRoles(channel, self)
 404        '''
 405         A GroupRole is an assignment of a Group to a Role.
 406
 407        See `strongdm.svc.GroupsRoles`.
 408        '''
 409        self.groups_roles_history = svc.GroupsRolesHistory(channel, self)
 410        '''
 411         GroupsRolesHistory records all changes to the state of a GroupRole.
 412
 413        See `strongdm.svc.GroupsRolesHistory`.
 414        '''
 415        self.health_checks = svc.HealthChecks(channel, self)
 416        '''
 417         HealthChecks lists the last healthcheck between each node and resource.
 418         Note the unconventional capitalization here is to prevent having a collision with GRPC
 419
 420        See `strongdm.svc.HealthChecks`.
 421        '''
 422        self.identity_aliases = svc.IdentityAliases(channel, self)
 423        '''
 424         IdentityAliases assign an alias to an account within an IdentitySet.
 425         The alias is used as the username when connecting to a identity supported resource.
 426
 427        See `strongdm.svc.IdentityAliases`.
 428        '''
 429        self.identity_aliases_history = svc.IdentityAliasesHistory(
 430            channel, self)
 431        '''
 432         IdentityAliasesHistory records all changes to the state of a IdentityAlias.
 433
 434        See `strongdm.svc.IdentityAliasesHistory`.
 435        '''
 436        self.identity_sets = svc.IdentitySets(channel, self)
 437        '''
 438         A IdentitySet is a named grouping of Identity Aliases for Accounts.
 439         An Account's relationship to a IdentitySet is defined via IdentityAlias objects.
 440
 441        See `strongdm.svc.IdentitySets`.
 442        '''
 443        self.identity_sets_history = svc.IdentitySetsHistory(channel, self)
 444        '''
 445         IdentitySetsHistory records all changes to the state of a IdentitySet.
 446
 447        See `strongdm.svc.IdentitySetsHistory`.
 448        '''
 449        self.managed_secrets = svc.ManagedSecrets(channel, self)
 450        '''
 451         ManagedSecret is a private vertical for creating, reading, updating,
 452         deleting, listing and rotating the managed secrets in the secrets engines as
 453         an authenticated user.
 454
 455        See `strongdm.svc.ManagedSecrets`.
 456        '''
 457        self.nodes = svc.Nodes(channel, self)
 458        '''
 459         Nodes make up the StrongDM network, and allow your users to connect securely to your resources.
 460         There are three types of nodes:
 461         1. **Relay:** creates connectivity to your datasources, while maintaining the egress-only nature of your firewall
 462         2. **Gateway:** a relay that also listens for connections from StrongDM clients
 463         3. **Proxy Cluster:** a cluster of workers that together mediate access from clients to resources
 464
 465        See `strongdm.svc.Nodes`.
 466        '''
 467        self.nodes_history = svc.NodesHistory(channel, self)
 468        '''
 469         NodesHistory records all changes to the state of a Node.
 470
 471        See `strongdm.svc.NodesHistory`.
 472        '''
 473        self.organization_history = svc.OrganizationHistory(channel, self)
 474        '''
 475         OrganizationHistory records all changes to the state of an Organization.
 476
 477        See `strongdm.svc.OrganizationHistory`.
 478        '''
 479        self.organizations = svc.Organizations(channel, self)
 480        '''
 481         Organizations exposes organization configuration. Most RPCs remain private to the
 482         go_private SDK; public MFA management is exposed to all public SDK targets.
 483         The terraform-provider target is opted out at the service level because the
 484         provider's data-source generator assumes every service has a List RPC; MFA is
 485         instead surfaced via a hand-written resource template.
 486
 487        See `strongdm.svc.Organizations`.
 488        '''
 489        self.peering_group_nodes = svc.PeeringGroupNodes(channel, self)
 490        '''
 491         PeeringGroupNodes provides the building blocks necessary to obtain attach a node to a peering group.
 492
 493        See `strongdm.svc.PeeringGroupNodes`.
 494        '''
 495        self.peering_group_peers = svc.PeeringGroupPeers(channel, self)
 496        '''
 497         PeeringGroupPeers provides the building blocks necessary to link two peering groups.
 498
 499        See `strongdm.svc.PeeringGroupPeers`.
 500        '''
 501        self.peering_group_resources = svc.PeeringGroupResources(channel, self)
 502        '''
 503         PeeringGroupResources provides the building blocks necessary to obtain attach a resource to a peering group.
 504
 505        See `strongdm.svc.PeeringGroupResources`.
 506        '''
 507        self.peering_groups = svc.PeeringGroups(channel, self)
 508        '''
 509         PeeringGroups provides the building blocks necessary to obtain explicit network topology and routing.
 510
 511        See `strongdm.svc.PeeringGroups`.
 512        '''
 513        self.policies = svc.Policies(channel, self)
 514        '''
 515         Policies are the collection of one or more statements that enforce fine-grained access
 516         control for the users of an organization.
 517
 518        See `strongdm.svc.Policies`.
 519        '''
 520        self.policies_history = svc.PoliciesHistory(channel, self)
 521        '''
 522         PoliciesHistory records all changes to the state of a Policy.
 523
 524        See `strongdm.svc.PoliciesHistory`.
 525        '''
 526        self.proxy_cluster_keys = svc.ProxyClusterKeys(channel, self)
 527        '''
 528         Proxy Cluster Keys are authentication keys for all proxies within a cluster.
 529         The proxies within a cluster share the same key. One cluster can have
 530         multiple keys in order to facilitate key rotation.
 531
 532        See `strongdm.svc.ProxyClusterKeys`.
 533        '''
 534        self.queries = svc.Queries(channel, self)
 535        '''
 536         A Query is a record of a single client request to a resource, such as a SQL query.
 537         Long-running SSH, RDP, or Kubernetes interactive sessions also count as queries.
 538         The Queries service is read-only.
 539
 540        See `strongdm.svc.Queries`.
 541        '''
 542        self.remote_identities = svc.RemoteIdentities(channel, self)
 543        '''
 544         RemoteIdentities assign a resource directly to an account, giving the account the permission to connect to that resource.
 545
 546        See `strongdm.svc.RemoteIdentities`.
 547        '''
 548        self.remote_identities_history = svc.RemoteIdentitiesHistory(
 549            channel, self)
 550        '''
 551         RemoteIdentitiesHistory records all changes to the state of a RemoteIdentity.
 552
 553        See `strongdm.svc.RemoteIdentitiesHistory`.
 554        '''
 555        self.remote_identity_groups = svc.RemoteIdentityGroups(channel, self)
 556        '''
 557         A RemoteIdentityGroup is a named grouping of Remote Identities for Accounts.
 558         An Account's relationship to a RemoteIdentityGroup is defined via RemoteIdentity objects.
 559
 560        See `strongdm.svc.RemoteIdentityGroups`.
 561        '''
 562        self.remote_identity_groups_history = svc.RemoteIdentityGroupsHistory(
 563            channel, self)
 564        '''
 565         RemoteIdentityGroupsHistory records all changes to the state of a RemoteIdentityGroup.
 566
 567        See `strongdm.svc.RemoteIdentityGroupsHistory`.
 568        '''
 569        self.replays = svc.Replays(channel, self)
 570        '''
 571         A Replay captures the data transferred over a long-running SSH, RDP, or Kubernetes interactive session
 572         (otherwise referred to as a query). The Replays service is read-only.
 573
 574        See `strongdm.svc.Replays`.
 575        '''
 576        self.requestable_account_entitlements = svc.RequestableAccountEntitlements(
 577            channel, self)
 578        '''
 579         RequestableAccountEntitlements enumerates the resources that an account is permitted to request access to.
 580         The RequestableAccountEntitlements service is read-only.
 581
 582        See `strongdm.svc.RequestableAccountEntitlements`.
 583        '''
 584        self.requestable_resource_entitlements = svc.RequestableResourceEntitlements(
 585            channel, self)
 586        '''
 587         RequestableResourceEntitlements enumerates the accounts that are permitted to request access to a given resource.
 588         The RequestableResourceEntitlements service is read-only.
 589
 590        See `strongdm.svc.RequestableResourceEntitlements`.
 591        '''
 592        self.requestable_role_entitlements = svc.RequestableRoleEntitlements(
 593            channel, self)
 594        '''
 595         RequestableRoleEntitlements enumerates the resources that a role permits its members to request access to.
 596         The RequestableRoleEntitlements service is read-only.
 597
 598        See `strongdm.svc.RequestableRoleEntitlements`.
 599        '''
 600        self.resources = svc.Resources(channel, self)
 601        '''
 602         Resources are databases, servers, clusters, websites, or clouds that strongDM
 603         delegates access to.
 604
 605        See `strongdm.svc.Resources`.
 606        '''
 607        self.resources_history = svc.ResourcesHistory(channel, self)
 608        '''
 609         ResourcesHistory records all changes to the state of a Resource.
 610
 611        See `strongdm.svc.ResourcesHistory`.
 612        '''
 613        self.role_resources = svc.RoleResources(channel, self)
 614        '''
 615         RoleResources enumerates the resources to which roles have access.
 616         The RoleResources service is read-only.
 617
 618        See `strongdm.svc.RoleResources`.
 619        '''
 620        self.role_resources_history = svc.RoleResourcesHistory(channel, self)
 621        '''
 622         RoleResourcesHistory records all changes to the state of a RoleResource.
 623
 624        See `strongdm.svc.RoleResourcesHistory`.
 625        '''
 626        self.roles_history = svc.RolesHistory(channel, self)
 627        '''
 628         RolesHistory records all changes to the state of a Role.
 629
 630        See `strongdm.svc.RolesHistory`.
 631        '''
 632        self.secret_stores = svc.SecretStores(channel, self)
 633        '''
 634         SecretStores are servers where resource secrets (passwords, keys) are stored.
 635
 636        See `strongdm.svc.SecretStores`.
 637        '''
 638        self.secret_engines = svc.SecretEngines(channel, self)
 639        '''
 640
 641
 642        See `strongdm.svc.SecretEngines`.
 643        '''
 644        self.secret_store_healths = svc.SecretStoreHealths(channel, self)
 645        '''
 646         SecretStoreHealths exposes health states for secret stores.
 647
 648        See `strongdm.svc.SecretStoreHealths`.
 649        '''
 650        self.secret_stores_history = svc.SecretStoresHistory(channel, self)
 651        '''
 652         SecretStoresHistory records all changes to the state of a SecretStore.
 653
 654        See `strongdm.svc.SecretStoresHistory`.
 655        '''
 656        self.workflow_approvers = svc.WorkflowApprovers(channel, self)
 657        '''
 658         WorkflowApprovers is an account or a role with the ability to approve requests bound to a workflow.
 659
 660        See `strongdm.svc.WorkflowApprovers`.
 661        '''
 662        self.workflow_approvers_history = svc.WorkflowApproversHistory(
 663            channel, self)
 664        '''
 665         WorkflowApproversHistory provides records of all changes to the state of a WorkflowApprover.
 666
 667        See `strongdm.svc.WorkflowApproversHistory`.
 668        '''
 669        self.workflow_roles = svc.WorkflowRoles(channel, self)
 670        '''
 671         WorkflowRole links a role to a workflow. The linked roles indicate which roles a user must be a part of
 672         to request access to a resource via the workflow.
 673
 674        See `strongdm.svc.WorkflowRoles`.
 675        '''
 676        self.workflow_roles_history = svc.WorkflowRolesHistory(channel, self)
 677        '''
 678         WorkflowRolesHistory provides records of all changes to the state of a WorkflowRole
 679
 680        See `strongdm.svc.WorkflowRolesHistory`.
 681        '''
 682        self.workflows = svc.Workflows(channel, self)
 683        '''
 684         Workflows are the collection of rules that define the resources to which access can be requested,
 685         the users that can request that access, and the mechanism for approving those requests which can either
 686         be automatic approval or a set of users authorized to approve the requests.
 687
 688        See `strongdm.svc.Workflows`.
 689        '''
 690        self.workflows_history = svc.WorkflowsHistory(channel, self)
 691        '''
 692         WorkflowsHistory provides records of all changes to the state of a Workflow.
 693
 694        See `strongdm.svc.WorkflowsHistory`.
 695        '''
 696
 697    def close(self):
 698        '''Closes this Client and releases all resources held by it.
 699
 700        Closing the Client will immediately terminate all RPCs active with the
 701        Client and it is not valid to invoke new RPCs with the Client.
 702
 703        This method is idempotent.
 704        '''
 705        self.channel.close()
 706
 707    def get_metadata(self, method_name, req):
 708        return [
 709            ('x-sdm-authentication', self.api_access_key),
 710            ('x-sdm-signature', self.sign(method_name,
 711                                          req.SerializeToString())),
 712            ('x-sdm-api-version', API_VERSION),
 713            ('x-sdm-user-agent', USER_AGENT),
 714        ]
 715
 716    def sign(self, method_name, request_bytes):
 717        def hmac_digest(key, msg_byte_string):
 718            return hmac.new(key, msg=msg_byte_string,
 719                            digestmod=hashlib.sha256).digest()
 720
 721        current_utc_date = datetime.datetime.now(
 722            datetime.timezone.utc).strftime('%Y-%m-%d')
 723        signing_key = hmac_digest(self.api_secret, current_utc_date.encode())
 724        signing_key = hmac_digest(signing_key, b'sdm_api_v1')
 725
 726        hash = hashlib.sha256()
 727
 728        hash.update(method_name.encode())
 729        hash.update(b'\n')
 730        hash.update(request_bytes)
 731
 732        return base64.b64encode(hmac_digest(signing_key, hash.digest()))
 733
 734    def exponentialBackoff(self, retries, deadline=None):
 735        def applyDeadline(delay, deadline):
 736            if deadline is None:
 737                return delay
 738            remaining = deadline - time.time()
 739            if remaining < 0:
 740                return 0
 741            return min(delay, remaining)
 742
 743        if retries == 0:
 744            return applyDeadline(self.base_retry_delay, deadline)
 745
 746        backoff, max_delay = self.base_retry_delay, self.max_retry_delay
 747        while backoff < max_delay and retries > 0:
 748            backoff *= self.retry_factor
 749            retries -= 1
 750
 751        if backoff > max_delay:
 752            backoff = max_delay
 753
 754        # Randomize backoff delays so that if a cluster of requests start at
 755        # the same time, they won't operate in lockstep.
 756        backoff *= 1 + self.retry_jitter * (random.random() * 2 - 1)
 757        if backoff < 0:
 758            return 0
 759
 760        return applyDeadline(backoff, deadline)
 761
 762    def shouldRetry(self, retries, err, deadline=None):
 763        # Check if we've passed the deadline
 764        if deadline is not None and time.time() >= deadline:
 765            return False
 766
 767        if not isinstance(err, grpc.RpcError):
 768            return False
 769
 770        if self.retry_rate_limit_errors and err.code(
 771        ) == grpc.StatusCode.RESOURCE_EXHAUSTED:
 772            return True
 773
 774        return retries <= 3 and (err.code() == grpc.StatusCode.INTERNAL
 775                                 or err.code() == grpc.StatusCode.UNAVAILABLE)
 776
 777    def snapshot_at(self, snapshot_datetime):
 778        '''
 779        Constructs a read-only client that will provide historical data from the provided timestamp.
 780
 781        See `SnapshotClient`.
 782        '''
 783        client = copy.copy(self)
 784        client.snapshot_datetime = snapshot_datetime
 785        client.access_requests = svc.AccessRequests(client.channel, client)
 786        client.account_attachments = svc.AccountAttachments(
 787            client.channel, client)
 788        client.account_grants = svc.AccountGrants(client.channel, client)
 789        client.account_permissions = svc.AccountPermissions(
 790            client.channel, client)
 791        client.account_resources = svc.AccountResources(client.channel, client)
 792        client.accounts = svc.Accounts(client.channel, client)
 793        client.accounts_groups = svc.AccountsGroups(client.channel, client)
 794        client.approval_workflow_approvers = svc.ApprovalWorkflowApprovers(
 795            client.channel, client)
 796        client.approval_workflow_steps = svc.ApprovalWorkflowSteps(
 797            client.channel, client)
 798        client.approval_workflows = svc.ApprovalWorkflows(
 799            client.channel, client)
 800        client.discovery_connectors = svc.DiscoveryConnectors(
 801            client.channel, client)
 802        client.granted_account_entitlements = svc.GrantedAccountEntitlements(
 803            client.channel, client)
 804        client.granted_resource_entitlements = svc.GrantedResourceEntitlements(
 805            client.channel, client)
 806        client.granted_role_entitlements = svc.GrantedRoleEntitlements(
 807            client.channel, client)
 808        client.roles = svc.Roles(client.channel, client)
 809        client.groups = svc.Groups(client.channel, client)
 810        client.groups_roles = svc.GroupsRoles(client.channel, client)
 811        client.identity_aliases = svc.IdentityAliases(client.channel, client)
 812        client.identity_sets = svc.IdentitySets(client.channel, client)
 813        client.nodes = svc.Nodes(client.channel, client)
 814        client.policies = svc.Policies(client.channel, client)
 815        client.proxy_cluster_keys = svc.ProxyClusterKeys(
 816            client.channel, client)
 817        client.remote_identities = svc.RemoteIdentities(client.channel, client)
 818        client.remote_identity_groups = svc.RemoteIdentityGroups(
 819            client.channel, client)
 820        client.requestable_account_entitlements = svc.RequestableAccountEntitlements(
 821            client.channel, client)
 822        client.requestable_resource_entitlements = svc.RequestableResourceEntitlements(
 823            client.channel, client)
 824        client.requestable_role_entitlements = svc.RequestableRoleEntitlements(
 825            client.channel, client)
 826        client.resources = svc.Resources(client.channel, client)
 827        client.role_resources = svc.RoleResources(client.channel, client)
 828        client.secret_stores = svc.SecretStores(client.channel, client)
 829        client.workflow_approvers = svc.WorkflowApprovers(
 830            client.channel, client)
 831        client.workflow_roles = svc.WorkflowRoles(client.channel, client)
 832        client.workflows = svc.Workflows(client.channel, client)
 833        return SnapshotClient(client)
 834
 835
 836class SnapshotClient:
 837    '''SnapshotClient exposes methods to query historical records at a provided timestamp.'''
 838    def __init__(self, client):
 839        self.access_requests = svc.SnapshotAccessRequests(
 840            client.access_requests)
 841        '''
 842         AccessRequests are requests for access to a resource that may match a Workflow.
 843
 844        See `strongdm.svc.SnapshotAccessRequests`.
 845        '''
 846        self.account_attachments = svc.SnapshotAccountAttachments(
 847            client.account_attachments)
 848        '''
 849         AccountAttachments assign an account to a role.
 850
 851        See `strongdm.svc.SnapshotAccountAttachments`.
 852        '''
 853        self.account_grants = svc.SnapshotAccountGrants(client.account_grants)
 854        '''
 855         AccountGrants assign a resource directly to an account, giving the account the permission to connect to that resource.
 856
 857        See `strongdm.svc.SnapshotAccountGrants`.
 858        '''
 859        self.account_permissions = svc.SnapshotAccountPermissions(
 860            client.account_permissions)
 861        '''
 862         AccountPermissions records the granular permissions accounts have, allowing them to execute
 863         relevant commands via StrongDM's APIs.
 864
 865        See `strongdm.svc.SnapshotAccountPermissions`.
 866        '''
 867        self.account_resources = svc.SnapshotAccountResources(
 868            client.account_resources)
 869        '''
 870         AccountResources enumerates the resources to which accounts have access.
 871         The AccountResources service is read-only.
 872
 873        See `strongdm.svc.SnapshotAccountResources`.
 874        '''
 875        self.accounts = svc.SnapshotAccounts(client.accounts)
 876        '''
 877         Accounts are users that have access to strongDM. There are two types of accounts:
 878         1. **Users:** humans who are authenticated through username and password or SSO.
 879         2. **Service Accounts:** machines that are authenticated using a service token.
 880         3. **Tokens** are access keys with permissions that can be used for authentication.
 881
 882        See `strongdm.svc.SnapshotAccounts`.
 883        '''
 884        self.accounts_groups = svc.SnapshotAccountsGroups(
 885            client.accounts_groups)
 886        '''
 887         An AccountGroup links an account and a group.
 888
 889        See `strongdm.svc.SnapshotAccountsGroups`.
 890        '''
 891        self.approval_workflow_approvers = svc.SnapshotApprovalWorkflowApprovers(
 892            client.approval_workflow_approvers)
 893        '''
 894         ApprovalWorkflowApprovers link approval workflow approvers to an ApprovalWorkflowStep
 895
 896        See `strongdm.svc.SnapshotApprovalWorkflowApprovers`.
 897        '''
 898        self.approval_workflow_steps = svc.SnapshotApprovalWorkflowSteps(
 899            client.approval_workflow_steps)
 900        '''
 901         ApprovalWorkflowSteps link approval workflow steps to an ApprovalWorkflow
 902
 903        See `strongdm.svc.SnapshotApprovalWorkflowSteps`.
 904        '''
 905        self.approval_workflows = svc.SnapshotApprovalWorkflows(
 906            client.approval_workflows)
 907        '''
 908         ApprovalWorkflows are the mechanism by which requests for access can be viewed by authorized
 909         approvers and be approved or denied.
 910
 911        See `strongdm.svc.SnapshotApprovalWorkflows`.
 912        '''
 913        self.discovery_connectors = svc.SnapshotDiscoveryConnectors(
 914            client.discovery_connectors)
 915        '''
 916         A Discovery Connector is a configuration object for performing Resource
 917         Scans in remote systems such as AWS, GCP, Azure, and other systems.
 918
 919        See `strongdm.svc.SnapshotDiscoveryConnectors`.
 920        '''
 921        self.granted_account_entitlements = svc.SnapshotGrantedAccountEntitlements(
 922            client.granted_account_entitlements)
 923        '''
 924         GrantedAccountEntitlements enumerates the resources to which an account has been granted access.
 925         The GrantedAccountEntitlements service is read-only.
 926
 927        See `strongdm.svc.SnapshotGrantedAccountEntitlements`.
 928        '''
 929        self.granted_resource_entitlements = svc.SnapshotGrantedResourceEntitlements(
 930            client.granted_resource_entitlements)
 931        '''
 932         GrantedResourceEntitlements enumerates the accounts that have been granted access to a given resource.
 933         The GrantedResourceEntitlements service is read-only.
 934
 935        See `strongdm.svc.SnapshotGrantedResourceEntitlements`.
 936        '''
 937        self.granted_role_entitlements = svc.SnapshotGrantedRoleEntitlements(
 938            client.granted_role_entitlements)
 939        '''
 940         GrantedRoleEntitlements enumerates the resources to which a role grants access.
 941         The GrantedRoleEntitlements service is read-only.
 942
 943        See `strongdm.svc.SnapshotGrantedRoleEntitlements`.
 944        '''
 945        self.roles = svc.SnapshotRoles(client.roles)
 946        '''
 947         A Role has a list of access rules which determine which Resources the members
 948         of the Role have access to. An Account can be a member of multiple Roles via
 949         AccountAttachments.
 950
 951        See `strongdm.svc.SnapshotRoles`.
 952        '''
 953        self.groups = svc.SnapshotGroups(client.groups)
 954        '''
 955         A Group is a set of principals.
 956
 957        See `strongdm.svc.SnapshotGroups`.
 958        '''
 959        self.groups_roles = svc.SnapshotGroupsRoles(client.groups_roles)
 960        '''
 961         A GroupRole is an assignment of a Group to a Role.
 962
 963        See `strongdm.svc.SnapshotGroupsRoles`.
 964        '''
 965        self.identity_aliases = svc.SnapshotIdentityAliases(
 966            client.identity_aliases)
 967        '''
 968         IdentityAliases assign an alias to an account within an IdentitySet.
 969         The alias is used as the username when connecting to a identity supported resource.
 970
 971        See `strongdm.svc.SnapshotIdentityAliases`.
 972        '''
 973        self.identity_sets = svc.SnapshotIdentitySets(client.identity_sets)
 974        '''
 975         A IdentitySet is a named grouping of Identity Aliases for Accounts.
 976         An Account's relationship to a IdentitySet is defined via IdentityAlias objects.
 977
 978        See `strongdm.svc.SnapshotIdentitySets`.
 979        '''
 980        self.nodes = svc.SnapshotNodes(client.nodes)
 981        '''
 982         Nodes make up the StrongDM network, and allow your users to connect securely to your resources.
 983         There are three types of nodes:
 984         1. **Relay:** creates connectivity to your datasources, while maintaining the egress-only nature of your firewall
 985         2. **Gateway:** a relay that also listens for connections from StrongDM clients
 986         3. **Proxy Cluster:** a cluster of workers that together mediate access from clients to resources
 987
 988        See `strongdm.svc.SnapshotNodes`.
 989        '''
 990        self.policies = svc.SnapshotPolicies(client.policies)
 991        '''
 992         Policies are the collection of one or more statements that enforce fine-grained access
 993         control for the users of an organization.
 994
 995        See `strongdm.svc.SnapshotPolicies`.
 996        '''
 997        self.proxy_cluster_keys = svc.SnapshotProxyClusterKeys(
 998            client.proxy_cluster_keys)
 999        '''
1000         Proxy Cluster Keys are authentication keys for all proxies within a cluster.
1001         The proxies within a cluster share the same key. One cluster can have
1002         multiple keys in order to facilitate key rotation.
1003
1004        See `strongdm.svc.SnapshotProxyClusterKeys`.
1005        '''
1006        self.remote_identities = svc.SnapshotRemoteIdentities(
1007            client.remote_identities)
1008        '''
1009         RemoteIdentities assign a resource directly to an account, giving the account the permission to connect to that resource.
1010
1011        See `strongdm.svc.SnapshotRemoteIdentities`.
1012        '''
1013        self.remote_identity_groups = svc.SnapshotRemoteIdentityGroups(
1014            client.remote_identity_groups)
1015        '''
1016         A RemoteIdentityGroup is a named grouping of Remote Identities for Accounts.
1017         An Account's relationship to a RemoteIdentityGroup is defined via RemoteIdentity objects.
1018
1019        See `strongdm.svc.SnapshotRemoteIdentityGroups`.
1020        '''
1021        self.requestable_account_entitlements = svc.SnapshotRequestableAccountEntitlements(
1022            client.requestable_account_entitlements)
1023        '''
1024         RequestableAccountEntitlements enumerates the resources that an account is permitted to request access to.
1025         The RequestableAccountEntitlements service is read-only.
1026
1027        See `strongdm.svc.SnapshotRequestableAccountEntitlements`.
1028        '''
1029        self.requestable_resource_entitlements = svc.SnapshotRequestableResourceEntitlements(
1030            client.requestable_resource_entitlements)
1031        '''
1032         RequestableResourceEntitlements enumerates the accounts that are permitted to request access to a given resource.
1033         The RequestableResourceEntitlements service is read-only.
1034
1035        See `strongdm.svc.SnapshotRequestableResourceEntitlements`.
1036        '''
1037        self.requestable_role_entitlements = svc.SnapshotRequestableRoleEntitlements(
1038            client.requestable_role_entitlements)
1039        '''
1040         RequestableRoleEntitlements enumerates the resources that a role permits its members to request access to.
1041         The RequestableRoleEntitlements service is read-only.
1042
1043        See `strongdm.svc.SnapshotRequestableRoleEntitlements`.
1044        '''
1045        self.resources = svc.SnapshotResources(client.resources)
1046        '''
1047         Resources are databases, servers, clusters, websites, or clouds that strongDM
1048         delegates access to.
1049
1050        See `strongdm.svc.SnapshotResources`.
1051        '''
1052        self.role_resources = svc.SnapshotRoleResources(client.role_resources)
1053        '''
1054         RoleResources enumerates the resources to which roles have access.
1055         The RoleResources service is read-only.
1056
1057        See `strongdm.svc.SnapshotRoleResources`.
1058        '''
1059        self.secret_stores = svc.SnapshotSecretStores(client.secret_stores)
1060        '''
1061         SecretStores are servers where resource secrets (passwords, keys) are stored.
1062
1063        See `strongdm.svc.SnapshotSecretStores`.
1064        '''
1065        self.workflow_approvers = svc.SnapshotWorkflowApprovers(
1066            client.workflow_approvers)
1067        '''
1068         WorkflowApprovers is an account or a role with the ability to approve requests bound to a workflow.
1069
1070        See `strongdm.svc.SnapshotWorkflowApprovers`.
1071        '''
1072        self.workflow_roles = svc.SnapshotWorkflowRoles(client.workflow_roles)
1073        '''
1074         WorkflowRole links a role to a workflow. The linked roles indicate which roles a user must be a part of
1075         to request access to a resource via the workflow.
1076
1077        See `strongdm.svc.SnapshotWorkflowRoles`.
1078        '''
1079        self.workflows = svc.SnapshotWorkflows(client.workflows)
1080        '''
1081         Workflows are the collection of rules that define the resources to which access can be requested,
1082         the users that can request that access, and the mechanism for approving those requests which can either
1083         be automatic approval or a set of users authorized to approve the requests.
1084
1085        See `strongdm.svc.SnapshotWorkflows`.
1086        '''