pangea-sdk 3.8.0b1__py3-none-any.whl → 3.8.0b3__py3-none-any.whl

pangea/services/authz.py

@@ -0,0 +1,377 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+
+import enum
+from typing import Any, Dict, List, Optional, Union
+
+from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
+from pangea.services.base import ServiceBase
+
+
+class ItemOrder(str, enum.Enum):
+    ASC = "asc"
+    DESC = "desc"
+
+    def __str__(self):
+        return str(self.value)
+
+    def __repr__(self):
+        return str(self.value)
+
+
+class TupleOrderBy(str, enum.Enum):
+    RESOURCE_NAMESPACE = "resource_namespace"
+    RESOURCE_ID = "resource_id"
+    RELATION = "relation"
+    SUBJECT_NAMESPACE = "subject_namespace"
+    SUBJECT_ID = "subject_id"
+    SUBJECT_ACTION = "subject_action"
+
+    def __str__(self):
+        return str(self.value)
+
+    def __repr__(self):
+        return str(self.value)
+
+
+class Resource(PangeaResponseResult):
+    namespace: str
+    id: Optional[str] = None
+
+
+class Subject(PangeaResponseResult):
+    namespace: str
+    id: Optional[str] = None
+    action: Optional[str] = None
+
+
+class Tuple(PangeaResponseResult):
+    resource: Resource
+    relation: str
+    subject: Subject
+
+
+class TupleCreateRequest(APIRequestModel):
+    tuples: List[Tuple]
+
+
+class TupleCreateResult(PangeaResponseResult):
+    pass
+
+
+class TupleListFilter(APIRequestModel):
+    resource_namespace: Optional[str] = None
+    resource_namespace__contains: Optional[List[str]] = None
+    resource_namespace__in: Optional[List[str]] = None
+    resource_id: Optional[str] = None
+    resource_id__contains: Optional[List[str]] = None
+    resource_id__in: Optional[List[str]] = None
+    relation: Optional[str] = None
+    relation__contains: Optional[List[str]] = None
+    relation__in: Optional[List[str]] = None
+    subject_namespace: Optional[str] = None
+    subject_namespace__contains: Optional[List[str]] = None
+    subject_namespace__in: Optional[List[str]] = None
+    subject_id: Optional[str] = None
+    subject_id__contains: Optional[List[str]] = None
+    subject_id__in: Optional[List[str]] = None
+    subject_action: Optional[str] = None
+    subject_action__contains: Optional[List[str]] = None
+    subject_action__in: Optional[List[str]] = None
+
+
+class TupleListRequest(APIRequestModel):
+    filter: Optional[Union[Dict, TupleListFilter]] = None
+    size: Optional[int] = None
+    last: Optional[str] = None
+    order: Optional[ItemOrder] = None
+    order_by: Optional[TupleOrderBy] = None
+
+
+class TupleListResult(PangeaResponseResult):
+    tuples: List[Tuple]
+    last: str
+    count: int
+
+
+class TupleDeleteRequest(APIRequestModel):
+    tuples: List[Tuple]
+
+
+class TupleDeleteResult(PangeaResponseResult):
+    pass
+
+
+class CheckRequest(APIRequestModel):
+    resource: Resource
+    action: str
+    subject: Subject
+    debug: Optional[bool] = None
+    attributes: Optional[Dict[str, Any]] = None
+
+
+class DebugPath(APIResponseModel):
+    namespace: str
+    id: str
+    action: Optional[str]
+
+
+class Debug(APIResponseModel):
+    path: List[DebugPath]
+
+
+class CheckResult(PangeaResponseResult):
+    schema_id: str
+    schema_version: int
+    depth: int
+    allowed: bool
+    debug: Optional[Debug] = None
+
+
+class ListResourcesRequest(APIRequestModel):
+    namespace: str
+    action: str
+    subject: Subject
+
+
+class ListResourcesResult(PangeaResponseResult):
+    ids: List[str]
+
+
+class ListSubjectsRequest(APIRequestModel):
+    resource: Resource
+    action: str
+
+
+class ListSubjectsResult(PangeaResponseResult):
+    subjects: List[Subject]
+
+
+class AuthZ(ServiceBase):
+    """AuthZ service client. (Beta)
+
+    Provides methods to interact with the Pangea AuthZ Service.
+    Documentation for the AuthZ Service API can be found at
+    <https://pangea.cloud/docs/api/authz>. Note that this service is in Beta and
+    is subject to change.
+
+    Examples:
+        import os
+        from pangea.config import PangeaConfig
+        from pangea.services import AuthZ
+
+        PANGEA_TOKEN = os.getenv("PANGEA_AUTHZ_TOKEN")
+
+        authz_config = PangeaConfig(domain="aws.us.pangea.cloud")
+
+        # Setup Pangea AuthZ service client
+        authz = AuthZ(token=PANGEA_TOKEN, config=authz_config)
+    """
+
+    service_name = "authz"
+
+    def __init__(self, token: str, config=None, logger_name="pangea", config_id: Optional[str] = None):
+        super().__init__(token, config, logger_name, config_id=config_id)
+
+    def tuple_create(self, tuples: List[Tuple]) -> PangeaResponse[TupleCreateResult]:
+        """Create tuples. (Beta)
+
+        Create tuples in the AuthZ Service. The request will fail if there is no schema
+        or the tuples do not validate against the schema.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            tuples (List[Tuple]): List of tuples to be created.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with empty result.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/tuple/create).
+
+        Examples:
+            response = authz.tuple_create(
+                tuples=[
+                    Tuple(
+                        resource=Resource(namespace="file", id="file_1"),
+                        relation="owner",
+                        subject=Subject(namespace="user", id="user_1"),
+                    )
+                ]
+            )
+        """
+
+        input_data = TupleCreateRequest(tuples=tuples)
+        return self.request.post("v1beta/tuple/create", TupleCreateResult, data=input_data.dict(exclude_none=True))
+
+    def tuple_list(
+        self,
+        filter: TupleListFilter,
+        size: Optional[int] = None,
+        last: Optional[str] = None,
+        order: Optional[ItemOrder] = None,
+        order_by: Optional[TupleOrderBy] = None,
+    ) -> PangeaResponse[TupleListResult]:
+        """List tuples. (Beta)
+
+        Return a paginated list of filtered tuples. The filter is given in terms
+        of a tuple. Fill out the fields that you want to filter. If the filter
+        is empty it will return all the tuples.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            filter (TupleListFilter): The filter for listing tuples.
+            size (Optional[int]): The size of the result set. Default is None.
+            last (Optional[str]): The last token from a previous response. Default is None.
+            order (Optional[ItemOrder]): Order results asc(ending) or desc(ending).
+            order_by (Optional[TupleOrderBy]): Which field to order results by.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of tuples and the last token.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/tuple/list).
+
+        Examples:
+            authz.tuple_list(TupleListFilter(subject_namespace="user", subject_id="user_1"))
+        """
+        input_data = TupleListRequest(
+            filter=filter.dict(exclude_none=True), size=size, last=last, order=order, order_by=order_by
+        )
+        return self.request.post("v1beta/tuple/list", TupleListResult, data=input_data.dict(exclude_none=True))
+
+    def tuple_delete(self, tuples: List[Tuple]) -> PangeaResponse[TupleDeleteResult]:
+        """Delete tuples. (Beta)
+
+        Delete tuples in the AuthZ Service.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            tuples (List[Tuple]): List of tuples to be deleted.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with empty result.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/tuple/delete).
+
+        Examples:
+            response = authz.tuple_delete(
+                tuples=[
+                    Tuple(
+                        resource=Resource(namespace="file", id="file_1"),
+                        relation="owner",
+                        subject=Subject(namespace="user", id="user_1"),
+                    )
+                ]
+            )
+        """
+
+        input_data = TupleDeleteRequest(tuples=tuples)
+        return self.request.post("v1beta/tuple/delete", TupleDeleteResult, data=input_data.dict(exclude_none=True))
+
+    def check(
+        self,
+        resource: Resource,
+        action: str,
+        subject: Subject,
+        debug: Optional[bool] = None,
+        attributes: Optional[Dict[str, Union[int, str]]] = None,
+    ) -> PangeaResponse[CheckResult]:
+        """Perform a check request. (Beta)
+
+        Check if a subject has permission to perform an action on the resource.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            resource (Resource): The resource to check.
+            action (str): The action to check.
+            subject (Subject): The subject to check.
+            debug (Optional[bool]): Setting this value to True will provide a detailed analysis of the check.
+            attributes (Optional[Dict[str, Union[int, str]]]): Additional attributes for the check.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with the result of the check.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/check).
+
+        Examples:
+            response = authz.check(
+                resource=Resource(namespace="file", id="file_1"),
+                action="update",
+                subject=Subject(namespace="user", id="user_1"),
+                debug=True,
+            )
+        """
+
+        input_data = CheckRequest(resource=resource, action=action, subject=subject, debug=debug, attributes=attributes)
+        return self.request.post("v1beta/check", CheckResult, data=input_data.dict(exclude_none=True))
+
+    def list_resources(self, namespace: str, action: str, subject: Subject) -> PangeaResponse[ListResourcesResult]:
+        """List resources. (Beta)
+
+        Given a namespace, action, and subject, list all the resources in the
+        namespace that the subject has access to the action with.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            namespace (str): The namespace to filter resources.
+            action (str): The action to filter resources.
+            subject (Subject): The subject to filter resources.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of resource IDs.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/list-resources).
+
+        Examples:
+            authz.list_resources(
+                namespace="file",
+                action="update",
+                subject=Subject(namespace="user", id="user_1"),
+            )
+        """
+
+        input_data = ListResourcesRequest(namespace=namespace, action=action, subject=subject)
+        return self.request.post("v1beta/list-resources", ListResourcesResult, data=input_data.dict(exclude_none=True))
+
+    def list_subjects(self, resource: Resource, action: str) -> PangeaResponse[ListSubjectsResult]:
+        """List subjects. (Beta)
+
+        Given a resource and an action, return the list of subjects who have
+        access to the action for the given resource.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            resource (Resource): The resource to filter subjects.
+            action (str): The action to filter subjects.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of subjects.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/list-subjects).
+
+        Examples:
+            response = authz.list_subjects(
+                resource=Resource(namespace="file", id="file_1"),
+                action="update",
+            )
+        """
+
+        input_data = ListSubjectsRequest(resource=resource, action=action)
+        return self.request.post("v1beta/list-subjects", ListSubjectsResult, data=input_data.dict(exclude_none=True))

