iris-security-crewai 0.1.1__py3-none-any.whl

examples/governed_crew.py

@@ -0,0 +1,84 @@
+"""
+Minimal two-agent CrewAI crew with IRIS governance.
+
+Requires: pip install iris-crewai crewai[tools]
+Set OPENAI_API_KEY before running.
+"""
+
+from __future__ import annotations
+
+from crewai import Crew, Task
+from crewai.tools import tool
+
+from iris import AgentPassport, ComplianceTag
+from iris_crewai import IrisCrew, IrisCrewAgent
+
+
+@tool
+def web_search(query: str, data_region: str = "us-east-1") -> str:
+    """Search the web for information on a topic."""
+    return f"Findings for '{query}' in {data_region}: AI governance is evolving rapidly."
+
+
+@tool
+def write_summary(content: str) -> str:
+    """Write a polished summary from research notes."""
+    return f"Summary: {content[:200]}"
+
+
+def main() -> None:
+    researcher_passport = AgentPassport(
+        name="researcher-agent",
+        owner="team@company.com",
+        compliance_tags=[ComplianceTag.COLORADO_AI_ACT],
+    )
+    writer_passport = AgentPassport(
+        name="writer-agent",
+        owner="team@company.com",
+        compliance_tags=[ComplianceTag.COLORADO_AI_ACT],
+    )
+
+    researcher = IrisCrewAgent(
+        researcher_passport,
+        role="Researcher",
+        goal="Find accurate information on the assigned topic",
+        backstory="You are a diligent research analyst.",
+        tools=[web_search],
+        verbose=True,
+    )
+    writer = IrisCrewAgent(
+        writer_passport,
+        role="Writer",
+        goal="Produce a clear summary from research notes",
+        backstory="You are an experienced technical writer.",
+        tools=[write_summary],
+        verbose=True,
+    )
+
+    research_task = Task(
+        description="Research the topic: {topic}",
+        expected_output="Bullet-point research notes",
+        agent=researcher,
+    )
+    write_task = Task(
+        description="Write a summary based on the research",
+        expected_output="A concise paragraph",
+        agent=writer,
+        context=[research_task],
+    )
+
+    crew = IrisCrew.from_crew(
+        Crew(agents=[researcher, writer], tasks=[research_task, write_task], verbose=True),
+        passports={"Researcher": researcher_passport, "Writer": writer_passport},
+    )
+
+    kickoff = crew.kickoff(inputs={"topic": "AI governance"})
+    report = crew.compliance_report()
+
+    print(kickoff["result"])
+    print(f"Crew pass rate: {report['crew_pass_rate']:.0%}")
+    print("Compliance report:", report)
+
+
+if __name__ == "__main__":
+    main()

iris_crewai/__init__.py

@@ -0,0 +1,47 @@
+"""
+IRIS CrewAI integration — governance in two lines per agent.
+
+Quickstart:
+    from iris_crewai import IrisCrewAgent, IrisCrew
+    from iris import AgentPassport, ComplianceTag
+
+    passport = AgentPassport(
+        name="researcher-agent",
+        owner="team@company.com",
+        compliance_tags=[ComplianceTag.COLORADO_AI_ACT],
+    )
+    agent = IrisCrewAgent(passport, role="Researcher", goal="...", backstory="...")
+"""
+
+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 PolicyResult, Severity, Violation
+
+from iris_crewai.agent import IrisCrewAgent
+from iris_crewai.crew import IrisCrew
+from iris_crewai.tools import iris_crew_tool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "IrisCrewAgent",
+    "IrisCrew",
+    "iris_crew_tool",
+    "IrisViolationError",
+    "AgentPassport",
+    "ComplianceTag",
+    "DataClassification",
+    "Environment",
+    "ToolPermission",
+    "PolicyResult",
+    "Severity",
+    "Violation",
+]

iris_crewai/_governance.py

