voidhack-agent-firewall 1.0.0__py3-none-any.whl

voidhack_agent_firewall/__init__.py

@@ -0,0 +1,19 @@
+from .client import FirewallOpenAI
+from .langchain import FirewallCallbackHandler
+from .providers import (
+    OPENAI_COMPATIBLE_BASE_URLS,
+    FirewallAnthropic,
+    FirewallGeminiModel,
+    FirewallGoogleGenerativeAI,
+    create_openai_compatible_firewall,
+)
+
+__all__ = [
+    "FirewallOpenAI",
+    "FirewallCallbackHandler",
+    "FirewallAnthropic",
+    "FirewallGeminiModel",
+    "FirewallGoogleGenerativeAI",
+    "OPENAI_COMPATIBLE_BASE_URLS",
+    "create_openai_compatible_firewall",
+]

voidhack_agent_firewall/client.py

@@ -0,0 +1,124 @@
+from typing import Any, Dict
+from openai import OpenAI
+
+from . import pii
+from .policy import Policy, load_policy
+from .rules import check_tool_calls
+from .schemas import Status, ToolCall
+
+class CompletionsWrapper:
+    def __init__(self, original_completions: Any, policy: Policy):
+        self._original = original_completions
+        self._policy = policy
+
+    def create(self, *args: Any, **kwargs: Any) -> Any:
+        # 1. Inbound Inspection (Locally check input messages for PII/secrets)
+        messages = kwargs.get("messages", [])
+        for msg in messages:
+            content = msg.get("content")
+            if isinstance(content, str) and content:
+                # Mask credentials or secrets in prompts locally
+                redacted, pii_check = pii.scan_and_redact(content, self._policy, source=msg.get("role", "user"))
+                if pii_check.status is Status.FLAG:
+                    msg["content"] = redacted
+
+        # 2. Call the actual upstream LLM
+        response = self._original.create(*args, **kwargs)
+
+        # 3. Outbound Inspection (Locally check response tool calls and arguments)
+        choices = getattr(response, "choices", [])
+        if not choices:
+            return response
+
+        message = choices[0].message
+        raw_calls = getattr(message, "tool_calls", None) or []
+        
+        # Parse into our schema structure to run checks
+        tool_calls = []
+        for tc in raw_calls:
+            tool_calls.append(ToolCall(
+                id=tc.id,
+                type=tc.type,
+                function={"name": tc.function.name, "arguments": tc.function.arguments}
+            ))
+
+        firewall_meta: Dict[str, Any] = {
+            "action": "allow",
+            "reason": None,
+            "rule_fired": None,
+            "stripped_tool_calls": [],
+            "blocked_calls": []
+        }
+
+        if tool_calls:
+            findings, rules_check = check_tool_calls(tool_calls, self._policy)
+            blocked_ids = {f.tool_call_id for f in findings if f.status is Status.BLOCK}
+
+            if blocked_ids:
+                # Strip blocked tool calls so agent framework never receives them
+                kept = [tc for tc in raw_calls if tc.id not in blocked_ids]
+                message.tool_calls = kept if kept else None
+                
+                # If everything was stripped and no text response remains, inject block message
+                if not kept and not getattr(message, "content", None):
+                    message.content = self._policy.block_message
+                    choices[0].finish_reason = "content_filter"
+
+                firewall_meta["action"] = "block"
+                firewall_meta["stripped_tool_calls"] = sorted(blocked_ids)
+                first_blocked = next(f for f in findings if f.status is Status.BLOCK)
+                firewall_meta["rule_fired"] = "deterministic_rules"
+                firewall_meta["reason"] = "; ".join(first_blocked.reasons)
+
+                # Capture safe representation for logging
+                by_id = {tc.id: tc for tc in raw_calls}
+                for f in findings:
+                    if f.status is Status.BLOCK:
+                        tc_ref = by_id.get(f.tool_call_id)
+                        raw_args = tc_ref.function.arguments if tc_ref else ""
+                        safe_args, _ = pii.redact(raw_args or "", self._policy)
+                        firewall_meta["blocked_calls"].append({
+                            "name": f.tool_name,
+                            "arguments": safe_args,
+                            "reasons": f.reasons
+                        })
+
+        # Redact secrets from text output if any
+        content = getattr(message, "content", None)
+        if isinstance(content, str) and content:
+            redacted, pii_check = pii.scan_and_redact(content, self._policy, source="completion")
+            if pii_check.status is Status.FLAG:
+                message.content = redacted
+                firewall_meta["action"] = "redact"
+                firewall_meta["reason"] = "secret/PII redacted from model output"
+
+        # Inject firewall metadata into response object
+        response.model_extra = getattr(response, "model_extra", {}) or {}
+        response.model_extra["firewall"] = firewall_meta
+
+        return response
+
+
+class ChatWrapper:
+    def __init__(self, original_chat: Any, policy: Policy):
+        self._chat = original_chat
+        self.completions = CompletionsWrapper(original_chat.completions, policy)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._chat, name)
+
+
+class FirewallOpenAI:
+    """Sleek drop-in client wrapper that adds policy controls to any OpenAI client in-process."""
+    def __init__(
+        self,
+        client: OpenAI,
+        policy_path: str
+    ):
+        self._client = client
+        self._policy = load_policy(policy_path)
+        self.chat = ChatWrapper(client.chat, self._policy)
+
+    def __getattr__(self, name: str) -> Any:
+        # Proxy attributes back to the original client
+        return getattr(self._client, name)

