llm-firewall 0.2.0__py3-none-any.whl

llm_firewall-0.2.0.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: llm-firewall
+Version: 0.2.0
+Summary: A lightweight, domain-aware safety firewall for LLM applications — works with any API or local model, with dynamic policy-document support.
+Author-email: Parshva Shah <shahparshva2005@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/Parshva2605/LLM-Firewall
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML
+Provides-Extra: openai
+Requires-Dist: openai; extra == "openai"
+Provides-Extra: groq
+Requires-Dist: groq; extra == "groq"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: dynamic
+Requires-Dist: sentence-transformers; extra == "dynamic"
+Dynamic: license-file
+
+# LLM-Shield
+
+A lightweight, domain-aware safety firewall for LLM applications — works with any API or local model.
+
+Install with:
+
+```bash
+pip install llm-shield
+```
+
+Import with:
+
+```python
+from llm_shield import Firewall
+```

llm_firewall-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+llm_firewall-0.2.0.dist-info/licenses/LICENSE,sha256=qMQlMNwgG8wsjeGk6fQZ1wHVNwNS-GuCzEAEWiPLuH8,1088
+llm_shield/__init__.py,sha256=AJGesdRAEGe5YU7DERbX2J8VGOpexMs0BSn7JOc5hcI,53
+llm_shield/cli.py,sha256=CA-74qNk119E7R1mr6JCOq536pl118KzU4Dd83SWVaU,1108
+llm_shield/core.py,sha256=waTZbMEchTQHs3LpsCXPCKsEVueBplLWzhole1S6E4k,7254
+llm_shield/dynamic.py,sha256=DuHane88aO9p8_i_ssht7NQPO2t51JOv19p4_oUAyOE,3376
+llm_shield/logger.py,sha256=H_-ECKgc6szdkk2yOUugCKvILjr-ZPyNPD-OvRRFLpg,1787
+llm_shield/adapters/__init__.py,sha256=v3X7OBxEZdp9HtJgxiOZ9-jy2n5cVFsJYl5F4jjr0M8,2474
+llm_shield/profiles/__init__.py,sha256=vxfLu-r1-tt8dkApQx4bPvE1H8YVJmXZN9LK8OZMlXg,1463
+llm_shield/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+llm_firewall-0.2.0.dist-info/METADATA,sha256=CS7TaaF1IwRYg6K7f5C_S9WQpnktPs9dA6zRlLk9JzA,1226
+llm_firewall-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+llm_firewall-0.2.0.dist-info/entry_points.txt,sha256=vvzt36AUP_N_FKztitgZOz9enG8U_1UC0cKGdPjN9Qc,51
+llm_firewall-0.2.0.dist-info/top_level.txt,sha256=asiKd3KjIYyVykvfgz6H6_xnnu0HoLPubFqS4Envt1U,11
+llm_firewall-0.2.0.dist-info/RECORD,,

llm_firewall-0.2.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
+

llm_firewall-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+llm-shield = llm_shield.cli:main

llm_firewall-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parshva Shah
+
+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.

llm_firewall-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llm_shield

llm_shield/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.2.0"
+
+from .core import Firewall

llm_shield/adapters/__init__.py