@@ -0,0 +1,431 @@
+"""Shared IRIS evaluation helpers for CrewAI integrations."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import threading
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from iris_core.cost import record_llm_cost_async
+from iris_core.dlp import DLPScanner
+from iris_core.dlp.enforcement import enforce_prompt_dlp
+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
+
+from iris import IrisViolationError
+
+logger = logging.getLogger("iris.crewai")
+
+_VAULT_LOCK = threading.Lock()
+_MOCK_SAFE_RESPONSE = "[IRIS] Action blocked by policy — mock safe response returned."
+
+
+@dataclass
+class EvaluationRecord:
+    agent_name: str
+    action: str
+    resource: str
+    decision: str
+    violations: List[dict] = field(default_factory=list)
+
+
+def resolve_environment(env: Optional[Environment] = None) -> Environment:
+    if env is not None:
+        return env
+    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:
+    """Load Cedar policy from passport.policy_ref when present on disk."""
+    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 apply_no_policy_gate(
+    engine: CedarEngine,
+    passport: AgentPassport,
+    env: Environment,
+    result: PolicyResult,
+) -> PolicyResult:
+    """Fail open in dev/test when no policy is loaded; fail closed in staging/prod."""
+    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 extract_regions(inputs: Optional[Dict[str, Any]]) -> tuple[Optional[str], Optional[str]]:
+    if not inputs:
+        return None, None
+    data_region = inputs.get("data_region")
+    destination_region = inputs.get("destination_region") or inputs.get("dest_region")
+    return (
+        str(data_region) if data_region is not None else None,
+        str(destination_region) if destination_region is not None else None,
+    )
+
+
+def parse_tool_input(tool_input: str) -> Optional[Dict[str, Any]]:
+    """Parse CrewAI tool_input string into a dict when possible."""
+    if not tool_input:
+        return None
+    stripped = tool_input.strip()
+    if not stripped:
+        return None
+    try:
+        parsed = json.loads(stripped)
+        if isinstance(parsed, dict):
+            return parsed
+    except json.JSONDecodeError:
+        pass
+    return {"input": stripped}
+
+
+def vault_partition_id(passport: AgentPassport) -> str:
+    """Evidence vault partition key — one vault per agent name."""
+    return passport.name or passport.agent_id
+
+
+class AgentGovernor:
+    """Per-agent Cedar evaluation, evidence recording, and compliance tracking."""
+
+    def __init__(
+        self,
+        passport: AgentPassport,
+        environment: Optional[Environment] = None,
+        user_email: Optional[str] = None,
+        user_role: Optional[str] = None,
+    ):
+        self.passport = passport
+        self.env = resolve_environment(environment)
+        self._user_email = user_email
+        self._user_role = user_role
+        self._engine = CedarEngine()
+        self._vault = EvidenceVault(agent_id=vault_partition_id(passport))
+        self._dlp = DLPScanner(passport)
+        load_passport_policy(self._engine, passport)
+        self.records: List[EvaluationRecord] = []
+
+    def evaluate_tool(
+        self,
+        *,
+        action: str,
+        resource: str,
+        inputs: Optional[Dict[str, Any]] = None,
+    ) -> PolicyResult:
+        data_region, destination_region = extract_regions(inputs)
+        data_classification = None
+        if inputs and inputs.get("data_classification") is not None:
+            data_classification = str(inputs["data_classification"])
+        prompt_text = ""
+        if inputs:
+            prompt_text = str(
+                inputs.get("input")
+                or inputs.get("prompt")
+                or inputs.get("tool_input")
+                or ""
+            )
+        dlp_result = (
+            enforce_prompt_dlp(
+                self._dlp,
+                self._vault,
+                self.passport,
+                self.env,
+                prompt_text,
+                resource=resource,
+            )
+            if prompt_text.strip()
+            else None
+        )
+        user_ctx = UserContext.from_params(self._user_email, self._user_role)
+        ctx = EvaluationContext(
+            agent_id=self.passport.agent_id,
+            action=action,
+            resource=resource,
+            resource_type="tool",
+            environment=self.env,
+            data_region=data_region,
+            destination_region=destination_region,
+            data_classification=data_classification,
+            user_consent_logged=bool(inputs.get("user_consent_logged")) if inputs else False,
+            dlp_prompt_findings=dlp_result.findings if dlp_result else None,
+            **user_ctx.evaluation_fields(),
+        )
+        result = self._engine.evaluate(self.passport, ctx)
+        result = apply_no_policy_gate(self._engine, self.passport, self.env, result)
+        with _VAULT_LOCK:
+            self._vault.record(ctx, result)
+        self._track(result)
+        return result
+
+    def _track(self, result: PolicyResult) -> None:
+        self.records.append(
+            EvaluationRecord(
+                agent_name=vault_partition_id(self.passport),
+                action=result.action,
+                resource=result.resource,
+                decision=result.decision,
+                violations=[
+                    {
+                        "rule_id": v.rule_id,
+                        "severity": v.severity.value,
+                        "message": v.message,
+                    }
+                    for v in result.violations
+                ],
+            )
+        )
+
+    def evaluate_step_action(self, agent_action: Any) -> Optional[str]:
+        """
+        Evaluate a CrewAI AgentAction step without altering crew output formatting.
+
+        Returns a mock safe response in dev when denied; raises in production.
+        """
+        from crewai.agents.parser import AgentAction, AgentFinish
+
+        if isinstance(agent_action, AgentFinish):
+            logger.debug(
+                "IRIS step: agent=%s finished",
+                vault_partition_id(self.passport),
+            )
+            return None
+
+        if not isinstance(agent_action, AgentAction):
+            return None
+
+        tool_name = agent_action.tool
+        inputs = parse_tool_input(agent_action.tool_input)
+        result = self.evaluate_tool(action="call", resource=tool_name, inputs=inputs)
+
+        if result.decision == "DENY":
+            if self.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 _MOCK_SAFE_RESPONSE
+            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)
+
+        logger.debug(
+            "IRIS step: agent=%s tool=%s decision=%s",
+            vault_partition_id(self.passport),
+            tool_name,
+            result.decision,
+        )
+        return None
+
+    def record_step_llm_cost(self, agent_action: Any) -> None:
+        """Record LLM cost when token usage is available on a CrewAI step."""
+        usage = getattr(agent_action, "usage", None) or getattr(agent_action, "token_usage", None)
+        if usage is None:
+            return
+
+        model = (
+            getattr(agent_action, "model", None)
+            or getattr(agent_action, "model_name", None)
+            or "crewai-llm"
+        )
+        provider = "openai"
+        model_lower = str(model).lower()
+        if "claude" in model_lower:
+            provider = "anthropic"
+        elif "gemini" in model_lower:
+            provider = "google"
+
+        class _UsageResponse:
+            def __init__(self, usage_data: Any):
+                self.usage = usage_data
+
+        record_llm_cost_async(
+            agent_id=self.passport.agent_id,
+            agent_name=vault_partition_id(self.passport),
+            provider=provider,
+            model=str(model),
+            response=_UsageResponse(usage),
+            tool_name=getattr(agent_action, "tool", "crewai-llm"),
+            duration_ms=0.0,
+            environment=self.env.value,
+        )
+
+    @property
+    def vault(self) -> EvidenceVault:
+        return self._vault
+
+
+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)
+
+
+def make_step_callback(
+    governor: AgentGovernor,
+    user_callback: Optional[Callable[..., Any]] = None,
+) -> Callable[[Any], Any]:
+    """Chain IRIS step evaluation with an optional user step_callback."""
+
+    def iris_step_callback(step_output: Any) -> Any:
+        mock_response = governor.evaluate_step_action(step_output)
+        governor.record_step_llm_cost(step_output)
+        if user_callback is not None:
+            user_result = user_callback(step_output)
+            return user_result if user_result is not None else mock_response
+        return mock_response
+
+    return iris_step_callback
+
+
+def _agent_pass_rate(records: List[EvaluationRecord]) -> float:
+    if not records:
+        return 1.0
+    violations = sum(
+        len(r.violations) if r.violations else (1 if r.decision == "DENY" else 0)
+        for r in records
+        if r.decision != "PERMIT"
+    )
+    return max(0.0, (len(records) - violations) / len(records))
+
+
+def _agent_violation_count(records: List[EvaluationRecord]) -> int:
+    return sum(
+        len(r.violations) if r.violations else (1 if r.decision == "DENY" else 0)
+        for r in records
+        if r.decision != "PERMIT"
+    )
+
+
+def _violations_by_severity(records: List[EvaluationRecord]) -> Dict[str, int]:
+    counter: Counter[str] = Counter()
+    for record in records:
+        if record.decision == "PERMIT":
+            continue
+        if record.violations:
+            for v in record.violations:
+                counter[v["severity"]] += 1
+        elif record.decision == "DENY":
+            counter["unknown"] += 1
+    return dict(counter)
+
+
+def _most_violated_rule(records: List[EvaluationRecord]) -> Optional[str]:
+    counter: Counter[str] = Counter()
+    for record in records:
+        if record.decision == "PERMIT":
+            continue
+        for v in record.violations:
+            counter[v["rule_id"]] += 1
+    if not counter:
+        return None
+    return counter.most_common(1)[0][0]
+
+
+def build_compliance_report(governors: Dict[str, AgentGovernor]) -> dict:
+    """Aggregate per-agent evaluations into a crew compliance report."""
+    agents_report: Dict[str, dict] = {}
+    total_evaluations = 0
+    total_crew_violations = 0
+    violations_by_agent: Counter[str] = Counter()
+
+    for role, governor in governors.items():
+        records = governor.records
+        agent_name = vault_partition_id(governor.passport)
+        agent_violations = _agent_violation_count(records)
+        total_evaluations += len(records)
+        total_crew_violations += agent_violations
+        violations_by_agent[agent_name] = agent_violations
+
+        agents_report[role] = {
+            "agent_name": agent_name,
+            "total_evaluations": len(records),
+            "total_violations": agent_violations,
+            "violations_by_severity": _violations_by_severity(records),
+            "most_violated_rule": _most_violated_rule(records),
+            "pass_rate": round(_agent_pass_rate(records), 4),
+        }
+
+    crew_pass_rate = (
+        round(max(0.0, (total_evaluations - total_crew_violations) / total_evaluations), 4)
+        if total_evaluations
+        else 1.0
+    )
+    most_problematic_agent = (
+        violations_by_agent.most_common(1)[0][0] if violations_by_agent else None
+    )
+
+    all_severity: Counter[str] = Counter()
+    all_rules: Counter[str] = Counter()
+    for role, governor in governors.items():
+        for severity, count in _violations_by_severity(governor.records).items():
+            all_severity[severity] += count
+        rule = _most_violated_rule(governor.records)
+        if rule:
+            all_rules[rule] += _agent_violation_count(governor.records)
+
+    return {
+        "agents": agents_report,
+        "most_problematic_agent": most_problematic_agent,
+        "total_crew_violations": total_crew_violations,
+        "crew_pass_rate": crew_pass_rate,
+        "total_evaluations": total_evaluations,
+        "violations_by_severity": dict(all_severity),
+        "most_common_rule_violations": [
+            {"rule_id": rule_id, "count": count}
+            for rule_id, count in all_rules.most_common(10)
+        ],
+    }

iris_crewai/agent.py

@@ -0,0 +1,121 @@
+"""IrisCrewAgent — wrap any CrewAI agent with IRIS governance."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from iris_core.models.passport import AgentPassport
+
+from iris_crewai._governance import AgentGovernor, make_step_callback
+from iris_crewai.tools import iris_crew_tool
+
+_IRIS_CREW_AGENT_CLS: type | None = None
+
+
+def _iris_crew_agent_class() -> type:
+    global _IRIS_CREW_AGENT_CLS
+    if _IRIS_CREW_AGENT_CLS is not None:
+        return _IRIS_CREW_AGENT_CLS
+
+    from crewai import Agent
+
+    class _IrisCrewAgentImpl(Agent):
+        """
+        CrewAI Agent with per-agent IRIS governance.
+
+        Tool calls are evaluated against the agent's AgentPassport before execution.
+        step_callback records each step without altering crew output formatting.
+        """
+
+        def __init__(self, passport: AgentPassport, /, **crewai_agent_kwargs: Any):
+            governor = AgentGovernor(passport)
+            tools = crewai_agent_kwargs.get("tools")
+            if tools:
+                crewai_agent_kwargs["tools"] = _govern_tool_list(tools, passport, governor)
+
+            user_cb = crewai_agent_kwargs.pop("step_callback", None)
+            crewai_agent_kwargs["step_callback"] = make_step_callback(governor, user_cb)
+
+            super().__init__(**crewai_agent_kwargs)
+            object.__setattr__(self, "_iris_passport", passport)
+            object.__setattr__(self, "_iris_governor", governor)
+
+        def _iris_step_callback(self, agent_action: Any) -> Any:
+            """Evaluate a CrewAI step against this agent's passport."""
+            result = self._iris_governor.evaluate_step_action(agent_action)
+            self._iris_governor.record_step_llm_cost(agent_action)
+            return result
+
+        @classmethod
+        def from_crew_agent(cls, agent: Agent, passport: AgentPassport) -> "_IrisCrewAgentImpl":
+            """Wrap an existing CrewAI Agent with IRIS governance."""
+            kwargs = _agent_kwargs_from_instance(agent)
+            return cls(passport, **kwargs)
+
+    _IRIS_CREW_AGENT_CLS = _IrisCrewAgentImpl
+    return _IRIS_CREW_AGENT_CLS
+
+
+def _govern_tool_list(
+    tools: List[Any],
+    passport: AgentPassport,
+    governor: AgentGovernor,
+) -> List[Any]:
+    governed = []
+    for item in tools:
+        if hasattr(item, "_iris_governor"):
+            governed.append(item)
+            continue
+        wrapped = iris_crew_tool(item, passport, governor=governor)
+        governed.append(wrapped)
+    return governed
+
+
+def _agent_kwargs_from_instance(agent: Any) -> Dict[str, Any]:
+    fields = (
+        "role",
+        "goal",
+        "backstory",
+        "llm",
+        "tools",
+        "verbose",
+        "allow_delegation",
+        "max_iter",
+        "max_rpm",
+        "max_execution_time",
+        "memory",
+        "cache",
+        "allow_code_execution",
+        "respect_context_window",
+        "max_retry_limit",
+        "function_calling_llm",
+        "embedder",
+        "system_template",
+        "prompt_template",
+        "response_template",
+        "use_system_prompt",
+    )
+    kwargs: Dict[str, Any] = {}
+    for field in fields:
+        value = getattr(agent, field, None)
+        if value is not None:
+            kwargs[field] = value
+    return kwargs
+
+
+class IrisCrewAgent:
+    """
+    Drop-in governed CrewAI agent — two lines per agent in a crew.
+
+    Example:
+        researcher = IrisCrewAgent(researcher_passport, role="Researcher", goal="...", ...)
+    """
+
+    def __new__(cls, passport: AgentPassport, **crewai_agent_kwargs: Any) -> Any:
+        impl = _iris_crew_agent_class()
+        return impl(passport, **crewai_agent_kwargs)
+
+    @classmethod
+    def from_crew_agent(cls, agent: Any, passport: AgentPassport) -> Any:
+        impl = _iris_crew_agent_class()
+        return impl.from_crew_agent(agent, passport)