voidhack_agent_firewall/langchain.py

@@ -0,0 +1,65 @@
+from typing import Any, Dict, List, Optional
+
+from .policy import load_policy
+from .rules import check_tool_calls
+from .schemas import Status, ToolCall
+
+# Attempt to import LangChain's callback base class
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+except ImportError:
+    # Fallback mock if langchain is not installed in the current environment
+    class BaseCallbackHandler: # type: ignore
+        pass
+
+class PolicyViolationError(ValueError):
+    """Raised when an agent action violates security policies."""
+    pass
+
+class FirewallCallbackHandler(BaseCallbackHandler):
+    """LangChain callback plugin that halts agent runs when tool calls or arguments violate security policy."""
+    def __init__(self, policy_path: str):
+        self.policy = load_policy(policy_path)
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any
+    ) -> Any:
+        """Intercepts tool execution right before it starts."""
+        tool_name = serialized.get("name", "")
+        
+        # Check against denied tools
+        if tool_name in self.policy.tool_denylist:
+            raise PolicyViolationError(
+                f"Security Block: Tool '{tool_name}' is restricted by security policy."
+            )
+
+        # Check against allowed tools & argument-level rules
+        if self.policy.tool_allowlist and tool_name not in self.policy.tool_allowlist:
+            raise PolicyViolationError(
+                f"Security Block: Tool '{tool_name}' is not in the allowed tool list."
+            )
+
+        # Wrap in a ToolCall object to run argument checks
+        # LangChain tools typically pass inputs as JSON string or keyword args
+        tc = ToolCall(
+            id=str(run_id or "lc-run"),
+            type="function",
+            function={"name": tool_name, "arguments": input_str}
+        )
+
+        findings, rules_check = check_tool_calls([tc], self.policy)
+        blocked = [f for f in findings if f.status is Status.BLOCK]
+        
+        if blocked:
+            reasons = "; ".join(blocked[0].reasons)
+            raise PolicyViolationError(
+                f"Security Block: Tool '{tool_name}' argument check failed. Reason: {reasons}"
+            )

