iris-security-openai 0.1.0__py3-none-any.whl

examples/governed_gpt.py

@@ -0,0 +1,61 @@
+"""
+Governed OpenAI — change one line, keep everything else identical.
+
+Requires: pip install iris-openai
+Set IRIS_ENV=dev (default) or production for fail-closed enforcement.
+"""
+
+from __future__ import annotations
+
+from iris import AgentPassport, ComplianceTag, ToolPermission
+from iris_openai import IrisOpenAI
+
+passport = AgentPassport(
+    name="analysis-agent",
+    owner="team@company.com",
+    compliance_tags=[ComplianceTag.COLORADO_AI_ACT],
+    tool_permissions=[
+        ToolPermission(tool_id="search", description="Web search", allowed_actions=["call"]),
+    ],
+)
+
+# One line change from: client = openai.OpenAI()
+client = IrisOpenAI(passport=passport)
+
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Analyze this data."}],
+)
+print(response.choices[0].message.content)
+
+search_tool = {
+    "type": "function",
+    "function": {
+        "name": "search",
+        "description": "Search the web",
+        "parameters": {"type": "object", "properties": {}},
+    },
+}
+payments_tool = {
+    "type": "function",
+    "function": {
+        "name": "payments",
+        "description": "Process payments",
+        "parameters": {"type": "object", "properties": {}},
+    },
+}
+email_tool = {
+    "type": "function",
+    "function": {
+        "name": "email",
+        "description": "Send email",
+        "parameters": {"type": "object", "properties": {}},
+    },
+}
+
+# IRIS filters to permitted tools; payments/email removed if not on passport
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Look up the account."}],
+    tools=[search_tool, payments_tool, email_tool],
+)

iris_openai/__init__.py

@@ -0,0 +1,46 @@
+"""
+IRIS OpenAI integration — one-line drop-in for openai.OpenAI().
+
+Quickstart:
+    from iris_openai import IrisOpenAI
+    from iris import AgentPassport, ComplianceTag
+
+    passport = AgentPassport(
+        name="analysis-agent",
+        owner="team@company.com",
+        compliance_tags=[ComplianceTag.COLORADO_AI_ACT],
+    )
+    client = IrisOpenAI(passport=passport)
+    response = client.chat.completions.create(model="gpt-4o", messages=[...])
+"""
+
+from __future__ import annotations
+
+from iris import IrisViolationError
+from iris_core.models.passport import (
+    AgentPassport,
+    ComplianceTag,
+    DataClassification,
+    Environment,
+    ToolPermission,
+)
+from iris_core.models.policy import Violation
+
+from iris_openai.client import IrisAzureOpenAI, IrisOpenAI, IrisOpenAIAsync
+from iris_openai.tool_guard import guard_openai_tools
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "IrisOpenAI",
+    "IrisOpenAIAsync",
+    "IrisAzureOpenAI",
+    "IrisViolationError",
+    "AgentPassport",
+    "ComplianceTag",
+    "DataClassification",
+    "Environment",
+    "ToolPermission",
+    "Violation",
+    "guard_openai_tools",
+]

iris_openai/_governance.py