@@ -0,0 +1,86 @@
+from ..core import Firewall
+
+
+def detect_client_type(client) -> str:
+	module_name = type(client).__module__.lower()
+	if "openai" in module_name:
+		return "openai"
+	if "groq" in module_name:
+		return "groq"
+	if "ollama" in module_name:
+		return "ollama"
+	return "unknown"
+
+
+class FirewallProtectedClient:
+	"""Wrap an LLM client so input is filtered, the model is called, then output is filtered.
+
+	The wrapper keeps the underlying client transparent while routing requests through a Firewall
+	instance before and after the LLM call.
+	"""
+
+	def __init__(self, client, firewall):
+		self.client = client
+		self.firewall = firewall
+		self.client_type = detect_client_type(client)
+
+	def chat(self, message: str, **kwargs) -> dict:
+		input_result = self.firewall.check_input(message)
+		if input_result.blocked:
+			return {
+				"blocked": True,
+				"stage": "input",
+				"reason": input_result.reason,
+				"category": input_result.category,
+				"response": None,
+			}
+
+		try:
+			if self.client_type == "openai":
+				response = self.client.chat.completions.create(
+					model=kwargs.get("model", "gpt-4o-mini"),
+					messages=[{"role": "user", "content": message}],
+				)
+				response_text = response.choices[0].message.content
+			elif self.client_type == "groq":
+				response = self.client.chat.completions.create(
+					model=kwargs.get("model", "llama-3.1-8b-instant"),
+					messages=[{"role": "user", "content": message}],
+				)
+				response_text = response.choices[0].message.content
+			elif self.client_type == "ollama":
+				response = self.client.chat(
+					model=kwargs.get("model", "llama3.2"),
+					messages=[{"role": "user", "content": message}],
+				)
+				response_text = response["message"]["content"]
+			else:
+				raise NotImplementedError(
+					"Unsupported client type 'unknown'. Supported client types are: openai, groq, ollama."
+				)
+		except Exception as exception:
+			return {
+				"blocked": False,
+				"stage": "error",
+				"reason": str(exception),
+				"category": "error",
+				"response": None,
+			}
+
+		output_result = self.firewall.check_output(response_text)
+		if output_result.blocked:
+			return {
+				"blocked": True,
+				"stage": "output",
+				"reason": output_result.reason,
+				"category": output_result.category,
+				"response": None,
+			}
+
+		return {
+			"blocked": False,
+			"stage": None,
+			"reason": "",
+			"category": "clean",
+			"response": response_text,
+		}

llm_shield/cli.py

@@ -0,0 +1,40 @@
+import argparse
+import json
+
+from llm_shield.logger import AuditLogger
+from llm_shield.profiles import list_profiles
+
+
+def main():
+	parser = argparse.ArgumentParser(prog="llm-shield")
+	subparsers = parser.add_subparsers(dest="command")
+
+	subparsers.add_parser("profiles", help="List available firewall profiles")
+	subparsers.add_parser("logs", help="Show audit log summary and recent entries")
+
+	args = parser.parse_args()
+
+	if args.command == "profiles":
+		for profile_name in list_profiles():
+			print(profile_name)
+		return
+
+	if args.command == "logs":
+		logger = AuditLogger()
+		summary = logger.get_summary()
+		print(f"total_requests: {summary['total_requests']}")
+		print(f"blocked_count: {summary['blocked_count']}")
+		print(f"allowed_count: {summary['allowed_count']}")
+		print("by_category:")
+		for category, count in summary["by_category"].items():
+			print(f"  {category}: {count}")
+		print("recent_entries:")
+		for entry in logger.read_logs(limit=10):
+			print(json.dumps(entry, indent=2))
+		return
+
+	parser.print_help()
+
+
+if __name__ == "__main__":
+	main()

llm_shield/core.py