voidhack_agent_firewall/pii.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import re
+
+from .policy import Policy
+from .schemas import CheckResult, Status
+
+_PII_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("email", re.compile(r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}")),
+    ("ssn", re.compile(r"\b\d{3}-\d{2}-\d{4}\b")),
+    ("credit_card", re.compile(r"\b(?:\d[ -]*?){13,16}\b")),
+    (
+        "phone",
+        re.compile(r"\b(?:\+?\d{1,2}[ -]?)?\(?\d{3}\)?[ -]?\d{3}[ -]?\d{4}\b"),
+    ),
+    ("ipv4", re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")),
+]
+
+
+def _mask(label: str) -> str:
+    return f"[REDACTED:{label}]"
+
+
+def redact(text: str, policy: Policy) -> tuple[str, list[str]]:
+    if not text:
+        return text, []
+
+    labels: list[str] = []
+    out = text
+
+    for name, pattern in policy.compiled_secrets():
+        if pattern.search(out):
+            out = pattern.sub(_mask(name), out)
+            labels.append(name)
+
+    for name, pattern in _PII_PATTERNS:
+        if pattern.search(out):
+            out = pattern.sub(_mask(name), out)
+            labels.append(name)
+
+    return out, labels
+
+
+def scan_and_redact(text: str, policy: Policy, source: str = "content") -> tuple[str, CheckResult]:
+    redacted, labels = redact(text, policy)
+    status = Status.FLAG if labels else Status.PASS
+    detail = f"redacted in {source}: {', '.join(labels)}" if labels else f"no PII in {source}"
+    return redacted, CheckResult(
+        name="pii_redaction",
+        status=status,
+        detail=detail,
+        meta={"labels": labels},
+    )

voidhack_agent_firewall/policy.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class SecretPattern:
+    name: str
+    regex: str
+
+    def compiled(self) -> re.Pattern[str]:
+        return re.compile(self.regex)
+
+
+@dataclass
+class ArgRule:
+    name: str
+    reason: str
+    regex: str
+    tools: list[str] = field(default_factory=lambda: ["*"])
+
+    def compiled(self) -> re.Pattern[str]:
+        return re.compile(self.regex)
+
+    def applies_to(self, tool: str) -> bool:
+        return "*" in self.tools or tool in self.tools
+
+
+@dataclass
+class Policy:
+    version: int = 1
+    description: str = ""
+    tool_allowlist: list[str] = field(default_factory=list)
+    tool_denylist: list[str] = field(default_factory=list)
+    egress_allowlist: list[str] = field(default_factory=list)
+    secret_patterns: list[SecretPattern] = field(default_factory=list)
+    arg_rules: list[ArgRule] = field(default_factory=list)
+    injection_phrases: list[str] = field(default_factory=list)
+    injection_threshold: float = 0.80
+    token_budget_per_session: int = 20000
+    fail_closed: bool = True
+    block_message: str = "[Agent Firewall] Action blocked by policy."
+
+    def tool_allowed(self, name: str) -> bool:
+        if name in self.tool_denylist:
+            return False
+        if not self.tool_allowlist:
+            return True
+        return name in self.tool_allowlist
+
+    def host_allowed(self, host: str) -> bool:
+        host = host.lower().strip()
+        for allowed in self.egress_allowlist:
+            allowed_host = allowed.lower().strip()
+            if host == allowed_host or host.endswith("." + allowed_host):
+                return True
+        return False
+
+    def compiled_secrets(self) -> list[tuple[str, re.Pattern[str]]]:
+        return [(pattern.name, pattern.compiled()) for pattern in self.secret_patterns]
+
+    def compiled_arg_rules(self) -> list[tuple[ArgRule, re.Pattern[str]]]:
+        return [(rule, rule.compiled()) for rule in self.arg_rules]
+
+
+def load_policy(path: str | Path) -> Policy:
+    raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+    return Policy(
+        version=int(raw.get("version", 1)),
+        description=str(raw.get("description", "")),
+        tool_allowlist=list(raw.get("tool_allowlist") or []),
+        tool_denylist=list(raw.get("tool_denylist") or []),
+        egress_allowlist=list(raw.get("egress_allowlist") or []),
+        secret_patterns=[
+            SecretPattern(name=str(item["name"]), regex=str(item["regex"]))
+            for item in raw.get("secret_patterns") or []
+        ],
+        arg_rules=[
+            ArgRule(
+                name=str(item["name"]),
+                reason=str(item["reason"]),
+                regex=str(item["regex"]),
+                tools=list(item.get("tools") or ["*"]),
+            )
+            for item in raw.get("arg_rules") or []
+        ],
+        injection_phrases=list(raw.get("injection_phrases") or []),
+        injection_threshold=float(raw.get("injection_threshold", 0.80)),
+        token_budget_per_session=int(raw.get("token_budget_per_session", 20000)),
+        fail_closed=bool(raw.get("fail_closed", True)),
+        block_message=str(
+            raw.get("block_message", "[Agent Firewall] Action blocked by policy.")
+        ),
+    )

voidhack_agent_firewall/providers.py

@@ -0,0 +1,249 @@
+import json
+from typing import Any, Callable
+
+from openai import OpenAI
+
+from . import pii
+from .client import FirewallOpenAI
+from .policy import Policy, load_policy
+from .rules import check_tool_calls
+from .schemas import Status, ToolCall
+
+OPENAI_COMPATIBLE_BASE_URLS: dict[str, str] = {
+    "openai": "https://api.openai.com/v1",
+    "groq": "https://api.groq.com/openai/v1",
+    "nvidia": "https://integrate.api.nvidia.com/v1",
+    "mistral": "https://api.mistral.ai/v1",
+    "together": "https://api.together.xyz/v1",
+    "fireworks": "https://api.fireworks.ai/inference/v1",
+    "perplexity": "https://api.perplexity.ai",
+    "deepseek": "https://api.deepseek.com",
+    "openrouter": "https://openrouter.ai/api/v1",
+    "local": "http://localhost:8000/v1",
+}
+
+
+def create_openai_compatible_firewall(
+    provider: str,
+    *,
+    api_key: str | None = None,
+    policy_path: str,
+    base_url: str | None = None,
+    **client_kwargs: Any,
+) -> FirewallOpenAI:
+    """Create a guarded OpenAI-compatible client for Groq/NVIDIA/Mistral/Together/etc."""
+    resolved_base_url = base_url or OPENAI_COMPATIBLE_BASE_URLS.get(provider)
+    if not resolved_base_url:
+        raise ValueError(f"Unknown OpenAI-compatible provider: {provider}")
+    raw = OpenAI(api_key=api_key, base_url=resolved_base_url, **client_kwargs)
+    return FirewallOpenAI(raw, policy_path=policy_path)
+
+
+def _stringify_args(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value if value is not None else {})
+    except TypeError:
+        return str(value)
+
+
+def _get(obj: Any, name: str, default: Any = None) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(name, default)
+    return getattr(obj, name, default)
+
+
+def _set(obj: Any, name: str, value: Any) -> None:
+    if isinstance(obj, dict):
+        obj[name] = value
+    else:
+        setattr(obj, name, value)
+
+
+def _firewall_meta() -> dict[str, Any]:
+    return {
+        "action": "allow",
+        "reason": None,
+        "rule_fired": None,
+        "stripped_tool_calls": [],
+        "blocked_calls": [],
+    }
+
+
+def _enforce_tool_calls(
+    calls: list[dict[str, Any]],
+    policy: Policy,
+    remove_blocked: Callable[[set[str]], None],
+) -> dict[str, Any]:
+    meta = _firewall_meta()
+    if not calls:
+        return meta
+
+    tool_calls = [
+        ToolCall(
+            id=call["id"],
+            type="function",
+            function={"name": call["name"], "arguments": _stringify_args(call.get("arguments"))},
+        )
+        for call in calls
+    ]
+    findings, _ = check_tool_calls(tool_calls, policy)
+    blocked_ids = {f.tool_call_id for f in findings if f.status is Status.BLOCK}
+    if not blocked_ids:
+        return meta
+
+    remove_blocked(blocked_ids)
+    first_blocked = next(f for f in findings if f.status is Status.BLOCK)
+    meta["action"] = "block"
+    meta["stripped_tool_calls"] = sorted(blocked_ids)
+    meta["rule_fired"] = "deterministic_rules"
+    meta["reason"] = "; ".join(first_blocked.reasons)
+    meta["blocked_calls"] = [
+        {"name": f.tool_name, "reasons": f.reasons}
+        for f in findings
+        if f.status is Status.BLOCK
+    ]
+    return meta
+
+
+def _redact_anthropic_messages(body: dict[str, Any], policy: Policy) -> None:
+    for msg in body.get("messages", []) or []:
+        content = msg.get("content")
+        role = msg.get("role", "user")
+        if isinstance(content, str) and content:
+            redacted, check = pii.scan_and_redact(content, policy, source=role)
+            if check.status is Status.FLAG:
+                msg["content"] = redacted
+        elif isinstance(content, list):
+            for part in content:
+                if isinstance(part, dict) and part.get("type") == "text":
+                    text = part.get("text")
+                    if isinstance(text, str) and text:
+                        redacted, check = pii.scan_and_redact(text, policy, source=role)
+                        if check.status is Status.FLAG:
+                            part["text"] = redacted
+
+
+class _AnthropicMessagesWrapper:
+    def __init__(self, messages: Any, policy: Policy):
+        self._messages = messages
+        self._policy = policy
+
+    def create(self, *args: Any, **kwargs: Any) -> Any:
+        body = kwargs if kwargs else (args[0] if args and isinstance(args[0], dict) else {})
+        _redact_anthropic_messages(body, self._policy)
+        response = self._messages.create(*args, **kwargs)
+        content = _get(response, "content", []) or []
+        calls = [
+            {"id": _get(part, "id"), "name": _get(part, "name"), "arguments": _get(part, "input")}
+            for part in content
+            if _get(part, "type") == "tool_use"
+        ]
+
+        def remove(blocked_ids: set[str]) -> None:
+            kept = [
+                part
+                for part in content
+                if _get(part, "type") != "tool_use" or _get(part, "id") not in blocked_ids
+            ]
+            if not kept:
+                kept = [{"type": "text", "text": self._policy.block_message}]
+            _set(response, "content", kept)
+
+        _set(response, "firewall", _enforce_tool_calls(calls, self._policy, remove))
+        return response
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._messages, name)
+
+
+class FirewallAnthropic:
+    """Drop-in wrapper for Anthropic Claude clients using native tool_use blocks."""
+
+    def __init__(self, client: Any, policy_path: str):
+        self._client = client
+        self._policy = load_policy(policy_path)
+        self.messages = _AnthropicMessagesWrapper(client.messages, self._policy)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+class FirewallGeminiModel:
+    """Wrapper for Gemini model objects that strips blocked function_call parts."""
+
+    def __init__(self, model: Any, policy: Policy):
+        self._model = model
+        self._policy = policy
+
+    def generate_content(self, *args: Any, **kwargs: Any) -> Any:
+        response = self._model.generate_content(*args, **kwargs)
+        candidates = _get(response, "candidates", []) or []
+        calls: list[dict[str, Any]] = []
+        for candidate_index, candidate in enumerate(candidates):
+            content = _get(candidate, "content")
+            parts = _get(content, "parts", []) if content is not None else []
+            for part_index, part in enumerate(parts):
+                fn = _get(part, "function_call") or _get(part, "functionCall")
+                if fn is not None:
+                    calls.append(
+                        {
+                            "id": f"gemini-{candidate_index}-{part_index}",
+                            "candidate_index": candidate_index,
+                            "part_index": part_index,
+                            "name": _get(fn, "name"),
+                            "arguments": _get(fn, "args") or _get(fn, "arguments") or {},
+                        }
+                    )
+
+        def remove(blocked_ids: set[str]) -> None:
+            for call in sorted(calls, key=lambda c: c["part_index"], reverse=True):
+                if call["id"] not in blocked_ids:
+                    continue
+                candidate = candidates[call["candidate_index"]]
+                parts = _get(_get(candidate, "content"), "parts", [])
+                if isinstance(parts, list):
+                    parts.pop(call["part_index"])
+                    if not parts:
+                        parts.append({"text": self._policy.block_message})
+
+        _set(response, "firewall", _enforce_tool_calls(calls, self._policy, remove))
+        return response
+
+    def start_chat(self, *args: Any, **kwargs: Any) -> Any:
+        chat = self._model.start_chat(*args, **kwargs)
+        return FirewallGeminiChat(chat, self._policy)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._model, name)
+
+
+class FirewallGeminiChat:
+    def __init__(self, chat: Any, policy: Policy):
+        self._chat = chat
+        self._policy = policy
+
+    def send_message(self, *args: Any, **kwargs: Any) -> Any:
+        response = self._chat.send_message(*args, **kwargs)
+        return FirewallGeminiModel(
+            type("_OneShotGeminiModel", (), {"generate_content": lambda *_a, **_k: response})(),
+            self._policy,
+        ).generate_content()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._chat, name)
+
+
+class FirewallGoogleGenerativeAI:
+    """Drop-in wrapper for google-generativeai clients."""
+
+    def __init__(self, client: Any, policy_path: str):
+        self._client = client
+        self._policy = load_policy(policy_path)
+
+    def GenerativeModel(self, *args: Any, **kwargs: Any) -> FirewallGeminiModel:
+        return FirewallGeminiModel(self._client.GenerativeModel(*args, **kwargs), self._policy)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

