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/16.23.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.peering_group_nodes = svc.PeeringGroupNodes(channel, self)
 480        '''
 481         PeeringGroupNodes provides the building blocks necessary to obtain attach a node to a peering group.
 482
 483        See `strongdm.svc.PeeringGroupNodes`.
 484        '''
 485        self.peering_group_peers = svc.PeeringGroupPeers(channel, self)
 486        '''
 487         PeeringGroupPeers provides the building blocks necessary to link two peering groups.
 488
 489        See `strongdm.svc.PeeringGroupPeers`.
 490        '''
 491        self.peering_group_resources = svc.PeeringGroupResources(channel, self)
 492        '''
 493         PeeringGroupResources provides the building blocks necessary to obtain attach a resource to a peering group.
 494
 495        See `strongdm.svc.PeeringGroupResources`.
 496        '''
 497        self.peering_groups = svc.PeeringGroups(channel, self)
 498        '''
 499         PeeringGroups provides the building blocks necessary to obtain explicit network topology and routing.
 500
 501        See `strongdm.svc.PeeringGroups`.
 502        '''
 503        self.policies = svc.Policies(channel, self)
 504        '''
 505         Policies are the collection of one or more statements that enforce fine-grained access
 506         control for the users of an organization.
 507
 508        See `strongdm.svc.Policies`.
 509        '''
 510        self.policies_history = svc.PoliciesHistory(channel, self)
 511        '''
 512         PoliciesHistory records all changes to the state of a Policy.
 513
 514        See `strongdm.svc.PoliciesHistory`.
 515        '''
 516        self.proxy_cluster_keys = svc.ProxyClusterKeys(channel, self)
 517        '''
 518         Proxy Cluster Keys are authentication keys for all proxies within a cluster.
 519         The proxies within a cluster share the same key. One cluster can have
 520         multiple keys in order to facilitate key rotation.
 521
 522        See `strongdm.svc.ProxyClusterKeys`.
 523        '''
 524        self.queries = svc.Queries(channel, self)
 525        '''
 526         A Query is a record of a single client request to a resource, such as a SQL query.
 527         Long-running SSH, RDP, or Kubernetes interactive sessions also count as queries.
 528         The Queries service is read-only.
 529
 530        See `strongdm.svc.Queries`.
 531        '''
 532        self.remote_identities = svc.RemoteIdentities(channel, self)
 533        '''
 534         RemoteIdentities assign a resource directly to an account, giving the account the permission to connect to that resource.
 535
 536        See `strongdm.svc.RemoteIdentities`.
 537        '''
 538        self.remote_identities_history = svc.RemoteIdentitiesHistory(
 539            channel, self)
 540        '''
 541         RemoteIdentitiesHistory records all changes to the state of a RemoteIdentity.
 542
 543        See `strongdm.svc.RemoteIdentitiesHistory`.
 544        '''
 545        self.remote_identity_groups = svc.RemoteIdentityGroups(channel, self)
 546        '''
 547         A RemoteIdentityGroup is a named grouping of Remote Identities for Accounts.
 548         An Account's relationship to a RemoteIdentityGroup is defined via RemoteIdentity objects.
 549
 550        See `strongdm.svc.RemoteIdentityGroups`.
 551        '''
 552        self.remote_identity_groups_history = svc.RemoteIdentityGroupsHistory(
 553            channel, self)
 554        '''
 555         RemoteIdentityGroupsHistory records all changes to the state of a RemoteIdentityGroup.
 556
 557        See `strongdm.svc.RemoteIdentityGroupsHistory`.
 558        '''
 559        self.replays = svc.Replays(channel, self)
 560        '''
 561         A Replay captures the data transferred over a long-running SSH, RDP, or Kubernetes interactive session
 562         (otherwise referred to as a query). The Replays service is read-only.
 563
 564        See `strongdm.svc.Replays`.
 565        '''
 566        self.requestable_account_entitlements = svc.RequestableAccountEntitlements(
 567            channel, self)
 568        '''
 569         RequestableAccountEntitlements enumerates the resources that an account is permitted to request access to.
 570         The RequestableAccountEntitlements service is read-only.
 571
 572        See `strongdm.svc.RequestableAccountEntitlements`.
 573        '''
 574        self.requestable_resource_entitlements = svc.RequestableResourceEntitlements(
 575            channel, self)
 576        '''
 577         RequestableResourceEntitlements enumerates the accounts that are permitted to request access to a given resource.
 578         The RequestableResourceEntitlements service is read-only.
 579
 580        See `strongdm.svc.RequestableResourceEntitlements`.
 581        '''
 582        self.requestable_role_entitlements = svc.RequestableRoleEntitlements(
 583            channel, self)
 584        '''
 585         RequestableRoleEntitlements enumerates the resources that a role permits its members to request access to.
 586         The RequestableRoleEntitlements service is read-only.
 587
 588        See `strongdm.svc.RequestableRoleEntitlements`.
 589        '''
 590        self.resources = svc.Resources(channel, self)
 591        '''
 592         Resources are databases, servers, clusters, websites, or clouds that strongDM
 593         delegates access to.
 594
 595        See `strongdm.svc.Resources`.
 596        '''
 597        self.resources_history = svc.ResourcesHistory(channel, self)
 598        '''
 599         ResourcesHistory records all changes to the state of a Resource.
 600
 601        See `strongdm.svc.ResourcesHistory`.
 602        '''
 603        self.role_resources = svc.RoleResources(channel, self)
 604        '''
 605         RoleResources enumerates the resources to which roles have access.
 606         The RoleResources service is read-only.
 607
 608        See `strongdm.svc.RoleResources`.
 609        '''
 610        self.role_resources_history = svc.RoleResourcesHistory(channel, self)
 611        '''
 612         RoleResourcesHistory records all changes to the state of a RoleResource.
 613
 614        See `strongdm.svc.RoleResourcesHistory`.
 615        '''
 616        self.roles_history = svc.RolesHistory(channel, self)
 617        '''
 618         RolesHistory records all changes to the state of a Role.
 619
 620        See `strongdm.svc.RolesHistory`.
 621        '''
 622        self.secret_stores = svc.SecretStores(channel, self)
 623        '''
 624         SecretStores are servers where resource secrets (passwords, keys) are stored.
 625
 626        See `strongdm.svc.SecretStores`.
 627        '''
 628        self.secret_engines = svc.SecretEngines(channel, self)
 629        '''
 630
 631
 632        See `strongdm.svc.SecretEngines`.
 633        '''
 634        self.secret_store_healths = svc.SecretStoreHealths(channel, self)
 635        '''
 636         SecretStoreHealths exposes health states for secret stores.
 637
 638        See `strongdm.svc.SecretStoreHealths`.
 639        '''
 640        self.secret_stores_history = svc.SecretStoresHistory(channel, self)
 641        '''
 642         SecretStoresHistory records all changes to the state of a SecretStore.
 643
 644        See `strongdm.svc.SecretStoresHistory`.
 645        '''
 646        self.workflow_approvers = svc.WorkflowApprovers(channel, self)
 647        '''
 648         WorkflowApprovers is an account or a role with the ability to approve requests bound to a workflow.
 649
 650        See `strongdm.svc.WorkflowApprovers`.
 651        '''
 652        self.workflow_approvers_history = svc.WorkflowApproversHistory(
 653            channel, self)
 654        '''
 655         WorkflowApproversHistory provides records of all changes to the state of a WorkflowApprover.
 656
 657        See `strongdm.svc.WorkflowApproversHistory`.
 658        '''
 659        self.workflow_roles = svc.WorkflowRoles(channel, self)
 660        '''
 661         WorkflowRole links a role to a workflow. The linked roles indicate which roles a user must be a part of
 662         to request access to a resource via the workflow.
 663
 664        See `strongdm.svc.WorkflowRoles`.
 665        '''
 666        self.workflow_roles_history = svc.WorkflowRolesHistory(channel, self)
 667        '''
 668         WorkflowRolesHistory provides records of all changes to the state of a WorkflowRole
 669
 670        See `strongdm.svc.WorkflowRolesHistory`.
 671        '''
 672        self.workflows = svc.Workflows(channel, self)
 673        '''
 674         Workflows are the collection of rules that define the resources to which access can be requested,
 675         the users that can request that access, and the mechanism for approving those requests which can either
 676         be automatic approval or a set of users authorized to approve the requests.
 677
 678        See `strongdm.svc.Workflows`.
 679        '''
 680        self.workflows_history = svc.WorkflowsHistory(channel, self)
 681        '''
 682         WorkflowsHistory provides records of all changes to the state of a Workflow.
 683
 684        See `strongdm.svc.WorkflowsHistory`.
 685        '''
 686
 687    def close(self):
 688        '''Closes this Client and releases all resources held by it.
 689
 690        Closing the Client will immediately terminate all RPCs active with the
 691        Client and it is not valid to invoke new RPCs with the Client.
 692
 693        This method is idempotent.
 694        '''
 695        self.channel.close()
 696
 697    def get_metadata(self, method_name, req):
 698        return [
 699            ('x-sdm-authentication', self.api_access_key),
 700            ('x-sdm-signature', self.sign(method_name,
 701                                          req.SerializeToString())),
 702            ('x-sdm-api-version', API_VERSION),
 703            ('x-sdm-user-agent', USER_AGENT),
 704        ]
 705
 706    def sign(self, method_name, request_bytes):
 707        def hmac_digest(key, msg_byte_string):
 708            return hmac.new(key, msg=msg_byte_string,
 709                            digestmod=hashlib.sha256).digest()
 710
 711        current_utc_date = datetime.datetime.now(
 712            datetime.timezone.utc).strftime('%Y-%m-%d')
 713        signing_key = hmac_digest(self.api_secret, current_utc_date.encode())
 714        signing_key = hmac_digest(signing_key, b'sdm_api_v1')
 715
 716        hash = hashlib.sha256()
 717
 718        hash.update(method_name.encode())
 719        hash.update(b'\n')
 720        hash.update(request_bytes)
 721
 722        return base64.b64encode(hmac_digest(signing_key, hash.digest()))
 723
 724    def exponentialBackoff(self, retries, deadline=None):
 725        def applyDeadline(delay, deadline):
 726            if deadline is None:
 727                return delay
 728            remaining = deadline - time.time()
 729            if remaining < 0:
 730                return 0
 731            return min(delay, remaining)
 732
 733        if retries == 0:
 734            return applyDeadline(self.base_retry_delay, deadline)
 735
 736        backoff, max_delay = self.base_retry_delay, self.max_retry_delay
 737        while backoff < max_delay and retries > 0:
 738            backoff *= self.retry_factor
 739            retries -= 1
 740
 741        if backoff > max_delay:
 742            backoff = max_delay
 743
 744        # Randomize backoff delays so that if a cluster of requests start at
 745        # the same time, they won't operate in lockstep.
 746        backoff *= 1 + self.retry_jitter * (random.random() * 2 - 1)
 747        if backoff < 0:
 748            return 0
 749
 750        return applyDeadline(backoff, deadline)
 751
 752    def shouldRetry(self, retries, err, deadline=None):
 753        # Check if we've passed the deadline
 754        if deadline is not None and time.time() >= deadline:
 755            return False
 756
 757        if not isinstance(err, grpc.RpcError):
 758            return False
 759
 760        if self.retry_rate_limit_errors and err.code(
 761        ) == grpc.StatusCode.RESOURCE_EXHAUSTED:
 762            return True
 763
 764        return retries <= 3 and (err.code() == grpc.StatusCode.INTERNAL
 765                                 or err.code() == grpc.StatusCode.UNAVAILABLE)
 766
 767    def snapshot_at(self, snapshot_datetime):
 768        '''
 769        Constructs a read-only client that will provide historical data from the provided timestamp.
 770
 771        See `SnapshotClient`.
 772        '''
 773        client = copy.copy(self)
 774        client.snapshot_datetime = snapshot_datetime
 775        client.access_requests = svc.AccessRequests(client.channel, client)
 776        client.account_attachments = svc.AccountAttachments(
 777            client.channel, client)
 778        client.account_grants = svc.AccountGrants(client.channel, client)
 779        client.account_permissions = svc.AccountPermissions(
 780            client.channel, client)
 781        client.account_resources = svc.AccountResources(client.channel, client)
 782        client.accounts = svc.Accounts(client.channel, client)
 783        client.accounts_groups = svc.AccountsGroups(client.channel, client)
 784        client.approval_workflow_approvers = svc.ApprovalWorkflowApprovers(
 785            client.channel, client)
 786        client.approval_workflow_steps = svc.ApprovalWorkflowSteps(
 787            client.channel, client)
 788        client.approval_workflows = svc.ApprovalWorkflows(
 789            client.channel, client)
 790        client.discovery_connectors = svc.DiscoveryConnectors(
 791            client.channel, client)
 792        client.granted_account_entitlements = svc.GrantedAccountEntitlements(
 793            client.channel, client)
 794        client.granted_resource_entitlements = svc.GrantedResourceEntitlements(
 795            client.channel, client)
 796        client.granted_role_entitlements = svc.GrantedRoleEntitlements(
 797            client.channel, client)
 798        client.roles = svc.Roles(client.channel, client)
 799        client.groups = svc.Groups(client.channel, client)
 800        client.groups_roles = svc.GroupsRoles(client.channel, client)
 801        client.identity_aliases = svc.IdentityAliases(client.channel, client)
 802        client.identity_sets = svc.IdentitySets(client.channel, client)
 803        client.nodes = svc.Nodes(client.channel, client)
 804        client.policies = svc.Policies(client.channel, client)
 805        client.proxy_cluster_keys = svc.ProxyClusterKeys(
 806            client.channel, client)
 807        client.remote_identities = svc.RemoteIdentities(client.channel, client)
 808        client.remote_identity_groups = svc.RemoteIdentityGroups(
 809            client.channel, client)
 810        client.requestable_account_entitlements = svc.RequestableAccountEntitlements(
 811            client.channel, client)
 812        client.requestable_resource_entitlements = svc.RequestableResourceEntitlements(
 813            client.channel, client)
 814        client.requestable_role_entitlements = svc.RequestableRoleEntitlements(
 815            client.channel, client)
 816        client.resources = svc.Resources(client.channel, client)
 817        client.role_resources = svc.RoleResources(client.channel, client)
 818        client.secret_stores = svc.SecretStores(client.channel, client)
 819        client.workflow_approvers = svc.WorkflowApprovers(
 820            client.channel, client)
 821        client.workflow_roles = svc.WorkflowRoles(client.channel, client)
 822        client.workflows = svc.Workflows(client.channel, client)
 823        return SnapshotClient(client)
 824
 825
 826class SnapshotClient:
 827    '''SnapshotClient exposes methods to query historical records at a provided timestamp.'''
 828    def __init__(self, client):
 829        self.access_requests = svc.SnapshotAccessRequests(
 830            client.access_requests)
 831        '''
 832         AccessRequests are requests for access to a resource that may match a Workflow.
 833
 834        See `strongdm.svc.SnapshotAccessRequests`.
 835        '''
 836        self.account_attachments = svc.SnapshotAccountAttachments(
 837            client.account_attachments)
 838        '''
 839         AccountAttachments assign an account to a role.
 840
 841        See `strongdm.svc.SnapshotAccountAttachments`.
 842        '''
 843        self.account_grants = svc.SnapshotAccountGrants(client.account_grants)
 844        '''
 845         AccountGrants assign a resource directly to an account, giving the account the permission to connect to that resource.
 846
 847        See `strongdm.svc.SnapshotAccountGrants`.
 848        '''
 849        self.account_permissions = svc.SnapshotAccountPermissions(
 850            client.account_permissions)
 851        '''
 852         AccountPermissions records the granular permissions accounts have, allowing them to execute
 853         relevant commands via StrongDM's APIs.
 854
 855        See `strongdm.svc.SnapshotAccountPermissions`.
 856        '''
 857        self.account_resources = svc.SnapshotAccountResources(
 858            client.account_resources)
 859        '''
 860         AccountResources enumerates the resources to which accounts have access.
 861         The AccountResources service is read-only.
 862
 863        See `strongdm.svc.SnapshotAccountResources`.
 864        '''
 865        self.accounts = svc.SnapshotAccounts(client.accounts)
 866        '''
 867         Accounts are users that have access to strongDM. There are two types of accounts:
 868         1. **Users:** humans who are authenticated through username and password or SSO.
 869         2. **Service Accounts:** machines that are authenticated using a service token.
 870         3. **Tokens** are access keys with permissions that can be used for authentication.
 871
 872        See `strongdm.svc.SnapshotAccounts`.
 873        '''
 874        self.accounts_groups = svc.SnapshotAccountsGroups(
 875            client.accounts_groups)
 876        '''
 877         An AccountGroup links an account and a group.
 878
 879        See `strongdm.svc.SnapshotAccountsGroups`.
 880        '''
 881        self.approval_workflow_approvers = svc.SnapshotApprovalWorkflowApprovers(
 882            client.approval_workflow_approvers)
 883        '''
 884         ApprovalWorkflowApprovers link approval workflow approvers to an ApprovalWorkflowStep
 885
 886        See `strongdm.svc.SnapshotApprovalWorkflowApprovers`.
 887        '''
 888        self.approval_workflow_steps = svc.SnapshotApprovalWorkflowSteps(
 889            client.approval_workflow_steps)
 890        '''
 891         ApprovalWorkflowSteps link approval workflow steps to an ApprovalWorkflow
 892
 893        See `strongdm.svc.SnapshotApprovalWorkflowSteps`.
 894        '''
 895        self.approval_workflows = svc.SnapshotApprovalWorkflows(
 896            client.approval_workflows)
 897        '''
 898         ApprovalWorkflows are the mechanism by which requests for access can be viewed by authorized
 899         approvers and be approved or denied.
 900
 901        See `strongdm.svc.SnapshotApprovalWorkflows`.
 902        '''
 903        self.discovery_connectors = svc.SnapshotDiscoveryConnectors(
 904            client.discovery_connectors)
 905        '''
 906         A Discovery Connector is a configuration object for performing Resource
 907         Scans in remote systems such as AWS, GCP, Azure, and other systems.
 908
 909        See `strongdm.svc.SnapshotDiscoveryConnectors`.
 910        '''
 911        self.granted_account_entitlements = svc.SnapshotGrantedAccountEntitlements(
 912            client.granted_account_entitlements)
 913        '''
 914         GrantedAccountEntitlements enumerates the resources to which an account has been granted access.
 915         The GrantedAccountEntitlements service is read-only.
 916
 917        See `strongdm.svc.SnapshotGrantedAccountEntitlements`.
 918        '''
 919        self.granted_resource_entitlements = svc.SnapshotGrantedResourceEntitlements(
 920            client.granted_resource_entitlements)
 921        '''
 922         GrantedResourceEntitlements enumerates the accounts that have been granted access to a given resource.
 923         The GrantedResourceEntitlements service is read-only.
 924
 925        See `strongdm.svc.SnapshotGrantedResourceEntitlements`.
 926        '''
 927        self.granted_role_entitlements = svc.SnapshotGrantedRoleEntitlements(
 928            client.granted_role_entitlements)
 929        '''
 930         GrantedRoleEntitlements enumerates the resources to which a role grants access.
 931         The GrantedRoleEntitlements service is read-only.
 932
 933        See `strongdm.svc.SnapshotGrantedRoleEntitlements`.
 934        '''
 935        self.roles = svc.SnapshotRoles(client.roles)
 936        '''
 937         A Role has a list of access rules which determine which Resources the members
 938         of the Role have access to. An Account can be a member of multiple Roles via
 939         AccountAttachments.
 940
 941        See `strongdm.svc.SnapshotRoles`.
 942        '''
 943        self.groups = svc.SnapshotGroups(client.groups)
 944        '''
 945         A Group is a set of principals.
 946
 947        See `strongdm.svc.SnapshotGroups`.
 948        '''
 949        self.groups_roles = svc.SnapshotGroupsRoles(client.groups_roles)
 950        '''
 951         A GroupRole is an assignment of a Group to a Role.
 952
 953        See `strongdm.svc.SnapshotGroupsRoles`.
 954        '''
 955        self.identity_aliases = svc.SnapshotIdentityAliases(
 956            client.identity_aliases)
 957        '''
 958         IdentityAliases assign an alias to an account within an IdentitySet.
 959         The alias is used as the username when connecting to a identity supported resource.
 960
 961        See `strongdm.svc.SnapshotIdentityAliases`.
 962        '''
 963        self.identity_sets = svc.SnapshotIdentitySets(client.identity_sets)
 964        '''
 965         A IdentitySet is a named grouping of Identity Aliases for Accounts.
 966         An Account's relationship to a IdentitySet is defined via IdentityAlias objects.
 967
 968        See `strongdm.svc.SnapshotIdentitySets`.
 969        '''
 970        self.nodes = svc.SnapshotNodes(client.nodes)
 971        '''
 972         Nodes make up the StrongDM network, and allow your users to connect securely to your resources.
 973         There are three types of nodes:
 974         1. **Relay:** creates connectivity to your datasources, while maintaining the egress-only nature of your firewall
 975         2. **Gateway:** a relay that also listens for connections from StrongDM clients
 976         3. **Proxy Cluster:** a cluster of workers that together mediate access from clients to resources
 977
 978        See `strongdm.svc.SnapshotNodes`.
 979        '''
 980        self.policies = svc.SnapshotPolicies(client.policies)
 981        '''
 982         Policies are the collection of one or more statements that enforce fine-grained access
 983         control for the users of an organization.
 984
 985        See `strongdm.svc.SnapshotPolicies`.
 986        '''
 987        self.proxy_cluster_keys = svc.SnapshotProxyClusterKeys(
 988            client.proxy_cluster_keys)
 989        '''
 990         Proxy Cluster Keys are authentication keys for all proxies within a cluster.
 991         The proxies within a cluster share the same key. One cluster can have
 992         multiple keys in order to facilitate key rotation.
 993
 994        See `strongdm.svc.SnapshotProxyClusterKeys`.
 995        '''
 996        self.remote_identities = svc.SnapshotRemoteIdentities(
 997            client.remote_identities)
 998        '''
 999         RemoteIdentities assign a resource directly to an account, giving the account the permission to connect to that resource.
1000
1001        See `strongdm.svc.SnapshotRemoteIdentities`.
1002        '''
1003        self.remote_identity_groups = svc.SnapshotRemoteIdentityGroups(
1004            client.remote_identity_groups)
1005        '''
1006         A RemoteIdentityGroup is a named grouping of Remote Identities for Accounts.
1007         An Account's relationship to a RemoteIdentityGroup is defined via RemoteIdentity objects.
1008
1009        See `strongdm.svc.SnapshotRemoteIdentityGroups`.
1010        '''
1011        self.requestable_account_entitlements = svc.SnapshotRequestableAccountEntitlements(
1012            client.requestable_account_entitlements)
1013        '''
1014         RequestableAccountEntitlements enumerates the resources that an account is permitted to request access to.
1015         The RequestableAccountEntitlements service is read-only.
1016
1017        See `strongdm.svc.SnapshotRequestableAccountEntitlements`.
1018        '''
1019        self.requestable_resource_entitlements = svc.SnapshotRequestableResourceEntitlements(
1020            client.requestable_resource_entitlements)
1021        '''
1022         RequestableResourceEntitlements enumerates the accounts that are permitted to request access to a given resource.
1023         The RequestableResourceEntitlements service is read-only.
1024
1025        See `strongdm.svc.SnapshotRequestableResourceEntitlements`.
1026        '''
1027        self.requestable_role_entitlements = svc.SnapshotRequestableRoleEntitlements(
1028            client.requestable_role_entitlements)
1029        '''
1030         RequestableRoleEntitlements enumerates the resources that a role permits its members to request access to.
1031         The RequestableRoleEntitlements service is read-only.
1032
1033        See `strongdm.svc.SnapshotRequestableRoleEntitlements`.
1034        '''
1035        self.resources = svc.SnapshotResources(client.resources)
1036        '''
1037         Resources are databases, servers, clusters, websites, or clouds that strongDM
1038         delegates access to.
1039
1040        See `strongdm.svc.SnapshotResources`.
1041        '''
1042        self.role_resources = svc.SnapshotRoleResources(client.role_resources)
1043        '''
1044         RoleResources enumerates the resources to which roles have access.
1045         The RoleResources service is read-only.
1046
1047        See `strongdm.svc.SnapshotRoleResources`.
1048        '''
1049        self.secret_stores = svc.SnapshotSecretStores(client.secret_stores)
1050        '''
1051         SecretStores are servers where resource secrets (passwords, keys) are stored.
1052
1053        See `strongdm.svc.SnapshotSecretStores`.
1054        '''
1055        self.workflow_approvers = svc.SnapshotWorkflowApprovers(
1056            client.workflow_approvers)
1057        '''
1058         WorkflowApprovers is an account or a role with the ability to approve requests bound to a workflow.
1059
1060        See `strongdm.svc.SnapshotWorkflowApprovers`.
1061        '''
1062        self.workflow_roles = svc.SnapshotWorkflowRoles(client.workflow_roles)
1063        '''
1064         WorkflowRole links a role to a workflow. The linked roles indicate which roles a user must be a part of
1065         to request access to a resource via the workflow.
1066
1067        See `strongdm.svc.SnapshotWorkflowRoles`.
1068        '''
1069        self.workflows = svc.SnapshotWorkflows(client.workflows)
1070        '''
1071         Workflows are the collection of rules that define the resources to which access can be requested,
1072         the users that can request that access, and the mechanism for approving those requests which can either
1073         be automatic approval or a set of users authorized to approve the requests.
1074
1075        See `strongdm.svc.SnapshotWorkflows`.
1076        '''