arceo 0.1.0__tar.gz

arceo-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: arceo
+Version: 0.1.0
+Summary: Monitor any AI agent's tool calls and get a risk report.
+Author: Arceo
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.50; extra == "crewai"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: backend
+Requires-Dist: httpx>=0.27; extra == "backend"
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == "cli"
+Requires-Dist: pyyaml>=6.0; extra == "cli"
+Requires-Dist: httpx>=0.27; extra == "cli"
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.2; extra == "all"
+Requires-Dist: crewai>=0.50; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: anthropic>=0.30; extra == "all"
+Requires-Dist: httpx>=0.27; extra == "all"
+Requires-Dist: click>=8.0; extra == "all"
+Requires-Dist: pyyaml>=6.0; extra == "all"
+Dynamic: author
+Dynamic: requires-python

arceo-0.1.0/arceo/__init__.py

@@ -0,0 +1,28 @@
+"""Arceo SDK — monitor any AI agent's tool calls and get a risk report.
+
+    from arceo import monitor, tool
+
+    @tool(service="stripe", risk="moves_money")
+    def create_refund(customer_id, amount):
+        ...
+
+    @monitor(verbose=True)
+    def my_agent(prompt):
+        ...
+
+    # Or local analysis with no agent execution:
+    from arceo import analyze_local
+    analyze_local(tools=[{"name": "stripe", "actions": ["create_refund"]}])
+"""
+
+from arceo.decorator import monitor, analyze_local, ArceoSecurityError
+from arceo.client import ArceoClient
+from arceo.models import ArceoTrace, ArceoToolCall, ArceoToolSchema, ArceoLLMCall
+from arceo.frameworks.vanilla import tool
+
+__all__ = [
+    "monitor", "analyze_local", "ArceoSecurityError",
+    "ArceoClient", "ArceoTrace", "ArceoToolCall", "ArceoToolSchema", "ArceoLLMCall",
+    "tool",
+]
+__version__ = "0.1.0"

arceo-0.1.0/arceo/analysis/__init__.py

@@ -0,0 +1 @@
+from arceo.analysis.risk import infer_risk, infer_verb, detect_chains_local

arceo-0.1.0/arceo/analysis/risk.py