voidhack_agent_firewall/rules.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import re
+import time
+import urllib.parse
+from dataclasses import dataclass, field
+
+from .policy import Policy
+from .schemas import CheckResult, Status, ToolCall
+
+_URL_RE = re.compile(r"(?:[a-z][a-z0-9+.\-]*:)?//[^\s\"'<>]+", re.IGNORECASE)
+_EMAIL_RE = re.compile(r"[A-Za-z0-9._%+\-]+@([A-Za-z0-9.\-]+\.[A-Za-z]{2,})")
+
+
+@dataclass
+class ToolFinding:
+    tool_call_id: str
+    tool_name: str
+    status: Status
+    reasons: list[str] = field(default_factory=list)
+    hosts: list[str] = field(default_factory=list)
+    secrets: list[str] = field(default_factory=list)
+    arg_hits: list[str] = field(default_factory=list)
+
+
+def _extract_hosts(arguments: str) -> list[str]:
+    hosts: list[str] = []
+    for url in _URL_RE.findall(arguments):
+        netloc = urllib.parse.urlparse(url).netloc.lower()
+        if netloc:
+            hosts.append(netloc.split("@")[-1].split(":")[0])
+    for match in _EMAIL_RE.finditer(arguments):
+        hosts.append(match.group(1).lower())
+    return hosts
+
+
+def find_secrets(text: str, policy: Policy) -> list[str]:
+    hits: list[str] = []
+    for name, pattern in policy.compiled_secrets():
+        if pattern.search(text or ""):
+            hits.append(name)
+    return hits
+
+
+def check_arg_rules(tool: str, arguments: str, policy: Policy) -> list[str]:
+    hits: list[str] = []
+    for rule, pattern in policy.compiled_arg_rules():
+        if rule.applies_to(tool) and pattern.search(arguments or ""):
+            hits.append(rule.reason)
+    return hits
+
+
+def inspect_tool_call(tc: ToolCall, policy: Policy) -> ToolFinding:
+    name = tc.function.name or "(unnamed)"
+    args = tc.function.arguments or ""
+    finding = ToolFinding(tool_call_id=tc.id, tool_name=name, status=Status.PASS)
+
+    if not policy.tool_allowed(name):
+        finding.status = Status.BLOCK
+        verb = "denied" if name in policy.tool_denylist else "not on allowlist"
+        finding.reasons.append(f"tool '{name}' is {verb}")
+
+    hosts = _extract_hosts(args)
+    finding.hosts = hosts
+    bad_hosts = [host for host in hosts if not policy.host_allowed(host)]
+    if bad_hosts:
+        finding.status = Status.BLOCK
+        finding.reasons.append(
+            f"egress to non-allowlisted host(s): {', '.join(sorted(set(bad_hosts)))}"
+        )
+
+    secrets = find_secrets(args, policy)
+    finding.secrets = secrets
+    if secrets:
+        finding.status = Status.BLOCK
+        finding.reasons.append(f"secret(s) in tool args: {', '.join(secrets)}")
+
+    arg_hits = check_arg_rules(name, args, policy)
+    finding.arg_hits = arg_hits
+    if arg_hits:
+        finding.status = Status.BLOCK
+        finding.reasons.extend(arg_hits)
+
+    return finding
+
+
+def check_tool_calls(
+    tool_calls: list[ToolCall], policy: Policy
+) -> tuple[list[ToolFinding], CheckResult]:
+    started_at = time.perf_counter()
+    findings = [inspect_tool_call(tool_call, policy) for tool_call in tool_calls]
+    blocked = [finding for finding in findings if finding.status is Status.BLOCK]
+    detail = (
+        "; ".join(reason for finding in blocked for reason in finding.reasons)
+        if blocked
+        else f"{len(tool_calls)} tool call(s) within policy"
+    )
+    return findings, CheckResult(
+        name="deterministic_rules",
+        status=Status.BLOCK if blocked else Status.PASS,
+        detail=detail,
+        latency_ms=(time.perf_counter() - started_at) * 1000,
+        meta={"blocked_tools": [finding.tool_name for finding in blocked]},
+    )