@@ -0,0 +1,176 @@
+from dataclasses import dataclass
+import re
+
+from .logger import AuditLogger
+from .profiles import load_profile, load_profile_from_path
+
+try:
+	from llm_shield.dynamic import LocalEmbedder, SENTENCE_TRANSFORMERS_AVAILABLE
+except ImportError:
+	LocalEmbedder = None
+	SENTENCE_TRANSFORMERS_AVAILABLE = False
+
+
+@dataclass
+class FirewallResult:
+	"""Result of a firewall check.
+
+	The category field may be one of: off_topic, prompt_injection, safety_violation,
+	pii_leak, malicious_code, or clean.
+	"""
+	blocked: bool
+	reason: str
+	category: str = "clean"
+	confidence: float = 1.0
+	matched_rule: str = ""
+
+
+class Firewall:
+	"""Rule-based firewall for basic input blocking and output leak detection.
+
+	It checks user input against explicit blocked keyword patterns and checks model output for
+	simple PII and secret-like leaks using regexes. It can also optionally use a policy document
+	to reject messages that fall outside the document's semantic scope.
+	
+	Note: The policy_document semantic scope-checking is a best-effort probabilistic layer based
+	on local embeddings. It works best when the policy document is detailed (a few sentences per
+	topic, not single short phrases) and should be used alongside blocked_keywords for explicit
+	or known-bad patterns rather than as a sole line of defense. Results may vary based on the
+	specificity of the policy text and the similarity threshold.
+	"""
+
+	def __init__(self, allowed_topics: list[str] = None, blocked_keywords: list[str] = None, profile: str = None, profile_path: str = None, enable_logging: bool = False, log_file: str = "firewall_audit.log", policy_document: str = None, similarity_threshold: float = 0.12):
+		if profile is not None and profile_path is not None:
+			raise ValueError("Provide either 'profile' or 'profile_path', not both")
+		
+		self.profile_data = None
+		if profile is not None:
+			self.profile_data = load_profile(profile)
+		elif profile_path is not None:
+			self.profile_data = load_profile_from_path(profile_path)
+		
+		if self.profile_data is not None:
+			self.allowed_topics = self.profile_data.get("allowed_topics", [])
+			profile_blocked_keywords = self.profile_data.get("blocked_keywords", [])
+			combined_blocked_keywords = list(dict.fromkeys(profile_blocked_keywords + (blocked_keywords or [])))
+			self.blocked_keywords = combined_blocked_keywords
+			# If policy_document not explicitly passed but profile contains one, use it
+			if policy_document is None and "policy_document" in self.profile_data:
+				policy_document = self.profile_data.get("policy_document")
+		else:
+			self.allowed_topics = allowed_topics or []
+			self.blocked_keywords = blocked_keywords or []
+		self.logger = AuditLogger(log_file=log_file) if enable_logging else None
+		self.similarity_threshold = similarity_threshold
+		if policy_document is not None:
+			if not SENTENCE_TRANSFORMERS_AVAILABLE:
+				raise ImportError(
+					"sentence-transformers is required to use policy_document. Install with: pip install llm-shield[dynamic]"
+				)
+			self.embedder = LocalEmbedder()
+			self.embedder.index_document(policy_document)
+		else:
+			self.embedder = None
+
+	def check_input(self, text: str) -> FirewallResult:
+		"""Check input text against blocked keyword patterns.
+
+		The first substring match wins and returns a blocked result; otherwise the input is clean.
+		Matches can be labeled as prompt_injection, safety_violation, malicious_code, or off_topic.
+		"""
+		lowered_text = text.lower()
+		for keyword in self.blocked_keywords:
+			lowered_keyword = keyword.lower()
+			if lowered_keyword in lowered_text:
+				if any(trigger in lowered_keyword for trigger in ["ignore", "disregard", "you are now", "act as", "new instructions", "system prompt", "forget your"]):
+					category = "prompt_injection"
+				elif any(trigger in lowered_keyword for trigger in ["phone number", "address", "meet me", "keep this secret", "don't tell", "keep secret", "your location", "where do you live"]):
+					category = "safety_violation"
+				elif any(trigger in lowered_keyword for trigger in ["write code", "python script", "javascript", "write a program", "sql injection", "exploit"]):
+					category = "malicious_code"
+				else:
+					category = "off_topic"
+				result = FirewallResult(
+					blocked=True,
+					reason=f"Input matched blocked pattern: '{keyword}'",
+					category=category,
+					confidence=1.0,
+					matched_rule=keyword,
+				)
+				if self.logger is not None:
+					self.logger.log(result, input_text=text)
+				return result
+
+		result = FirewallResult(blocked=False, reason="", category="clean", confidence=1.0, matched_rule="")
+		if self.embedder is not None:
+			score = self.embedder.max_similarity_score(text)
+			if score < self.similarity_threshold:
+				result = FirewallResult(
+					blocked=True,
+					reason=f"Message does not appear related to the provided policy document (similarity score: {score:.2f}, threshold: {self.similarity_threshold})",
+					category="off_topic",
+					confidence=round(1.0 - score, 2),
+					matched_rule="policy_document_similarity",
+				)
+				if self.logger is not None:
+					self.logger.log(result, input_text=text)
+				return result
+		if self.logger is not None:
+			self.logger.log(result, input_text=text)
+		return result
+
+	def check_output(self, text: str) -> FirewallResult:
+		"""Check output text for obvious PII or secret-like leaks.
+
+		It currently detects email addresses and simple API key patterns, then returns a blocked result.
+		"""
+		email_pattern = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+		api_key_patterns = [
+			re.compile(r"sk-[A-Za-z0-9]{20,}"),
+			re.compile(r"sk-ant-[A-Za-z0-9]{20,}"),
+			re.compile(r"sk-proj-[A-Za-z0-9]{20,}"),
+		]
+
+		if email_pattern.search(text):
+			result = FirewallResult(
+				blocked=True,
+				reason="Output contains a detected email address leak.",
+				category="pii_leak",
+				confidence=1.0,
+				matched_rule="email_pattern",
+			)
+			if self.logger is not None:
+				self.logger.log(result, output_text=text)
+			return result
+
+		for pattern in api_key_patterns:
+			if pattern.search(text):
+				result = FirewallResult(
+					blocked=True,
+					reason="Output contains a detected API key leak.",
+					category="pii_leak",
+					confidence=1.0,
+					matched_rule="api_key_pattern",
+				)
+				if self.logger is not None:
+					self.logger.log(result, output_text=text)
+				return result
+
+		if self.embedder is not None:
+			score = self.embedder.max_similarity_score(text)
+			if score < self.similarity_threshold:
+				result = FirewallResult(
+					blocked=True,
+					reason=f"Response does not appear related to the provided policy document (similarity score: {score:.2f}, threshold: {self.similarity_threshold})",
+					category="off_topic",
+					confidence=round(1.0 - score, 2),
+					matched_rule="policy_document_similarity_output",
+				)
+				if self.logger is not None:
+					self.logger.log(result, output_text=text)
+				return result
+
+		result = FirewallResult(blocked=False, reason="", category="clean", confidence=1.0, matched_rule="")
+		if self.logger is not None:
+			self.logger.log(result, output_text=text)
+		return result