@@ -0,0 +1,172 @@
+"""Local risk inference — runs in <10ms, no LLM, no network."""
+
+from __future__ import annotations
+
+VERB_MAP = {
+    "get": "read", "list": "read", "read": "read", "describe": "read",
+    "fetch": "read", "search": "read", "query": "read", "check": "read",
+    "find": "read", "lookup": "read", "show": "read", "view": "read",
+    "create": "create", "add": "create", "insert": "create", "post": "create",
+    "new": "create", "register": "create", "provision": "create",
+    "update": "update", "modify": "update", "patch": "update", "set": "update",
+    "edit": "update", "change": "update", "configure": "update",
+    "delete": "delete", "remove": "delete", "destroy": "delete", "purge": "delete",
+    "drop": "delete", "wipe": "delete", "erase": "delete", "revoke": "delete",
+    "send": "send", "email": "send", "notify": "send", "publish": "send",
+    "broadcast": "send", "forward": "send", "export": "send", "post": "send",
+    "deploy": "execute", "migrate": "execute", "scale": "execute",
+    "restart": "execute", "terminate": "execute", "reboot": "execute",
+    "rollback": "execute", "trigger": "execute", "merge": "execute",
+    "pay": "transact", "charge": "transact", "refund": "transact",
+    "transfer": "transact", "payout": "transact", "invoice": "transact",
+    "void": "transact", "cancel": "transact",
+}
+
+SERVICE_RISK = {
+    "stripe": "moves_money", "square": "moves_money", "paypal": "moves_money",
+    "braintree": "moves_money", "quickbooks": "moves_money",
+    "gmail": "sends_external", "sendgrid": "sends_external", "ses": "sends_external",
+    "mailgun": "sends_external", "twilio": "sends_external",
+    "salesforce": "touches_pii", "hubspot": "touches_pii", "zendesk": "touches_pii",
+    "bamboohr": "touches_pii", "clearbit": "touches_pii", "intercom": "touches_pii",
+}
+
+INFRA_SERVICES = {"aws", "gcp", "azure", "aws_ec2", "aws_ecs", "aws_rds", "aws_iam", "aws_s3"}
+
+ARG_HINTS = {
+    "touches_pii": {"email", "phone", "ssn", "address", "dob", "date_of_birth",
+                     "first_name", "last_name", "name", "social_security", "customer_id"},
+    "moves_money": {"amount", "price", "cents", "currency", "total", "subtotal", "payment_id"},
+    "sends_external": {"to", "recipient", "destination", "webhook_url", "email_to"},
+}
+
+LABEL_TRANSITIONS = [
+    ("touches_pii", "sends_external", "potential_exfiltration", "critical"),
+    ("touches_pii", "moves_money", "pii_to_financial", "critical"),
+    ("touches_pii", "deletes_data", "pii_then_delete", "critical"),
+    ("moves_money", "deletes_data", "fraud_and_cover", "critical"),
+    ("moves_money", "sends_external", "money_then_external", "high"),
+    ("changes_production", "deletes_data", "infrastructure_destruction", "critical"),
+    ("changes_production", "changes_production", "cascading_changes", "high"),
+    ("deletes_data", "sends_external", "destroy_and_exfil", "high"),
+]
+
+READ_PREFIXES = ("get_", "list_", "read_", "describe_", "fetch_", "search_", "query_", "check_", "find_", "show_")
+
+
+def infer_verb(action_name: str) -> str:
+    """Infer the verb category from an action name."""
+    lower = action_name.lower()
+    for prefix, verb in VERB_MAP.items():
+        if lower.startswith(prefix + "_") or lower.startswith(prefix):
+            return verb
+    return "unknown"
+
+
+def infer_risk(tool_name: str, action_name: str, arg_keys: list = None) -> tuple[list, bool]:
+    """Infer risk hints from tool name, action name, and argument keys.
+
+    Returns (risk_hints, is_read_only). Runs in <1ms.
+    """
+    hints = set()
+    lower_action = action_name.lower()
+    lower_tool = tool_name.lower()
+    is_read_only = lower_action.startswith(READ_PREFIXES)
+
+    # From verb
+    verb = infer_verb(action_name)
+    if verb == "delete":
+        hints.add("deletes_data")
+    elif verb == "send":
+        hints.add("sends_external")
+    elif verb == "transact":
+        hints.add("moves_money")
+    elif verb == "execute":
+        hints.add("changes_production")
+
+    # From service name
+    if lower_tool in SERVICE_RISK:
+        hints.add(SERVICE_RISK[lower_tool])
+    if lower_tool in INFRA_SERVICES and not is_read_only:
+        hints.add("changes_production")
+
+    # From action keywords
+    money_words = {"refund", "charge", "pay", "transfer", "payout", "invoice", "billing", "subscription", "price"}
+    pii_words = {"customer", "user", "contact", "account", "personal", "profile", "patient", "employee"}
+    send_words = {"send", "email", "notify", "message", "sms", "alert", "forward", "export"}
+    delete_words = {"delete", "remove", "destroy", "purge", "drop", "wipe", "terminate", "cancel", "revoke"}
+    prod_words = {"deploy", "merge", "release", "scale", "restart", "migrate", "provision", "reboot", "rollback"}
+
+    for w in money_words:
+        if w in lower_action:
+            hints.add("moves_money")
+    for w in pii_words:
+        if w in lower_action:
+            hints.add("touches_pii")
+    for w in send_words:
+        if w in lower_action:
+            hints.add("sends_external")
+    for w in delete_words:
+        if w in lower_action:
+            hints.add("deletes_data")
+    for w in prod_words:
+        if w in lower_action:
+            hints.add("changes_production")
+
+    # From argument keys
+    if arg_keys:
+        lower_keys = {k.lower() for k in arg_keys}
+        for label, hint_keys in ARG_HINTS.items():
+            if lower_keys & hint_keys:
+                hints.add(label)
+
+    return sorted(hints), is_read_only
+
+
+def detect_chains_local(tool_calls) -> list:
+    """Detect dangerous chains from a sequence of tool calls. No network.
+
+    tool_calls: list of ArceoToolCall objects
+    Returns list of chain dicts.
+
+    A chain requires at least one non-read-only step — pure read sequences
+    (e.g. list_customers → get_customer) are not flagged as dangerous.
+    """
+    if len(tool_calls) < 2:
+        return []
+
+    # Build (index, risk_hints, is_read_only) triples
+    steps = [(i, set(tc.inferred_risk_hints), tc.is_read_only) for i, tc in enumerate(tool_calls)]
+
+    chains = []
+    seen = set()
+
+    for from_label, to_label, chain_name, severity in LABEL_TRANSITIONS:
+        if chain_name in seen:
+            continue
+        for i, (idx_a, hints_a, ro_a) in enumerate(steps):
+            if from_label not in hints_a:
+                continue
+            for idx_b, hints_b, ro_b in steps[i + 1:]:
+                if to_label not in hints_b:
+                    continue
+                # Skip chains where both steps are read-only — not actually dangerous
+                if ro_a and ro_b:
+                    continue
+                # Same label needs different operations
+                if from_label == to_label:
+                    if tool_calls[idx_a].full_operation == tool_calls[idx_b].full_operation:
+                        continue
+                chains.append({
+                    "chain_name": chain_name,
+                    "severity": severity,
+                    "from_label": from_label,
+                    "to_label": to_label,
+                    "steps": [idx_a, idx_b],
+                    "from_operation": tool_calls[idx_a].full_operation,
+                    "to_operation": tool_calls[idx_b].full_operation,
+                })
+                seen.add(chain_name)
+                break
+
+    return chains

