capo-securityhub 0.1.0__tar.gz → 0.3.0__tar.gz

capo_securityhub-0.3.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: capo-securityhub
+Version: 0.3.0
+Summary: Python SDK for AWS Securityhub.
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: zapros>=0.13.0
+Provides-Extra: anyio
+Requires-Dist: anyio>=3.0; extra == "anyio"
+Provides-Extra: sso
+Requires-Dist: capo-sso>=0.2.0; extra == "sso"
+Requires-Dist: capo-sso-oidc>=0.2.0; extra == "sso"
+Requires-Dist: capo-sts>=0.3.0; extra == "sso"
+Dynamic: license-file
+
+# Getting Started
+
+## Installation
+
+```
+pip install capo-securityhub
+```
+
+## Usage
+
+```python
+from capo_securityhub import AsyncSecurityHubClient
+
+
+async def main():
+    async with AsyncSecurityHubClient() as security_hub:
+        # Example: call the accept_administrator_invitation operation
+        response = await security_hub.accept_administrator_invitation()
+        print(response)
+```
+
+## Pagination
+
+Some operations in this SDK support pagination. If the operation supports pagination it will have an `iter_` prefixed method that returns an async iterator.
+
+```python
+from capo_securityhub import AsyncSecurityHubClient
+
+
+async def main():
+    async with AsyncSecurityHubClient() as security_hub:
+        # Example: paginate over describe_action_targets
+        async for item in security_hub.iter_describe_action_targets():
+            print(item)
+```
+
+## Error Handling
+
+The SDK raises exceptions for errors returned by the API. Catch them to handle failures gracefully.
+
+```python
+from capo_securityhub import AsyncSecurityHubClient
+from capo_securityhub.error import InternalException
+
+
+async def main():
+    async with AsyncSecurityHubClient() as security_hub:
+        try:
+            await security_hub.accept_administrator_invitation()
+        except InternalException as e:
+            print(f"Error: {e}")
+            print(e.data)  # additional error data
+```
+
+## Retrying
+
+The SDK retries failed operations automatically. Retry behaviour follows the Smithy specification: errors are retried based on their `is_retryable` and `is_throttling_error` attributes. Throttling errors use a longer base delay. Network-level failures (connection errors and timeouts) are also retried. Non-retryable errors, such as client errors without the `@retryable` trait, are raised immediately without further attempts.
+
+The number of attempts defaults to 3 and can be changed at the client level via `retry_max_attempts`, or per call via `config_overrides`.
+
+```python
+from capo_securityhub import AsyncSecurityHubClient
+
+
+async def main():
+    async with AsyncSecurityHubClient() as security_hub:
+        # Default: 3 attempts for every operation
+        response = await security_hub.accept_administrator_invitation()
+
+        # Override per operation
+        response = await security_hub.accept_administrator_invitation(config_overrides={"retry_max_attempts": 5})
+
+        # Disable retries for this call
+        response = await security_hub.accept_administrator_invitation(config_overrides={"retry_max_attempts": 1})
+```

capo_securityhub-0.3.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "capo-securityhub"
+version = "0.3.0"
+description = "Python SDK for AWS Securityhub."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Code Generators",
+    "Typing :: Typed",
+]
+dependencies = [
+    "zapros>=0.13.0",
+]
+
+[project.optional-dependencies]
+# Async file request bodies via Body.async_from_path
+anyio = ["anyio>=3.0"]
+# IAM Identity Center (SSO), assume-role and web-identity credentials providers
+sso = [
+    "capo-sso>=0.2.0",
+    "capo-sso-oidc>=0.2.0",
+    "capo-sts>=0.3.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ty.environment]
+python-version = "3.14"
+root = ["./src"]
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ty.rules]
+missing-typed-dict-key = "ignore"
+unused-type-ignore-comment = "ignore"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501", "E741"]
+
+[dependency-groups]
+dev = [
+    "inline-snapshot>=0.33.0",
+    # TODO: fix for 0.0.69
+    "ty==0.0.68",
+    "pytest>=9.0.3",
+    "ruff>=0.15.14",
+    "trio",
+]

capo_securityhub-0.3.0/src/capo_securityhub/__init__.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from . import _iter as _iter
+from . import _protocol as _protocol
+from ._auth._identity import Credentials as Credentials
+from ._auth._identity import Identity as Identity
+from ._auth._providers import (
+    AssumeRoleCredentialsProvider as AssumeRoleCredentialsProvider,
+)
+from ._auth._providers import (
+    AssumeRoleError as AssumeRoleError,
+)
+from ._auth._providers import (
+    CachedProvider as CachedProvider,
+)
+from ._auth._providers import (
+    ChainedProvider as ChainedProvider,
+)
+from ._auth._providers import (
+    CredentialsProvider as CredentialsProvider,
+)
+from ._auth._providers import (
+    EnvCredentialsProvider as EnvCredentialsProvider,
+)
+from ._auth._providers import (
+    IdentityNotFound as IdentityNotFound,
+)
+from ._auth._providers import (
+    IdentityProvider as IdentityProvider,
+)
+from ._auth._providers import (
+    MissingDependencyError as MissingDependencyError,
+)
+from ._auth._providers import (
+    ProfileCredentialsProvider as ProfileCredentialsProvider,
+)
+from ._auth._providers import (
+    SsoCredentialsProvider as SsoCredentialsProvider,
+)
+from ._auth._providers import (
+    SSOError as SSOError,
+)
+from ._auth._providers import (
+    StaticAwsCredentialsProvider as StaticAwsCredentialsProvider,
+)
+from ._auth._providers import (
+    WebIdentityCredentialsProvider as WebIdentityCredentialsProvider,
+)
+from ._auth._signers import Signer as Signer
+from ._auth._signers import SigV4Signer as SigV4Signer
+from ._body import Body as Body
+from ._services._pipeline import (
+    AsyncOperationOptions as AsyncOperationOptions,
+)
+from ._services._pipeline import (
+    AsyncOperationRequest as AsyncOperationRequest,
+)
+from ._services._pipeline import (
+    AsyncOperationResponse as AsyncOperationResponse,
+)
+from ._services._pipeline import (
+    OperationOptions as OperationOptions,
+)
+from ._services._pipeline import (
+    OperationRequest as OperationRequest,
+)
+from ._services._pipeline import (
+    OperationResponse as OperationResponse,
+)
+from ._services.async_security_hub import (
+    AsyncSecurityHubClient as AsyncSecurityHubClient,
+)
+from ._services.security_hub import SecurityHubClient as SecurityHubClient

