openscript-sdk 0.1.0__py3-none-any.whl

openscript_sdk/hooks/config.py

@@ -0,0 +1,144 @@
+"""The Claude Code hook's configuration: one YAML file, checked strictly.
+
+    version: 1
+    firewall:  {rules: {...}}                     # ToolRules, or rules_path next to this file
+    session:   {sources: [...], sinks: [...]}     # SessionTaintPolicy, names may end in *
+    redact:    {secrets: true, pii: false, tools: [...]}
+    audit:     {path: null, include_args: false}
+
+Every section is optional except ``version``, and every key is checked: a
+misspelt one is an error, not a setting quietly ignored. A section that is
+present but would never act (a firewall with no rules, a session rule with no
+sources) is an error too, as it is everywhere else in this package.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+from openscript_sdk.policies.session_taint import TaintAction
+from openscript_sdk.policies.tool_firewall import ToolRules, load_rules
+
+#: Claude Code's own tool names, for telling a typo from an MCP tool.
+BUILT_IN_TOOLS = frozenset(
+    {
+        "Agent",
+        "Bash",
+        "Edit",
+        "Glob",
+        "Grep",
+        "MultiEdit",
+        "NotebookEdit",
+        "Read",
+        "Task",
+        "TodoWrite",
+        "WebFetch",
+        "WebSearch",
+        "Write",
+    }
+)
+
+
+class ConfigError(Exception):
+    """The configuration is missing, unreadable, or would not do what it says."""
+
+
+class _Section(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class FirewallSection(_Section):
+    rules: dict[str, Any] = Field(default_factory=dict)
+    default_deny: bool = False
+    rules_path: str | None = None
+
+    @model_validator(mode="after")
+    def _one_source_of_rules(self) -> FirewallSection:
+        if self.rules_path and self.rules:
+            raise ValueError("firewall takes rules or rules_path, not both")
+        if not self.rules_path and not self.rules:
+            raise ValueError("firewall has no rules, so it would never act; remove the section")
+        return self
+
+
+class SessionSection(_Section):
+    sources: list[str]
+    sinks: list[str]
+    on_taint: TaintAction = TaintAction.REQUIRE_APPROVAL
+    known: dict[str, dict[str, list[str]]] | None = None
+    updates: list[str] | None = None
+
+
+class RedactSection(_Section):
+    secrets: bool = True
+    pii: bool = False
+    internal_urls: bool = False
+    tools: list[str] = Field(
+        default_factory=lambda: ["Bash", "Read", "WebFetch", "WebSearch", "mcp__*"]
+    )
+
+    def covers(self, name: str) -> bool:
+        return (self.secrets or self.pii or self.internal_urls) and any(
+            name == tool or (tool.endswith("*") and name.startswith(tool[:-1]))
+            for tool in self.tools
+        )
+
+
+class AuditSection(_Section):
+    path: str | None = None
+    include_args: bool = False
+
+
+class HookConfig(_Section):
+    version: Literal[1]
+    role: str | None = None
+    firewall: FirewallSection | None = None
+    session: SessionSection | None = None
+    redact: RedactSection = Field(default_factory=RedactSection)
+    audit: AuditSection = Field(default_factory=AuditSection)
+
+
+def load_config(path: Path) -> tuple[HookConfig, ToolRules | None]:
+    """The config at *path*, and its firewall rules (None when there is no firewall)."""
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise ConfigError(f"no OpenScript config at {path}") from None
+    except (OSError, yaml.YAMLError) as error:
+        raise ConfigError(f"cannot read the OpenScript config at {path}: {error}") from None
+    if not isinstance(raw, dict):
+        raise ConfigError(f"the OpenScript config at {path} is empty or not a mapping")
+    try:
+        config = HookConfig.model_validate(raw)
+        rules = None
+        if config.firewall is not None:
+            if config.firewall.rules_path:
+                rules = load_rules(str(path.parent / config.firewall.rules_path))
+            else:
+                rules = ToolRules.model_validate(
+                    {"rules": config.firewall.rules, "default_deny": config.firewall.default_deny}
+                )
+    except (ValidationError, ValueError, OSError) as error:
+        raise ConfigError(f"the OpenScript config at {path} is not valid: {error}") from None
+    return config, rules
+
+
+def unknown_names(config: HookConfig, rules: ToolRules | None) -> list[str]:
+    """Tool names in the config that are neither Claude Code's nor an MCP tool's.
+
+    A misspelt name ("Webfetch") matches nothing and nobody is told, so the
+    hook's ``check`` command reports them.
+    """
+    names: set[str] = set(rules.rules) if rules is not None else set()
+    if config.session is not None:
+        names |= set(config.session.sources) | set(config.session.sinks)
+    names |= set(config.redact.tools)
+    return sorted(
+        name
+        for name in names
+        if name != "*" and not name.startswith("mcp__") and name.rstrip("*") not in BUILT_IN_TOOLS
+    )

openscript_sdk/hooks/settings_example.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(WebFetch|WebSearch|Write|Edit|MultiEdit|NotebookEdit|mcp__.*)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/ABSOLUTE/PATH/TO/.venv/bin/openscript-hook pre-tool-use || exit 2",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(Bash|Read|WebFetch|WebSearch|mcp__.*)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/ABSOLUTE/PATH/TO/.venv/bin/openscript-hook post-tool-use",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

openscript_sdk/hooks/settings_strict_example.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(Bash|WebFetch|WebSearch|Write|Edit|MultiEdit|NotebookEdit|mcp__.*)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/ABSOLUTE/PATH/TO/.venv/bin/openscript-hook pre-tool-use || exit 2",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(Bash|Read|WebFetch|WebSearch|mcp__.*)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/ABSOLUTE/PATH/TO/.venv/bin/openscript-hook post-tool-use",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

openscript_sdk/integrations/langchain.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Sequence
+from typing import Any
+
+from openscript_sdk.contracts.interceptor import Policy
+from openscript_sdk.middleware.middleware import SecureAgent
+
+
+def wrap_agent(
+    agent: Any,
+    policies: Sequence[Policy] | None = None,
+    *,
+    interceptors: Sequence[Policy] | None = None,
+) -> SecureAgent:
+    """Wrap a LangChain AgentExecutor with OpenScript policies.
+
+    Usage:
+      from openscript_sdk.integrations.langchain import wrap_agent
+      from openscript_sdk import NoopInterceptor
+      secure = wrap_agent(agent, policies=[NoopInterceptor()])
+      result = await secure.invoke({"input": "hello"})
+    """
+    if interceptors is not None:
+        warnings.warn(
+            "interceptors= is deprecated; use policies= instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        policies = policies or interceptors
+    return SecureAgent(agent=agent, policies=policies)

openscript_sdk/integrations/langgraph.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Sequence
+from typing import Any
+
+from openscript_sdk.contracts.interceptor import Policy
+from openscript_sdk.middleware.middleware import SecureAgent
+
+
+def wrap_graph_agent(
+    graph: Any,
+    policies: Sequence[Policy] | None = None,
+    *,
+    interceptors: Sequence[Policy] | None = None,
+) -> SecureAgent:
+    """Wrap a LangGraph compiled graph with OpenScript policies.
+
+    A named alias for SecureAgent(graph, policies=...) — it proxies the
+    graph's whole invoke()/stream() call through the policy pipeline, not
+    individual node executions. Nothing here is LangGraph-specific beyond
+    the name: any object exposing that same invoke/stream shape works
+    identically via SecureAgent directly.
+    """
+    if interceptors is not None:
+        warnings.warn(
+            "interceptors= is deprecated; use policies= instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        policies = policies or interceptors
+    return SecureAgent(agent=graph, policies=policies)

openscript_sdk/interceptors/base.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from openscript_sdk.contracts.types import ActionContext, FailureMode
+
+
+class NoopInterceptor:
+    """Pass-through interceptor with zero logic. Default when no interceptors configured."""
+
+    failure_mode: FailureMode = FailureMode.FAIL_OPEN
+
+    async def before_action(self, context: ActionContext) -> ActionContext:
+        return context
+
+    async def after_action(self, context: ActionContext) -> ActionContext:
+        return context

openscript_sdk/interceptors/event_writer.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import structlog
+
+from openscript_sdk.contracts.server_types import Event, EventType
+from openscript_sdk.contracts.types import ActionContext, FailureMode
+from openscript_sdk.events.approvals import action_hash
+from openscript_sdk.events.writer import EventWriter
+from openscript_sdk.observability.risk import aggregate_risk
+
+logger = structlog.get_logger(__name__)
+
+
+class AuditPolicy:
+    """Writes before/after events to the event store for every agent action,
+    and an ``action_blocked`` event for every action the pipeline refuses.
+
+    Satisfies the openscript_sdk/contracts/Policy protocol. Lives alongside
+    NoopInterceptor in openscript_sdk/interceptors/.
+
+    A refused action is recorded through on_blocked(), which SecureAgent calls
+    wherever this policy sits in the list. That matters because the place it is
+    meant to sit is last: a prompt denied by an earlier policy never reaches
+    before_action here, and used to leave no event at all.
+
+    The blocked event carries the input as it stood when the action was
+    refused, so redactions made by policies listed *before* the one that denied
+    are applied and later ones are not. Pass ``record_blocked_input=False`` to
+    store only the input hash when the raw text of a refused prompt should not
+    reach the event store.
+    """
+
+    failure_mode: FailureMode = FailureMode.FAIL_OPEN
+
+    def __init__(self, writer: EventWriter, record_blocked_input: bool = True) -> None:
+        self._writer = writer
+        self._record_blocked_input = record_blocked_input
+        self._sequence_counters: dict[str, int] = {}
+
+    async def before_action(self, context: ActionContext) -> ActionContext:
+        seq = self._next_sequence(context.session_id)
+        event = Event(
+            session_id=context.session_id,
+            agent_id=context.agent_id,
+            event_type=EventType.INTERCEPTOR_BEFORE,
+            payload={
+                "action": context.action,
+                "input_data": context.input_data,
+                "capabilities": {
+                    "untrusted_input": context.capabilities.untrusted_input,
+                    "sensitive_access": context.capabilities.sensitive_access,
+                    "external_write": context.capabilities.external_write,
+                },
+            },
+            sequence_num=seq,
+        )
+        await self._writer.write(event)
+        return context
+
+    async def after_action(self, context: ActionContext) -> ActionContext:
+        # Computed here (not read from context) because SecureAgent's final
+        # aggregation runs after the policy loop; place AuditPolicy last in
+        # policies=[...] so the recorded score covers every other policy.
+        risk_score, risk_categories = aggregate_risk(context)
+        seq = self._next_sequence(context.session_id)
+        event = Event(
+            session_id=context.session_id,
+            agent_id=context.agent_id,
+            event_type=EventType.INTERCEPTOR_AFTER,
+            payload={
+                "action": context.action,
+                "output_data": context.output_data,
+                "risk_score": risk_score,
+                "risk_categories": risk_categories,
+            },
+            sequence_num=seq,
+        )
+        await self._writer.write(event)
+        return context
+
+    async def on_blocked(
+        self,
+        context: ActionContext,
+        *,
+        blocked_by: str,
+        phase: str,
+        approval_id: str = "",
+    ) -> None:
+        payload: dict[str, Any] = {
+            "action": context.action,
+            "phase": phase,
+            "blocked_by": blocked_by,
+            "decision": context.decision.value,
+            "reason": context.decision_reason,
+            # Final: SecureAgent aggregates before it calls this hook.
+            "risk_score": context.risk_score,
+            "risk_categories": context.risk_categories,
+            "input_hash": action_hash(context.action, context.input_data),
+        }
+        if self._record_blocked_input:
+            payload["input_data"] = context.input_data
+        if approval_id:
+            payload["approval_id"] = approval_id
+        event = Event(
+            session_id=context.session_id,
+            agent_id=context.agent_id,
+            event_type=EventType.ACTION_BLOCKED,
+            payload=payload,
+            sequence_num=self._next_sequence(context.session_id),
+        )
+        await self._writer.write(event)
+
+    def _next_sequence(self, session_id: str) -> int:
+        count = self._sequence_counters.get(session_id, 0) + 1
+        self._sequence_counters[session_id] = count
+        return count
+
+
+class EventWriterInterceptor(AuditPolicy):
+    """Deprecated — use AuditPolicy instead."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn(
+            "EventWriterInterceptor is deprecated; use AuditPolicy instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)