@@ -0,0 +1,368 @@
+"""Shared IRIS evaluation helpers for OpenAI SDK integration."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import threading
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlparse
+
+import yaml
+
+from iris import IrisViolationError
+from iris_core.engine.cedar import CedarEngine, EvaluationContext
+from iris_core.rbac.context import UserContext
+from iris_core.evidence.vault import EvidenceVault
+from iris_core.models.passport import AgentPassport, Environment
+from iris_core.models.policy import PolicyResult, Severity, Violation
+from iris_core.models.region import RegionPolicy, TransferRule
+
+logger = logging.getLogger("iris.openai")
+
+_VAULT_LOCK = threading.Lock()
+
+_AZURE_LOCATION_TOKENS: Dict[str, str] = {
+    "westeurope": "eu-west-1",
+    "northeurope": "eu-north-1",
+    "swedencentral": "eu-north-1",
+    "francecentral": "eu-central-1",
+    "germanywestcentral": "eu-central-1",
+    "eastus": "us-east-1",
+    "eastus2": "us-east-2",
+    "westus": "us-west-1",
+    "westus2": "us-west-2",
+    "centralus": "us-central-1",
+    "southcentralus": "us-central-1",
+}
+
+_EU_REGION_PREFIXES = ("eu-",)
+
+
+def current_environment() -> Environment:
+    return Environment(os.environ.get("IRIS_ENV", "dev"))
+
+
+def has_policy_loaded(engine: CedarEngine, passport: AgentPassport) -> bool:
+    return bool(engine._policy_cache.get(passport.agent_id))
+
+
+def load_passport_policy(engine: CedarEngine, passport: AgentPassport) -> None:
+    if not passport.policy_ref:
+        return
+    policy_path = Path(passport.policy_ref)
+    if not policy_path.is_absolute():
+        policy_path = Path.cwd() / policy_path
+    if policy_path.exists():
+        engine.load_policy_file(passport.agent_id, policy_path)
+
+
+def load_region_policy() -> Optional[RegionPolicy]:
+    """Load optional RegionPolicy from GitOps or ~/.iris."""
+    candidates = [
+        Path.cwd() / "governance" / "region-policy.yaml",
+        Path.home() / ".iris" / "region-policy.yaml",
+    ]
+    env_path = os.environ.get("IRIS_REGION_POLICY")
+    if env_path:
+        candidates.insert(0, Path(env_path))
+
+    for path in candidates:
+        if not path.exists():
+            continue
+        data = yaml.safe_load(path.read_text()) or {}
+        spec = data.get("spec", data)
+        transfers = []
+        for rule in spec.get("restricted_transfers", []):
+            transfers.append(
+                TransferRule(
+                    from_region=rule["from_region"],
+                    to_region=rule["to_region"],
+                    compliance_ref=rule.get("compliance_ref", "iris:cross-region"),
+                    action=rule.get("action", "block"),
+                    note=rule.get("note"),
+                )
+            )
+        return RegionPolicy(
+            name=spec.get("name", data.get("metadata", {}).get("name", "default")),
+            restricted_transfers=transfers,
+        )
+    return None
+
+
+def parse_azure_endpoint_region(azure_endpoint: Optional[str]) -> Optional[str]:
+    """
+    Extract a canonical region from an Azure OpenAI endpoint URL.
+
+    https://my-resource.openai.azure.com → no region in hostname
+    https://my-resource.cognitiveservices.azure.com/openai → location token in host
+    """
+    if not azure_endpoint:
+        return None
+    host = (urlparse(azure_endpoint).hostname or "").lower()
+    if not host:
+        return None
+    if host.endswith(".openai.azure.com"):
+        return None
+    for token, region in _AZURE_LOCATION_TOKENS.items():
+        if token in host:
+            return region
+    for part in host.split("."):
+        if part.startswith(("eu-", "us-", "ap-", "cn-")):
+            return part
+    return None
+
+
+def is_eu_region(region: Optional[str]) -> bool:
+    return bool(region and region.startswith(_EU_REGION_PREFIXES))
+
+
+def check_region_policy_transfer(
+    region_policy: RegionPolicy,
+    data_region: str,
+    destination_region: str,
+) -> Optional[Violation]:
+    for rule in region_policy.restricted_transfers:
+        if rule.from_region == data_region and rule.to_region == destination_region:
+            if rule.action == "block":
+                return Violation(
+                    rule_id="IRIS-XR-001",
+                    severity=Severity.CRITICAL,
+                    message=(
+                        f"Cross-region data transfer blocked by region policy "
+                        f"'{region_policy.name}': {data_region} → {destination_region}. "
+                        f"{rule.note or ''}".strip()
+                    ),
+                    compliance_refs=[rule.compliance_ref],
+                    remediation=(
+                        "Use an Azure endpoint in an approved region or update "
+                        "governance/region-policy.yaml with a documented exception."
+                    ),
+                )
+    return None
+
+
+def azure_cross_region_violation(
+    passport: AgentPassport,
+    azure_endpoint: Optional[str],
+    region_policy: Optional[RegionPolicy] = None,
+) -> Optional[Violation]:
+    """Flag EU/US mismatches when Azure endpoint region is known."""
+    destination = parse_azure_endpoint_region(azure_endpoint)
+    if not destination:
+        return None
+
+    data_region = passport.allowed_regions[0] if passport.allowed_regions else None
+    if not data_region:
+        if is_eu_region(destination):
+            return Violation(
+                rule_id="IRIS-XR-002",
+                severity=Severity.HIGH,
+                message=(
+                    f"Azure OpenAI endpoint resolves to EU region '{destination}' "
+                    f"but agent '{passport.name}' has no allowed_regions declared. "
+                    f"EU-hosted inference may process EU personal data under GDPR."
+                ),
+                compliance_refs=["gdpr:chapter-5-transfer", "iris:cross-region"],
+                remediation=(
+                    "Set allowed_regions on the agent passport to document approved "
+                    "data residency, or use a non-EU Azure endpoint."
+                ),
+            )
+        return None
+
+    policy = region_policy or load_region_policy()
+    if policy:
+        violation = check_region_policy_transfer(policy, data_region, destination)
+        if violation:
+            return violation
+
+    if is_eu_region(data_region) != is_eu_region(destination):
+        return Violation(
+            rule_id="IRIS-XR-001",
+            severity=Severity.CRITICAL,
+            message=(
+                f"Cross-region Azure OpenAI call blocked: passport data region "
+                f"'{data_region}' does not match endpoint region '{destination}'."
+            ),
+            compliance_refs=["gdpr:chapter-5-transfer", "iris:cross-region"],
+            remediation=(
+                "Point azure_endpoint at a region that matches the agent's "
+                "allowed_regions, or update the passport after security review."
+            ),
+        )
+    return None
+
+
+def apply_no_policy_gate(
+    engine: CedarEngine,
+    passport: AgentPassport,
+    env: Environment,
+    result: PolicyResult,
+) -> PolicyResult:
+    if has_policy_loaded(engine, passport):
+        return result
+    if env in (Environment.DEV, Environment.TEST):
+        if result.decision == "DENY":
+            return PolicyResult(
+                decision="PERMIT_WITH_WARNINGS",
+                violations=result.violations,
+                agent_id=result.agent_id,
+                action=result.action,
+                resource=result.resource,
+                environment=result.environment,
+            )
+    return result
+
+
+def merge_results(base: PolicyResult, extra_violations: List[Violation]) -> PolicyResult:
+    if not extra_violations:
+        return base
+    violations = list(base.violations) + list(extra_violations)
+    critical = [v for v in violations if v.severity == Severity.CRITICAL]
+    high = [v for v in violations if v.severity in (Severity.HIGH, Severity.CRITICAL)]
+    if critical:
+        decision = "DENY"
+    elif high and base.decision == "PERMIT":
+        decision = "DENY"
+    elif violations and base.decision == "PERMIT":
+        decision = "PERMIT_WITH_WARNINGS"
+    else:
+        decision = base.decision
+    return PolicyResult(
+        decision=decision,
+        violations=violations,
+        agent_id=base.agent_id,
+        action=base.action,
+        resource=base.resource,
+        environment=base.environment,
+    )
+
+
+def evaluate_openai_call(
+    engine: CedarEngine,
+    vault: EvidenceVault,
+    passport: AgentPassport,
+    env: Environment,
+    *,
+    resource: str = "openai-api",
+    operation: str = "chat.completions",
+    model: Optional[str] = None,
+    tool_names: Optional[List[str]] = None,
+    data_classification: Optional[str] = None,
+    azure_endpoint: Optional[str] = None,
+    extra_violations: Optional[List[Violation]] = None,
+    dlp_prompt_findings: Optional[list] = None,
+    user_email: Optional[str] = None,
+    user_role: Optional[str] = None,
+) -> PolicyResult:
+    data_region = passport.allowed_regions[0] if passport.allowed_regions else None
+    destination_region = parse_azure_endpoint_region(azure_endpoint)
+    user_ctx = UserContext.from_params(user_email, user_role)
+    user_fields = user_ctx.evaluation_fields()
+
+    ctx = EvaluationContext(
+        agent_id=passport.agent_id,
+        action="call",
+        resource=resource,
+        resource_type="api",
+        environment=env,
+        data_region=data_region,
+        destination_region=destination_region,
+        data_classification=data_classification or passport.data_classification.value,
+        dlp_prompt_findings=dlp_prompt_findings,
+        additional={
+            "operation": operation,
+            "model": model,
+            "tool_names": tool_names or [],
+            "azure_endpoint": azure_endpoint,
+        },
+        **user_fields,
+    )
+
+    result = engine.evaluate(passport, ctx)
+    result = apply_no_policy_gate(engine, passport, env, result)
+
+    violations: List[Violation] = list(extra_violations or [])
+    azure_v = azure_cross_region_violation(passport, azure_endpoint)
+    if azure_v:
+        violations.append(azure_v)
+
+    for name in tool_names or []:
+        tool_ctx = EvaluationContext(
+            agent_id=passport.agent_id,
+            action="call",
+            resource=name,
+            resource_type="tool",
+            environment=env,
+            data_classification=data_classification or passport.data_classification.value,
+            **user_fields,
+        )
+        tool_result = engine.evaluate(passport, tool_ctx)
+        tool_result = apply_no_policy_gate(engine, passport, env, tool_result)
+        violations.extend(tool_result.violations)
+        if tool_result.decision == "DENY":
+            result = PolicyResult(
+                decision="DENY",
+                violations=list(result.violations) + violations,
+                agent_id=result.agent_id,
+                action=result.action,
+                resource=result.resource,
+                environment=result.environment,
+            )
+
+    if env == Environment.PRODUCTION and (tool_names or []) and not passport.tool_permissions:
+        for name in tool_names:
+            violations.append(
+                Violation(
+                    rule_id="IRIS-TOOL-001",
+                    severity=Severity.CRITICAL,
+                    message=(
+                        f"Agent '{passport.name}' invoked tool '{name}' in production "
+                        f"with no tool_permissions declared on the passport."
+                    ),
+                    compliance_refs=["iris:tool-permission", "colorado-ai-act:transparency"],
+                    remediation=(
+                        "Declare permitted tools in passport.yaml tool_permissions "
+                        "before enabling tools in production."
+                    ),
+                )
+            )
+        result = PolicyResult(
+            decision="DENY",
+            violations=list(result.violations) + violations,
+            agent_id=result.agent_id,
+            action=result.action,
+            resource=result.resource,
+            environment=result.environment,
+        )
+
+    result = merge_results(result, violations)
+
+    with _VAULT_LOCK:
+        vault.record(ctx, result)
+    return result
+
+
+def enforce_result(result: PolicyResult, env: Environment) -> None:
+    if result.decision == "DENY":
+        if env in (Environment.DEV, Environment.TEST):
+            for violation in result.violations:
+                msg = (
+                    f"[IRIS WARNING] {violation.message} "
+                    f"Remediation: {violation.remediation}"
+                )
+                logger.warning(msg)
+                print(msg, file=sys.stderr)
+            return
+        raise IrisViolationError(result)
+    if result.decision == "PERMIT_WITH_WARNINGS":
+        for violation in result.violations:
+            msg = (
+                f"[IRIS WARNING] {violation.message} "
+                f"Remediation: {violation.remediation}"
+            )
+            logger.warning(msg)
+            print(msg, file=sys.stderr)

iris_openai/client.py

@@ -0,0 +1,343 @@
+"""Drop-in OpenAI client wrapper with IRIS governance on every API call."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from iris_core.dlp import DLPScanner
+from iris_core.dlp.enforcement import (
+    enforce_prompt_dlp,
+    extract_openai_response_text,
+    handle_response_dlp,
+)
+from iris_core.engine.cedar import CedarEngine
+from iris_core.evidence.vault import EvidenceVault
+from iris_core.models.passport import AgentPassport
+
+from iris_openai._governance import (
+    current_environment,
+    enforce_result,
+    evaluate_openai_call,
+    load_passport_policy,
+)
+from iris_openai.tool_guard import guard_openai_tools
+
+
+def _lazy_openai():
+    import openai
+
+    return openai
+
+
+def _extract_tool_names_from_messages(messages: List[Any]) -> List[str]:
+    names: List[str] = []
+    for msg in messages or []:
+        if not isinstance(msg, dict):
+            continue
+        for call in msg.get("tool_calls") or []:
+            if not isinstance(call, dict):
+                continue
+            fn = call.get("function") or {}
+            name = fn.get("name")
+            if name:
+                names.append(name)
+    return names
+
+
+def _extract_prompt_text(kwargs: dict) -> str:
+    parts: List[str] = []
+    for msg in kwargs.get("messages") or []:
+        if not isinstance(msg, dict):
+            continue
+        content = msg.get("content")
+        if isinstance(content, str):
+            parts.append(content)
+        elif isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict):
+                    text = block.get("text") or block.get("content")
+                    if text:
+                        parts.append(str(text))
+    return "\n".join(parts)
+
+
+def _extract_tool_names_from_kwargs(kwargs: dict) -> List[str]:
+    names: List[str] = []
+    tools = kwargs.get("tools") or kwargs.get("functions") or []
+    for tool in tools:
+        if isinstance(tool, dict):
+            if tool.get("type") == "function":
+                fn = tool.get("function") or {}
+                if fn.get("name"):
+                    names.append(fn["name"])
+            elif tool.get("name"):
+                names.append(tool["name"])
+        elif hasattr(tool, "name"):
+            names.append(getattr(tool, "name"))
+    names.extend(_extract_tool_names_from_messages(kwargs.get("messages") or []))
+    return list(dict.fromkeys(names))
+
+
+class _IrisOpenAIClientBase:
+    _passport: AgentPassport
+    _engine: CedarEngine
+    _vault: EvidenceVault
+    _dlp: DLPScanner
+    _azure_endpoint: Optional[str] = None
+    _user_email: Optional[str] = None
+    _user_role: Optional[str] = None
+
+
+class _GovernedCompletionsBase:
+    def __init__(self, parent: _IrisOpenAIClientBase, completions_resource: Any):
+        self._parent = parent
+        self._completions = completions_resource
+
+    @property
+    def _passport(self) -> AgentPassport:
+        return self._parent._passport
+
+    @property
+    def _engine(self) -> CedarEngine:
+        return self._parent._engine
+
+    @property
+    def _vault(self) -> EvidenceVault:
+        return self._parent._vault
+
+    def _govern_kwargs(self, kwargs: dict) -> None:
+        env = current_environment()
+        prompt = _extract_prompt_text(kwargs)
+        dlp_result = enforce_prompt_dlp(
+            self._parent._dlp,
+            self._vault,
+            self._passport,
+            env,
+            prompt,
+            resource="openai-api",
+        )
+        if kwargs.get("tools"):
+            kwargs["tools"] = guard_openai_tools(kwargs["tools"], self._passport, env)
+        tool_names = _extract_tool_names_from_kwargs(kwargs)
+        result = evaluate_openai_call(
+            self._engine,
+            self._vault,
+            self._passport,
+            env,
+            operation="chat.completions",
+            model=kwargs.get("model"),
+            tool_names=tool_names,
+            azure_endpoint=getattr(self._parent, "_azure_endpoint", None),
+            dlp_prompt_findings=dlp_result.findings,
+            user_email=getattr(self._parent, "_user_email", None),
+            user_role=getattr(self._parent, "_user_role", None),
+        )
+        enforce_result(result, env)
+
+    def _scan_response(self, response: Any) -> Any:
+        env = current_environment()
+        response_text = extract_openai_response_text(response)
+        blocked, _ = handle_response_dlp(
+            self._parent._dlp,
+            self._vault,
+            self._passport,
+            env,
+            response_text,
+            response,
+            resource="openai-api",
+        )
+        return blocked
+
+    def create(self, **kwargs: Any) -> Any:
+        self._govern_kwargs(kwargs)
+        response = self._completions.create(**kwargs)
+        return self._scan_response(response)
+
+    def stream(self, **kwargs: Any) -> Any:
+        self._govern_kwargs(kwargs)
+        return self._completions.stream(**kwargs)
+
+
+class _GovernedCompletionsAsyncBase(_GovernedCompletionsBase):
+    async def create(self, **kwargs: Any) -> Any:
+        self._govern_kwargs(kwargs)
+        response = await self._completions.create(**kwargs)
+        return self._scan_response(response)
+
+    async def stream(self, **kwargs: Any) -> Any:
+        self._govern_kwargs(kwargs)
+        return await self._completions.stream(**kwargs)
+
+
+class IrisChatCompletionsResource(_GovernedCompletionsBase):
+    pass
+
+
+class IrisChatCompletionsResourceAsync(_GovernedCompletionsAsyncBase):
+    pass
+
+
+class IrisChatResource:
+    def __init__(self, parent: _IrisOpenAIClientBase, chat_resource: Any):
+        self._parent = parent
+        self._chat = chat_resource
+        self._completions_resource = IrisChatCompletionsResource(
+            parent, self._chat.completions
+        )
+
+    @property
+    def completions(self) -> IrisChatCompletionsResource:
+        return self._completions_resource
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._chat, name)
+
+
+class IrisChatResourceAsync:
+    def __init__(self, parent: _IrisOpenAIClientBase, chat_resource: Any):
+        self._parent = parent
+        self._chat = chat_resource
+        self._completions_resource = IrisChatCompletionsResourceAsync(
+            parent, self._chat.completions
+        )
+
+    @property
+    def completions(self) -> IrisChatCompletionsResourceAsync:
+        return self._completions_resource
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._chat, name)
+
+
+class _GovernedEmbeddingsBase:
+    def __init__(self, parent: _IrisOpenAIClientBase, embeddings_resource: Any):
+        self._parent = parent
+        self._embeddings = embeddings_resource
+
+    def _govern_kwargs(self, kwargs: dict) -> None:
+        env = current_environment()
+        result = evaluate_openai_call(
+            self._parent._engine,
+            self._parent._vault,
+            self._parent._passport,
+            env,
+            operation="embeddings",
+            model=kwargs.get("model"),
+            data_classification=self._parent._passport.data_classification.value,
+            azure_endpoint=getattr(self._parent, "_azure_endpoint", None),
+            user_email=getattr(self._parent, "_user_email", None),
+            user_role=getattr(self._parent, "_user_role", None),
+        )
+        enforce_result(result, env)
+
+    def create(self, **kwargs: Any) -> Any:
+        self._govern_kwargs(kwargs)
+        return self._embeddings.create(**kwargs)
+
+
+class _GovernedEmbeddingsAsyncBase(_GovernedEmbeddingsBase):
+    async def create(self, **kwargs: Any) -> Any:
+        self._govern_kwargs(kwargs)
+        return await self._embeddings.create(**kwargs)
+
+
+class IrisEmbeddingsResource(_GovernedEmbeddingsBase):
+    pass
+
+
+class IrisEmbeddingsResourceAsync(_GovernedEmbeddingsAsyncBase):
+    pass
+
+
+class IrisOpenAI(_IrisOpenAIClientBase):
+    """
+    Drop-in replacement for openai.OpenAI() with IRIS governance.
+
+    Pass an AgentPassport and the same kwargs you would give OpenAI().
+    All attributes not defined here are proxied to the underlying client.
+    """
+
+    def __init__(
+        self,
+        passport: AgentPassport,
+        user_email: Optional[str] = None,
+        user_role: Optional[str] = None,
+        **openai_kwargs: Any,
+    ):
+        from iris_core.dev_trust import print_dev_trust_message
+
+        print_dev_trust_message()
+        openai = _lazy_openai()
+        self._passport = passport
+        self._user_email = user_email
+        self._user_role = user_role
+        self._engine = CedarEngine()
+        self._vault = EvidenceVault(agent_id=passport.agent_id)
+        self._dlp = DLPScanner(passport)
+        load_passport_policy(self._engine, passport)
+        self._client = openai.OpenAI(**openai_kwargs)
+        self._chat_resource = IrisChatResource(self, self._client.chat)
+        self._embeddings_resource = IrisEmbeddingsResource(self, self._client.embeddings)
+
+    @property
+    def chat(self) -> IrisChatResource:
+        return self._chat_resource
+
+    @property
+    def embeddings(self) -> IrisEmbeddingsResource:
+        return self._embeddings_resource
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+class IrisOpenAIAsync(_IrisOpenAIClientBase):
+    """Async drop-in replacement for openai.AsyncOpenAI()."""
+
+    def __init__(
+        self,
+        passport: AgentPassport,
+        user_email: Optional[str] = None,
+        user_role: Optional[str] = None,
+        **openai_kwargs: Any,
+    ):
+        openai = _lazy_openai()
+        self._passport = passport
+        self._user_email = user_email
+        self._user_role = user_role
+        self._engine = CedarEngine()
+        self._vault = EvidenceVault(agent_id=passport.agent_id)
+        self._dlp = DLPScanner(passport)
+        load_passport_policy(self._engine, passport)
+        self._client = openai.AsyncOpenAI(**openai_kwargs)
+        self._chat_resource = IrisChatResourceAsync(self, self._client.chat)
+        self._embeddings_resource = IrisEmbeddingsResourceAsync(
+            self, self._client.embeddings
+        )
+
+    @property
+    def chat(self) -> IrisChatResourceAsync:
+        return self._chat_resource
+
+    @property
+    def embeddings(self) -> IrisEmbeddingsResourceAsync:
+        return self._embeddings_resource
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+class IrisAzureOpenAI(IrisOpenAI):
+    """Drop-in replacement for openai.AzureOpenAI() with Azure region checks."""
+
+    def __init__(self, passport: AgentPassport, **openai_kwargs: Any):
+        self._azure_endpoint = openai_kwargs.get("azure_endpoint")
+        super().__init__(passport, **openai_kwargs)
+
+
+class IrisAzureOpenAIAsync(IrisOpenAIAsync):
+    """Async Azure OpenAI client with IRIS governance."""
+
+    def __init__(self, passport: AgentPassport, **openai_kwargs: Any):
+        self._azure_endpoint = openai_kwargs.get("azure_endpoint")
+        super().__init__(passport, **openai_kwargs)

