sigil-protocol 0.1.0__tar.gz

sigil_protocol-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write   # required for Trusted Publishing OIDC
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/sigil-protocol/
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build
+        run: python -m pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

sigil_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: sigil-protocol
+Version: 0.1.0
+Summary: SIGIL security layer for AI agent tool calls — scans MCP tool arguments for leaked secrets, enforces policies, and writes audit logs
+Project-URL: Homepage, https://sigil-protocol.org
+Project-URL: Repository, https://github.com/sigil-eu/sigil
+Project-URL: Documentation, https://sigil-protocol.org
+Project-URL: Bug Tracker, https://github.com/sigil-eu/sigil/issues
+License: MIT
+Keywords: ai-agent,autogen,crewai,langchain,mcp,secrets-scanning,security,sigil
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: crewai>=0.1; extra == 'all'
+Requires-Dist: langchain-core>=0.1; extra == 'all'
+Requires-Dist: mcp>=0.9; extra == 'all'
+Requires-Dist: pyautogen>=0.2; extra == 'all'
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2; extra == 'autogen'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == 'langchain'
+Provides-Extra: mcp
+Requires-Dist: mcp>=0.9; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai-agents>=0.1; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# sigil-protocol
+
+> 🔐 SIGIL security layer for AI agent tool calls — scans MCP tool arguments for leaked secrets, blocks dangerous operations, and writes audit logs.
+> **MIT licensed.** Works with LangChain, CrewAI, AutoGen, mcp-agent, and OpenAI Agents SDK.
+
+```bash
+pip install sigil-protocol
+```
+
+## 30-second start
+
+```python
+from sigil_protocol import scan
+
+result = scan('{"key": "AKIAIOSFODNN7EXAMPLE"}')
+if result.blocked:
+    print(f"BLOCKED: {result.pattern} ({result.severity})")
+# → BLOCKED: aws_access_key_id (Critical)
+```
+
+---
+
+## Framework Adapters
+
+### LangChain
+
+```bash
+pip install 'sigil-protocol[langchain]'
+```
+
+**Option A — Give the LLM an explicit scan tool:**
+
+```python
+from sigil_protocol.langchain import SigilScanTool
+from langchain.agents import initialize_agent
+
+agent = initialize_agent(
+    tools=[SigilScanTool(), my_db_tool, my_api_tool],
+    llm=llm,
+    ...
+)
+# The LLM will call sigil_scan before passing data to any backend tool
+```
+
+**Option B — Gate an existing tool transparently:**
+
+```python
+from sigil_protocol.langchain import sigil_tool
+from langchain_core.tools import BaseTool
+
+@sigil_tool
+class ExecuteSQLTool(BaseTool):
+    name = "execute_sql"
+    description = "Runs SQL queries"
+    def _run(self, query: str) -> str:
+        return db.execute(query)
+# → Raises ValueError on Critical findings before _run is ever called
+```
+
+---
+
+### CrewAI
+
+```bash
+pip install 'sigil-protocol[crewai]'
+```
+
+```python
+from sigil_protocol.crewai import sigil_gate, SigilBaseTool
+from crewai import Agent
+
+# Explicit scan tool
+agent = Agent(tools=[SigilBaseTool(), ...])
+
+# Or gate any existing tool
+@sigil_gate
+class PaymentTool(BaseTool):
+    name: str = "initiate_payment"
+    ...
+```
+
+---
+
+### AutoGen
+
+```bash
+pip install 'sigil-protocol[autogen]'
+```
+
+```python
+from sigil_protocol.autogen import sigil_function
+
+@user_proxy.register_for_execution()
+@assistant.register_for_llm(description="Execute a shell command")
+@sigil_function
+def run_shell(cmd: str) -> str:
+    return subprocess.check_output(cmd, shell=True).decode()
+# → Raises RuntimeError if cmd contains a leaked secret
+```
+
+---
+
+### mcp-agent (lastmile-ai)
+
+```bash
+pip install 'sigil-protocol[mcp]'
+```
+
+```python
+from sigil_protocol.mcp_agent import SigilMiddleware
+
+async with app.run() as agent_app:
+    agent = Agent(name="my_agent", servers=["filesystem", "github"])
+    async with agent.activate() as active_agent:
+        llm = await active_agent.attach_llm(OpenAIAugmentedLLM)
+        llm.add_middleware(SigilMiddleware())  # ← scans args AND responses
+```
+
+---
+
+### OpenAI Agents SDK
+
+```bash
+pip install 'sigil-protocol[openai]'
+```
+
+```python
+from agents import Agent, Runner
+from sigil_protocol.openai_agents import SigilGuardrail
+
+agent = Agent(
+    name="secure_agent",
+    instructions="You are a helpful assistant.",
+    input_guardrails=[SigilGuardrail()],
+)
+result = await Runner.run(agent, user_input)
+# → GuardrailTripwireTriggered if input contains leaked secrets
+```
+
+---
+
+## Pattern Coverage
+
+Patterns are fetched from [registry.sigil-protocol.org](https://registry.sigil-protocol.org) (cached 5 min locally). Falls back to built-ins if offline.
+
+| Category | Examples |
+|---|---|
+| Cloud credentials | AWS, GCP, Azure, OpenAI, GitHub, npm, Stripe |
+| Cryptographic keys | RSA/EC private keys, SSH keys, JWT secrets |
+| PII (EU GDPR) | IBAN, phone, email, SSN |
+| Dangerous SQL | DROP TABLE, DELETE without WHERE, TRUNCATE |
+| Prompt injection | Jailbreak openers, system prompt leaks |
+
+## Configuration
+
+| Env variable | Default | Description |
+|---|---|---|
+| `SIGIL_REGISTRY_URL` | `https://registry.sigil-protocol.org` | Pattern registry endpoint |
+| `SIGIL_BUNDLE_TTL` | `300` | Pattern cache TTL in seconds |
+| `SIGIL_OFFLINE` | `false` | Use built-in patterns only |
+| `SIGIL_MIN_SEVERITY` | `High` | Minimum severity to flag (`Warn`/`High`/`Critical`) |
+
+## License
+
+**MIT** — this package. The SIGIL core Rust library is EUPL-1.2.
+
+## Links
+
+- 🌐 [sigil-protocol.org](https://sigil-protocol.org)
+- 📦 [PyPI: sigil-protocol](https://pypi.org/project/sigil-protocol/)
+- 🗂 [registry.sigil-protocol.org](https://registry.sigil-protocol.org)
+- 📄 [Protocol spec & Rust crate](https://github.com/sigil-eu/sigil)

sigil_protocol-0.1.0/README.md

@@ -0,0 +1,172 @@
+# sigil-protocol
+
+> 🔐 SIGIL security layer for AI agent tool calls — scans MCP tool arguments for leaked secrets, blocks dangerous operations, and writes audit logs.
+> **MIT licensed.** Works with LangChain, CrewAI, AutoGen, mcp-agent, and OpenAI Agents SDK.
+
+```bash
+pip install sigil-protocol
+```
+
+## 30-second start
+
+```python
+from sigil_protocol import scan
+
+result = scan('{"key": "AKIAIOSFODNN7EXAMPLE"}')
+if result.blocked:
+    print(f"BLOCKED: {result.pattern} ({result.severity})")
+# → BLOCKED: aws_access_key_id (Critical)
+```
+
+---
+
+## Framework Adapters
+
+### LangChain
+
+```bash
+pip install 'sigil-protocol[langchain]'
+```
+
+**Option A — Give the LLM an explicit scan tool:**
+
+```python
+from sigil_protocol.langchain import SigilScanTool
+from langchain.agents import initialize_agent
+
+agent = initialize_agent(
+    tools=[SigilScanTool(), my_db_tool, my_api_tool],
+    llm=llm,
+    ...
+)
+# The LLM will call sigil_scan before passing data to any backend tool
+```
+
+**Option B — Gate an existing tool transparently:**
+
+```python
+from sigil_protocol.langchain import sigil_tool
+from langchain_core.tools import BaseTool
+
+@sigil_tool
+class ExecuteSQLTool(BaseTool):
+    name = "execute_sql"
+    description = "Runs SQL queries"
+    def _run(self, query: str) -> str:
+        return db.execute(query)
+# → Raises ValueError on Critical findings before _run is ever called
+```
+
+---
+
+### CrewAI
+
+```bash
+pip install 'sigil-protocol[crewai]'
+```
+
+```python
+from sigil_protocol.crewai import sigil_gate, SigilBaseTool
+from crewai import Agent
+
+# Explicit scan tool
+agent = Agent(tools=[SigilBaseTool(), ...])
+
+# Or gate any existing tool
+@sigil_gate
+class PaymentTool(BaseTool):
+    name: str = "initiate_payment"
+    ...
+```
+
+---
+
+### AutoGen
+
+```bash
+pip install 'sigil-protocol[autogen]'
+```
+
+```python
+from sigil_protocol.autogen import sigil_function
+
+@user_proxy.register_for_execution()
+@assistant.register_for_llm(description="Execute a shell command")
+@sigil_function
+def run_shell(cmd: str) -> str:
+    return subprocess.check_output(cmd, shell=True).decode()
+# → Raises RuntimeError if cmd contains a leaked secret
+```
+
+---
+
+### mcp-agent (lastmile-ai)
+
+```bash
+pip install 'sigil-protocol[mcp]'
+```
+
+```python
+from sigil_protocol.mcp_agent import SigilMiddleware
+
+async with app.run() as agent_app:
+    agent = Agent(name="my_agent", servers=["filesystem", "github"])
+    async with agent.activate() as active_agent:
+        llm = await active_agent.attach_llm(OpenAIAugmentedLLM)
+        llm.add_middleware(SigilMiddleware())  # ← scans args AND responses
+```
+
+---
+
+### OpenAI Agents SDK
+
+```bash
+pip install 'sigil-protocol[openai]'
+```
+
+```python
+from agents import Agent, Runner
+from sigil_protocol.openai_agents import SigilGuardrail
+
+agent = Agent(
+    name="secure_agent",
+    instructions="You are a helpful assistant.",
+    input_guardrails=[SigilGuardrail()],
+)
+result = await Runner.run(agent, user_input)
+# → GuardrailTripwireTriggered if input contains leaked secrets
+```
+
+---
+
+## Pattern Coverage
+
+Patterns are fetched from [registry.sigil-protocol.org](https://registry.sigil-protocol.org) (cached 5 min locally). Falls back to built-ins if offline.
+
+| Category | Examples |
+|---|---|
+| Cloud credentials | AWS, GCP, Azure, OpenAI, GitHub, npm, Stripe |
+| Cryptographic keys | RSA/EC private keys, SSH keys, JWT secrets |
+| PII (EU GDPR) | IBAN, phone, email, SSN |
+| Dangerous SQL | DROP TABLE, DELETE without WHERE, TRUNCATE |
+| Prompt injection | Jailbreak openers, system prompt leaks |
+
+## Configuration
+
+| Env variable | Default | Description |
+|---|---|---|
+| `SIGIL_REGISTRY_URL` | `https://registry.sigil-protocol.org` | Pattern registry endpoint |
+| `SIGIL_BUNDLE_TTL` | `300` | Pattern cache TTL in seconds |
+| `SIGIL_OFFLINE` | `false` | Use built-in patterns only |
+| `SIGIL_MIN_SEVERITY` | `High` | Minimum severity to flag (`Warn`/`High`/`Critical`) |
+
+## License
+
+**MIT** — this package. The SIGIL core Rust library is EUPL-1.2.
+
+## Links
+
+- 🌐 [sigil-protocol.org](https://sigil-protocol.org)
+- 📦 [PyPI: sigil-protocol](https://pypi.org/project/sigil-protocol/)
+- 🗂 [registry.sigil-protocol.org](https://registry.sigil-protocol.org)
+- 📄 [Protocol spec & Rust crate](https://github.com/sigil-eu/sigil)

sigil_protocol-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sigil-protocol"
+version = "0.1.0"
+description = "SIGIL security layer for AI agent tool calls — scans MCP tool arguments for leaked secrets, enforces policies, and writes audit logs"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["sigil", "mcp", "security", "ai-agent", "langchain", "crewai", "autogen", "secrets-scanning"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "httpx>=0.25",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1"]
+crewai   = ["crewai>=0.1"]
+autogen  = ["pyautogen>=0.2"]
+mcp      = ["mcp>=0.9"]
+openai   = ["openai-agents>=0.1"]
+all      = [
+    "langchain-core>=0.1",
+    "crewai>=0.1",
+    "pyautogen>=0.2",
+    "mcp>=0.9",
+]
+
+[project.urls]
+Homepage      = "https://sigil-protocol.org"
+Repository    = "https://github.com/sigil-eu/sigil"
+Documentation = "https://sigil-protocol.org"
+"Bug Tracker" = "https://github.com/sigil-eu/sigil/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sigil_protocol"]

sigil_protocol-0.1.0/sigil_protocol/__init__.py

@@ -0,0 +1,29 @@
+"""
+sigil-protocol — SIGIL security layer for AI agent tool calls.
+
+Quick start:
+    from sigil_protocol import scan, ScanResult
+
+    result = scan('{"key": "AKIAIOSFODNN7EXAMPLE"}')
+    if result.blocked:
+        raise ValueError(f"SIGIL blocked: {result.pattern} ({result.severity})")
+
+Framework adapters:
+    from sigil_protocol.langchain  import SigilScanTool, sigil_tool
+    from sigil_protocol.crewai     import sigil_gate, SigilBaseTool
+    from sigil_protocol.autogen    import sigil_function, SigilFunctionExecutor
+    from sigil_protocol.mcp_agent  import SigilMiddleware
+    from sigil_protocol.openai_agents import SigilGuardrail
+"""
+
+from .scanner import RemoteScanner, ScanResult, Severity, scan, scanner
+
+__all__ = [
+    "RemoteScanner",
+    "ScanResult",
+    "Severity",
+    "scan",
+    "scanner",
+]
+
+__version__ = "0.1.0"

sigil_protocol-0.1.0/sigil_protocol/autogen.py

@@ -0,0 +1,107 @@
+"""
+SIGIL adapter for Microsoft AutoGen.
+
+Provides:
+  - sigil_function  — function decorator; wraps a @register_for_execution function
+  - SigilProxy      — a ConversableAgent that intercepts all outgoing function calls
+
+Usage:
+    from sigil_protocol.autogen import sigil_function, SigilProxy
+    import autogen
+
+    # Option 1: Per-function decorator
+    @user_proxy.register_for_execution()
+    @assistant.register_for_llm(description="Execute SQL query")
+    @sigil_function
+    def execute_sql(query: str) -> str:
+        return db.execute(query)
+
+    # Option 2: Proxy agent that gates ALL tool calls
+    sigil_proxy = SigilProxy(name="sigil_guard")
+    # Place sigil_proxy in your agent graph between LLM and executor
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from functools import wraps
+from typing import Any, Callable
+
+from .scanner import scanner
+
+logger = logging.getLogger("sigil_protocol.autogen")
+
+
+def sigil_function(fn: Callable) -> Callable:
+    """
+    Decorator for AutoGen @register_for_execution functions.
+    Scans all arguments before calling the wrapped function.
+    Raises RuntimeError on Critical-severity findings.
+
+    Example:
+        @user_proxy.register_for_execution()
+        @assistant.register_for_llm(description="Send email")
+        @sigil_function
+        def send_email(to: str, body: str) -> str:
+            ...
+    """
+    @wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        payload = json.dumps({"args": list(args), "kwargs": kwargs})
+        result = scanner().scan(payload)
+        if result.blocked:
+            raise RuntimeError(
+                f"🔐 SIGIL blocked call to `{fn.__name__}`: "
+                f"leaked secret detected ({result.pattern}, severity={result.severity}). "
+                "Remove sensitive data from arguments and retry."
+            )
+        if result.warned:
+            logger.warning(
+                "SIGIL warning in call to `%s`: %s (%s)",
+                fn.__name__, result.pattern, result.severity,
+            )
+        return fn(*args, **kwargs)
+
+    return wrapper
+
+
+class SigilProxy:
+    """
+    A lightweight AutoGen-compatible proxy that can be placed in an agent
+    graph to intercept all tool/function calls made by any upstream agent.
+
+    Use by wrapping a ConversableAgent's generate_tool_calls_reply or
+    by registering it as a middleware in custom agent graphs.
+
+    Minimal usage in a two-agent setup:
+        from autogen import AssistantAgent, UserProxyAgent
+        from sigil_protocol.autogen import SigilProxy, sigil_function
+
+        # Decorate individual functions (simpler)
+        @user_proxy.register_for_execution()
+        @assistant.register_for_llm(description="...")
+        @sigil_function
+        def my_tool(...): ...
+    """
+
+    def __call__(self, func_name: str, func_args: dict) -> dict | None:
+        """
+        Call gate. Returns None to allow the call, or a dict with
+        {"content": "SIGIL BLOCKED: ..."} to short-circuit with an error.
+        """
+        payload = json.dumps({"function": func_name, "args": func_args})
+        result = scanner().scan(payload)
+        if result.blocked:
+            msg = (
+                f"🔐 SIGIL blocked `{func_name}`: "
+                f"leaked secret ({result.pattern}, severity={result.severity}). "
+                "Retry without the sensitive data."
+            )
+            logger.error(msg)
+            return {"content": msg, "role": "tool"}
+        if result.warned:
+            logger.warning(
+                "SIGIL warning for `%s`: %s (%s)", func_name, result.pattern, result.severity
+            )
+        return None  # proceed

sigil_protocol-0.1.0/sigil_protocol/crewai.py

@@ -0,0 +1,95 @@
+"""
+SIGIL adapter for CrewAI.
+
+Provides:
+  - sigil_gate     — class decorator that wraps any CrewAI BaseTool with a gate
+  - SigilBaseTool  — ready-to-use CrewAI tool for explicit LLM scans
+
+Usage:
+    from sigil_protocol.crewai import sigil_gate, SigilBaseTool
+    from crewai_tools import BaseTool
+
+    # Option 1: Explicit scan tool
+    scan_tool = SigilBaseTool()
+    agent = Agent(tools=[scan_tool, my_other_tool])
+
+    # Option 2: Gate an existing tool
+    @sigil_gate
+    class MyApiTool(BaseTool):
+        name: str = "call_api"
+        description: str = "Calls the payment API"
+        def _run(self, endpoint: str, payload: str) -> str: ...
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional, Type
+
+from .scanner import scanner
+
+try:
+    from crewai.tools import BaseTool
+except ImportError:
+    try:
+        from crewai_tools import BaseTool  # type: ignore[no-redef]
+    except ImportError as e:
+        raise ImportError(
+            "CrewAI adapter requires crewai. "
+            "Install with: pip install 'sigil-protocol[crewai]'"
+        ) from e
+
+
+class SigilBaseTool(BaseTool):
+    """
+    CrewAI tool that scans a JSON payload for SIGIL security findings.
+    Add to any Agent's tool list. The LLM will call it before passing
+    sensitive data to any other tool.
+    """
+
+    name: str = "sigil_scan"
+    description: str = (
+        "Scans any JSON payload for leaked secrets (API keys, credentials, PII), "
+        "dangerous SQL operations, or prompt injection using SIGIL's 43+ verified patterns. "
+        "Call this BEFORE invoking any tool that processes external or user-supplied data. "
+        "If severity='Critical' is returned, abort the tool call and inform the user."
+    )
+
+    def _run(self, payload: str) -> str:
+        result = scanner().scan(payload)
+        if not result.hit:
+            return "SIGIL: clean — no findings."
+        status = "BLOCKED" if result.blocked else "WARNING"
+        findings = ", ".join(
+            f"{h.get('id') or h.get('pattern_name')} ({h.get('severity')})"
+            for h in result.all_hits
+        )
+        return f"SIGIL {status}: {findings}"
+
+
+def sigil_gate(cls: Type[BaseTool]) -> Type[BaseTool]:
+    """
+    Class decorator for CrewAI BaseTool. Scans all _run() arguments
+    before executing. Raises on Critical-severity findings.
+
+    Example:
+        @sigil_gate
+        class DatabaseQueryTool(BaseTool):
+            name: str = "query_database"
+            ...
+    """
+    original_run = cls._run
+
+    def _guarded_run(self, *args: Any, **kwargs: Any) -> Any:
+        payload = json.dumps({"args": list(args), "kwargs": kwargs})
+        result = scanner().scan(payload)
+        if result.blocked:
+            return (
+                f"🔐 SIGIL BLOCKED: This call to `{self.name}` was blocked because "
+                f"a leaked secret was detected ({result.pattern}, severity={result.severity}). "
+                "Remove the sensitive data and retry."
+            )
+        return original_run(self, *args, **kwargs)
+
+    cls._run = _guarded_run
+    return cls

sigil_protocol-0.1.0/sigil_protocol/langchain.py

@@ -0,0 +1,117 @@
+"""
+SIGIL adapter for LangChain.
+
+Provides:
+  - SigilScanTool  — a LangChain BaseTool that the LLM can call explicitly
+  - sigil_tool     — decorator that wraps any BaseTool with a SIGIL pre-scan gate
+
+Usage:
+    from sigil_protocol.langchain import SigilScanTool, sigil_tool
+    from langchain.agents import initialize_agent
+
+    # Option 1: Give the LLM an explicit scan tool
+    agent = initialize_agent(tools=[SigilScanTool(), my_db_tool, ...], ...)
+
+    # Option 2: Gate an existing tool
+    @sigil_tool
+    class MySensitiveTool(BaseTool):
+        name = "execute_sql"
+        ...
+"""
+
+from __future__ import annotations
+
+import json
+from functools import wraps
+from typing import Any, Optional, Type
+
+from .scanner import ScanResult, Severity, scanner
+
+try:
+    from langchain_core.tools import BaseTool
+    from pydantic import BaseModel, Field
+except ImportError as e:
+    raise ImportError(
+        "LangChain adapter requires langchain-core. "
+        "Install with: pip install 'sigil-protocol[langchain]'"
+    ) from e
+
+
+class _ScanInput(BaseModel):
+    payload: str = Field(description="JSON string or plain text to scan for secrets or dangerous content.")
+
+
+class SigilScanTool(BaseTool):
+    """
+    LangChain tool that scans a payload for SIGIL security findings.
+    Register alongside your other tools — the LLM will call this before
+    sending sensitive data to any backend.
+    """
+
+    name: str = "sigil_scan"
+    description: str = (
+        "Scans a JSON payload or text for leaked secrets (API keys, credentials, "
+        "private keys, PII), dangerous SQL (DROP TABLE, DELETE without WHERE), or "
+        "prompt injection patterns using the SIGIL registry of 43+ verified patterns. "
+        "Call this BEFORE passing any user-supplied or sensitive data to a tool backend. "
+        "If the result contains severity='Critical', you MUST NOT proceed and MUST "
+        "inform the user immediately."
+    )
+    args_schema: Type[BaseModel] = _ScanInput
+
+    def _run(self, payload: str) -> str:
+        result = scanner().scan(payload)
+        if not result.hit:
+            return json.dumps({"status": "clean", "findings": []})
+        findings = [
+            {"pattern": h.get("id") or h.get("pattern_name"), "severity": h.get("severity"), "category": h.get("category")}
+            for h in result.all_hits
+        ]
+        status = "blocked" if result.blocked else "warn"
+        return json.dumps({"status": status, "findings": findings})
+
+    async def _arun(self, payload: str) -> str:
+        return self._run(payload)
+
+
+def sigil_tool(cls: Type[BaseTool]) -> Type[BaseTool]:
+    """
+    Class decorator that wraps a LangChain BaseTool's _run/_arun methods
+    with a SIGIL pre-scan gate. Critical findings raise ValueError (blocking
+    the tool call). High findings log a warning but allow the call through.
+
+    Example:
+        @sigil_tool
+        class MyDatabaseTool(BaseTool):
+            name = "query_db"
+            ...
+    """
+    original_run = cls._run
+    original_arun = cls._arun if hasattr(cls, "_arun") else None
+
+    def _guarded_run(self, *args: Any, **kwargs: Any) -> Any:
+        payload = json.dumps({"args": args, "kwargs": kwargs})
+        result = scanner().scan(payload)
+        if result.blocked:
+            raise ValueError(
+                f"🔐 SIGIL blocked tool call to `{self.name}`: "
+                f"leaked secret detected ({result.pattern}, {result.severity}). "
+                "Remove sensitive data from the arguments and retry."
+            )
+        return original_run(self, *args, **kwargs)
+
+    async def _guarded_arun(self, *args: Any, **kwargs: Any) -> Any:
+        payload = json.dumps({"args": list(args), "kwargs": kwargs})
+        result = scanner().scan(payload)
+        if result.blocked:
+            raise ValueError(
+                f"🔐 SIGIL blocked tool call to `{self.name}`: "
+                f"leaked secret ({result.pattern}, {result.severity})."
+            )
+        if original_arun:
+            return await original_arun(self, *args, **kwargs)
+        return _guarded_run(self, *args, **kwargs)
+
+    cls._run = _guarded_run
+    cls._arun = _guarded_arun
+    return cls

sigil_protocol-0.1.0/sigil_protocol/mcp_agent.py

@@ -0,0 +1,89 @@
+"""
+SIGIL adapter for lastmile-ai/mcp-agent.
+
+Provides SigilMiddleware — drop into MCPAgent's middleware list to scan
+every outgoing tool call and return result for secret leaks before they
+reach any MCP server backend.
+
+Usage:
+    from mcp_agent.app import MCPApp
+    from mcp_agent.agents.agent import Agent
+    from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+    from sigil_protocol.mcp_agent import SigilMiddleware
+
+    app = MCPApp(name="my_agent")
+
+    async with app.run() as agent_app:
+        agent = Agent(
+            name="my_agent",
+            instruction="You are a helpful assistant.",
+            servers=["filesystem", "github"],
+        )
+        async with agent.activate() as active_agent:
+            llm = await active_agent.attach_llm(OpenAIAugmentedLLM)
+            # Middleware scans all tool args before they leave the process
+            llm.add_middleware(SigilMiddleware())
+            result = await llm.generate_str("List my files")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from .scanner import scanner
+
+logger = logging.getLogger("sigil_protocol.mcp_agent")
+
+
+class SigilMiddleware:
+    """
+    mcp-agent middleware that scans tool call arguments with SIGIL before
+    they are sent to any MCP server. Blocks Critical findings.
+
+    Attach via: llm.add_middleware(SigilMiddleware())
+    Or: app = MCPApp(..., middleware=[SigilMiddleware()])
+    """
+
+    async def on_tool_call(
+        self,
+        tool_name: str,
+        tool_args: dict[str, Any],
+        next_handler,
+    ) -> Any:
+        payload = json.dumps({"tool": tool_name, "args": tool_args})
+        result = scanner().scan(payload)
+
+        if result.blocked:
+            msg = (
+                f"🔐 SIGIL blocked `{tool_name}`: "
+                f"leaked secret detected ({result.pattern}, severity={result.severity}). "
+                "Remove the sensitive data from the arguments and retry."
+            )
+            logger.error(msg)
+            # Return an error content block compatible with mcp-agent's response format
+            return {"content": [{"type": "text", "text": msg}], "isError": True}
+
+        if result.warned:
+            logger.warning(
+                "SIGIL warning for `%s`: %s (%s)", tool_name, result.pattern, result.severity
+            )
+
+        return await next_handler(tool_name, tool_args)
+
+    async def on_tool_result(
+        self,
+        tool_name: str,
+        result_content: Any,
+        next_handler,
+    ) -> Any:
+        """Also scan tool *responses* for accidentally returned credentials."""
+        payload = json.dumps(result_content) if not isinstance(result_content, str) else result_content
+        scan_result = scanner().scan(payload)
+        if scan_result.hit:
+            logger.warning(
+                "SIGIL: secret in response from `%s`: %s (%s) — logged.",
+                tool_name, scan_result.pattern, scan_result.severity,
+            )
+        return await next_handler(tool_name, result_content)

sigil_protocol-0.1.0/sigil_protocol/openai_agents.py

@@ -0,0 +1,101 @@
+"""
+SIGIL adapter for the OpenAI Agents SDK (openai-agents).
+
+Provides SigilGuardrail — an InputGuardrail that can be applied to any
+OpenAI Agent to scan tool arguments (and optionally response content)
+for leaked secrets before they are processed.
+
+Usage:
+    from agents import Agent, Runner
+    from sigil_protocol.openai_agents import SigilGuardrail
+
+    agent = Agent(
+        name="my_agent",
+        instructions="You are a helpful assistant.",
+        input_guardrails=[SigilGuardrail()],
+    )
+    result = await Runner.run(agent, "Send this API key to the webhook: sk-abc123...")
+    # → Guardrail trips, run is exited with a GuardrailTripwireTriggered exception
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from .scanner import Severity, scanner
+
+logger = logging.getLogger("sigil_protocol.openai_agents")
+
+try:
+    from agents import (  # type: ignore[import]
+        Agent,
+        GuardrailFunctionOutput,
+        InputGuardrail,
+        RunContextWrapper,
+        TResponseInputItem,
+    )
+    _HAS_SDK = True
+except ImportError:
+    _HAS_SDK = False
+
+
+if _HAS_SDK:
+    from pydantic import BaseModel
+
+    class _SigilOutput(BaseModel):
+        blocked: bool
+        reason: str | None = None
+
+    class SigilGuardrail(InputGuardrail):
+        """
+        OpenAI Agents SDK InputGuardrail backed by SIGIL's remote scanner.
+        Trips on Critical-severity findings and warns on High.
+        """
+
+        name: str = "sigil_guardrail"
+
+        async def run(
+            self,
+            ctx: RunContextWrapper,
+            agent: Agent,
+            input: str | list[TResponseInputItem],
+        ) -> GuardrailFunctionOutput:
+            text = input if isinstance(input, str) else json.dumps(input)
+            result = scanner().scan(text)
+
+            if result.blocked:
+                reason = (
+                    f"🔐 SIGIL: Leaked secret detected ({result.pattern}, "
+                    f"severity={result.severity}). Input rejected."
+                )
+                logger.error(reason)
+                return GuardrailFunctionOutput(
+                    output_info=_SigilOutput(blocked=True, reason=reason),
+                    tripwire_triggered=True,
+                )
+
+            if result.warned:
+                logger.warning(
+                    "SIGIL warning: %s (%s) in agent input", result.pattern, result.severity
+                )
+
+            return GuardrailFunctionOutput(
+                output_info=_SigilOutput(blocked=False),
+                tripwire_triggered=False,
+            )
+
+else:
+    # Stub when openai-agents is not installed
+    class SigilGuardrail:  # type: ignore[no-redef]
+        """
+        Stub — install openai-agents to use this adapter:
+            pip install 'sigil-protocol[openai]'
+        """
+
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError(
+                "OpenAI Agents adapter requires openai-agents. "
+                "Install with: pip install 'sigil-protocol[openai]'"
+            )

sigil_protocol-0.1.0/sigil_protocol/scanner.py

@@ -0,0 +1,162 @@
+"""
+Core scanner — fetches the SIGIL pattern bundle from the public registry
+and scans arbitrary text/JSON for security findings.
+
+Uses no EUPL code — this file is MIT-licensed and calls the registry HTTP API.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+import httpx
+
+REGISTRY_URL = os.getenv(
+    "SIGIL_REGISTRY_URL", "https://registry.sigil-protocol.org"
+)
+BUNDLE_TTL   = int(os.getenv("SIGIL_BUNDLE_TTL", "300"))   # seconds
+OFFLINE      = os.getenv("SIGIL_OFFLINE", "").lower() in ("1", "true", "yes")
+MIN_SEVERITY = os.getenv("SIGIL_MIN_SEVERITY", "High")     # Warn|High|Critical
+
+# ── Built-in fallback patterns (subset) ──────────────────────────────────────
+_BUILTIN_PATTERNS = [
+    {"id": "aws_access_key_id",    "severity": "Critical", "regex": r"AKIA[0-9A-Z]{16}"},
+    {"id": "openai_api_key",       "severity": "Critical", "regex": r"sk-[a-zA-Z0-9]{32,}"},
+    {"id": "github_pat",           "severity": "Critical", "regex": r"gh[ps]_[a-zA-Z0-9]{36}"},
+    {"id": "rsa_private_key",      "severity": "Critical", "regex": r"-----BEGIN RSA PRIVATE KEY-----"},
+    {"id": "generic_secret",       "severity": "High",     "regex": r"(?i)(secret|password|passwd|api_key)\s*[:=]\s*['\"]?[A-Za-z0-9+/]{16,}"},
+    {"id": "sql_drop_table",       "severity": "Critical", "regex": r"(?i)DROP\s+TABLE\s+\w+"},
+    {"id": "sql_delete_no_where",  "severity": "High",     "regex": r"(?i)DELETE\s+FROM\s+\w+\s*(?!WHERE)"},
+    {"id": "sql_truncate",         "severity": "High",     "regex": r"(?i)TRUNCATE\s+(TABLE\s+)?\w+"},
+    {"id": "prompt_injection",     "severity": "High",     "regex": r"(?i)(ignore previous instructions|you are now|act as|jailbreak)"},
+]
+
+
+class Severity(str, Enum):
+    Warn     = "Warn"
+    High     = "High"
+    Critical = "Critical"
+
+    @classmethod
+    def _order(cls) -> dict[str, int]:
+        return {"Warn": 0, "High": 1, "Critical": 2}
+
+    def __ge__(self, other: "Severity") -> bool:
+        return self._order()[self.value] >= self._order()[other.value]
+
+
+@dataclass
+class ScanResult:
+    hit: bool
+    pattern: Optional[str] = None
+    severity: Optional[Severity] = None
+    category: Optional[str] = None
+    all_hits: list[dict] = field(default_factory=list)
+
+    @property
+    def blocked(self) -> bool:
+        return self.hit and self.severity == Severity.Critical
+
+    @property
+    def warned(self) -> bool:
+        return self.hit and self.severity in (Severity.High, Severity.Warn)
+
+    def __bool__(self) -> bool:
+        return self.hit
+
+
+class RemoteScanner:
+    """
+    Fetches the SIGIL pattern bundle from registry.sigil-protocol.org and
+    compiles regexes locally. Patterns are cached for SIGIL_BUNDLE_TTL seconds
+    (default 5 minutes). Falls back to built-ins if the registry is unreachable.
+    """
+
+    def __init__(self) -> None:
+        self._patterns: list[dict] = []
+        self._compiled: list[tuple[re.Pattern, dict]] = []
+        self._fetched_at: float = 0.0
+        self._min_sev = Severity(MIN_SEVERITY)
+
+    def _needs_refresh(self) -> bool:
+        return time.monotonic() - self._fetched_at > BUNDLE_TTL
+
+    def _load(self) -> None:
+        if OFFLINE:
+            self._patterns = _BUILTIN_PATTERNS
+        else:
+            try:
+                resp = httpx.get(
+                    f"{REGISTRY_URL}/patterns/bundle",
+                    timeout=5.0,
+                    headers={"Accept": "application/json"},
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                self._patterns = data if isinstance(data, list) else data.get("patterns", [])
+            except Exception:
+                if not self._patterns:
+                    self._patterns = _BUILTIN_PATTERNS
+
+        self._compiled = []
+        for p in self._patterns:
+            try:
+                self._compiled.append((re.compile(p["regex"]), p))
+            except re.error:
+                pass
+        self._fetched_at = time.monotonic()
+
+    def scan(self, text: str) -> ScanResult:
+        """Scan text for security findings. Returns the highest-severity hit."""
+        if self._needs_refresh():
+            self._load()
+
+        if isinstance(text, (dict, list)):
+            text = json.dumps(text)
+
+        hits = []
+        for pattern, meta in self._compiled:
+            if pattern.search(text):
+                sev = Severity(meta.get("severity", "Warn"))
+                if sev >= self._min_sev:
+                    hits.append({**meta, "severity_enum": sev})
+
+        if not hits:
+            return ScanResult(hit=False)
+
+        # Return the highest-severity hit as the primary
+        hits.sort(key=lambda h: Severity._order()[h["severity_enum"].value], reverse=True)
+        top = hits[0]
+        return ScanResult(
+            hit=True,
+            pattern=top.get("id") or top.get("pattern_name"),
+            severity=top["severity_enum"],
+            category=top.get("category"),
+            all_hits=hits,
+        )
+
+    def scan_json(self, obj) -> ScanResult:
+        return self.scan(json.dumps(obj))
+
+
+# Module-level default scanner instance (lazy-loaded)
+_default_scanner: Optional[RemoteScanner] = None
+
+
+def scanner() -> RemoteScanner:
+    """Return the module-level default scanner, creating it if necessary."""
+    global _default_scanner
+    if _default_scanner is None:
+        _default_scanner = RemoteScanner()
+    return _default_scanner
+
+
+def scan(text: str) -> ScanResult:
+    """Convenience function — scan text using the default scanner."""
+    return scanner().scan(text)

sigil_protocol-0.1.0/tests/test_scanner.py

@@ -0,0 +1,114 @@
+"""Tests for sigil-protocol core scanner."""
+
+import json
+import pytest
+from unittest.mock import patch, MagicMock
+
+from sigil_protocol.scanner import RemoteScanner, ScanResult, Severity, scan
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+@pytest.fixture
+def offline_scanner(monkeypatch):
+    """Scanner forced to use built-in patterns (no HTTP)."""
+    monkeypatch.setenv("SIGIL_OFFLINE", "true")
+    s = RemoteScanner()
+    s._needs_refresh = lambda: True  # force reload
+    return s
+
+
+# ── Core scanner ──────────────────────────────────────────────────────────────
+
+def test_clean_payload(offline_scanner):
+    result = offline_scanner.scan('{"query": "SELECT name FROM users WHERE id=1"}')
+    assert not result.hit
+    assert not result.blocked
+    assert result.severity is None
+
+
+def test_aws_key_detected(offline_scanner):
+    result = offline_scanner.scan("AKIAIOSFODNN7EXAMPLE")
+    assert result.hit
+    assert result.pattern == "aws_access_key_id"
+    assert result.severity == Severity.Critical
+    assert result.blocked
+
+
+def test_openai_key_detected(offline_scanner):
+    result = offline_scanner.scan("Authorization: Bearer sk-abc123def456ghi789jkl012mno345pqr678")
+    assert result.hit
+    assert result.severity == Severity.Critical
+
+
+def test_sql_drop_detected(offline_scanner):
+    result = offline_scanner.scan("DROP TABLE users")
+    assert result.hit
+    assert result.blocked
+
+
+def test_sql_delete_no_where(offline_scanner):
+    result = offline_scanner.scan("DELETE FROM accounts")
+    assert result.hit
+
+
+def test_json_input(offline_scanner):
+    payload = {"db": "prod", "query": "DROP TABLE payments"}
+    result = offline_scanner.scan(json.dumps(payload))
+    assert result.hit
+
+
+def test_dict_input_coerced(offline_scanner):
+    """scan() should accept dict and coerce to JSON string."""
+    result = offline_scanner.scan(json.dumps({"key": "AKIAIOSFODNN7EXAMPLE"}))
+    assert result.hit
+
+
+def test_multiple_hits_highest_severity_returned(offline_scanner):
+    """When multiple patterns hit, the most severe should be primary."""
+    payload = json.dumps({
+        "key": "AKIAIOSFODNN7EXAMPLE",
+        "q": "DROP TABLE payments",
+    })
+    result = offline_scanner.scan(payload)
+    assert result.severity == Severity.Critical
+    assert len(result.all_hits) >= 2
+
+
+def test_scan_result_bool_false():
+    r = ScanResult(hit=False)
+    assert not r
+    assert not r.blocked
+    assert not r.warned
+
+
+def test_scan_result_bool_true():
+    r = ScanResult(hit=True, severity=Severity.Critical, pattern="aws_access_key_id")
+    assert r
+    assert r.blocked
+    assert not r.warned
+
+
+def test_scan_result_high_severity():
+    r = ScanResult(hit=True, severity=Severity.High, pattern="generic_secret")
+    assert r.warned
+    assert not r.blocked
+
+
+# ── Module-level convenience function ─────────────────────────────────────────
+
+def test_module_scan_clean(monkeypatch):
+    monkeypatch.setenv("SIGIL_OFFLINE", "true")
+    from sigil_protocol.scanner import RemoteScanner, scan as module_scan
+    s = RemoteScanner()
+    result = s.scan("hello world — nothing sensitive here at all")
+    assert not result.hit
+    assert result.severity is None
+
+
+# ── Severity ordering ─────────────────────────────────────────────────────────
+
+def test_severity_ordering():
+    assert Severity.Critical >= Severity.High
+    assert Severity.High >= Severity.Warn
+    assert not (Severity.Warn >= Severity.Critical)