clue-api 1.0.0.dev7__py3-none-any.whl

clue/models/results/graph.py

@@ -0,0 +1,26 @@
+from typing import override
+
+from pydantic import Field
+
+from clue.models.graph import BaseGraphModel, Metadata, Node
+from clue.models.results.base import Result
+
+
+class GraphResult(BaseGraphModel, Result):
+    "A result describing a graph that should be returned"
+
+    @override
+    @staticmethod
+    def format():
+        "Return the clue format for this result"
+        return "graph"
+
+    id: str = Field(description="An ID for this generated graph.")
+    metadata: Metadata = Metadata()
+    data: list[list[Node]] = Field(
+        description=(
+            "A list of lists of nodes to render. The outer list breaks the nodes into columns, "
+            "while the inner list breaks the nodes into rows."
+        )
+    )
+    # related: dict[str, str] = Field(description="A dictionary of other related graphs.")

clue/models/results/image.py

@@ -0,0 +1,22 @@
+# ruff: noqa: D101
+
+
+from pydantic import Field
+
+from clue.common.logging import get_logger
+from clue.models.results.base import Result
+
+logger = get_logger(__file__)
+
+
+class ImageResult(Result):
+    @staticmethod
+    def format():
+        "Return the clue format for this result"
+        return "image"
+
+    image: str = Field(
+        description="An image URL, either redirecting to a valid network location or encoded image data in "
+        "base64 format."
+    )
+    alt: str = Field(description="The label for the image.")

clue/models/results/status.py

@@ -0,0 +1,55 @@
+import os
+import re
+from typing import Self
+
+from pydantic import BaseModel, Field, model_validator
+from pydantic_core import Url
+
+from clue.common.exceptions import ClueValueError
+from clue.common.logging import get_logger
+from clue.models.results.base import Result
+
+logger = get_logger(__file__)
+
+
+class StatusLabel(BaseModel):
+    "Labels for the status, tied to s specific localization"
+
+    language: str = Field(description="Localization language for this label (i.e., en, fr)")
+    label: str = Field(description="The localized label text.")
+
+
+class StatusResult(Result):
+    "Information about the status of a selector"
+
+    @staticmethod
+    def format():
+        "Return the clue format for this result"
+        return "status"
+
+    empty: bool = Field(
+        description="Is this status empty (i.e., if there's no applicable status result)?", default=False
+    )
+    labels: list[StatusLabel] = Field(description="A list of status labels in various languages", default=[])
+    link: Url | None = Field(description="An optional link for more information", default=None)
+    icon: str | None = Field(description="An optional icon to style the status", default=None)
+    color: str | None = Field(description="An optional hexadecimal colour to style the status", default=None)
+
+    @model_validator(mode="after")
+    def validate_model(self: Self) -> Self:
+        "Ensure the model has correct localizations, and the color is a valid hex string"
+        if self.empty:
+            return self
+
+        for language in os.environ.get("LOCALIZATION_LANGUAGES", "en,fr").split(","):
+            if not language:
+                continue
+
+            if not any(label.language == language for label in self.labels):
+                raise ClueValueError(f"Status is missing a localized result for the localization '{language}'")
+
+        if self.color:
+            if not re.match(r"^#[0-9a-f]{6}$", self.color, re.IGNORECASE):
+                raise ClueValueError("Invalid hex color value provided. Shorthand colors are not supported.")
+
+        return self

clue/models/results/validation.py

@@ -0,0 +1,57 @@
+import json
+from typing import cast
+
+from pydantic import BaseModel, ValidationInfo
+
+from clue.common.exceptions import ClueValueError
+from clue.common.logging import get_logger
+from clue.models.results import DATA, FORMAT_MAPPINGS, FORMAT_MAPPINGS_REVERSE
+
+logger = get_logger(__file__)
+
+
+def validate_result(_format: str, data: DATA | None, info: ValidationInfo) -> DATA | None:  # noqa: C901
+    "Validate a result in a model"
+    if isinstance(data, BaseModel) and data.__class__ in FORMAT_MAPPINGS:
+        expected_format = FORMAT_MAPPINGS[data.__class__]
+        if expected_format != _format:
+            raise ClueValueError(
+                f"Format should be {expected_format} if data is of type {data.__class__.__name__}, "
+                f"but is set to {_format}"
+            )
+
+    if _format in FORMAT_MAPPINGS_REVERSE and not any(
+        isinstance(data, _type) for _type in FORMAT_MAPPINGS_REVERSE[_format]
+    ):
+        resolved = False
+        for expected_type in FORMAT_MAPPINGS_REVERSE[_format]:
+            if info.context and info.context.get("is_response", False) and issubclass(expected_type, BaseModel):
+                data = cast(DATA, cast(BaseModel, expected_type).model_validate(data))
+                resolved = True
+            elif _format == "json" and isinstance(data, str):
+                data = json.loads(data)
+                resolved = True
+            elif _format == "json" and isinstance(data, BaseModel):
+                data = cast(DATA, data.model_dump(mode="json", exclude_none=True))
+                resolved = True
+
+            if resolved:
+                break
+
+        if not resolved:
+            raise ClueValueError(
+                f"data should be of type {getattr(expected_type, '__name__', str(expected_type))}, "
+                f"but is set to {data.__class__.__name__}"
+            )
+
+    if _format == "graph" and isinstance(data, BaseModel):
+        data = cast(DATA, data.model_dump(mode="json", exclude_none=True, by_alias=True))
+
+    if _format == "json":
+        try:
+            json.dumps(data)
+        except Exception:
+            logger.exception("Exception on serialization")
+            raise ClueValueError("Data is not JSON serializable, or is not valid JSON.")
+
+    return data