arceo-0.1.0/arceo/ci.py

@@ -0,0 +1,106 @@
+"""CI output formatting and exit code handling."""
+
+from __future__ import annotations
+
+from arceo.scanner import ScanResult
+
+
+def format_results(results: list[ScanResult], verbose: bool = False) -> str:
+    """Format scan results for terminal output."""
+    lines = ["", "arceo scan results:"]
+
+    for r in results:
+        lines.append(f"  {r.agent_name}:")
+
+        if r.error:
+            lines.append(f"    error: {r.error}")
+            continue
+
+        # Blast radius
+        icon = "pass" if r.blast_radius_pass else "FAIL"
+        threshold = f" (threshold: {r.blast_radius:.0f})" if not r.blast_radius_pass else ""
+        lines.append(f"    blast_radius: {r.blast_radius:.0f}/100 {icon}{threshold}")
+
+        # Chains
+        icon = "pass" if r.chains_pass else "FAIL"
+        if r.chains_detected > 0:
+            chain_detail = f" ({', '.join(r.chain_names[:3])})" if r.chain_names else ""
+            lines.append(f"    dangerous_chains: {r.chains_detected} {icon}{chain_detail}")
+        else:
+            lines.append(f"    dangerous_chains: 0 {icon}")
+
+        # Policy violations
+        icon = "pass" if r.policy_pass else "FAIL"
+        if r.approval_violations:
+            detail = f" ({', '.join(r.approval_violations[:3])})"
+            lines.append(f"    policy_violations: {len(r.approval_violations)} {icon}{detail}")
+        else:
+            lines.append(f"    policy_violations: 0 {icon}")
+
+        # Extra detail in verbose mode
+        if verbose and r.report:
+            if r.violations_count > 0:
+                lines.append(f"    violations: {r.violations_count}")
+                for v in r.violation_details[:5]:
+                    lines.append(f"      - {v}")
+            if r.data_flows_count > 0:
+                lines.append(f"    data_flows: {r.data_flows_count}")
+            if r.risk_score > 0:
+                lines.append(f"    simulation_risk: {r.risk_score:.1f}/100")
+
+    # Summary
+    failed = [r for r in results if not r.passed]
+    lines.append("")
+    if failed:
+        lines.append(f"  FAILED: {len(failed)} agent(s) exceeded policy thresholds")
+    else:
+        lines.append(f"  PASSED: all {len(results)} agent(s) within policy")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def format_github_comment(results: list[ScanResult]) -> str:
+    """Format results as a GitHub PR comment (markdown)."""
+    lines = ["## Arceo Scan Results", ""]
+
+    all_passed = all(r.passed for r in results)
+
+    for r in results:
+        status = "PASS" if r.passed else "FAIL"
+        lines.append(f"### {r.agent_name} — {status}")
+
+        if r.error:
+            lines.append(f"> Error: {r.error}")
+            lines.append("")
+            continue
+
+        lines.append("")
+        lines.append("| Check | Result | Detail |")
+        lines.append("|-------|--------|--------|")
+
+        br_icon = "PASS" if r.blast_radius_pass else "FAIL"
+        lines.append(f"| Blast Radius | {br_icon} | {r.blast_radius:.0f}/100 |")
+
+        ch_icon = "PASS" if r.chains_pass else "FAIL"
+        chains_detail = ", ".join(r.chain_names[:3]) if r.chain_names else "none"
+        lines.append(f"| Dangerous Chains | {ch_icon} | {r.chains_detected} ({chains_detail}) |")
+
+        pv_icon = "PASS" if r.policy_pass else "FAIL"
+        pv_detail = ", ".join(r.approval_violations[:3]) if r.approval_violations else "none"
+        lines.append(f"| Policy Violations | {pv_icon} | {len(r.approval_violations)} ({pv_detail}) |")
+
+        lines.append("")
+
+    if all_passed:
+        lines.append("**All agents passed policy checks.**")
+    else:
+        failed = [r.agent_name for r in results if not r.passed]
+        lines.append(f"**FAILED:** {', '.join(failed)} exceeded policy thresholds.")
+
+    return "\n".join(lines)
+
+
+def get_exit_code(results: list[ScanResult]) -> int:
+    """Return 0 if all passed, 1 if any failed."""
+    return 0 if all(r.passed for r in results) else 1

arceo-0.1.0/arceo/cli.py