voidhack_agent_firewall/schemas.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Status(Enum):
+    PASS = "pass"
+    FLAG = "flag"
+    BLOCK = "block"
+
+
+@dataclass
+class FunctionCall:
+    name: str = ""
+    arguments: str = ""
+
+
+@dataclass
+class ToolCall:
+    id: str = ""
+    type: str = "function"
+    function: FunctionCall = field(default_factory=FunctionCall)
+
+    def __init__(
+        self,
+        id: str = "",
+        type: str = "function",
+        function: FunctionCall | dict[str, Any] | None = None,
+    ):
+        self.id = id
+        self.type = type
+        if isinstance(function, FunctionCall):
+            self.function = function
+        elif isinstance(function, dict):
+            self.function = FunctionCall(
+                name=str(function.get("name") or ""),
+                arguments=str(function.get("arguments") or ""),
+            )
+        else:
+            self.function = FunctionCall()
+
+
+@dataclass
+class CheckResult:
+    name: str
+    status: Status = Status.PASS
+    detail: str = ""
+    latency_ms: float = 0.0
+    meta: dict[str, Any] = field(default_factory=dict)

voidhack_agent_firewall-1.0.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: voidhack-agent-firewall
+Version: 1.0.0
+Summary: Provider-agnostic action firewall SDK for AI agents
+Author: VoidHack Agent Firewall
+License: MIT
+Project-URL: Homepage, https://github.com/Dinaltium/VoidHackJune26
+Project-URL: Repository, https://github.com/Dinaltium/VoidHackJune26
+Keywords: ai,agents,firewall,guardrails,prompt-injection,langchain,openai,anthropic,gemini
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.59
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.24; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.8; extra == "gemini"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.24; extra == "all"
+Requires-Dist: google-generativeai>=0.8; extra == "all"
+Requires-Dist: langchain-core>=0.2; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Dynamic: license-file
+
+# Agent Firewall
+
+> The operating layer that guards what AI agents actually **do**.
+>
+> *Guardrails check what the model says. We check what the agent does.*
+
+**VoidHack June 2026** — Theme: *The Operating Layer of the Internet*.
+
+A transparent, **OpenAI-compatible proxy** that sits between an AI agent and the
+LLM/world and enforces **action-level** policy. Point your agent's `base_url` at
+it — nothing else changes — and every tool call, egress destination, secret, and
+token budget is checked before the agent can act.
+
+The enforcement engine is provider-agnostic: OpenAI-compatible providers
+(OpenAI, Groq, NVIDIA NIM, Mistral, Together, Fireworks, OpenRouter, local
+gateways) work through the proxy or SDK wrapper, while native Claude/Anthropic
+and Gemini adapters translate their tool-call formats into the same policy
+checks. LangChain integrations block tool execution regardless of the model
+provider.
+
+## Why
+
+Prompt injection is unsolved (OWASP LLM01:2025). Existing guardrails classify
+*text* and approve the words — then the agent emails your secrets in the next
+call. The firewall enforces at the layer where damage happens: **the action**.
+
+It blocks by **stripping the disallowed `tool_call` out of the model's response
+before the agent ever sees it** — prevention, not a warning. Default **fail-closed**.
+
+## What it enforces
+
+- **Tool allowlist** — default-deny; `send_email`, `run_shell`, … are blocked.
+- **Egress allowlist** — URLs/email domains must be on the allowlist.
+- **Injection scan** — heuristic + Meta **Prompt Guard 2** on tool results.
+- **PII / secret redaction** — in-flight, both directions (regex; Presidio optional).
+- **Cost guard** — per-session token budget.
+- **Signed receipts** — every decision is HMAC-signed and auditable, streamed
+  live to a control-plane dashboard.
+- **Safeguard reasoner** — `gpt-oss-safeguard-20b` adds an auditable explanation
+  on flagged actions (policy-following; reads `policies/policy.yaml`).
+
+## Demo (before / after)
+
+```bash
+# BREACH — agent talks straight to the model; it emails data externally
+python -m agent.run_attack --task email --direct
+
+# SAFE — same task through the firewall; send_email is blocked, 0 exfiltration
+python -m agent.run_attack --task email
+```
+
+The dashboard (`/`) shows decisions stream in live; **Run demo attack** replays a
+spread of attacks through the real engine. See [docs/RUNBOOK.md](docs/RUNBOOK.md).
+
+### Mission Control (`/mission`)
+
+An interactive page where you hand an autonomous agent a real goal (editable task
++ a knowledge document you can poison), toggle the **firewall ON/OFF**, and watch
+a **live LLM** execute step by step. Governed: the agent gets hijacked but every
+dangerous call is stripped — *"Firewall held."* Ungoverned: the same agent
+exfiltrates — *"Breach."* An Impact panel proves what reached the outside world.
+
+## Stack
+
+| Layer | Tech |
+|-------|------|
+| Proxy | Python 3.12 · FastAPI 0.136 · Uvicorn · httpx · Pydantic 2 |
+| Detection | deterministic rules · Prompt Guard 2 (Groq) · regex/Presidio PII |
+| Reasoner | gpt-oss-safeguard-20b (Groq, selective) |
+| Store | SQLite · SQLAlchemy 2.0 · HMAC-SHA256 receipts |
+| Dashboard | Next.js 16 · Tailwind 4 · SSE live feed |
+| Demo agent | OpenAI SDK · llama-3.3-70b-versatile |
+
+All models run on the **Groq free tier** — zero cost, no card.
+
+## SDKs and provider adapters
+
+Install from npm:
+
+```bash
+npm install voidhack-agent-firewall
+```
+
+Install from PyPI once published:
+
+```bash
+pip install voidhack-agent-firewall
+```
+
+- **Python**: `FirewallOpenAI`, `FirewallAnthropic`, `FirewallGoogleGenerativeAI`,
+  `FirewallCallbackHandler`, and `create_openai_compatible_firewall`.
+- **Node.js**: `FirewallOpenAI`, `FirewallAnthropic`,
+  `FirewallGoogleGenerativeAI`, LangChain.js callback support, and
+  `createFirewallOpenAICompatible`.
+
+See [docs/SDK_INTEGRATION.md](docs/SDK_INTEGRATION.md) for Claude, Gemini,
+Groq, NVIDIA, Mistral, Together, and LangChain examples.
+
+## Layout
+
+```
+proxy/        FastAPI firewall (app/ + tests/)
+dashboard/    Next.js 16 control-plane UI
+agent/        demo victim agent + poisoned document
+policies/     policy.yaml
+docs/         DESIGN · ARCHITECTURE · RUNBOOK
+```
+
+## Status
+
+Working end-to-end. Backend: ruff + mypy + 34 pytest green. Dashboard: biome +
+tsc + build + 2 Playwright e2e green. Verified live against Groq.
+
+See [docs/DESIGN.md](docs/DESIGN.md) for the design + decision log and
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for components and data flow.
+
+## License
+
+MIT