openscript_sdk/interceptors/pii.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import warnings
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from openscript_sdk.contracts.interceptor import GuardScan, StreamGuard
+from openscript_sdk.contracts.server_types import Event, EventType
+from openscript_sdk.contracts.types import ActionContext, FailureMode, InterceptorDecision
+from openscript_sdk.policies.redaction import _find_pii as _find_pii
+from openscript_sdk.policies.redaction import _redact_pii_text as _redact_text
+from openscript_sdk.policies.redaction import _walk_redact_pii as _walk_redact
+
+if TYPE_CHECKING:
+    from openscript_sdk.events.writer import EventWriter
+
+logger = structlog.get_logger(__name__)
+
+
+class PIIMode(StrEnum):
+    REDACT = "redact"
+    DENY = "deny"
+
+
+# Labels whose exposure is directly exploitable (identity theft, account
+# takeover); the rest are contact/network identifiers.
+_HIGH_SEVERITY_LABELS = frozenset({"ssn", "credit_card", "api_key"})
+
+
+def _pii_risk(found_labels: list[str]) -> float:
+    if not found_labels:
+        return 0.0
+    return 0.8 if any(label in _HIGH_SEVERITY_LABELS for label in found_labels) else 0.4
+
+
+class _PIIStreamGuard:
+    """Incremental scanner backing PIIPolicy in guarded streams."""
+
+    name = "PIIPolicy"
+    # generous bound: the longest realistic PII match (emails, spaced card
+    # numbers) is well under this
+    max_match_len = 256
+
+    def __init__(self, mode: PIIMode) -> None:
+        self._mode = mode
+
+    def scan(self, text: str, final: bool = False) -> GuardScan:
+        redacted, labels = _redact_text(text, final=final)
+        if not labels:
+            return GuardScan(text=text)
+        risk = _pii_risk(labels)
+        if self._mode == PIIMode.DENY:
+            return GuardScan(
+                text=text,
+                labels=labels,
+                risk=risk,
+                deny=True,
+                reason=f"PII detected in stream: {', '.join(set(labels))}",
+            )
+        return GuardScan(text=redacted, labels=labels, risk=risk)
+
+
+class PIIPolicy:
+    """Scans agent output for PII and either redacts or blocks.
+
+    Runs in after_action. before_action is a pass-through.
+    Default mode is REDACT so observability is preserved; use DENY for
+    strict environments.
+
+    Results land in context.metadata["pii"] using the standardized shape:
+      {"risk": float, "category": "pii", "found": [labels...], "redacted": bool}
+    """
+
+    failure_mode: FailureMode = FailureMode.FAIL_OPEN
+
+    def __init__(
+        self,
+        mode: PIIMode | str = PIIMode.REDACT,
+        writer: EventWriter | None = None,
+    ) -> None:
+        self._mode = PIIMode(mode)
+        self._writer = writer
+        self._sequence_counters: dict[str, int] = {}
+
+    async def before_action(self, context: ActionContext) -> ActionContext:
+        return context
+
+    def stream_guard(self) -> StreamGuard:
+        return _PIIStreamGuard(self._mode)
+
+    async def after_action(self, context: ActionContext) -> ActionContext:
+        redacted_output, found_labels = _walk_redact(context.output_data)
+
+        if not found_labels:
+            context.metadata["pii"] = {
+                "risk": 0.0,
+                "category": "pii",
+                "found": [],
+                "redacted": False,
+            }
+            return context
+
+        logger.warning(
+            "pii_detected",
+            session_id=context.session_id,
+            agent_id=context.agent_id,
+            types=found_labels,
+            mode=self._mode.value,
+        )
+
+        risk = _pii_risk(found_labels)
+        if self._mode == PIIMode.DENY:
+            context.metadata["pii"] = {
+                "risk": risk,
+                "category": "pii",
+                "found": found_labels,
+                "redacted": False,
+            }
+            context.decision = InterceptorDecision.DENY
+            context.decision_reason = f"PII detected in output: {', '.join(set(found_labels))}"
+        else:
+            context.output_data = redacted_output
+            context.metadata["pii"] = {
+                "risk": risk,
+                "category": "pii",
+                "found": found_labels,
+                "redacted": True,
+            }
+
+        if self._writer is not None:
+            await self._emit_pii_event(context, found_labels)
+
+        return context
+
+    async def _emit_pii_event(self, context: ActionContext, found_labels: list[str]) -> None:
+        seq = self._next_sequence(context.session_id)
+        event = Event(
+            session_id=context.session_id,
+            agent_id=context.agent_id,
+            event_type=EventType.POLICY_EVALUATED,
+            payload={
+                "policy": "pii_check",
+                "pii_types": list(set(found_labels)),
+                "mode": self._mode.value,
+                "decision": context.decision.value,
+            },
+            sequence_num=seq,
+        )
+        await self._writer.write(event)  # type: ignore[union-attr]
+
+    def _next_sequence(self, session_id: str) -> int:
+        count = self._sequence_counters.get(session_id, 0) + 1
+        self._sequence_counters[session_id] = count
+        return count
+
+
+class PIIInterceptor(PIIPolicy):
+    """Deprecated — use PIIPolicy instead."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn(
+            "PIIInterceptor is deprecated; use PIIPolicy instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)