@@ -0,0 +1,78 @@
+"""CLI: arceo scan — runs Arceo simulation on agent code."""
+
+from __future__ import annotations
+
+import sys
+
+try:
+    import click
+except ImportError:
+    # Minimal fallback if click not installed
+    class click:
+        @staticmethod
+        def command(*a, **k):
+            def d(f): return f
+            return d
+        @staticmethod
+        def option(*a, **k):
+            def d(f): return f
+            return d
+        @staticmethod
+        def group(*a, **k):
+            def d(f): return f
+            return d
+
+
+from arceo.config import load_config
+from arceo.scanner import scan_all
+from arceo.ci import format_results, format_github_comment, get_exit_code
+
+
+@click.group()
+def cli():
+    """Arceo — AI agent risk scanner."""
+    pass
+
+
+@cli.command()
+@click.option("--config", "-c", default="arceo.yaml", help="Path to arceo.yaml config file")
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed output")
+@click.option("--format", "output_format", type=click.Choice(["text", "github"]), default="text", help="Output format")
+@click.option("--url", default=None, help="Override Arceo backend URL")
+def scan(config, verbose, output_format, url):
+    """Scan all agents defined in arceo.yaml against policy thresholds."""
+    try:
+        cfg = load_config(config)
+    except FileNotFoundError:
+        click.echo(f"Error: Config file '{config}' not found.", err=True)
+        click.echo("Create an arceo.yaml file. See: https://github.com/Nikhilrangaa/ActionGate", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"Error loading config: {e}", err=True)
+        sys.exit(1)
+
+    if url:
+        cfg.arceo_url = url
+
+    if not cfg.agents:
+        click.echo("No agents defined in config.", err=True)
+        sys.exit(1)
+
+    click.echo(f"Scanning {len(cfg.agents)} agent(s)...")
+
+    results = scan_all(cfg)
+
+    if output_format == "github":
+        click.echo(format_github_comment(results))
+    else:
+        click.echo(format_results(results, verbose=verbose))
+
+    sys.exit(get_exit_code(results))
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

arceo-0.1.0/arceo/client.py

@@ -0,0 +1,38 @@
+"""HTTP client for the Arceo backend."""
+
+from __future__ import annotations
+
+import sys
+from arceo.models import ArceoTrace
+
+
+class ArceoClient:
+    def __init__(self, api_url="http://localhost:8000", api_key="", timeout=30.0):
+        self.api_url = api_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def analyze(self, trace: ArceoTrace) -> dict:
+        """Send trace to backend. Returns raw response dict or None."""
+        try:
+            import httpx
+        except ImportError:
+            print("Arceo: httpx not installed, skipping backend. pip install httpx", file=sys.stderr)
+            return None
+
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+
+        try:
+            resp = httpx.post(
+                "%s/api/sdk/analyze-trace" % self.api_url,
+                json=trace.to_api_payload(),
+                headers=headers,
+                timeout=self.timeout,
+            )
+            resp.raise_for_status()
+            return resp.json()
+        except Exception as e:
+            print("Arceo: Backend unreachable (%s), local analysis only." % e, file=sys.stderr)
+            return None

arceo-0.1.0/arceo/config.py

@@ -0,0 +1,65 @@
+"""Parses arceo.yaml config file."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class AgentConfig:
+    name: str
+    entry: str
+    decorator: str = "arceo.monitor"
+
+
+@dataclass
+class PolicyConfig:
+    max_blast_radius: float = 100.0
+    block_chains: bool = False
+    require_approval_for: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ArceoConfig:
+    agents: list[AgentConfig] = field(default_factory=list)
+    policy: PolicyConfig = field(default_factory=PolicyConfig)
+    arceo_url: str = "http://localhost:8000"
+    api_key: str = ""
+
+
+def load_config(path: str | Path = "arceo.yaml") -> ArceoConfig:
+    """Load and parse arceo.yaml from the given path."""
+    config_path = Path(path)
+
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+
+    with open(config_path) as f:
+        raw = yaml.safe_load(f)
+
+    if not raw:
+        raise ValueError("Empty config file")
+
+    agents = []
+    for a in raw.get("agents", []):
+        agents.append(AgentConfig(
+            name=a["name"],
+            entry=a.get("entry", ""),
+            decorator=a.get("decorator", "arceo.monitor"),
+        ))
+
+    policy_raw = raw.get("policy", {})
+    policy = PolicyConfig(
+        max_blast_radius=float(policy_raw.get("max_blast_radius", 100)),
+        block_chains=bool(policy_raw.get("block_chains", False)),
+        require_approval_for=policy_raw.get("require_approval_for", []),
+    )
+
+    arceo_url = raw.get("arceo_url", os.getenv("ARCEO_URL", "http://localhost:8000"))
+    api_key = raw.get("api_key", os.getenv("ARCEO_API_KEY", ""))
+
+    return ArceoConfig(agents=agents, policy=policy, arceo_url=arceo_url, api_key=api_key)