pangea/services/file_scan.py

@@ -71,7 +71,6 @@ class FileScan(ServiceBase):
     """
 
     service_name = "file-scan"
-    version = "v1"
 
     def file_scan(
         self,

pangea/services/sanitize.py

@@ -0,0 +1,275 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+import io
+from typing import Dict, List, Optional, Tuple
+
+from pangea.response import APIRequestModel, PangeaResponse, PangeaResponseResult, TransferMethod
+from pangea.services.base import ServiceBase
+from pangea.utils import FileUploadParams, get_file_upload_params
+
+
+class SanitizeFile(APIRequestModel):
+    scan_provider: Optional[str] = None
+    """Provider to use for File Scan."""
+
+    cdr_provider: Optional[str] = None
+    """Provider to use for CDR."""
+
+
+class SanitizeContent(APIRequestModel):
+    url_intel: Optional[bool] = None
+    """Perform URL Intel lookup."""
+
+    url_intel_provider: Optional[str] = None
+    """Provider to use for URL Intel."""
+
+    domain_intel: Optional[bool] = None
+    """Perform Domain Intel lookup."""
+
+    domain_intel_provider: Optional[str] = None
+    """Provider to use for Domain Intel lookup."""
+
+    defang: Optional[bool] = None
+    """Defang external links."""
+
+    defang_threshold: Optional[int] = None
+    """Defang risk threshold."""
+
+    redact: Optional[bool] = None
+    """Redact sensitive content."""
+
+    remove_attachments: Optional[bool] = None
+    """Remove file attachments (PDF only)."""
+
+    remove_interactive: Optional[bool] = None
+    """Remove interactive content (PDF only)."""
+
+
+class SanitizeShareOutput(APIRequestModel):
+    enabled: Optional[bool] = None
+    """Store Sanitized files to Pangea Secure Share."""
+
+    output_folder: Optional[str] = None
+    """
+    Store Sanitized files to this Secure Share folder (will be auto-created if
+    it does not exist)
+    """
+
+
+class SanitizeRequest(APIRequestModel):
+    transfer_method: TransferMethod = TransferMethod.POST_URL
+    source_url: Optional[str] = None
+    share_id: Optional[str] = None
+    file: Optional[SanitizeFile] = None
+    content: Optional[SanitizeContent] = None
+    share_output: Optional[SanitizeShareOutput] = None
+    size: Optional[int] = None
+    crc32c: Optional[str] = None
+    sha256: Optional[str] = None
+    uploaded_file_name: Optional[str] = None
+
+
+class DefangData(PangeaResponseResult):
+    external_urls_count: Optional[int] = None
+    external_domains_count: Optional[int] = None
+    defanged_count: Optional[int] = None
+    url_intel_summary: Optional[str] = None
+    domain_intel_summary: Optional[str] = None
+
+
+class RedactData(PangeaResponseResult):
+    redaction_count: Optional[int] = None
+    summary_counts: Dict = {}
+
+
+class CDR(PangeaResponseResult):
+    file_attachments_removed: Optional[int] = None
+    interactive_contents_removed: Optional[int] = None
+
+
+class SanitizeData(PangeaResponseResult):
+    defang: Optional[DefangData] = None
+    redact: Optional[RedactData] = None
+    malicious_file: Optional[bool] = None
+    cdr: Optional[CDR] = None
+
+
+class SanitizeResult(PangeaResponseResult):
+    dest_url: Optional[str] = None
+    dest_share_id: Optional[str] = None
+    data: SanitizeData
+    parameters: Dict = {}
+
+
+class Sanitize(ServiceBase):
+    """Sanitize service client.
+
+    Examples:
+        import os
+
+        # Pangea SDK
+        from pangea.config import PangeaConfig
+        from pangea.services import Sanitize
+
+        PANGEA_SANITIZE_TOKEN = os.getenv("PANGEA_SANITIZE_TOKEN")
+        config = PangeaConfig(domain="pangea.cloud")
+
+        sanitize = Sanitize(token=PANGEA_SANITIZE_TOKEN, config=config)
+    """
+
+    service_name = "sanitize"
+
+    def sanitize(
+        self,
+        transfer_method: TransferMethod = TransferMethod.POST_URL,
+        file_path: Optional[str] = None,
+        file: Optional[io.BufferedReader] = None,
+        source_url: Optional[str] = None,
+        share_id: Optional[str] = None,
+        file_scan: Optional[SanitizeFile] = None,
+        content: Optional[SanitizeContent] = None,
+        share_output: Optional[SanitizeShareOutput] = None,
+        size: Optional[int] = None,
+        crc32c: Optional[str] = None,
+        sha256: Optional[str] = None,
+        uploaded_file_name: Optional[str] = None,
+        sync_call: bool = True,
+    ) -> PangeaResponse[SanitizeResult]:
+        """
+        Sanitize (Beta)
+
+        Apply file sanitization actions according to specified rules.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        OperationId: sanitize_post_v1beta_sanitize
+
+        Args:
+            transfer_method: The transfer method used to upload the file data.
+            file_path: Path to file to sanitize.
+            file: File to sanitize.
+            source_url: A URL where the file to be sanitized can be downloaded.
+            share_id: A Pangea Secure Share ID where the file to be sanitized is stored.
+            file_scan: Options for File Scan.
+            content: Options for how the file should be sanitized.
+            share_output: Integration with Secure Share.
+            size: The size (in bytes) of the file. If the upload doesn't match, the call will fail.
+            crc32c: The CRC32C hash of the file data, which will be verified by the server if provided.
+            sha256: The hexadecimal-encoded SHA256 hash of the file data, which will be verified by the server if provided.
+            uploaded_file_name: Name of the user-uploaded file, required for `TransferMethod.PUT_URL` and `TransferMethod.POST_URL`.
+            sync_call: Whether or not to poll on HTTP/202.
+
+        Raises:
+            PangeaAPIException: If an API error happens.
+
+        Returns:
+            The sanitized file and information on the sanitization that was
+            performed.
+
+        Examples:
+            with open("/path/to/file.pdf", "rb") as f:
+                response = sanitize.sanitize(
+                    file=f,
+                    transfer_method=TransferMethod.POST_URL,
+                    uploaded_file_name="uploaded_file",
+                )
+        """
+
+        if file or file_path:
+            if file_path:
+                file = open(file_path, "rb")
+            if transfer_method == TransferMethod.POST_URL and (sha256 is None or crc32c is None or size is None):
+                params = get_file_upload_params(file)  # type: ignore[arg-type]
+                crc32c = params.crc_hex if crc32c is None else crc32c
+                sha256 = params.sha256_hex if sha256 is None else sha256
+                size = params.size if size is None else size
+            else:
+                crc32c, sha256, size = None, None, None
+            files: List[Tuple] = [("upload", ("filename", file, "application/octet-stream"))]
+        else:
+            raise ValueError("Need to set file_path or file arguments")
+
+        input = SanitizeRequest(
+            transfer_method=transfer_method,
+            source_url=source_url,
+            share_id=share_id,
+            file=file_scan,
+            content=content,
+            share_output=share_output,
+            crc32c=crc32c,
+            sha256=sha256,
+            size=size,
+            uploaded_file_name=uploaded_file_name,
+        )
+        data = input.dict(exclude_none=True)
+        response = self.request.post("v1beta/sanitize", SanitizeResult, data=data, files=files, poll_result=sync_call)
+        if file_path and file is not None:
+            file.close()
+        return response
+
+    def request_upload_url(
+        self,
+        transfer_method: TransferMethod = TransferMethod.PUT_URL,
+        params: Optional[FileUploadParams] = None,
+        file_scan: Optional[SanitizeFile] = None,
+        content: Optional[SanitizeContent] = None,
+        share_output: Optional[SanitizeShareOutput] = None,
+        size: Optional[int] = None,
+        crc32c: Optional[str] = None,
+        sha256: Optional[str] = None,
+        uploaded_file_name: Optional[str] = None,
+    ) -> PangeaResponse[SanitizeResult]:
+        """
+        Sanitize via presigned URL (Beta)
+
+        Apply file sanitization actions according to specified rules via a
+        [presigned URL](https://pangea.cloud/docs/api/presigned-urls).
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        OperationId: sanitize_post_v1beta_sanitize 2
+
+        Args:
+            transfer_method: The transfer method used to upload the file data.
+            params: File upload parameters.
+            file_scan: Options for File Scan.
+            content: Options for how the file should be sanitized.
+            share_output: Integration with Secure Share.
+            size: The size (in bytes) of the file. If the upload doesn't match, the call will fail.
+            crc32c: The CRC32C hash of the file data, which will be verified by the server if provided.
+            sha256: The hexadecimal-encoded SHA256 hash of the file data, which will be verified by the server if provided.
+            uploaded_file_name: Name of the user-uploaded file, required for `TransferMethod.PUT_URL` and `TransferMethod.POST_URL`.
+
+        Raises:
+            PangeaAPIException: If an API error happens.
+
+        Returns:
+            A presigned URL.
+
+        Examples:
+            presignedUrl = sanitize.request_upload_url(
+                transfer_method=TransferMethod.PUT_URL,
+                uploaded_file_name="uploaded_file",
+            )
+
+            # Upload file to `presignedUrl.accepted_result.put_url`.
+
+            # Poll for Sanitize's result.
+            response: PangeaResponse[SanitizeResult] = sanitize.poll_result(response=presignedUrl)
+        """
+
+        input = SanitizeRequest(
+            transfer_method=transfer_method,
+            file=file_scan,
+            content=content,
+            share_output=share_output,
+            crc32c=crc32c,
+            sha256=sha256,
+            size=size,
+            uploaded_file_name=uploaded_file_name,
+        )
+        if params is not None and (transfer_method == TransferMethod.POST_URL):
+            input.crc32c = params.crc_hex
+            input.sha256 = params.sha256_hex
+            input.size = params.size
+
+        data = input.dict(exclude_none=True)
+        return self.request.request_presigned_url("v1beta/sanitize", SanitizeResult, data=data)