correctover-ccs 1.0.0__tar.gz

correctover_ccs-1.0.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: correctover-ccs
+Version: 1.0.0
+Summary: Correctover Conformance Standard (CCS) v1.0 — Synchronous interceptor governance for AI Agent frameworks
+Author-email: Correctover Standards <wangguigui@correctover.com>
+License: CC BY 4.0
+Project-URL: Homepage, https://correctover.com
+Project-URL: Paper, https://doi.org/10.5281/zenodo.21271910
+Project-URL: Standard, https://github.com/Correctover/standards
+Keywords: ai,agent,governance,security,conformance,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+
+# CCS — Correctover Conformance Standard v1.0
+
+Synchronous interceptor-based governance for AI Agent frameworks.
+
+## Why CCS?
+
+Every major Agent framework (CrewAI AGT, AutoGen, LangGraph) uses **observer-pattern hooks** for governance. These hooks are structurally vulnerable to **fail-open bypass** — when the governance layer throws an exception, the framework defaults to allowing tool execution.
+
+**This is not a bug. It's an architectural flaw.** (CWE-636, CVSS 9.1)
+
+CCS uses **function decorators** instead of hooks. The decorator owns the execution path — if governance fails, the tool is BLOCKED. Never allowed.
+
+```
+Observer hooks:  governance_crash → exception caught → hook_blocked=False → tool EXECUTES ❌
+CCS decorators:  governance_crash → exception caught → tool NEVER CALLED ✅
+```
+
+## Installation
+
+```bash
+pip install ccs
+```
+
+## Quick Start (3 lines)
+
+```python
+from ccs import govern
+
+@govern(policy="default")
+def my_tool(args: dict) -> str:
+    return "result"
+
+# Governance evaluation happens BEFORE the function runs
+# If denied → PermissionError, function never executes
+```
+
+## Framework Adapters
+
+Adapters intercept at the framework's tool execution entry point.
+Once installed, ALL tool calls go through CCS governance.
+
+### CrewAI
+```python
+from ccs.adapters import crewai_adapter
+crewai_adapter.install()   # patches BaseTool.run globally
+# All CrewAI tool calls now governed by CCS
+crewai_adapter.uninstall() # restore original
+```
+
+### AutoGen (async)
+```python
+from ccs.adapters import autogen_adapter
+autogen_adapter.install()  # patches FunctionTool.run
+autogen_adapter.uninstall()
+```
+
+### LangGraph / LangChain
+```python
+from ccs.adapters import langgraph_adapter
+langgraph_adapter.install()  # patches LCBaseTool.run
+langgraph_adapter.uninstall()
+```
+
+### Verified Against
+| Framework | Version | Interception Point | Pattern |
+|-----------|---------|--------------------|---------|
+| CrewAI | >= 0.1.0 | `BaseTool.run()` | sync |
+| AutoGen | >= 0.7.0 | `FunctionTool.run()` | async |
+| LangGraph | >= 0.2.0 | `LCBaseTool.run()` | sync |
+
+## Custom Policies
+
+```python
+from ccs import CCSPolicy, GovernanceResult, govern
+
+class CompliancePolicy(CCSPolicy):
+    def evaluate(self, tool_name: str, tool_input: dict) -> GovernanceResult:
+        if "delete" in tool_name.lower():
+            return GovernanceResult.DENY
+        return GovernanceResult.ALLOW
+
+from ccs.core import get_runtime
+runtime = get_runtime()
+runtime.register_policy("compliance", CompliancePolicy())
+
+@govern(policy="compliance")
+def delete_user(user_id: str):
+    ...  # This will never execute — policy denies it
+```
+
+## Fail-Closed Guarantee
+
+The fundamental difference from observer-pattern hooks:
+
+| | Observer Hooks (AGT) | CCS Decorators |
+|---|---|---|
+| Integration | Framework catches hook exception | Decorator owns execution path |
+| On governance crash | `hook_blocked` stays `False` → tool executes | Exception propagates → tool never called |
+| Fail mode | **FAIL-OPEN** ❌ | **FAIL-CLOSED** ✅ |
+| CWE | CWE-636 (Not Failing Securely) | Structurally immune |
+
+## Performance
+
+CANON benchmark (50,000 traces):
+- **P50 latency: 22µs**
+- **P99 latency: 99µs**
+
+## Test Results
+
+Verified on 2026-07-09 with real framework installations:
+
+```
+CrewAI Adapter:   BaseTool.run intercepted → fail-closed ✅
+AutoGen Adapter:  FunctionTool.run intercepted → fail-closed ✅
+LangGraph Adapter: LCBaseTool.run intercepted → fail-closed ✅
+All adapters support install/uninstall lifecycle ✅
+```
+
+Performance (10,000 iterations, decorator + policy evaluation):
+```
+P50:  6.2µs
+P99:  15.0µs
+P999: 53.0µs
+```
+
+## MCP Server
+
+CCS is available as a [Model Context Protocol](https://modelcontextprotocol.io) server, enabling any MCP-compatible agent (Claude Desktop, Cursor, Cline) to validate tool calls against CCS governance.
+
+```bash
+pip install ccs[mcp]
+python -m ccs.mcp_server
+```
+
+Configure in Claude Desktop:
+```json
+{
+  "mcpServers": {
+    "ccs": {
+      "command": "python",
+      "args": ["-m", "ccs.mcp_server"]
+    }
+  }
+}
+```
+
+### MCP Tools
+| Tool | Description |
+|------|-------------|
+| `ccs_govern` | Evaluate a tool call against a policy → allow/deny |
+| `ccs_status` | Runtime stats, policies, latency metrics |
+| `ccs_register_deny_rule` | Register custom deny rules by tool name/pattern |
+| `ccs_audit_log` | Recent governance audit traces |
+
+## TypeScript SDK
+
+```bash
+npm install correctover-ccs
+```
+
+```typescript
+import { govern, GovernanceResult, CCSPolicy } from "correctover-ccs";
+
+const governedSearch = govern(searchWeb, { policy: "default" });
+governedSearch({ query: "test" }); // Throws PermissionError if denied
+```
+
+Source: [`ts/`](./ts) | [npm package](https://www.npmjs.com/package/correctover-ccs)
+
+## Go SDK
+
+```bash
+go get github.com/Correctover/ccs-sdk/go
+```
+
+```go
+rt := ccs.NewRuntime()
+governed := ccs.Govern(searchFn, "default", rt)
+result, err := governed(ccs.ToolInput{"query": "CCS standard"})
+// err = *PermissionError if denied — fn NEVER called
+```
+
+Source: [`go/`](./go)
+
+## Repository Structure
+
+```
+ccs-sdk/
+├── ccs/              # Python SDK (core + adapters + MCP server)
+│   ├── core.py       # Governance runtime
+│   ├── adapters.py   # CrewAI/AutoGen/LangGraph adapters
+│   └── mcp_server/   # MCP server (stdio transport)
+├── ts/               # TypeScript SDK (npm: correctover-ccs)
+│   ├── src/          # Source
+│   └── dist/         # Built output
+├── go/               # Go SDK
+│   └── ccs/          # Core package
+├── strict_9test.py   # Python 9-test verification suite
+└── pyproject.toml
+```
+
+## SDK Versions
+
+| SDK | Version | Package |
+|-----|---------|---------|
+| Python | 1.0.0 | `pip install ccs` |
+| TypeScript | 1.0.0 | `npm install correctover-ccs` |
+| Go | 1.0.0 | `go get github.com/Correctover/ccs-sdk/go` |
+
+## References
+
+- CCS v1.0 Standard: https://doi.org/10.5281/zenodo.21271910
+- CVE Audit (CWE-636 in AGT): https://gist.github.com/Correctover/9cfb97bcf374f79b793fd0bacd4e9d62
+- Correctover: https://correctover.com

correctover_ccs-1.0.0/README.md

@@ -0,0 +1,214 @@
+# CCS — Correctover Conformance Standard v1.0
+
+Synchronous interceptor-based governance for AI Agent frameworks.
+
+## Why CCS?
+
+Every major Agent framework (CrewAI AGT, AutoGen, LangGraph) uses **observer-pattern hooks** for governance. These hooks are structurally vulnerable to **fail-open bypass** — when the governance layer throws an exception, the framework defaults to allowing tool execution.
+
+**This is not a bug. It's an architectural flaw.** (CWE-636, CVSS 9.1)
+
+CCS uses **function decorators** instead of hooks. The decorator owns the execution path — if governance fails, the tool is BLOCKED. Never allowed.
+
+```
+Observer hooks:  governance_crash → exception caught → hook_blocked=False → tool EXECUTES ❌
+CCS decorators:  governance_crash → exception caught → tool NEVER CALLED ✅
+```
+
+## Installation
+
+```bash
+pip install ccs
+```
+
+## Quick Start (3 lines)
+
+```python
+from ccs import govern
+
+@govern(policy="default")
+def my_tool(args: dict) -> str:
+    return "result"
+
+# Governance evaluation happens BEFORE the function runs
+# If denied → PermissionError, function never executes
+```
+
+## Framework Adapters
+
+Adapters intercept at the framework's tool execution entry point.
+Once installed, ALL tool calls go through CCS governance.
+
+### CrewAI
+```python
+from ccs.adapters import crewai_adapter
+crewai_adapter.install()   # patches BaseTool.run globally
+# All CrewAI tool calls now governed by CCS
+crewai_adapter.uninstall() # restore original
+```
+
+### AutoGen (async)
+```python
+from ccs.adapters import autogen_adapter
+autogen_adapter.install()  # patches FunctionTool.run
+autogen_adapter.uninstall()
+```
+
+### LangGraph / LangChain
+```python
+from ccs.adapters import langgraph_adapter
+langgraph_adapter.install()  # patches LCBaseTool.run
+langgraph_adapter.uninstall()
+```
+
+### Verified Against
+| Framework | Version | Interception Point | Pattern |
+|-----------|---------|--------------------|---------|
+| CrewAI | >= 0.1.0 | `BaseTool.run()` | sync |
+| AutoGen | >= 0.7.0 | `FunctionTool.run()` | async |
+| LangGraph | >= 0.2.0 | `LCBaseTool.run()` | sync |
+
+## Custom Policies
+
+```python
+from ccs import CCSPolicy, GovernanceResult, govern
+
+class CompliancePolicy(CCSPolicy):
+    def evaluate(self, tool_name: str, tool_input: dict) -> GovernanceResult:
+        if "delete" in tool_name.lower():
+            return GovernanceResult.DENY
+        return GovernanceResult.ALLOW
+
+from ccs.core import get_runtime
+runtime = get_runtime()
+runtime.register_policy("compliance", CompliancePolicy())
+
+@govern(policy="compliance")
+def delete_user(user_id: str):
+    ...  # This will never execute — policy denies it
+```
+
+## Fail-Closed Guarantee
+
+The fundamental difference from observer-pattern hooks:
+
+| | Observer Hooks (AGT) | CCS Decorators |
+|---|---|---|
+| Integration | Framework catches hook exception | Decorator owns execution path |
+| On governance crash | `hook_blocked` stays `False` → tool executes | Exception propagates → tool never called |
+| Fail mode | **FAIL-OPEN** ❌ | **FAIL-CLOSED** ✅ |
+| CWE | CWE-636 (Not Failing Securely) | Structurally immune |
+
+## Performance
+
+CANON benchmark (50,000 traces):
+- **P50 latency: 22µs**
+- **P99 latency: 99µs**
+
+## Test Results
+
+Verified on 2026-07-09 with real framework installations:
+
+```
+CrewAI Adapter:   BaseTool.run intercepted → fail-closed ✅
+AutoGen Adapter:  FunctionTool.run intercepted → fail-closed ✅
+LangGraph Adapter: LCBaseTool.run intercepted → fail-closed ✅
+All adapters support install/uninstall lifecycle ✅
+```
+
+Performance (10,000 iterations, decorator + policy evaluation):
+```
+P50:  6.2µs
+P99:  15.0µs
+P999: 53.0µs
+```
+
+## MCP Server
+
+CCS is available as a [Model Context Protocol](https://modelcontextprotocol.io) server, enabling any MCP-compatible agent (Claude Desktop, Cursor, Cline) to validate tool calls against CCS governance.
+
+```bash
+pip install ccs[mcp]
+python -m ccs.mcp_server
+```
+
+Configure in Claude Desktop:
+```json
+{
+  "mcpServers": {
+    "ccs": {
+      "command": "python",
+      "args": ["-m", "ccs.mcp_server"]
+    }
+  }
+}
+```
+
+### MCP Tools
+| Tool | Description |
+|------|-------------|
+| `ccs_govern` | Evaluate a tool call against a policy → allow/deny |
+| `ccs_status` | Runtime stats, policies, latency metrics |
+| `ccs_register_deny_rule` | Register custom deny rules by tool name/pattern |
+| `ccs_audit_log` | Recent governance audit traces |
+
+## TypeScript SDK
+
+```bash
+npm install correctover-ccs
+```
+
+```typescript
+import { govern, GovernanceResult, CCSPolicy } from "correctover-ccs";
+
+const governedSearch = govern(searchWeb, { policy: "default" });
+governedSearch({ query: "test" }); // Throws PermissionError if denied
+```
+
+Source: [`ts/`](./ts) | [npm package](https://www.npmjs.com/package/correctover-ccs)
+
+## Go SDK
+
+```bash
+go get github.com/Correctover/ccs-sdk/go
+```
+
+```go
+rt := ccs.NewRuntime()
+governed := ccs.Govern(searchFn, "default", rt)
+result, err := governed(ccs.ToolInput{"query": "CCS standard"})
+// err = *PermissionError if denied — fn NEVER called
+```
+
+Source: [`go/`](./go)
+
+## Repository Structure
+
+```
+ccs-sdk/
+├── ccs/              # Python SDK (core + adapters + MCP server)
+│   ├── core.py       # Governance runtime
+│   ├── adapters.py   # CrewAI/AutoGen/LangGraph adapters
+│   └── mcp_server/   # MCP server (stdio transport)
+├── ts/               # TypeScript SDK (npm: correctover-ccs)
+│   ├── src/          # Source
+│   └── dist/         # Built output
+├── go/               # Go SDK
+│   └── ccs/          # Core package
+├── strict_9test.py   # Python 9-test verification suite
+└── pyproject.toml
+```
+
+## SDK Versions
+
+| SDK | Version | Package |
+|-----|---------|---------|
+| Python | 1.0.0 | `pip install ccs` |
+| TypeScript | 1.0.0 | `npm install correctover-ccs` |
+| Go | 1.0.0 | `go get github.com/Correctover/ccs-sdk/go` |
+
+## References
+
+- CCS v1.0 Standard: https://doi.org/10.5281/zenodo.21271910
+- CVE Audit (CWE-636 in AGT): https://gist.github.com/Correctover/9cfb97bcf374f79b793fd0bacd4e9d62
+- Correctover: https://correctover.com

correctover_ccs-1.0.0/ccs/__init__.py

@@ -0,0 +1,31 @@
+"""
+Correctover Conformance Standard (CCS) v1.0 — Python SDK
+
+Synchronous interceptor-based governance for AI Agent frameworks.
+Eliminates architectural fail-open bypasses inherent to observer-pattern hooks.
+
+Usage:
+    from ccs import govern
+    
+    @govern(policy="default")
+    def my_tool(args):
+        ...
+"""
+
+__version__ = "1.0.0"
+__author__ = "Correctover Standards"
+
+from ccs.core import govern, GovernanceResult, CCSConfig, CCSPolicy, CCSRuntime, get_runtime
+from ccs.adapters import crewai_adapter, autogen_adapter, langgraph_adapter
+
+__all__ = [
+    "govern",
+    "GovernanceResult", 
+    "CCSConfig",
+    "CCSPolicy",
+    "CCSRuntime",
+    "get_runtime",
+    "crewai_adapter",
+    "autogen_adapter", 
+    "langgraph_adapter",
+]

correctover_ccs-1.0.0/ccs/adapters.py

@@ -0,0 +1,195 @@
+"""
+CCS Framework Adapters — Verified interception for CrewAI, AutoGen, LangGraph.
+
+Each adapter replaces the framework's observer-pattern hooks with CCS
+synchronous interceptor decorators, eliminating CWE-636 fail-open vulnerabilities.
+
+Verified against:
+  - CrewAI >= 0.1.0 (BaseTool.run sync interception)
+  - AutoGen >= 0.7.0 (FunctionTool.run async interception)  
+  - LangGraph >= 0.2.0 (LCBaseTool.run sync interception)
+
+Reference: CCS v1.0 Standard, Section 3 — Formal Framework
+           DOI: 10.5281/zenodo.21271910
+"""
+
+from typing import Any, Optional
+
+
+class CrewAIAdapter:
+    """
+    CCS adapter for CrewAI.
+    
+    Intercepts crewai.tools.base_tool.BaseTool.run() — the single
+    entry point for ALL CrewAI tool executions. If CCS governance
+    denies or crashes, the tool is NEVER invoked (fail-closed).
+    
+    Usage:
+        from ccs.adapters import crewai_adapter
+        crewai_adapter.install()   # patches BaseTool.run globally
+        crewai_adapter.uninstall() # restores original
+    """
+    
+    _original_run = None
+    _installed = False
+    
+    @staticmethod
+    def install(policy: str = "default"):
+        """Install CCS governance on CrewAI's BaseTool.run."""
+        from crewai.tools.base_tool import BaseTool
+        from ccs.core import get_runtime, GovernanceResult
+        
+        if CrewAIAdapter._installed:
+            return  # Already installed
+        
+        runtime = get_runtime()
+        CrewAIAdapter._original_run = BaseTool.run
+        
+        def ccs_governed_run(self, *args, **kwargs):
+            tool_input = {"args": args, "kwargs": kwargs}
+            result, latency = runtime.evaluate(
+                tool_name=getattr(self, "name", type(self).__name__),
+                tool_input=tool_input,
+                policy_name=policy,
+            )
+            if result != GovernanceResult.ALLOW:
+                raise PermissionError(
+                    f"CCS DENIED: {getattr(self, 'name', 'unknown')} "
+                    f"(policy={policy}, latency={latency}µs)"
+                )
+            return CrewAIAdapter._original_run(self, *args, **kwargs)
+        
+        BaseTool.run = ccs_governed_run
+        CrewAIAdapter._installed = True
+    
+    @staticmethod
+    def uninstall():
+        """Restore original CrewAI BaseTool.run."""
+        if not CrewAIAdapter._installed:
+            return
+        from crewai.tools.base_tool import BaseTool
+        BaseTool.run = CrewAIAdapter._original_run
+        CrewAIAdapter._installed = False
+        CrewAIAdapter._original_run = None
+
+
+class AutoGenAdapter:
+    """
+    CCS adapter for Microsoft AutoGen.
+    
+    Intercepts autogen_core.tools.FunctionTool.run() — the async
+    entry point for all AutoGen function tool executions.
+    
+    Note: AutoGen 0.7+ uses async run(args, cancellation_token).
+    The adapter preserves this async signature.
+    
+    Usage:
+        from ccs.adapters import autogen_adapter
+        autogen_adapter.install()
+        autogen_adapter.uninstall()
+    """
+    
+    _original_run = None
+    _installed = False
+    
+    @staticmethod
+    def install(policy: str = "default"):
+        """Install CCS governance on AutoGen's FunctionTool.run."""
+        from autogen_core.tools import FunctionTool
+        from ccs.core import get_runtime, GovernanceResult
+        
+        if AutoGenAdapter._installed:
+            return
+        
+        runtime = get_runtime()
+        AutoGenAdapter._original_run = FunctionTool.run
+        
+        async def ccs_governed_run(self, args, cancellation_token):
+            tool_input = {"args": str(args), "tool": self.name}
+            result, latency = runtime.evaluate(
+                tool_name=self.name,
+                tool_input=tool_input,
+                policy_name=policy,
+            )
+            if result != GovernanceResult.ALLOW:
+                raise PermissionError(
+                    f"CCS DENIED: {self.name} "
+                    f"(policy={policy}, latency={latency}µs)"
+                )
+            return await AutoGenAdapter._original_run(self, args, cancellation_token)
+        
+        FunctionTool.run = ccs_governed_run
+        AutoGenAdapter._installed = True
+    
+    @staticmethod
+    def uninstall():
+        """Restore original AutoGen FunctionTool.run."""
+        if not AutoGenAdapter._installed:
+            return
+        from autogen_core.tools import FunctionTool
+        FunctionTool.run = AutoGenAdapter._original_run
+        AutoGenAdapter._installed = False
+        AutoGenAdapter._original_run = None
+
+
+class LangGraphAdapter:
+    """
+    CCS adapter for LangGraph / LangChain.
+    
+    Intercepts langchain_core.tools.BaseTool.run() — the sync
+    entry point for all LangChain/LangGraph tool executions.
+    Also covers invoke() since it delegates to run().
+    
+    Usage:
+        from ccs.adapters import langgraph_adapter
+        langgraph_adapter.install()
+        langgraph_adapter.uninstall()
+    """
+    
+    _original_run = None
+    _installed = False
+    
+    @staticmethod
+    def install(policy: str = "default"):
+        """Install CCS governance on LangChain's BaseTool.run."""
+        from langchain_core.tools import BaseTool as LCBaseTool
+        from ccs.core import get_runtime, GovernanceResult
+        
+        if LangGraphAdapter._installed:
+            return
+        
+        runtime = get_runtime()
+        LangGraphAdapter._original_run = LCBaseTool.run
+        
+        def ccs_governed_run(self, tool_input, *args, **kwargs):
+            governance_input = {"tool_input": tool_input, "kwargs": kwargs}
+            result, latency = runtime.evaluate(
+                tool_name=getattr(self, "name", type(self).__name__),
+                tool_input=governance_input,
+                policy_name=policy,
+            )
+            if result != GovernanceResult.ALLOW:
+                raise PermissionError(
+                    f"CCS DENIED: {getattr(self, 'name', 'unknown')} "
+                    f"(policy={policy}, latency={latency}µs)"
+                )
+            return LangGraphAdapter._original_run(self, tool_input, *args, **kwargs)
+        
+        LCBaseTool.run = ccs_governed_run
+        LangGraphAdapter._installed = True
+    
+    @staticmethod
+    def uninstall():
+        """Restore original LangChain BaseTool.run."""
+        if not LangGraphAdapter._installed:
+            return
+        from langchain_core.tools import BaseTool as LCBaseTool
+        LCBaseTool.run = LangGraphAdapter._original_run
+        LangGraphAdapter._installed = False
+        LangGraphAdapter._original_run = None
+
+
+# Convenience instances
+crewai_adapter = CrewAIAdapter()
+autogen_adapter = AutoGenAdapter()
+langgraph_adapter = LangGraphAdapter()