voidhack_agent_firewall-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+voidhack_agent_firewall/__init__.py,sha256=OZuzSztcGA86ub2hngEFkn1u3mnDW4xWCmL4f7bnIBI,491
+voidhack_agent_firewall/client.py,sha256=xr2QztCpnoImZ0vRH_vvLzZXctYyn8rBzs-pCA2_mOE,5086
+voidhack_agent_firewall/langchain.py,sha256=xSOgEZaItVWZtRPoz64b3GSYWdRFqltImIOFizTgDi4,2411
+voidhack_agent_firewall/pii.py,sha256=zuvma6_u5EHN42wVuq6PaJ_3FBptXGGZvkuDvkN3uEA,1530
+voidhack_agent_firewall/policy.py,sha256=pVQpK6cFhWABicZDHHy-qdHMK_gsxw4JNEwjS1AcF4o,3331
+voidhack_agent_firewall/providers.py,sha256=o0M44h6qVrircwynQ2Dp2meKTq1RlTScJoLgZQLFDX0,8948
+voidhack_agent_firewall/rules.py,sha256=iBC3Vh6ycm5IaShpP-XvEb_BHz458J5_Ct4CR9kcta4,3495
+voidhack_agent_firewall/schemas.py,sha256=ZDLxGaNgRejv2LG7FD56unu0qwAFtHUZU91Hy5xyggY,1156
+voidhack_agent_firewall-1.0.0.dist-info/licenses/LICENSE,sha256=MkOSykGmBxEgaEqe0o6Rr-Gj_G0WTh0c6U5Zk-wyRQI,1075
+voidhack_agent_firewall-1.0.0.dist-info/METADATA,sha256=3TAlRYTF0SqTGHu-8Dui_AkZrXwrpAaoE0IW4xEZuyk,5758
+voidhack_agent_firewall-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+voidhack_agent_firewall-1.0.0.dist-info/top_level.txt,sha256=8p4vG-kQ_vPz6J7UcMY18io8sMKis5D0hjjj9XPojhE,24
+voidhack_agent_firewall-1.0.0.dist-info/RECORD,,

voidhack_agent_firewall-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

voidhack_agent_firewall-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RAFAN AHAMAD SHEIK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

voidhack_agent_firewall-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+voidhack_agent_firewall