iris_openai/tool_guard.py

@@ -0,0 +1,97 @@
+"""Filter OpenAI tools[] to passport-declared permissions."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any, List, Optional
+
+from iris_core.models.passport import AgentPassport, Environment
+from iris_core.models.policy import Severity, Violation
+
+from iris_openai._governance import current_environment
+
+logger = logging.getLogger("iris.openai.tools")
+
+
+def _tool_name(tool: Any) -> Optional[str]:
+    if not isinstance(tool, dict):
+        return getattr(tool, "name", None)
+    if tool.get("type") == "function":
+        fn = tool.get("function") or {}
+        return fn.get("name")
+    return tool.get("name")
+
+
+def _log_tool_removal(violation: Violation) -> None:
+    msg = (
+        f"[IRIS TOOL FILTER] {violation.message} "
+        f"Remediation: {violation.remediation}"
+    )
+    logger.warning(msg)
+    # Always emit to stderr so removals are never silent (required in dev; auditable in prod).
+    print(msg, file=sys.stderr)
+
+
+def guard_openai_tools(
+    tools: List[Any],
+    passport: AgentPassport,
+    environment: Optional[Environment] = None,
+) -> List[Any]:
+    """
+    Return only tools permitted by passport.tool_permissions.
+
+    Removed tools are logged as IRIS-TOOL-001 violations. In dev/test, removal
+    is never silent — every dropped tool is logged with a reason. In production
+    with no tool_permissions declared, all tools are removed.
+    """
+    if not tools:
+        return []
+
+    env = environment or current_environment()
+    allowed = {t.tool_id for t in passport.tool_permissions}
+    filtered: List[Any] = []
+
+    if env == Environment.PRODUCTION and not allowed:
+        for tool in tools:
+            name = _tool_name(tool) or "unknown"
+            violation = Violation(
+                rule_id="IRIS-TOOL-001",
+                severity=Severity.CRITICAL,
+                message=(
+                    f"Tool '{name}' removed: agent '{passport.name}' has no "
+                    f"tool_permissions — all tools are blocked in production."
+                ),
+                compliance_refs=["iris:tool-permission"],
+                remediation=(
+                    "Add tool_permissions to the agent passport before using tools "
+                    "in production."
+                ),
+            )
+            _log_tool_removal(violation)
+        return []
+
+    for tool in tools:
+        name = _tool_name(tool)
+        if not name:
+            filtered.append(tool)
+            continue
+        if name in allowed:
+            filtered.append(tool)
+            continue
+        violation = Violation(
+            rule_id="IRIS-TOOL-001",
+            severity=Severity.HIGH,
+            message=(
+                f"Tool '{name}' removed: not in agent '{passport.name}' "
+                f"tool_permissions. Allowed: {sorted(allowed) or ['none declared']}."
+            ),
+            compliance_refs=["iris:tool-permission", "colorado-ai-act:transparency"],
+            remediation=(
+                f"Add '{name}' to tool_permissions in passport.yaml and obtain "
+                f"security engineer approval."
+            ),
+        )
+        _log_tool_removal(violation)
+
+    return filtered

iris_security_openai-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: iris-security-openai
+Version: 0.1.0
+Summary: IRIS governance for OpenAI — Cedar policy on every API call
+Author-email: IRIS Platform <sdk@iris.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/gimartinb/iris-sdk
+Project-URL: Repository, https://github.com/gimartinb/iris-sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: iris-security-core>=0.1.0
+Requires-Dist: iris-security-sdk>=0.1.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.30; extra == "openai"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+
+# iris-openai
+
+Drop-in IRIS governance for the [OpenAI Python SDK](https://github.com/openai/openai-python).
+
+Replace one line:
+
+```python
+# client = openai.OpenAI()
+client = IrisOpenAI(passport=passport)
+```
+
+Every `client.chat.completions.create()`, `stream()`, and `client.embeddings.create()` call is evaluated against Cedar policy, recorded in the Evidence Vault, and enforced per `IRIS_ENV` (warn in dev, block in production).
+
+Tool arrays are filtered to `passport.tool_permissions`; removed tools are logged as `IRIS-TOOL-001` (never silently dropped in dev).
+
+## Install
+
+```bash
+pip install iris-openai
+```
+
+## Quickstart
+
+See [examples/governed_gpt.py](examples/governed_gpt.py).
+
+## Environment
+
+| `IRIS_ENV`   | Behavior                                      |
+|-------------|-----------------------------------------------|
+| `dev`       | Fail open — warnings to stderr, never block   |
+| `production`| Fail closed — `IrisViolationError` on deny    |
+
+Defaults to `dev` when unset.

iris_security_openai-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+examples/governed_gpt.py,sha256=9hUgOwmkxFHT7aSR7_6ae3usW233zoH_bNTBAmOxD80,1689
+iris_openai/__init__.py,sha256=Ki23Jtmu9Jb1XQmdqtOsTnghGXGw07IjVWlruOeTQZE,1127
+iris_openai/_governance.py,sha256=sAzunRdikmaxP11xtSY-zZeLQ0zHSdxv_ZrbvBGxJ8g,13140
+iris_openai/client.py,sha256=00JIXZiWs-p8aHNSjSTdm6wFIWb6ASbkmcIMcxUEItg,10992
+iris_openai/tool_guard.py,sha256=a0aZB93TfTdUPou_19_oJFBnr1FgWwj98c6-lpSxGkc,3188
+tests/conftest.py,sha256=sm1aXg5mjLSgCZa0zAEHg1KLIGJRTuXMJZ2h_eshOd0,309
+tests/test_openai_integration.py,sha256=o1XmpuaU5ufjkR7S0lVddvSeCeKfVqc9GwsyOqd9nFI,12574
+iris_security_openai-0.1.0.dist-info/METADATA,sha256=2D5WVdWkypzsIZvc_yHXFy3xBzG_z-pTG7TqS5tUSxQ,1693
+iris_security_openai-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+iris_security_openai-0.1.0.dist-info/top_level.txt,sha256=MuZG3ngC-6xFGe0IKLD39hiDcWlgpK-_jHr7Ed2H42A,27
+iris_security_openai-0.1.0.dist-info/RECORD,,

iris_security_openai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

iris_security_openai-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+examples
+iris_openai
+tests

tests/conftest.py

@@ -0,0 +1,11 @@
+"""Test fixtures — isolate Evidence Vault from the developer home directory."""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def iris_home_tmp(monkeypatch, tmp_path):
+    """Write ~/.iris evidence under pytest tmp_path."""
+    monkeypatch.setenv("HOME", str(tmp_path))

tests/test_openai_integration.py

@@ -0,0 +1,322 @@
+"""
+Integration tests for iris-openai — mocked OpenAI API, no network calls.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from iris import IrisViolationError
+from iris_core.engine.cedar import CedarEngine
+from iris_core.evidence.vault import EvidenceVault
+from iris_core.models.passport import (
+    AgentPassport,
+    ComplianceTag,
+    DataClassification,
+    Environment,
+    ToolPermission,
+)
+from iris_openai import IrisAzureOpenAI, IrisOpenAI, guard_openai_tools
+from iris_openai._governance import parse_azure_endpoint_region
+
+
+@pytest.fixture
+def compliant_passport():
+    return AgentPassport(
+        name="support-agent",
+        owner="team@company.com",
+        data_classification=DataClassification.INTERNAL,
+        compliance_tags=[ComplianceTag.COLORADO_AI_ACT],
+        environments=[Environment.DEV, Environment.PRODUCTION],
+        is_high_risk_ai=True,
+        evidence_vault_id="vault-abc",
+        intent_ref="governance/agents/support-agent/policy-intent.md",
+        tool_permissions=[
+            ToolPermission(tool_id="search", description="Search", allowed_actions=["call"]),
+        ],
+    )
+
+
+@pytest.fixture
+def high_risk_incomplete_passport():
+    return AgentPassport(
+        name="loan-agent",
+        owner="gmoney@gmail.com",
+        compliance_tags=[ComplianceTag.COLORADO_AI_ACT],
+        environments=[Environment.DEV, Environment.PRODUCTION],
+        is_high_risk_ai=True,
+        evidence_vault_id=None,
+        intent_ref=None,
+    )
+
+
+def _mock_openai_module():
+    mock_module = MagicMock()
+    mock_choice = MagicMock()
+    mock_choice.message.content = "Hello from GPT"
+    mock_response = MagicMock()
+    mock_response.choices = [mock_choice]
+    mock_client = MagicMock()
+    mock_client.chat.completions.create.return_value = mock_response
+    mock_client.chat.completions.stream.return_value = iter([mock_response])
+    mock_client.embeddings.create.return_value = MagicMock(data=[])
+    mock_module.OpenAI.return_value = mock_client
+    mock_module.AzureOpenAI.return_value = mock_client
+    return mock_module, mock_client
+
+
+def _search_tool():
+    return {
+        "type": "function",
+        "function": {"name": "search", "description": "search", "parameters": {}},
+    }
+
+
+def _payments_tool():
+    return {
+        "type": "function",
+        "function": {"name": "payments", "description": "pay", "parameters": {}},
+    }
+
+
+class TestIrisOpenAIClient:
+    def test_client_permits_allowed_call(self, compliant_passport, tmp_path, monkeypatch):
+        monkeypatch.setenv("IRIS_ENV", "dev")
+        mock_module, mock_client = _mock_openai_module()
+        engine = CedarEngine()
+        engine.load_policy(compliant_passport.agent_id, "permit(principal, action, resource);")
+        vault = EvidenceVault(agent_id=compliant_passport.agent_id, vault_dir=tmp_path)
+
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            client = IrisOpenAI(passport=compliant_passport)
+            client._engine = engine
+            client._vault = vault
+
+            result = client.chat.completions.create(
+                model="gpt-4o",
+                messages=[{"role": "user", "content": "Help this customer."}],
+            )
+
+        assert result.choices[0].message.content == "Hello from GPT"
+        mock_client.chat.completions.create.assert_called_once()
+        events = vault.get_events()
+        assert len(events) == 1
+        assert events[0]["decision"] in ("PERMIT", "PERMIT_WITH_WARNINGS")
+        assert events[0]["resource"] == "openai-api"
+
+    def test_client_blocks_in_production(
+        self, high_risk_incomplete_passport, tmp_path, monkeypatch
+    ):
+        monkeypatch.setenv("IRIS_ENV", "production")
+        mock_module, _ = _mock_openai_module()
+        engine = CedarEngine()
+        engine.load_policy(
+            high_risk_incomplete_passport.agent_id,
+            "permit(principal, action, resource);",
+        )
+        vault = EvidenceVault(
+            agent_id=high_risk_incomplete_passport.agent_id, vault_dir=tmp_path
+        )
+
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            client = IrisOpenAI(passport=high_risk_incomplete_passport)
+            client._engine = engine
+            client._vault = vault
+
+            with pytest.raises(IrisViolationError) as exc_info:
+                client.chat.completions.create(
+                    model="gpt-4o",
+                    messages=[{"role": "user", "content": "Help this customer."}],
+                )
+
+        assert exc_info.value.result.decision == "DENY"
+        assert any(v.rule_id == "CO-001" for v in exc_info.value.result.violations)
+        mock_module.OpenAI.return_value.chat.completions.create.assert_not_called()
+
+    def test_client_warns_in_dev(
+        self, high_risk_incomplete_passport, tmp_path, monkeypatch, capsys
+    ):
+        monkeypatch.setenv("IRIS_ENV", "dev")
+        mock_module, mock_client = _mock_openai_module()
+        engine = CedarEngine()
+        engine.load_policy(
+            high_risk_incomplete_passport.agent_id,
+            "permit(principal, action, resource);",
+        )
+        vault = EvidenceVault(
+            agent_id=high_risk_incomplete_passport.agent_id, vault_dir=tmp_path
+        )
+
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            client = IrisOpenAI(passport=high_risk_incomplete_passport)
+            client._engine = engine
+            client._vault = vault
+
+            client.chat.completions.create(
+                model="gpt-4o",
+                messages=[{"role": "user", "content": "Help this customer."}],
+            )
+
+        mock_client.chat.completions.create.assert_called_once()
+        captured = capsys.readouterr()
+        assert "[IRIS WARNING]" in captured.err
+        events = vault.get_events()
+        assert events[0]["decision"] == "DENY"
+
+    def test_tool_filtering_removes_unpermitted_tools(
+        self, compliant_passport, tmp_path, monkeypatch, capsys
+    ):
+        monkeypatch.setenv("IRIS_ENV", "dev")
+        mock_module, mock_client = _mock_openai_module()
+        engine = CedarEngine()
+        engine.load_policy(compliant_passport.agent_id, "permit(principal, action, resource);")
+        vault = EvidenceVault(agent_id=compliant_passport.agent_id, vault_dir=tmp_path)
+
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            client = IrisOpenAI(passport=compliant_passport)
+            client._engine = engine
+            client._vault = vault
+
+            client.chat.completions.create(
+                model="gpt-4o",
+                messages=[{"role": "user", "content": "Run tools"}],
+                tools=[_search_tool(), _payments_tool()],
+            )
+
+        call_kwargs = mock_client.chat.completions.create.call_args.kwargs
+        tool_names = [t["function"]["name"] for t in call_kwargs["tools"]]
+        assert tool_names == ["search"]
+        assert "payments" not in tool_names
+        captured = capsys.readouterr()
+        assert "IRIS TOOL FILTER" in captured.err
+        assert "payments" in captured.err
+
+    def test_azure_openai_cross_region_detection(
+        self, compliant_passport, tmp_path, monkeypatch
+    ):
+        monkeypatch.setenv("IRIS_ENV", "production")
+        eu_passport = AgentPassport(
+            name=compliant_passport.name,
+            owner=compliant_passport.owner,
+            agent_id=compliant_passport.agent_id,
+            data_classification=DataClassification.PII,
+            allowed_regions=["eu-west-1"],
+            environments=[Environment.PRODUCTION],
+            compliance_tags=[ComplianceTag.GDPR],
+        )
+        mock_module, mock_client = _mock_openai_module()
+        engine = CedarEngine()
+        engine.load_policy(eu_passport.agent_id, "permit(principal, action, resource);")
+        vault = EvidenceVault(agent_id=eu_passport.agent_id, vault_dir=tmp_path)
+
+        endpoint = "https://my-resource-eastus.cognitiveservices.azure.com/openai"
+        assert parse_azure_endpoint_region(endpoint) == "us-east-1"
+
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            client = IrisAzureOpenAI(
+                passport=eu_passport,
+                azure_endpoint=endpoint,
+                api_key="test",
+            )
+            client._engine = engine
+            client._vault = vault
+
+            with pytest.raises(IrisViolationError) as exc_info:
+                client.chat.completions.create(
+                    model="gpt-4o",
+                    messages=[{"role": "user", "content": "Process EU data."}],
+                )
+
+        assert any(v.rule_id == "IRIS-XR-001" for v in exc_info.value.result.violations)
+        mock_client.chat.completions.create.assert_not_called()
+
+    def test_embeddings_intercept(self, compliant_passport, tmp_path, monkeypatch):
+        monkeypatch.setenv("IRIS_ENV", "dev")
+        mock_module, mock_client = _mock_openai_module()
+        engine = CedarEngine()
+        engine.load_policy(compliant_passport.agent_id, "permit(principal, action, resource);")
+        vault = EvidenceVault(agent_id=compliant_passport.agent_id, vault_dir=tmp_path)
+
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            client = IrisOpenAI(passport=compliant_passport)
+            client._engine = engine
+            client._vault = vault
+
+            client.embeddings.create(model="text-embedding-3-small", input="hello")
+
+        mock_client.embeddings.create.assert_called_once()
+        events = vault.get_events()
+        assert len(events) == 1
+        assert events[0]["resource"] == "openai-api"
+
+    def test_streaming_intercept(self, compliant_passport, tmp_path, monkeypatch):
+        monkeypatch.setenv("IRIS_ENV", "dev")
+        mock_module, mock_client = _mock_openai_module()
+        engine = CedarEngine()
+        engine.load_policy(compliant_passport.agent_id, "permit(principal, action, resource);")
+        vault = EvidenceVault(agent_id=compliant_passport.agent_id, vault_dir=tmp_path)
+
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            client = IrisOpenAI(passport=compliant_passport)
+            client._engine = engine
+            client._vault = vault
+
+            stream = client.chat.completions.stream(
+                model="gpt-4o",
+                messages=[{"role": "user", "content": "Stream a reply."}],
+            )
+            list(stream)
+
+        mock_client.chat.completions.stream.assert_called_once()
+        assert len(vault.get_events()) == 1
+
+    def test_evidence_vault_records_call(self, compliant_passport, tmp_path, monkeypatch):
+        monkeypatch.setenv("IRIS_ENV", "dev")
+        mock_module, _ = _mock_openai_module()
+        engine = CedarEngine()
+        engine.load_policy(compliant_passport.agent_id, "permit(principal, action, resource);")
+        vault = EvidenceVault(agent_id=compliant_passport.agent_id, vault_dir=tmp_path)
+
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            client = IrisOpenAI(passport=compliant_passport)
+            client._engine = engine
+            client._vault = vault
+
+            client.chat.completions.create(
+                model="gpt-4o",
+                messages=[{"role": "user", "content": "First"}],
+            )
+            client.chat.completions.create(
+                model="gpt-4o",
+                messages=[{"role": "user", "content": "Second"}],
+            )
+
+        events = vault.get_events()
+        assert len(events) == 2
+        assert all(e["action"] == "call" for e in events)
+        assert all(e["resource"] == "openai-api" for e in events)
+
+
+class TestGuardOpenAITools:
+    def test_production_blocks_all_tools_without_permissions(self, monkeypatch, capsys):
+        monkeypatch.setenv("IRIS_ENV", "production")
+        passport = AgentPassport(
+            name="no-tools",
+            owner="team@company.com",
+            environments=[Environment.PRODUCTION],
+        )
+        filtered = guard_openai_tools([_search_tool(), _payments_tool()], passport)
+        assert filtered == []
+        assert "IRIS TOOL FILTER" in capsys.readouterr().err
+
+    def test_guard_returns_only_permitted(self, compliant_passport, monkeypatch):
+        monkeypatch.setenv("IRIS_ENV", "production")
+        filtered = guard_openai_tools(
+            [_search_tool(), _payments_tool()],
+            compliant_passport,
+            Environment.PRODUCTION,
+        )
+        assert len(filtered) == 1
+        assert filtered[0]["function"]["name"] == "search"