cognexus 0.1.0__tar.gz

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

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest
+
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    needs: test
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publisher OIDC (no token needed)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Validate distributions
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cognexus-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Build artefacts
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Audit output (generated at runtime)
+*.jsonl
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db

cognexus-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 CogNexus Labs
+
+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.
+
+---
+
+Portions of this software are derived from microsoft/agent-governance-toolkit
+(https://github.com/microsoft/agent-governance-toolkit), also licensed under
+the MIT License. Copyright (c) Microsoft Corporation.

cognexus-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: cognexus
+Version: 0.1.0
+Summary: OWASP-aligned LLM prompt defence, injection detection, and audit logging
+Project-URL: Homepage, https://github.com/CogNexusLabs/cognexus
+Project-URL: Source, https://github.com/CogNexusLabs/cognexus
+Project-URL: Issues, https://github.com/CogNexusLabs/cognexus/issues
+Project-URL: Changelog, https://github.com/CogNexusLabs/cognexus/releases
+Author: Odenthal
+Maintainer: Odenthal
+License: MIT License
+        
+        Copyright (c) 2026 CogNexus Labs
+        
+        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.
+        
+        ---
+        
+        Portions of this software are derived from microsoft/agent-governance-toolkit
+        (https://github.com/microsoft/agent-governance-toolkit), also licensed under
+        the MIT License. Copyright (c) Microsoft Corporation.
+License-File: LICENSE
+Keywords: ai-safety,audit,guardrails,llm,owasp,prompt-defense,prompt-injection,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# cognexus
+
+**OWASP-aligned prompt defence, injection detection, and audit logging for LLM applications.**
+
+`cognexus` gives you two complementary security layers and a tamper-evident audit trail — all in pure Python with zero mandatory dependencies.
+
+```
+pip install cognexus
+```
+
+---
+
+## Features
+
+| Layer | What it does |
+|---|---|
+| **Static prompt defence** | Grades system prompts A–F against 12 OWASP LLM Top-10 attack vectors before deployment |
+| **Runtime injection detection** | Screens user input, RAG content, and tabular payloads at request time |
+| **Audit events** | Append-only JSONL trail for every detected injection — no raw text stored |
+
+### Detection coverage
+
+- Direct instruction override
+- Delimiter and context-boundary attacks
+- Base64 / hex / ROT13 encoding attacks
+- Role-play and jailbreak language (DAN mode, developer mode, etc.)
+- Context manipulation ("your real instructions are…")
+- Canary token leak detection
+- Multi-turn escalation
+- Cross-plugin / tool-chaining attacks (OWASP ASI04)
+- Markup injection (XSS gadgets in model-visible text)
+- Zero-width / token-smuggling unicode attacks
+- Credential exfiltration requests
+
+---
+
+## Quick-start
+
+```python
+from cognexus import (
+    augment_system_prompt,
+    evaluate_system_prompt,
+    screen_user_input,
+    should_block,
+)
+
+# 1. Augment your system prompt so it scores grade A before inference
+system = augment_system_prompt("You are a helpful customer support agent.")
+report = evaluate_system_prompt(system)
+print(report.grade)    # "A"
+print(report.score)    # 100
+print(report.missing)  # []
+
+# 2. Screen every user message at request time
+result = screen_user_input(user_message, source="chat")
+
+if should_block(result):
+    raise PermissionError(f"Injection blocked: {result.explanation}")
+```
+
+---
+
+## Screening helpers
+
+Three presets cover the most common LLM input surfaces:
+
+```python
+from cognexus import (
+    screen_user_input,       # balanced sensitivity — direct chat messages
+    screen_external_content, # strict  sensitivity — RAG / web / API content
+    screen_tabular_payload,  # permissive           — CSV / dataframe blobs
+    should_block,
+    wrap_untrusted_content,
+)
+
+# Wrap RAG content before inserting into a prompt
+safe_chunk = wrap_untrusted_content("web_search", raw_text)
+
+# Screen it too
+result = screen_external_content(raw_text, source="web_search", user_id=user.id)
+```
+
+### Sensitivity presets
+
+| Preset | Threshold | Min threat flagged | Use for |
+|---|---|---|---|
+| `strict` | 0.3 | LOW | External / RAG content |
+| `balanced` | 0.5 | LOW | Direct user input |
+| `permissive` | 0.7 | HIGH | CSV / tabular payloads |
+
+Override via environment variables:
+
+```
+COGNEXUS_PROMPT_INJECTION_USER_SENSITIVITY=balanced
+COGNEXUS_PROMPT_INJECTION_EXTERNAL_SENSITIVITY=strict
+COGNEXUS_PROMPT_INJECTION_TABULAR_SENSITIVITY=permissive
+COGNEXUS_PROMPT_INJECTION_BLOCK=0   # set to 1 to block any hit, not just CRITICAL
+```
+
+---
+
+## Using the core classes directly
+
+```python
+from cognexus import PromptInjectionDetector, DetectionConfig, InjectionType
+
+detector = PromptInjectionDetector(
+    config=DetectionConfig(
+        sensitivity="strict",
+        blocklist=["my-internal-keyword"],
+        allowlist=["safe phrase"],
+    )
+)
+
+result = detector.detect(text, source="api_gateway")
+print(result.is_injection)       # True / False
+print(result.threat_level)       # ThreatLevel.HIGH
+print(result.injection_type)     # InjectionType.DIRECT_OVERRIDE
+print(result.confidence)         # 0.9
+print(result.matched_patterns)   # ["direct_override:..."]
+```
+
+---
+
+## Audit events
+
+Detections are automatically written to a JSONL file (no raw input stored):
+
+```python
+# Events go to $COGNEXUS_PROMPT_DEFENSE_EVENTS_DIR/prompt_defense_events.jsonl
+# (falls back to $REPORTS_DIR, then /tmp)
+
+from cognexus.events import read_recent_events
+
+rows = read_recent_events(user_id=42, limit=20)
+# [{"ts": "...", "kind": "prompt_injection", "threat": "high", ...}, ...]
+```
+
+### Custom event sink (database, queue, dashboard)
+
+Pass an `on_event` callback to mirror records into your own store:
+
+```python
+def save_to_db(record: dict) -> None:
+    db.execute("INSERT INTO security_events ...", record)
+
+screen_user_input(text, source="chat", user_id=user.id, on_event=save_to_db)
+```
+
+---
+
+## Static prompt defence — standalone
+
+```python
+from cognexus import PromptDefenseEvaluator, PromptDefenseConfig
+
+evaluator = PromptDefenseEvaluator(
+    config=PromptDefenseConfig(min_grade="B")
+)
+report = evaluator.evaluate(my_system_prompt)
+
+print(report.grade)     # "C"
+print(report.score)     # 58
+print(report.missing)   # ["unicode-attack", "context-overflow"]
+
+if report.is_blocking():
+    print("System prompt is below minimum grade — fix before deploying.")
+
+# Evaluate a file
+report = evaluator.evaluate_file("prompts/assistant.txt")
+
+# Batch evaluation
+reports = evaluator.evaluate_batch({
+    "chat": chat_prompt,
+    "analyst": analyst_prompt,
+})
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `COGNEXUS_PROMPT_DEFENSE_EVENTS_DIR` | `/tmp` | JSONL audit file directory |
+| `COGNEXUS_PROMPT_INJECTION_LOG` | `1` | Log clean scans at DEBUG |
+| `COGNEXUS_PROMPT_INJECTION_BLOCK` | `0` | Block any injection (not just CRITICAL) |
+| `COGNEXUS_PROMPT_INJECTION_USER_SENSITIVITY` | `balanced` | User-input preset |
+| `COGNEXUS_PROMPT_INJECTION_EXTERNAL_SENSITIVITY` | `strict` | External/RAG preset |
+| `COGNEXUS_PROMPT_INJECTION_TABULAR_SENSITIVITY` | `permissive` | CSV/tabular preset |
+
+---
+
+## Security notes
+
+- All detection is **pure regex** — deterministic, zero LLM calls, zero network access, < 5 ms per input.
+- Audit records store a **SHA-256 hash** and a **96-character redacted preview** of the input. Raw user text is never written to disk.
+- The package ships **sample rules** that cover common attack patterns. Review and extend them for your production threat model using `DetectionConfig.custom_patterns` or a YAML config file loaded with `load_prompt_injection_config()`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Detection rules and evaluator logic originally derived from [microsoft/agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit) (MIT).

cognexus-0.1.0/README.md

@@ -0,0 +1,206 @@
+# cognexus
+
+**OWASP-aligned prompt defence, injection detection, and audit logging for LLM applications.**
+
+`cognexus` gives you two complementary security layers and a tamper-evident audit trail — all in pure Python with zero mandatory dependencies.
+
+```
+pip install cognexus
+```
+
+---
+
+## Features
+
+| Layer | What it does |
+|---|---|
+| **Static prompt defence** | Grades system prompts A–F against 12 OWASP LLM Top-10 attack vectors before deployment |
+| **Runtime injection detection** | Screens user input, RAG content, and tabular payloads at request time |
+| **Audit events** | Append-only JSONL trail for every detected injection — no raw text stored |
+
+### Detection coverage
+
+- Direct instruction override
+- Delimiter and context-boundary attacks
+- Base64 / hex / ROT13 encoding attacks
+- Role-play and jailbreak language (DAN mode, developer mode, etc.)
+- Context manipulation ("your real instructions are…")
+- Canary token leak detection
+- Multi-turn escalation
+- Cross-plugin / tool-chaining attacks (OWASP ASI04)
+- Markup injection (XSS gadgets in model-visible text)
+- Zero-width / token-smuggling unicode attacks
+- Credential exfiltration requests
+
+---
+
+## Quick-start
+
+```python
+from cognexus import (
+    augment_system_prompt,
+    evaluate_system_prompt,
+    screen_user_input,
+    should_block,
+)
+
+# 1. Augment your system prompt so it scores grade A before inference
+system = augment_system_prompt("You are a helpful customer support agent.")
+report = evaluate_system_prompt(system)
+print(report.grade)    # "A"
+print(report.score)    # 100
+print(report.missing)  # []
+
+# 2. Screen every user message at request time
+result = screen_user_input(user_message, source="chat")
+
+if should_block(result):
+    raise PermissionError(f"Injection blocked: {result.explanation}")
+```
+
+---
+
+## Screening helpers
+
+Three presets cover the most common LLM input surfaces:
+
+```python
+from cognexus import (
+    screen_user_input,       # balanced sensitivity — direct chat messages
+    screen_external_content, # strict  sensitivity — RAG / web / API content
+    screen_tabular_payload,  # permissive           — CSV / dataframe blobs
+    should_block,
+    wrap_untrusted_content,
+)
+
+# Wrap RAG content before inserting into a prompt
+safe_chunk = wrap_untrusted_content("web_search", raw_text)
+
+# Screen it too
+result = screen_external_content(raw_text, source="web_search", user_id=user.id)
+```
+
+### Sensitivity presets
+
+| Preset | Threshold | Min threat flagged | Use for |
+|---|---|---|---|
+| `strict` | 0.3 | LOW | External / RAG content |
+| `balanced` | 0.5 | LOW | Direct user input |
+| `permissive` | 0.7 | HIGH | CSV / tabular payloads |
+
+Override via environment variables:
+
+```
+COGNEXUS_PROMPT_INJECTION_USER_SENSITIVITY=balanced
+COGNEXUS_PROMPT_INJECTION_EXTERNAL_SENSITIVITY=strict
+COGNEXUS_PROMPT_INJECTION_TABULAR_SENSITIVITY=permissive
+COGNEXUS_PROMPT_INJECTION_BLOCK=0   # set to 1 to block any hit, not just CRITICAL
+```
+
+---
+
+## Using the core classes directly
+
+```python
+from cognexus import PromptInjectionDetector, DetectionConfig, InjectionType
+
+detector = PromptInjectionDetector(
+    config=DetectionConfig(
+        sensitivity="strict",
+        blocklist=["my-internal-keyword"],
+        allowlist=["safe phrase"],
+    )
+)
+
+result = detector.detect(text, source="api_gateway")
+print(result.is_injection)       # True / False
+print(result.threat_level)       # ThreatLevel.HIGH
+print(result.injection_type)     # InjectionType.DIRECT_OVERRIDE
+print(result.confidence)         # 0.9
+print(result.matched_patterns)   # ["direct_override:..."]
+```
+
+---
+
+## Audit events
+
+Detections are automatically written to a JSONL file (no raw input stored):
+
+```python
+# Events go to $COGNEXUS_PROMPT_DEFENSE_EVENTS_DIR/prompt_defense_events.jsonl
+# (falls back to $REPORTS_DIR, then /tmp)
+
+from cognexus.events import read_recent_events
+
+rows = read_recent_events(user_id=42, limit=20)
+# [{"ts": "...", "kind": "prompt_injection", "threat": "high", ...}, ...]
+```
+
+### Custom event sink (database, queue, dashboard)
+
+Pass an `on_event` callback to mirror records into your own store:
+
+```python
+def save_to_db(record: dict) -> None:
+    db.execute("INSERT INTO security_events ...", record)
+
+screen_user_input(text, source="chat", user_id=user.id, on_event=save_to_db)
+```
+
+---
+
+## Static prompt defence — standalone
+
+```python
+from cognexus import PromptDefenseEvaluator, PromptDefenseConfig
+
+evaluator = PromptDefenseEvaluator(
+    config=PromptDefenseConfig(min_grade="B")
+)
+report = evaluator.evaluate(my_system_prompt)
+
+print(report.grade)     # "C"
+print(report.score)     # 58
+print(report.missing)   # ["unicode-attack", "context-overflow"]
+
+if report.is_blocking():
+    print("System prompt is below minimum grade — fix before deploying.")
+
+# Evaluate a file
+report = evaluator.evaluate_file("prompts/assistant.txt")
+
+# Batch evaluation
+reports = evaluator.evaluate_batch({
+    "chat": chat_prompt,
+    "analyst": analyst_prompt,
+})
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `COGNEXUS_PROMPT_DEFENSE_EVENTS_DIR` | `/tmp` | JSONL audit file directory |
+| `COGNEXUS_PROMPT_INJECTION_LOG` | `1` | Log clean scans at DEBUG |
+| `COGNEXUS_PROMPT_INJECTION_BLOCK` | `0` | Block any injection (not just CRITICAL) |
+| `COGNEXUS_PROMPT_INJECTION_USER_SENSITIVITY` | `balanced` | User-input preset |
+| `COGNEXUS_PROMPT_INJECTION_EXTERNAL_SENSITIVITY` | `strict` | External/RAG preset |
+| `COGNEXUS_PROMPT_INJECTION_TABULAR_SENSITIVITY` | `permissive` | CSV/tabular preset |
+
+---
+
+## Security notes
+
+- All detection is **pure regex** — deterministic, zero LLM calls, zero network access, < 5 ms per input.
+- Audit records store a **SHA-256 hash** and a **96-character redacted preview** of the input. Raw user text is never written to disk.
+- The package ships **sample rules** that cover common attack patterns. Review and extend them for your production threat model using `DetectionConfig.custom_patterns` or a YAML config file loaded with `load_prompt_injection_config()`.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Detection rules and evaluator logic originally derived from [microsoft/agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit) (MIT).

cognexus-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cognexus"
+version = "0.1.0"
+description = "OWASP-aligned LLM prompt defence, injection detection, and audit logging"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Odenthal", email = "" },
+]
+maintainers = [
+    { name = "Odenthal", email = "" },
+]
+keywords = [
+    "llm",
+    "security",
+    "prompt-injection",
+    "prompt-defense",
+    "owasp",
+    "ai-safety",
+    "audit",
+    "guardrails",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+# Zero mandatory runtime dependencies — pure stdlib.
+dependencies = []
+
+[project.optional-dependencies]
+# Required only if you load custom detection patterns from YAML files via
+# load_prompt_injection_config().
+yaml = ["pyyaml>=6.0"]
+
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+    "build",
+    "twine",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage    = "https://github.com/CogNexusLabs/cognexus"
+Source      = "https://github.com/CogNexusLabs/cognexus"
+Issues      = "https://github.com/CogNexusLabs/cognexus/issues"
+Changelog   = "https://github.com/CogNexusLabs/cognexus/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cognexus"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts   = "-v"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]
+ignore = ["E501"]