iris-security-openai 0.1.0__tar.gz

iris_security_openai-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,33 @@
+# 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/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_security_openai-0.1.0/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_security_openai-0.1.0/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)