spot-sdk-python 1.0.0__py3-none-any.whl

spot_sdk/results.py

@@ -0,0 +1,129 @@
+"""Analysis result models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from .analyzer import ThreatLevel
+
+
+class IndicatorType(str, Enum):
+    """Types of phishing indicators."""
+
+    SUSPICIOUS_SENDER = "suspicious_sender"
+    URGENT_LANGUAGE = "urgent_language"
+    SUSPICIOUS_LINKS = "suspicious_links"
+    MALICIOUS_ATTACHMENT = "malicious_attachment"
+    SOCIAL_ENGINEERING = "social_engineering"
+    DOMAIN_SPOOFING = "domain_spoofing"
+    CREDENTIAL_HARVESTING = "credential_harvesting"
+    WIRE_TRANSFER_SCAM = "wire_transfer_scam"
+    CEO_FRAUD = "ceo_fraud"
+    INVOICE_SCAM = "invoice_scam"
+    IMPERSONATION = "impersonation"
+    SPELLING_GRAMMAR_ERRORS = "spelling_grammar_errors"
+    GENERIC_GREETING = "generic_greeting"
+    MISMATCHED_URL = "mismatched_url"
+    SUSPICIOUS_TIMING = "suspicious_timing"
+    MISP_IOC_MATCH = "misp_ioc_match"
+    DOMAIN_REPUTATION = "domain_reputation"
+    CONTEXT_MISMATCH = "context_mismatch"
+    SPF_FAILURE = "spf_failure"
+    UNUSUAL_HEADERS = "unusual_headers"
+    ENCODING_ANOMALY = "encoding_anomaly"
+    THREATENING_TONE = "threatening_tone"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class AnalysisIndicator(BaseModel):
+    """Individual phishing indicator found in email."""
+
+    type: IndicatorType
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    description: str
+    evidence: str | None = None  # Text excerpt or specific evidence
+    severity: str = Field(..., pattern="^(undetermined|low|medium|high|critical)$")
+
+    # Optional: location in email where indicator was found
+    location: str | None = None  # "subject", "body", "attachment", "headers"
+
+
+class AnalysisMetadata(BaseModel):
+    """Analysis execution metadata."""
+
+    analyzer_id: str
+    analyzer_version: str
+    analysis_duration_ms: int
+    model_version: str | None = None
+    language_detected: str | None = None
+    processing_timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+    # Resource usage (optional)
+    memory_usage_mb: int | None = None
+    cpu_usage_ms: int | None = None
+
+
+class AnalysisResult(BaseModel):
+    """
+    Standardized analysis result from any analyzer.
+
+    This is the common format returned by all analyzers,
+    enabling consistent processing by the orchestrator.
+    """
+
+    # Core classification
+    is_phishing: bool
+    threat_level: ThreatLevel
+    confidence: float = Field(..., ge=0.0, le=1.0)
+
+    # Detailed findings
+    indicators: list[AnalysisIndicator] = Field(default_factory=list)
+    explanation: str = ""  # Human-readable explanation
+
+    # Metadata
+    metadata: AnalysisMetadata
+
+    # Optional: raw analyzer output for debugging
+    raw_output: dict[str, Any] | None = None
+
+    # Additional context
+    recommendations: list[str] = Field(default_factory=list)
+    false_positive_likelihood: float | None = Field(None, ge=0.0, le=1.0)
+
+    @field_validator("threat_level")
+    @classmethod
+    def validate_threat_consistency(cls, v: str, info: Any) -> str:
+        """Ensure threat level is consistent with is_phishing."""
+        is_phishing = info.data.get("is_phishing")
+        if is_phishing and v == ThreatLevel.SAFE:
+            raise ValueError("Cannot have 'safe' threat level when is_phishing=True")
+        if not is_phishing and v in (ThreatLevel.HIGH, ThreatLevel.CRITICAL):
+            raise ValueError("High/critical threat levels require is_phishing=True")
+        return v
+
+    @property
+    def risk_score(self) -> int:
+        """Calculate numerical risk score (0-100)."""
+        base_score = int(self.confidence * 100)
+
+        # Adjust based on threat level
+        multipliers = {
+            ThreatLevel.SAFE: 0.0,
+            ThreatLevel.LOW: 0.3,
+            ThreatLevel.MEDIUM: 0.6,
+            ThreatLevel.HIGH: 0.8,
+            ThreatLevel.CRITICAL: 1.0,
+        }
+
+        return int(base_score * multipliers.get(self.threat_level, 0.5))
+
+    @property
+    def high_confidence_indicators(self) -> list[AnalysisIndicator]:
+        """Get indicators with confidence > 0.7."""
+        return [ind for ind in self.indicators if ind.confidence > 0.7]

spot_sdk/settings_schema.py

@@ -0,0 +1,56 @@
+"""Analyzer settings schema endpoint registration.
+
+Provides a helper to register a /settings/schema endpoint on any analyzer's
+FastAPI app. The endpoint returns the JSON Schema of the analyzer's Pydantic
+Settings model, which the platform uses to render typed configuration forms.
+
+Usage in an analyzer's main.py:
+
+    from spot_sdk.settings_schema import register_settings_schema
+    from .config import Settings
+
+    app = FastAPI(...)
+    register_settings_schema(app, Settings)
+"""
+
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+
+def register_settings_schema(app: FastAPI, settings_class: type[BaseSettings]) -> None:
+    """Register /settings/schema and /settings/values endpoints on a FastAPI app.
+
+    Args:
+        app: FastAPI application instance.
+        settings_class: The Pydantic BaseSettings class used by the analyzer.
+    """
+
+    @app.get("/settings/schema")
+    async def get_settings_schema() -> dict[str, Any]:
+        """Return JSON Schema for this analyzer's settings.
+
+        The schema includes field types, defaults, constraints (min/max),
+        and descriptions. The platform uses this to render typed forms
+        in the web dashboard.
+        """
+        return settings_class.model_json_schema()
+
+    @app.get("/settings/values")
+    async def get_settings_values() -> dict[str, Any]:
+        """Return current effective settings values.
+
+        Useful for debugging to see what values the analyzer is running with.
+        Sensitive fields (containing 'key', 'secret', 'password', 'token')
+        are redacted.
+        """
+        instance = settings_class()
+        values = instance.model_dump()
+
+        for key in list(values.keys()):
+            if any(s in key.lower() for s in ("key", "secret", "password", "token")):
+                if values[key]:
+                    values[key] = "[REDACTED]"
+
+        return values

spot_sdk/testing/README.md

@@ -0,0 +1,83 @@
+# SPOT SDK Testing Utilities
+
+Shared test utilities for all SPOT projects (platform and analyzers).
+
+## Installation
+
+The testing module is included with spot-sdk:
+
+```python
+from spot_sdk.testing import (
+    create_test_email,
+    create_phishing_email,
+    create_test_analysis_result,
+    create_test_indicator,
+)
+```
+
+## Usage
+
+### Creating Test Emails
+
+```python
+# Create a legitimate email
+email = create_test_email(
+    subject="Meeting Tomorrow",
+    sender="alice@company.com",
+    recipients=["team@company.com"],
+    body_text="Don't forget our meeting."
+)
+
+# Create a phishing email with common indicators
+phishing_email = create_phishing_email()
+```
+
+### Creating Test Analysis Results
+
+```python
+# Create a safe analysis result
+result = create_test_analysis_result(
+    is_phishing=False,
+    confidence=0.9,
+    threat_level="SAFE"
+)
+
+# Create a phishing detection result
+phishing_result = create_test_analysis_result(
+    is_phishing=True,
+    confidence=0.95,
+    threat_level="HIGH",
+    indicators=[
+        create_test_indicator(
+            indicator_type="URGENT_LANGUAGE",
+            description="Urgent language detected",
+            severity="high",
+            confidence=0.9
+        )
+    ]
+)
+```
+
+## In pytest
+
+Use these factories in your conftest.py:
+
+```python
+import pytest
+from spot_sdk.testing import create_test_email, create_phishing_email
+
+@pytest.fixture
+def sample_email():
+    return create_test_email()
+
+@pytest.fixture
+def phishing_email():
+    return create_phishing_email()
+```
+
+## Design Philosophy
+
+- **Simple**: Plain dictionaries, not complex mocks
+- **Practical**: Real test data that works with actual SDK models
+- **Flexible**: Easy to customize for specific test cases
+- **No magic**: No auto-mocking or complex test frameworks

spot_sdk/testing/__init__.py

@@ -0,0 +1,22 @@
+"""SPOT SDK Testing Utilities.
+
+Shared test fixtures, factories, and utilities for all SPOT projects.
+"""
+
+from .factories import (
+    create_analysis_request,
+    create_phishing_email,
+    create_test_analysis_result,
+    create_test_email,
+    create_test_indicator,
+    create_test_user,
+)
+
+__all__ = [
+    "create_test_email",
+    "create_phishing_email",
+    "create_test_analysis_result",
+    "create_test_indicator",
+    "create_analysis_request",
+    "create_test_user",
+]

spot_sdk/testing/factories.py

@@ -0,0 +1,177 @@
+"""Test data factories for SPOT SDK.
+
+Simple functions to create test data as plain dictionaries.
+These work with spot_sdk models when validated via Pydantic.
+"""
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def create_test_email(
+    subject: str = "Team Meeting Tomorrow",
+    sender: str = "alice@company.com",
+    recipients: list[str] | None = None,
+    body_text: str = "Hi team, don't forget about our meeting tomorrow.",
+) -> dict[str, Any]:
+    """Create a legitimate test email.
+
+    Args:
+        subject: Email subject
+        sender: Sender email address
+        recipients: List of recipient addresses
+        body_text: Email body text
+
+    Returns:
+        Email data dictionary
+    """
+    if recipients is None:
+        recipients = ["team@company.com"]
+
+    return {
+        "id": "test-email-123",
+        "headers": {
+            "message_id": "<test@test.com>",
+            "subject": subject,
+            "sender": sender,
+            "recipients": recipients,
+            "date": datetime.now(timezone.utc).isoformat(),
+        },
+        "body_text": body_text,
+        "body_html": None,
+        "attachments": [],
+        "received_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def create_phishing_email() -> dict[str, Any]:
+    """Create a phishing test email with common phishing indicators.
+
+    Returns:
+        Email data dictionary with phishing characteristics
+    """
+    return {
+        "id": "phishing-email-456",
+        "headers": {
+            "message_id": "<phish@evil.com>",
+            "subject": "URGENT: Verify Your Account Now!",
+            "sender": "security@paypal-verify.com",
+            "recipients": ["victim@company.com"],
+            "date": datetime.now(timezone.utc).isoformat(),
+        },
+        "body_text": (
+            "Your account has been suspended due to suspicious activity. "
+            "Click here immediately to verify: http://bit.ly/fake-link"
+        ),
+        "body_html": None,
+        "attachments": [],
+        "received_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def create_test_indicator(
+    indicator_type: str = "URGENT_LANGUAGE",
+    description: str = "Urgent language detected",
+    severity: str = "medium",
+    confidence: float = 0.8,
+) -> dict[str, Any]:
+    """Create a test analysis indicator.
+
+    Args:
+        indicator_type: Type of indicator
+        description: Human-readable description
+        severity: Severity level (low, medium, high)
+        confidence: Confidence score (0.0-1.0)
+
+    Returns:
+        Indicator data dictionary
+    """
+    return {
+        "type": indicator_type,
+        "description": description,
+        "severity": severity,
+        "confidence": confidence,
+        "source_analyzer": "test-analyzer",
+    }
+
+
+def create_test_analysis_result(
+    is_phishing: bool = False,
+    confidence: float = 0.9,
+    threat_level: str = "SAFE",
+    indicators: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Create a test analysis result.
+
+    Args:
+        is_phishing: Whether email is classified as phishing
+        confidence: Confidence score (0.0-1.0)
+        threat_level: Threat level (SAFE, LOW, MEDIUM, HIGH, CRITICAL)
+        indicators: List of indicators (created if None)
+
+    Returns:
+        Analysis result data dictionary
+    """
+    if indicators is None:
+        indicators = []
+        if is_phishing:
+            indicators.append(create_test_indicator())
+
+    return {
+        "is_phishing": is_phishing,
+        "confidence": confidence,
+        "threat_level": threat_level,
+        "indicators": indicators,
+        "metadata": {
+            "analyzer_id": "test-analyzer",
+            "analyzer_version": "1.0.0",
+            "analysis_timestamp": datetime.now(timezone.utc).isoformat(),
+            "processing_time_ms": 100,
+        },
+        "explanation": "Test analysis result",
+        "raw_output": {},
+    }
+
+
+def create_analysis_request(
+    email: dict[str, Any] | None = None,
+    workflow_id: str = "default-workflow",
+) -> dict[str, Any]:
+    """Create an analysis request.
+
+    Args:
+        email: Email data dictionary (created if None)
+        workflow_id: Workflow ID to use
+
+    Returns:
+        Analysis request dictionary
+    """
+    return {
+        "email": email or create_test_email(),
+        "workflow_id": workflow_id,
+    }
+
+
+def create_test_user(
+    username: str = "testuser",
+    email: str = "testuser@test.com",
+    is_active: bool = True,
+    is_superuser: bool = False,
+) -> dict[str, Any]:
+    """Create test user data.
+
+    Args:
+        username: Username
+        email: Email address
+        is_active: Whether user is active
+        is_superuser: Whether user is superuser
+
+    Returns:
+        User data dictionary
+    """
+    return {
+        "username": username,
+        "email": email,
+        "is_active": is_active,
+        "is_superuser": is_superuser,
+    }