clue/models/selector.py

@@ -0,0 +1,67 @@
+# ruff: noqa: D101
+import ipaddress
+import json
+
+from flask import request
+from pydantic import BaseModel, Field, model_validator
+from typing_extensions import Self
+
+from clue.common.logging import get_logger
+from clue.config import CLASSIFICATION
+from clue.constants.supported_types import CASE_INSENSITIVE_TYPES
+
+logger = get_logger(__file__)
+
+
+class Selector(BaseModel):
+    type: str
+    value: str
+    classification: str | None = Field(default=None)
+    sources: list[str] | None = Field(default=None)
+
+    @model_validator(mode="after")
+    def validate_model(self: Self) -> Self:  # noqa: C901
+        """Validates the entire model.
+
+        Raises:
+            AssertionError: Raised whenever a field is invalid on the model.
+
+        Returns:
+            Self: The validated model.
+        """
+        # For backwards compatability, if eml is used it is replaced with email
+        self.type = self.type.replace("eml", "email")
+
+        if self.type == "ip":
+            is_ipv4 = isinstance(ipaddress.ip_address(self.value), ipaddress.IPv4Address)
+            self.type = "ipv4" if is_ipv4 else "ipv6"
+
+        if self.type == "telemetry":
+            try:
+                json.loads(self.value)
+            except json.JSONDecodeError as e:
+                raise AssertionError("If type is telemetry, value must be a valid JSON object.") from e
+
+        if self.type in CASE_INSENSITIVE_TYPES:
+            self.value = self.value.lower()
+
+        if not self.classification:
+            try:
+                self.classification = request.args.get("classification", CLASSIFICATION.UNRESTRICTED)
+            except RuntimeError:
+                pass
+
+        if self.sources is None:
+            try:
+                if query_sources_str := request.args.get("sources", None):
+                    if "|" in query_sources_str:
+                        self.sources = query_sources_str.split("|")
+                    else:
+                        self.sources = query_sources_str.split(",")
+            except RuntimeError:
+                pass
+
+        return self
+
+
+BulkEnrich = Selector

clue/models/utils.py

@@ -0,0 +1,52 @@
+import random
+from datetime import datetime
+from typing import Union, get_args, get_origin
+
+from pydantic import BaseModel
+from pydantic_core import Url
+
+
+def generate_example_model(model: type[BaseModel], as_list: bool = False):  # noqa: C901
+    """Populate fields with example values"""
+    result = {}
+
+    if as_list:
+        full_list = []
+        for _ in range(random.randint(1, 3)):  # noqa: S311
+            full_list.append(generate_example_model(model))
+
+        return full_list
+
+    for name, field_info in model.model_fields.items():
+        field_type = field_info.annotation
+        if field_type:
+            if get_origin(field_type) is Union and type(None) in get_args(field_type):
+                field_type = (
+                    next((_type for _type in get_args(field_type) if _type is not type(None)), None) or field_type
+                )
+
+        _as_list = False
+        if get_origin(field_type) is list:
+            _as_list = True
+            field_type = get_args(field_type)[0]
+
+        _issubclass = False
+        try:
+            if field_type:
+                _issubclass = issubclass(field_type, BaseModel)
+        except TypeError:
+            pass
+
+        if field_type and _issubclass:
+            result[name] = generate_example_model(field_type, as_list=_as_list)
+        elif field_info.examples:
+            result[name] = random.choice(field_info.examples)  # noqa: S311
+        elif field_info.default:
+            result[name] = field_info.default
+
+        if isinstance(result[name], datetime):
+            result[name] = result[name].isoformat()
+        elif isinstance(result[name], Url):
+            result[name] = str(result[name])
+
+    return dict(result)

clue/models/validators.py

@@ -0,0 +1,19 @@
+from clue.config import CLASSIFICATION
+
+
+def validate_classification(classification: str):
+    """Validates the provided classification.
+
+    Args:
+        classification (str): The classification to validate.
+
+    Raises:
+        AssertionError: Raised whenever the provided classification is not valid.
+
+    Returns:
+        str: The validated classification.
+    """
+    if not CLASSIFICATION.is_valid(classification):
+        raise AssertionError(f"{classification} is not a valid classification.")
+
+    return classification

clue/patched.py

@@ -0,0 +1,8 @@
+from gevent.monkey import patch_all
+
+patch_all()
+
+from clue.app import app, main  # noqa: F401, E402
+
+if __name__ == "__main__":
+    main()