capo_securityhub-0.3.0/src/capo_securityhub/_auth/_signers.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from zapros import Request
+
+from capo_securityhub._auth._identity import Credentials, Identity
+from capo_securityhub._auth._providers import IdentityProvider
+from capo_securityhub._auth._sigv4 import S3_SIGNING_NAMES, SigV4AuthContext, sign_sigv4
+
+IdentityT = TypeVar("IdentityT", bound="Identity")
+
+
+class Signer(ABC, Generic[IdentityT]):
+    """Per-request request signer. Holds an IdentityProvider plus static config."""
+
+    def __init__(self, provider: IdentityProvider[IdentityT]) -> None:
+        self.provider = provider
+
+    @abstractmethod
+    async def asign(self, req: Request) -> Request: ...
+    @abstractmethod
+    def sign(self, req: Request) -> Request: ...
+
+
+class SigV4Signer(Signer[Credentials]):
+    """aws.auth#sigv4 — AWS Signature Version 4.
+
+    The full auth scheme (``name`` variant, ``signingName``, ``signingRegion``,
+    encoding/normalization flags) is provided by the caller — either from the
+    endpoint rule-set's ``authSchemes`` property or built by the generated
+    ``get_signer`` from operation defaults. ``unsigned_payload`` mirrors the
+    operation's ``aws.auth#unsignedPayload`` trait: the body is sent but left
+    out of the signature. ``event_stream`` marks a request event stream: the
+    request is signed with the ``STREAMING-AWS4-HMAC-SHA256-EVENTS`` payload
+    marker and every event with a signature chained from it.
+    """
+
+    def __init__(
+        self,
+        provider: IdentityProvider[Credentials],
+        *,
+        auth_scheme: dict[str, Any],
+        unsigned_payload: bool = False,
+        event_stream: bool = False,
+    ) -> None:
+        super().__init__(provider)
+        self._auth_scheme = auth_scheme
+        self._unsigned_payload = unsigned_payload
+        self._event_stream = event_stream
+
+    async def asign(self, req: Request) -> Request:
+        creds = await self.provider.aresolve_identity()
+        ctx: SigV4AuthContext = {
+            "type": "sig_v4",
+            "access_key_id": creds["access_key"],
+            "secret_access_key": creds["secret_key"],
+            "session_token": creds.get("session_token"),
+            "signing_region": self._auth_scheme["signingRegion"],
+            "signing_name": self._auth_scheme["signingName"],
+            "disable_double_encoding": self._auth_scheme.get(
+                "disableDoubleEncoding", False
+            ),
+            "disable_normalize_path": self._auth_scheme.get(
+                "disableNormalizePath", False
+            ),
+        }
+        unsigned_payload = self._unsigned_payload
+        if (
+            not unsigned_payload
+            and not self._event_stream
+            and req.body is not None
+            and not isinstance(req.body, bytes)
+        ):
+            if self._auth_scheme["signingName"] in S3_SIGNING_NAMES:
+                # S3 accepts UNSIGNED-PAYLOAD for any operation; streamed bodies rely on it.
+                unsigned_payload = True
+            else:
+                raise NotImplementedError(
+                    "Currently we don't support signed chunked payloads, so buffer the body and "
+                    "pass bytes as a workaround; chunked signed implementation coming soon"
+                )
+        return sign_sigv4(
+            req, ctx, unsigned_payload=unsigned_payload, event_stream=self._event_stream
+        )
+
+    def sign(self, req: Request) -> Request:
+        creds = self.provider.resolve_identity()
+        ctx: SigV4AuthContext = {
+            "type": "sig_v4",
+            "access_key_id": creds["access_key"],
+            "secret_access_key": creds["secret_key"],
+            "session_token": creds.get("session_token"),
+            "signing_region": self._auth_scheme["signingRegion"],
+            "signing_name": self._auth_scheme["signingName"],
+            "disable_double_encoding": self._auth_scheme.get(
+                "disableDoubleEncoding", False
+            ),
+            "disable_normalize_path": self._auth_scheme.get(
+                "disableNormalizePath", False
+            ),
+        }
+        unsigned_payload = self._unsigned_payload
+        if (
+            not unsigned_payload
+            and not self._event_stream
+            and req.body is not None
+            and not isinstance(req.body, bytes)
+        ):
+            if self._auth_scheme["signingName"] in S3_SIGNING_NAMES:
+                # S3 accepts UNSIGNED-PAYLOAD for any operation; streamed bodies rely on it.
+                unsigned_payload = True
+            else:
+                raise NotImplementedError(
+                    "Currently we don't support signed chunked payloads, so buffer the body and "
+                    "pass bytes as a workaround; chunked signed implementation coming soon"
+                )
+        return sign_sigv4(
+            req, ctx, unsigned_payload=unsigned_payload, event_stream=self._event_stream
+        )