spot_sdk/testing/fake_knowledge_client.py

@@ -0,0 +1,105 @@
+"""In-memory fake of :class:`spot_sdk.knowledge.KnowledgeClient` for tests.
+
+No HTTP, no embedding, no vector math — just a dict keyed by ``id``
+that supports the same upsert/fetch/delete methods. ``fetch()`` does
+naive substring matching over content + tag-expression filtering, which
+is enough for plugin unit tests to assert that an analyzer reads
+documents out of the store.
+
+Usage::
+
+    from spot_sdk.testing.fake_knowledge_client import FakeKnowledgeClient
+
+    kb = FakeKnowledgeClient()
+    await kb.upsert(KnowledgeDocument(id="...", content="...", tags=[...]))
+    docs = await kb.fetch(text="alice", tags="employee")
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..knowledge import KnowledgeDocument
+
+
+class FakeKnowledgeClient:
+    """In-memory fake compatible with :class:`KnowledgeClient`."""
+
+    def __init__(self, retrieval_limits: dict[str, Any] | None = None) -> None:
+        self._docs: dict[str, KnowledgeDocument] = {}
+        self._limits = dict(retrieval_limits or {})
+
+    # --- write side ---------------------------------------------------- #
+
+    async def upsert(self, doc: KnowledgeDocument) -> None:
+        self._docs[doc.id] = doc
+
+    async def bulk_upsert(self, docs: list[KnowledgeDocument]) -> None:
+        for d in docs:
+            self._docs[d.id] = d
+
+    async def delete(self, doc_id: str) -> None:
+        self._docs.pop(doc_id, None)
+
+    # --- read side ----------------------------------------------------- #
+
+    async def fetch(
+        self,
+        tags: str | None = None,
+        text: str | None = None,
+        top_k: int = 5,
+        min_score: float = 0.0,
+        strategy: str = "similarity",
+    ) -> list[KnowledgeDocument]:
+        if text is None or not text.strip():
+            raise ValueError("fetch() requires a non-empty 'text' argument")
+
+        # Apply caps
+        max_top_k = self._limits.get("max_top_k")
+        if max_top_k is not None and top_k > max_top_k:
+            top_k = max_top_k
+        floor = self._limits.get("min_score_floor")
+        if floor is not None and min_score < floor:
+            min_score = floor
+
+        # Tag filter
+        candidates = list(self._docs.values())
+        if tags:
+            candidates = [d for d in candidates if _match_tag_expr(d.tags, tags)]
+
+        # Scored by naive substring overlap (good enough for tests)
+        terms = [t for t in re.split(r"\s+", text.lower()) if t]
+        scored: list[tuple[float, KnowledgeDocument]] = []
+        for d in candidates:
+            content_lower = d.content.lower()
+            hits = sum(1 for t in terms if t in content_lower)
+            score = hits / max(len(terms), 1)
+            if score >= min_score:
+                scored.append((score, d.model_copy(update={"score": score})))
+
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [d for _, d in scored[:top_k]]
+
+    # --- test helpers -------------------------------------------------- #
+
+    def all(self) -> list[KnowledgeDocument]:
+        """Return all stored documents (test helper)."""
+        return list(self._docs.values())
+
+    def clear(self) -> None:
+        """Remove all stored documents (test helper)."""
+        self._docs.clear()
+
+
+# Same tiny tag-expression evaluator used by the real store.
+# Grammar: term (op term)*  where op is '+' (AND) or '|' (OR).
+# AND binds tighter than OR; no parentheses.
+def _match_tag_expr(doc_tags: list[str], expr: str) -> bool:
+    tag_set = set(doc_tags)
+    or_groups = expr.split("|")
+    for group in or_groups:
+        and_terms = [t.strip() for t in group.split("+") if t.strip()]
+        if and_terms and all(t in tag_set for t in and_terms):
+            return True
+    return False

spot_sdk/threat_levels.py

@@ -0,0 +1,33 @@
+"""Standardized threat level computation for SPOT analyzers."""
+
+from .analyzer import ThreatLevel
+
+
+def confidence_to_threat_level(
+    confidence: float,
+    *,
+    high: float = 0.8,
+    medium: float = 0.5,
+    low: float = 0.2,
+) -> ThreatLevel:
+    """Map a confidence score to a ThreatLevel.
+
+    Uses consistent default thresholds across all analyzers.
+    Individual analyzers can override thresholds via keyword arguments.
+
+    Args:
+        confidence: Confidence score in [0.0, 1.0].
+        high: Threshold for HIGH (default 0.8).
+        medium: Threshold for MEDIUM (default 0.5).
+        low: Threshold for LOW (default 0.2).
+
+    Returns:
+        The corresponding ThreatLevel.
+    """
+    if confidence >= high:
+        return ThreatLevel.HIGH
+    if confidence >= medium:
+        return ThreatLevel.MEDIUM
+    if confidence >= low:
+        return ThreatLevel.LOW
+    return ThreatLevel.SAFE