llm_shield/dynamic.py

@@ -0,0 +1,90 @@
+"""Dynamic embedding utilities for local semantic indexing.
+
+This module provides a small helper for chunking text and computing similarity scores
+with sentence-transformers when it is installed.
+"""
+
+import os
+import re
+from pathlib import Path
+
+import numpy as np
+
+try:
+    from sentence_transformers import SentenceTransformer
+except ImportError:
+    SentenceTransformer = None
+    SENTENCE_TRANSFORMERS_AVAILABLE = False
+else:
+    SENTENCE_TRANSFORMERS_AVAILABLE = True
+
+
+def chunk_text(text: str, chunk_size: int = 200, overlap: int = 50) -> list[str]:
+    """Split text into overlapping word-based chunks.
+
+    The function uses whitespace tokenization and returns the original text as a single chunk
+    when the input is shorter than the requested chunk size.
+    """
+    words = text.split()
+    if len(words) <= chunk_size:
+        return [text]
+
+    step = max(1, chunk_size - overlap)
+    chunks = []
+    for start in range(0, len(words), step):
+        chunk_words = words[start:start + chunk_size]
+        if not chunk_words:
+            break
+        chunks.append(" ".join(chunk_words))
+        if start + chunk_size >= len(words):
+            break
+
+    return chunks
+
+
+class LocalEmbedder:
+    """Index text locally and compare queries with sentence-transformer embeddings.
+
+    The class stores chunked document text and computes cosine similarity scores for queries
+    against the indexed chunks.
+    """
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+        """Load a sentence-transformers model for local semantic comparison."""
+        if not SENTENCE_TRANSFORMERS_AVAILABLE:
+            raise ImportError(
+                "sentence-transformers is required for dynamic profiles. Install with: pip install llm-shield[dynamic]"
+            )
+        self.model = SentenceTransformer(model_name)
+        self.chunks = []
+        self.embeddings = None
+
+    def index_document(self, text: str) -> None:
+        """Chunk and embed a document for later similarity search."""
+        self.chunks = chunk_text(text)
+        self.embeddings = self.model.encode(self.chunks)
+
+    def most_similar(self, query: str, top_k: int = 3) -> list[dict]:
+        """Return the most similar indexed chunks for a query string."""
+        if self.embeddings is None:
+            return []
+
+        query_embedding = np.asarray(self.model.encode([query])[0], dtype=float)
+        chunk_embeddings = np.asarray(self.embeddings, dtype=float)
+
+        query_norm = np.linalg.norm(query_embedding)
+        chunk_norms = np.linalg.norm(chunk_embeddings, axis=1)
+        denominator = chunk_norms * query_norm
+        scores = np.zeros(len(chunk_embeddings), dtype=float)
+        valid_mask = denominator != 0
+        scores[valid_mask] = np.dot(chunk_embeddings[valid_mask], query_embedding) / denominator[valid_mask]
+
+        ranked_indices = np.argsort(scores)[::-1][:top_k]
+        return [{"chunk": self.chunks[index], "score": float(scores[index])} for index in ranked_indices]
+
+    def max_similarity_score(self, query: str) -> float:
+        """Return the highest similarity score for a query or 0.0 when no chunks are indexed."""
+        results = self.most_similar(query, top_k=1)
+        if not results:
+            return 0.0
+        return results[0]["score"]