iris_crewai/crew.py

@@ -0,0 +1,144 @@
+"""IrisCrew — govern a multi-agent CrewAI crew with per-agent passports."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from iris_core.models.passport import AgentPassport, Environment
+
+from iris import IrisViolationError
+from iris_crewai._governance import AgentGovernor, build_compliance_report, resolve_environment
+
+logger = logging.getLogger("iris.crewai")
+
+
+class IrisCrew:
+    """
+    Wraps a CrewAI Crew and validates every agent has its own AgentPassport.
+
+    Example:
+        crew = IrisCrew.from_crew(
+            Crew(agents=[researcher, writer], tasks=[...]),
+            passports={"Researcher": researcher_passport, "Writer": writer_passport},
+        )
+        result = crew.kickoff(inputs={"topic": "AI governance"})
+        report = crew.compliance_report()
+    """
+
+    def __init__(
+        self,
+        crew: Any,
+        passports: Dict[str, AgentPassport],
+        governors: Dict[str, AgentGovernor],
+    ):
+        self._crew = crew
+        self._passports = passports
+        self._governors = governors
+        self._last_report: Optional[dict] = None
+        self._last_violations: list[IrisViolationError] = []
+
+    @classmethod
+    def from_crew(
+        cls,
+        crew: Any,
+        passports: Dict[str, AgentPassport],
+        user_email: Optional[str] = None,
+        user_role: Optional[str] = None,
+    ) -> "IrisCrew":
+        from iris_core.dev_trust import print_dev_trust_message
+
+        print_dev_trust_message()
+        cls._validate_passports(crew, passports, strict=True)
+        governors = cls._collect_governors(crew, passports, user_email, user_role)
+        return cls(crew, passports, governors)
+
+    @staticmethod
+    def _validate_passports(
+        crew: Any,
+        passports: Dict[str, AgentPassport],
+        *,
+        strict: bool = True,
+    ) -> None:
+        agent_roles = [agent.role for agent in crew.agents]
+        missing = [role for role in agent_roles if role not in passports]
+        if not missing:
+            return
+
+        message = (
+            "Every agent in the crew must have an AgentPassport keyed by role name. "
+            f"Missing passports for: {', '.join(missing)}"
+        )
+        env = resolve_environment()
+        if strict or env in (Environment.STAGING, Environment.PRODUCTION):
+            raise ValueError(message)
+        logger.warning(message)
+
+    @staticmethod
+    def _collect_governors(
+        crew: Any,
+        passports: Dict[str, AgentPassport],
+        user_email: Optional[str] = None,
+        user_role: Optional[str] = None,
+    ) -> Dict[str, AgentGovernor]:
+        governors: Dict[str, AgentGovernor] = {}
+        for agent in crew.agents:
+            role = agent.role
+            if hasattr(agent, "_iris_governor"):
+                governors[role] = agent._iris_governor
+            else:
+                governors[role] = AgentGovernor(
+                    passports[role],
+                    user_email=user_email,
+                    user_role=user_role,
+                )
+        return governors
+
+    def kickoff(self, inputs: Optional[dict] = None, **kwargs: Any) -> dict:
+        """
+        Run the governed crew.
+
+        Returns a dict with ``result`` (crew output) and ``compliance`` summary.
+        Compliance report is always generated, even when kickoff fails.
+        """
+        self._last_violations = []
+        env = resolve_environment()
+        self._validate_passports(self._crew, self._passports, strict=False)
+
+        if env in (Environment.STAGING, Environment.PRODUCTION):
+            missing = [
+                role
+                for role in (agent.role for agent in self._crew.agents)
+                if role not in self._passports
+            ]
+            if missing:
+                raise ValueError(
+                    "Cannot kickoff crew in production without passports for all agents. "
+                    f"Missing passports for: {', '.join(missing)}"
+                )
+
+        crew_result: Any = None
+        try:
+            crew_result = self._crew.kickoff(inputs=inputs, **kwargs)
+        except IrisViolationError as exc:
+            self._last_violations.append(exc)
+            for violation in exc.result.violations:
+                logger.error(
+                    "IRIS violation during crew kickoff [%s]: %s",
+                    violation.rule_id,
+                    violation.message,
+                )
+        finally:
+            self._last_report = build_compliance_report(self._governors)
+
+        return {
+            "result": crew_result,
+            "compliance": self._last_report,
+            "violations": [exc.result.decision for exc in self._last_violations],
+        }
+
+    def compliance_report(self) -> dict:
+        """Return crew compliance summary with per-agent violation counts."""
+        if self._last_report is not None:
+            return self._last_report
+        return build_compliance_report(self._governors)

iris_crewai/tools.py

@@ -0,0 +1,92 @@
+"""iris_crew_tool — Cedar-governed CrewAI tools."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from iris_core.models.passport import AgentPassport, Environment
+
+from iris_crewai._governance import AgentGovernor, enforce_result
+
+
+def iris_crew_tool(
+    tool_func: Any,
+    passport: AgentPassport,
+    action: str = "call",
+    environment: Optional[str] = None,
+    governor: Optional[AgentGovernor] = None,
+) -> Any:
+    """
+    Wrap a CrewAI @tool-decorated function or Tool with IRIS policy evaluation.
+
+    Preserves tool name, description, and args_schema metadata.
+
+    Example:
+        safe_search = iris_crew_tool(search_tool, passport, action="call")
+    """
+    env = Environment(environment) if environment else None
+    active_governor = governor or AgentGovernor(passport, environment=env)
+
+    def _evaluate(inputs: Optional[dict]) -> None:
+        resource = _tool_resource_name(tool_func)
+        result = active_governor.evaluate_tool(action=action, resource=resource, inputs=inputs)
+        enforce_result(result, active_governor.env)
+
+    if _is_crewai_tool(tool_func):
+        return _wrap_base_tool(tool_func, _evaluate)
+
+    if callable(tool_func):
+        decorated = _ensure_crew_tool(tool_func)
+        return _wrap_base_tool(decorated, _evaluate)
+
+    raise TypeError(
+        "iris_crew_tool expects a crewai Tool/BaseTool instance or @tool-decorated callable."
+    )
+
+
+def _is_crewai_tool(obj: Any) -> bool:
+    try:
+        from crewai.tools.base_tool import BaseTool
+
+        return isinstance(obj, BaseTool)
+    except ImportError:
+        return hasattr(obj, "name") and hasattr(obj, "run") and hasattr(obj, "func")
+
+
+def _ensure_crew_tool(func: Callable[..., Any]) -> Any:
+    if _is_crewai_tool(func):
+        return func
+    from crewai.tools import tool as crew_tool_decorator
+
+    return crew_tool_decorator(func)
+
+
+def _tool_resource_name(tool: Any) -> str:
+    return getattr(tool, "name", getattr(tool, "__name__", "tool"))
+
+
+def _normalize_inputs(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Optional[dict]:
+    if kwargs:
+        return kwargs
+    if args and isinstance(args[0], dict):
+        return args[0]
+    return None
+
+
+def _wrap_base_tool(tool: Any, evaluate: Callable[[Optional[dict]], None]) -> Any:
+    from crewai.tools.base_tool import Tool
+
+    original_func = tool.func
+
+    def guarded_func(*args: Any, **kwargs: Any) -> Any:
+        evaluate(_normalize_inputs(args, kwargs))
+        return original_func(*args, **kwargs)
+
+    return Tool(
+        name=tool.name,
+        description=tool.description,
+        func=guarded_func,
+        args_schema=tool.args_schema,
+        result_as_answer=getattr(tool, "result_as_answer", False),
+        max_usage_count=getattr(tool, "max_usage_count", None),
+    )

iris_security_crewai-0.1.1.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: iris-security-crewai
+Version: 0.1.1
+Summary: IRIS governance for CrewAI crews — Cedar policy on every agent tool 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
+Requires-Dist: iris-security-core>=0.1.2
+Requires-Dist: iris-security-sdk>=0.1.0
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.30; extra == "crewai"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"

iris_security_crewai-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+examples/governed_crew.py,sha256=NrRVJOFL2JSMQ_ZjcJDFZxNL69Doem2yM9m17Esn_qw,2418
+iris_crewai/__init__.py,sha256=Pv-XLny3Y1Qn_4jZ_QN9OdHC1cPr_Xlj9IJV07NCfns,1128
+iris_crewai/_governance.py,sha256=Kj8RMTCOT0gFb0CbCkaGBApsBCB-3FKJnGlY2ryoU6s,14878
+iris_crewai/agent.py,sha256=StrPdGm950gU0Rv_ae5sJ-ZaXjQOffH_PsCYwn96XHg,3856
+iris_crewai/crew.py,sha256=YvRWxS2vgfdMPiA9Eiu1NC7IX6LJZAkDAJ20FRtvc-4,4974
+iris_crewai/tools.py,sha256=uL8Cjb3kn-OhbM3moLuW3cWDEv5jJfAzYFMM1NkHiyk,2809
+tests/conftest.py,sha256=sm1aXg5mjLSgCZa0zAEHg1KLIGJRTuXMJZ2h_eshOd0,309
+tests/test_crewai_integration.py,sha256=rhrltYKiczEDfrTz8g5H8fhGaK4KmMAOIz4vBYeDxWg,10834
+iris_security_crewai-0.1.1.dist-info/METADATA,sha256=aa-UnL1e9Gle6pDoPD89BNoaxexrI96235yBy7nMd4I,613
+iris_security_crewai-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+iris_security_crewai-0.1.1.dist-info/top_level.txt,sha256=AVozfVQnYp2-_HkraadYbTpQgLkApkH3d-2GSMC1buo,27
+iris_security_crewai-0.1.1.dist-info/RECORD,,

iris_security_crewai-0.1.1.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_crewai-0.1.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+examples
+iris_crewai
+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_crewai_integration.py

@@ -0,0 +1,324 @@
+"""
+Integration tests for iris-crewai agent wrapper, crew wrapper, and tool guard.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+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_crewai import IrisCrew, IrisCrewAgent, iris_crew_tool
+from iris_crewai._governance import EvaluationRecord, vault_partition_id
+
+
+@pytest.fixture
+def permitted_passport():
+    return AgentPassport(
+        name="researcher-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/researcher-agent/policy-intent.md",
+        tool_permissions=[
+            ToolPermission(
+                tool_id="web_search",
+                description="Web search",
+                allowed_actions=["call"],
+            ),
+        ],
+    )
+
+
+@pytest.fixture
+def writer_passport():
+    return AgentPassport(
+        name="writer-agent",
+        owner="team@company.com",
+        compliance_tags=[ComplianceTag.COLORADO_AI_ACT],
+        tool_permissions=[
+            ToolPermission(
+                tool_id="write_summary",
+                description="Write summary",
+                allowed_actions=["call"],
+            ),
+        ],
+    )
+
+
+@pytest.fixture
+def engine_with_policy(permitted_passport):
+    engine = CedarEngine()
+    engine.load_policy(permitted_passport.agent_id, "permit(principal, action, resource);")
+    return engine
+
+
+class TestIrisCrewAgent:
+    def test_crew_agent_blocks_denied_tool_in_production(
+        self, permitted_passport, engine_with_policy, tmp_path
+    ):
+        from crewai.tools import tool
+
+        policy_file = tmp_path / "policy.cedar"
+        policy_file.write_text("permit(principal, action, resource);")
+        permitted_passport.policy_ref = str(policy_file)
+
+        @tool
+        def payments_api(action: str) -> str:
+            """Execute a payment."""
+            return action
+
+        agent = IrisCrewAgent(
+            permitted_passport,
+            role="Researcher",
+            goal="Research",
+            backstory="Analyst",
+            tools=[payments_api],
+        )
+        agent._iris_governor._engine = engine_with_policy
+        agent._iris_governor.env = Environment.PRODUCTION
+        governed_tool = agent.tools[0]
+
+        with pytest.raises(IrisViolationError) as exc_info:
+            governed_tool.run(action="transfer")
+
+        assert exc_info.value.result.decision == "DENY"
+        assert any(v.rule_id == "IRIS-TOOL-001" for v in exc_info.value.result.violations)
+
+    def test_crew_agent_permits_allowed_tool(
+        self, permitted_passport, engine_with_policy, tmp_path
+    ):
+        from crewai.tools import tool
+
+        policy_file = tmp_path / "policy.cedar"
+        policy_file.write_text("permit(principal, action, resource);")
+        permitted_passport.policy_ref = str(policy_file)
+
+        @tool
+        def web_search(query: str, data_region: str = "us-east-1") -> str:
+            """Search the web."""
+            return query
+
+        agent = IrisCrewAgent(
+            permitted_passport,
+            role="Researcher",
+            goal="Research",
+            backstory="Analyst",
+            tools=[web_search],
+        )
+        agent._iris_governor._engine = engine_with_policy
+        governed_tool = agent.tools[0]
+
+        result = governed_tool.run(query="AI governance", data_region="us-east-1")
+        assert result == "AI governance"
+
+
+class TestIrisCrew:
+    def test_crew_requires_all_passports(self, permitted_passport, writer_passport):
+        from crewai import Crew
+
+        researcher = IrisCrewAgent(
+            permitted_passport,
+            role="Researcher",
+            goal="Research",
+            backstory="Analyst",
+        )
+        writer = IrisCrewAgent(
+            writer_passport,
+            role="Writer",
+            goal="Write",
+            backstory="Writer",
+        )
+        base_crew = Crew(agents=[researcher, writer], tasks=[], verbose=False)
+
+        with pytest.raises(ValueError, match="Missing passports"):
+            IrisCrew.from_crew(base_crew, passports={"Researcher": permitted_passport})
+
+    def test_missing_passport_raises_clear_error(self, permitted_passport, writer_passport):
+        from crewai import Crew
+
+        researcher = IrisCrewAgent(
+            permitted_passport,
+            role="Researcher",
+            goal="Research",
+            backstory="Analyst",
+        )
+        writer = IrisCrewAgent(
+            writer_passport,
+            role="Writer",
+            goal="Write",
+            backstory="Writer",
+        )
+        base_crew = Crew(agents=[researcher, writer], tasks=[], verbose=False)
+
+        with pytest.raises(ValueError) as exc_info:
+            IrisCrew.from_crew(base_crew, passports={"Researcher": permitted_passport})
+
+        message = str(exc_info.value)
+        assert "Missing passports for: Writer" in message
+        assert "AgentPassport keyed by role name" in message
+
+    def test_crew_generates_compliance_report(self, permitted_passport, writer_passport):
+        researcher = IrisCrewAgent(
+            permitted_passport,
+            role="Researcher",
+            goal="Research",
+            backstory="Analyst",
+        )
+        writer = IrisCrewAgent(
+            writer_passport,
+            role="Writer",
+            goal="Write",
+            backstory="Writer",
+        )
+
+        researcher._iris_governor.records.append(
+            EvaluationRecord(
+                agent_name="researcher-agent",
+                action="call",
+                resource="web_search",
+                decision="PERMIT",
+            )
+        )
+        writer._iris_governor.records.append(
+            EvaluationRecord(
+                agent_name="writer-agent",
+                action="call",
+                resource="secret-tool",
+                decision="DENY",
+                violations=[
+                    {"rule_id": "IRIS-TOOL-001", "severity": "critical", "message": "blocked"}
+                ],
+            )
+        )
+
+        base_crew = MagicMock()
+        base_crew.agents = [researcher, writer]
+        base_crew.kickoff.return_value = "done"
+
+        crew = IrisCrew.from_crew(
+            base_crew,
+            passports={"Researcher": permitted_passport, "Writer": writer_passport},
+        )
+        kickoff_payload = crew.kickoff(inputs={"topic": "AI governance"})
+        report = crew.compliance_report()
+
+        assert kickoff_payload["result"] == "done"
+        assert kickoff_payload["compliance"] == report
+        assert report["total_evaluations"] == 2
+        assert report["total_crew_violations"] == 1
+        assert report["crew_pass_rate"] == 0.5
+        assert report["most_problematic_agent"] == "writer-agent"
+        assert report["agents"]["Researcher"]["pass_rate"] == 1.0
+        assert report["agents"]["Writer"]["total_violations"] == 1
+        assert report["agents"]["Writer"]["most_violated_rule"] == "IRIS-TOOL-001"
+        assert report["violations_by_severity"]["critical"] == 1
+
+    def test_per_agent_evidence_vault_partition(
+        self, permitted_passport, writer_passport, tmp_path, monkeypatch
+    ):
+        monkeypatch.setenv("HOME", str(tmp_path))
+
+        researcher = IrisCrewAgent(
+            permitted_passport,
+            role="Researcher",
+            goal="Research",
+            backstory="Analyst",
+        )
+        writer = IrisCrewAgent(
+            writer_passport,
+            role="Writer",
+            goal="Write",
+            backstory="Writer",
+        )
+
+        researcher._iris_governor.evaluate_tool(
+            action="call",
+            resource="web_search",
+            inputs={"query": "AI governance", "data_region": "us-east-1"},
+        )
+        writer._iris_governor.evaluate_tool(
+            action="call",
+            resource="write_summary",
+            inputs={"content": "summary"},
+        )
+
+        researcher_vault_path = (
+            Path(tmp_path) / ".iris" / "evidence" / vault_partition_id(permitted_passport)
+        )
+        writer_vault_path = (
+            Path(tmp_path) / ".iris" / "evidence" / vault_partition_id(writer_passport)
+        )
+
+        assert researcher_vault_path.exists()
+        assert writer_vault_path.exists()
+        assert researcher_vault_path != writer_vault_path
+
+        researcher_vault = EvidenceVault(agent_id=vault_partition_id(permitted_passport))
+        writer_vault = EvidenceVault(agent_id=vault_partition_id(writer_passport))
+
+        assert len(researcher_vault.get_events()) >= 1
+        assert len(writer_vault.get_events()) >= 1
+        assert all(
+            e["agent_id"] == vault_partition_id(permitted_passport)
+            for e in researcher_vault.get_events()
+        )
+        assert all(
+            e["agent_id"] == vault_partition_id(writer_passport)
+            for e in writer_vault.get_events()
+        )
+
+
+class TestIrisCrewTool:
+    def test_iris_crew_tool_decorator(self, permitted_passport, engine_with_policy, tmp_path):
+        from crewai.tools import tool
+
+        policy_file = tmp_path / "policy.cedar"
+        policy_file.write_text("permit(principal, action, resource);")
+        permitted_passport.policy_ref = str(policy_file)
+
+        @tool
+        def web_search(query: str, data_region: str = "us-east-1") -> str:
+            """Search the web."""
+            return query
+
+        guarded = iris_crew_tool(web_search, permitted_passport, environment="dev")
+        assert guarded.name == "web_search"
+        assert "Search the web" in guarded.description
+        assert guarded.args_schema is not None
+
+        result = guarded.run(query="AI governance", data_region="us-east-1")
+        assert result == "AI governance"
+
+    def test_iris_crew_tool_blocks_undeclared_in_prod(
+        self, permitted_passport, engine_with_policy, tmp_path
+    ):
+        from crewai.tools import tool
+
+        policy_file = tmp_path / "policy.cedar"
+        policy_file.write_text("permit(principal, action, resource);")
+        permitted_passport.policy_ref = str(policy_file)
+
+        @tool
+        def secret_tool(action: str) -> str:
+            """Perform a sensitive action."""
+            return action
+
+        guarded = iris_crew_tool(secret_tool, permitted_passport, environment="production")
+        with pytest.raises(IrisViolationError):
+            guarded.run(action="transfer")