llm_shield/logger.py

@@ -0,0 +1,55 @@
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class AuditLogger:
+	def __init__(self, log_file: str = "firewall_audit.log"):
+		self.log_file = os.fspath(log_file)
+
+	def log(self, result, input_text: str = None, output_text: str = None) -> None:
+		entry = {
+			"timestamp": datetime.now(timezone.utc).isoformat(),
+			"blocked": result.blocked,
+			"category": result.category,
+			"reason": result.reason,
+			"matched_rule": result.matched_rule,
+			"confidence": result.confidence,
+			"input_preview": input_text[:100] if input_text is not None else None,
+			"output_preview": output_text[:100] if output_text is not None else None,
+		}
+		with Path(self.log_file).open("a", encoding="utf-8") as log_handle:
+			log_handle.write(json.dumps(entry) + "\n")
+
+	def read_logs(self, limit: int = 50) -> list:
+		log_path = Path(self.log_file)
+		if not log_path.exists():
+			return []
+
+		entries = []
+		with log_path.open("r", encoding="utf-8") as log_handle:
+			for line in log_handle:
+				line = line.strip()
+				if not line:
+					continue
+				entries.append(json.loads(line))
+
+		return entries[-limit:]
+
+	def get_summary(self) -> dict:
+		log_path = Path(self.log_file)
+		if not log_path.exists():
+			return {"total_requests": 0, "blocked_count": 0, "allowed_count": 0, "by_category": {}}
+
+		entries = self.read_logs(limit=10**9)
+		summary = {"total_requests": len(entries), "blocked_count": 0, "allowed_count": 0, "by_category": {}}
+		for entry in entries:
+			if entry.get("blocked"):
+				summary["blocked_count"] += 1
+			else:
+				summary["allowed_count"] += 1
+			category = entry.get("category", "")
+			summary["by_category"][category] = summary["by_category"].get(category, 0) + 1
+
+		return summary

llm_shield/profiles/__init__.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+
+import yaml
+
+
+def _profiles_data_dir() -> Path:
+	return Path(__file__).resolve().parent / "data"
+
+
+def list_profiles() -> list[str]:
+	"""Return all available profile names from the built-in profiles directory.
+
+	Profile names are derived from YAML filenames and returned in sorted order.
+	"""
+	profiles_dir = _profiles_data_dir()
+	return sorted(profile_path.stem for profile_path in profiles_dir.glob("*.yaml"))
+
+
+def load_profile(name: str) -> dict:
+	"""Load a named YAML profile from the profiles data directory.
+
+	Raises ValueError if the requested profile file does not exist.
+	"""
+	profiles_dir = _profiles_data_dir()
+	profile_path = profiles_dir / f"{name}.yaml"
+	if not profile_path.exists():
+		available_profiles = list_profiles()
+		raise ValueError(f"Profile '{name}' not found. Available profiles: {available_profiles}")
+
+	with profile_path.open("r", encoding="utf-8") as profile_file:
+		profile_data = yaml.safe_load(profile_file)
+
+	return profile_data or {}
+
+
+def load_profile_from_path(path: str) -> dict:
+	"""Load a YAML profile from an external file path.
+
+	Raises FileNotFoundError if the file does not exist.
+	"""
+	profile_path = Path(path)
+	if not profile_path.exists():
+		raise FileNotFoundError(f"Profile file not found: {path}")
+
+	with profile_path.open("r", encoding="utf-8") as profile_file:
+		profile_data = yaml.safe_load(profile_file)
+
+	return profile_data or {}