stackone-defender 0.1.1__tar.gz → 0.6.2__tar.gz

stackone_defender-0.6.2/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.6.2"}

stackone_defender-0.6.2/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+## [0.6.2](https://github.com/StackOneHQ/stackone-defender/compare/stackone-defender-v0.6.1...stackone-defender-v0.6.2) (2026-04-22)
+
+
+### ⚠ BREAKING CHANGES
+
+* Drop ToolSanitizationRule, config/sanitizer tool_rules, use_default_tool_rules, and get_tool_rule/should_skip_field. Matches @stackone/defender post ENG-12594.
+
+### Features
+
+* add missing functions for full TS API parity ([aec0c5b](https://github.com/StackOneHQ/stackone-defender/commit/aec0c5b8d31715df7e4ec2e4d306b55d595bb1c3))
+* add PyPI publishing setup with Release Please CI ([2e28373](https://github.com/StackOneHQ/stackone-defender/commit/2e28373a27315dbb5e7deb23621977fe7fa2f7bc))
+* add tier2_fields filter and export ToolSanitizationRule ([cb7fd93](https://github.com/StackOneHQ/stackone-defender/commit/cb7fd93fb88a30f40edc171ef3fcdc5d6ce2534d))
+* align Python defender with Node (Tier 2 scoping, ONNX cache) ([482bfdd](https://github.com/StackOneHQ/stackone-defender/commit/482bfdda59b4617a75bc261621984cc321d28989))
+* **ENG-12402:** add PyPI publishing setup with Release Please CI ([f979748](https://github.com/StackOneHQ/stackone-defender/commit/f979748a8a3b2084ea241c352866adcfcd0145ea))
+* **ENG-12699:** TypeScript parity and synced ONNX bundle ([0449800](https://github.com/StackOneHQ/stackone-defender/commit/0449800fc2375c89ef231f5671f9a74bd84d3388))
+* port stackone-defender from TypeScript to Python ([e3ff70d](https://github.com/StackOneHQ/stackone-defender/commit/e3ff70dd6a0bc94578dc4dbfde87c5d75f00b7b8))
+* remove tool rules; batch Tier2 ONNX; lock ONNX load ([26c95c2](https://github.com/StackOneHQ/stackone-defender/commit/26c95c257175c892ae4be82ab7c17a099c1b6c6e))
+* **sanitizer:** remove dead use_tier2_classification from ToolResultSanitizer ([4646179](https://github.com/StackOneHQ/stackone-defender/commit/46461798fcf5acc6ac6e23bc65177c35d9353d9c))
+* sync Python package with TypeScript parity ([e1836dd](https://github.com/StackOneHQ/stackone-defender/commit/e1836dd967ad23997983ef1607118d1a25807e1c))
+* upgrade ML classifier to jbv2 model (AgentShield 73.7 → 79.8) ([bcd27f8](https://github.com/StackOneHQ/stackone-defender/commit/bcd27f8abf954700276249f9b03de34f733c67c4))
+* upgrade ML classifier to jbv5 (AgentShield 79.8 → 81.1) ([781dd10](https://github.com/StackOneHQ/stackone-defender/commit/781dd1007e7a0db03d58619a23b69f1b5d73e85d))
+
+
+### Bug Fixes
+
+* address Copilot/cubic review (Tier2 scope, tokens, SFE, thresholds) ([bf173ac](https://github.com/StackOneHQ/stackone-defender/commit/bf173ac42f6aaa7513ea2a1fc19083806a5c5ee1))
+* **ci:** avoid fasttext-wheel on Python 3.13 ([a6cda76](https://github.com/StackOneHQ/stackone-defender/commit/a6cda76894e3cd240c4f104e701e3202babb2682))
+* **classifier:** surface classification errors in classify_by_sentence skip_reason ([bd94639](https://github.com/StackOneHQ/stackone-defender/commit/bd9463978dac5572f999d8ec3ed1adbaf0bb97f2))
+* default enable_tier2 to True to match TypeScript SDK behaviour ([d66773b](https://github.com/StackOneHQ/stackone-defender/commit/d66773bee026517d09dd56b9311dd3c281c6f675))
+* **defender:** fix _extract_strings filtering, None checks, and cache ONNX load failure ([bf4ce99](https://github.com/StackOneHQ/stackone-defender/commit/bf4ce993287db9e067b661100b5bd92cc21aef6b))
+* **defender:** sync hasThreats blocking logic and tool rules precedence from JS package ([a217c3e](https://github.com/StackOneHQ/stackone-defender/commit/a217c3ef27aa0e4d92f21571bf0559ff9906f660))
+* enable tier2 by default to match TypeScript package ([f1fe990](https://github.com/StackOneHQ/stackone-defender/commit/f1fe990e1a81c32cb271f6ca85cc063f3da49223))
+* sync Python with TypeScript parity ([cec0813](https://github.com/StackOneHQ/stackone-defender/commit/cec0813ff8cc98f4502d5916d285a28877983d98))
+* **tier2:** apply max_text_length truncation in classify_by_sentence ([a67d2c6](https://github.com/StackOneHQ/stackone-defender/commit/a67d2c6524fb1d6b4f9331f547f28221867038de))
+* upgrade ML classifier to jbv2 (AgentShield 73.7 → 79.8) ([b452b39](https://github.com/StackOneHQ/stackone-defender/commit/b452b39c718329355f50c418bd50c37da2ed8698))
+* upgrade ML classifier to jbv2 (AgentShield 73.7 → 79.8) ([ccb1204](https://github.com/StackOneHQ/stackone-defender/commit/ccb1204d5e3d9763bb916d71bb49b75039ceb197))
+* use uv instead of pip in README installation instructions ([519759f](https://github.com/StackOneHQ/stackone-defender/commit/519759f09c6fc1eb6bf97f53ad0cbd25c78e2893))
+
+
+### Dependencies
+
+* **sfe:** switch optional FastText bindings to fasttext-ng ([bc9cc28](https://github.com/StackOneHQ/stackone-defender/commit/bc9cc283bc2da9f10472415d4aa94a0df083ec3d))
+
+
+### Documentation
+
+* add README adapted from TypeScript package ([a03c757](https://github.com/StackOneHQ/stackone-defender/commit/a03c757a1760b797d9a3ef444950e2839ca1c52d))
+* update README — enable_tier2 defaults to True ([af0d059](https://github.com/StackOneHQ/stackone-defender/commit/af0d05957e39a83b7e6e18b1f78b95219b14a4f5))
+* update README to reflect changes in package name and Python version ([d2fc2ca](https://github.com/StackOneHQ/stackone-defender/commit/d2fc2ca1900e2f6410df2ec075c5a8a1c3ac241b))
+
+
+### Miscellaneous Chores
+
+* prepare patch release 0.6.2 ([7b3c105](https://github.com/StackOneHQ/stackone-defender/commit/7b3c105b2ce23f88f284d72e41c1917aefdc4537))
+
+## [0.6.1](https://github.com/StackOneHQ/stackone-defender/compare/stackone-defender-v0.1.2...stackone-defender-v0.6.1) (2026-04-21)
+
+### Features
+
+* align Python package behavior with `@stackone/defender` 0.6.1
+* add SFE preprocessing support (`use_sfe`) with fail-open optional runtime loading
+* add packed-chunk Tier 2 batching and density-adjusted scoring
+* add dangerous-key traversal hardening (`__proto__`, `constructor`, `prototype`)
+* add cumulative-risk fractional thresholds to reduce list-response false positives
+
+### Bug Fixes
+
+* use `fasttext-ng` instead of `fasttext-wheel` for the `[sfe]` extra and dev tests so Python 3.13 CI can install maintained FastText bindings (NumPy 2.3+).
+
+### Breaking Changes
+
+* Python package version jumps from `0.1.2` to `0.6.1` to align release train with TypeScript parity.
+* `DefenseResult` now includes `fields_dropped` and `truncated_at_depth`.
+
+## [0.1.2](https://github.com/StackOneHQ/stackone-defender/compare/stackone-defender-v0.1.1...stackone-defender-v0.1.2) (2026-04-08)
+
+
+### Bug Fixes
+
+* upgrade ML classifier to jbv2 (AgentShield 73.7 → 79.8) ([b452b39](https://github.com/StackOneHQ/stackone-defender/commit/b452b39c718329355f50c418bd50c37da2ed8698))
+
+
+### Documentation
+
+* update README to reflect changes in package name and Python version ([d2fc2ca](https://github.com/StackOneHQ/stackone-defender/commit/d2fc2ca1900e2f6410df2ec075c5a8a1c3ac241b))
+
+## [0.1.1](https://github.com/StackOneHQ/stackone-defender/compare/stackone-defender-v0.1.0...stackone-defender-v0.1.1) (2026-04-08)
+
+
+### Features
+
+* add missing functions for full TS API parity ([aec0c5b](https://github.com/StackOneHQ/stackone-defender/commit/aec0c5b8d31715df7e4ec2e4d306b55d595bb1c3))
+* add PyPI publishing setup with Release Please CI ([2e28373](https://github.com/StackOneHQ/stackone-defender/commit/2e28373a27315dbb5e7deb23621977fe7fa2f7bc))
+* add tier2_fields filter and export ToolSanitizationRule ([cb7fd93](https://github.com/StackOneHQ/stackone-defender/commit/cb7fd93fb88a30f40edc171ef3fcdc5d6ce2534d))
+* **ENG-12402:** add PyPI publishing setup with Release Please CI ([f979748](https://github.com/StackOneHQ/stackone-defender/commit/f979748a8a3b2084ea241c352866adcfcd0145ea))
+* port stackone-defender from TypeScript to Python ([e3ff70d](https://github.com/StackOneHQ/stackone-defender/commit/e3ff70dd6a0bc94578dc4dbfde87c5d75f00b7b8))
+* **sanitizer:** remove dead use_tier2_classification from ToolResultSanitizer ([4646179](https://github.com/StackOneHQ/stackone-defender/commit/46461798fcf5acc6ac6e23bc65177c35d9353d9c))
+* sync Python package with TypeScript parity ([e1836dd](https://github.com/StackOneHQ/stackone-defender/commit/e1836dd967ad23997983ef1607118d1a25807e1c))
+
+
+### Bug Fixes
+
+* **classifier:** surface classification errors in classify_by_sentence skip_reason ([bd94639](https://github.com/StackOneHQ/stackone-defender/commit/bd9463978dac5572f999d8ec3ed1adbaf0bb97f2))
+* **defender:** fix _extract_strings filtering, None checks, and cache ONNX load failure ([bf4ce99](https://github.com/StackOneHQ/stackone-defender/commit/bf4ce993287db9e067b661100b5bd92cc21aef6b))
+* **defender:** sync hasThreats blocking logic and tool rules precedence from JS package ([a217c3e](https://github.com/StackOneHQ/stackone-defender/commit/a217c3ef27aa0e4d92f21571bf0559ff9906f660))
+* enable tier2 by default to match TypeScript package ([f1fe990](https://github.com/StackOneHQ/stackone-defender/commit/f1fe990e1a81c32cb271f6ca85cc063f3da49223))
+* sync Python with TypeScript parity ([cec0813](https://github.com/StackOneHQ/stackone-defender/commit/cec0813ff8cc98f4502d5916d285a28877983d98))
+* use uv instead of pip in README installation instructions ([519759f](https://github.com/StackOneHQ/stackone-defender/commit/519759f09c6fc1eb6bf97f53ad0cbd25c78e2893))
+
+
+### Documentation
+
+* add README adapted from TypeScript package ([a03c757](https://github.com/StackOneHQ/stackone-defender/commit/a03c757a1760b797d9a3ef444950e2839ca1c52d))
+
+## Changelog

stackone_defender-0.6.2/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: stackone-defender
+Version: 0.6.2
+Summary: Indirect prompt injection defense for AI agents using tool calls
+Project-URL: Homepage, https://github.com/StackOneHQ/stackone-defender
+Project-URL: Repository, https://github.com/StackOneHQ/stackone-defender
+Author-email: StackOne <support@stackone.com>
+License: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: onnx
+Requires-Dist: numpy>=1.24.0; extra == 'onnx'
+Requires-Dist: onnxruntime>=1.16.0; extra == 'onnx'
+Requires-Dist: tokenizers>=0.15.0; extra == 'onnx'
+Provides-Extra: sfe
+Requires-Dist: fasttext-ng>=0.9.3; extra == 'sfe'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/StackOneHQ/defender/main/assets/banner-dark.svg" />
+    <img src="https://raw.githubusercontent.com/StackOneHQ/defender/main/assets/banner-light.svg" alt="Defender by StackOne — Indirect prompt injection protection for MCP tool calls" width="800" />
+  </picture>
+
+  <p>
+    <a href="https://pypi.org/project/stackone-defender/"><img src="https://img.shields.io/pypi/v/stackone-defender?style=flat-square&color=047B43&label=pypi" alt="PyPI version" /></a>
+    <a href="https://github.com/StackOneHQ/stackone-defender/releases"><img src="https://img.shields.io/github/v/release/StackOneHQ/stackone-defender?style=flat-square&color=047B43&label=release" alt="latest GitHub release" /></a>
+    <a href="https://github.com/StackOneHQ/stackone-defender/stargazers"><img src="https://img.shields.io/github/stars/StackOneHQ/stackone-defender?style=flat-square&color=047B43" alt="GitHub stars" /></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/pypi/l/stackone-defender?style=flat-square&color=047B43" alt="License" /></a>
+    <img src="https://img.shields.io/badge/Python-3.11+-047B43?style=flat-square" alt="Python 3.11+" />
+  </p>
+  <p>
+    <img src="https://img.shields.io/badge/model-22MB-047B43?style=flat-square" alt="Model size: 22MB" />
+    <img src="https://img.shields.io/badge/latency-~10ms-047B43?style=flat-square" alt="Latency: ~10ms" />
+    <img src="https://img.shields.io/badge/CPU--only-no%20GPU%20needed-047B43?style=flat-square" alt="CPU only" />
+    <img src="https://img.shields.io/badge/F1%20Score-90.8%25-047B43?style=flat-square" alt="F1 Score: 90.8%" />
+  </p>
+
+</div>
+
+---
+
+Indirect prompt injection defense for AI agents using tool calls (MCP, CLI, or direct APIs). Detects and neutralizes attacks hidden in tool results (emails, documents, PRs, etc.) before they reach your LLM.
+
+**Python package:** [`stackone-defender`](https://pypi.org/project/stackone-defender/) — aligned with [`@stackone/defender`](https://www.npmjs.com/package/@stackone/defender) on npm.
+
+## Installation
+
+**pip**
+
+```bash
+pip install stackone-defender
+```
+
+**uv**
+
+```bash
+uv add stackone-defender
+```
+
+**Tier 2 (ONNX)** — add extras:
+
+```bash
+pip install stackone-defender[onnx]
+# or: uv add "stackone-defender[onnx]"
+```
+
+The ONNX model (~22MB) is bundled in the wheel — no extra downloads at runtime.
+
+**SFE preprocessor (optional)** — add extras:
+
+```bash
+pip install stackone-defender[sfe]
+# or: uv add "stackone-defender[sfe]"
+```
+
+The `[sfe]` extra installs [`fasttext-ng`](https://pypi.org/project/fasttext-ng/) (provides the `fasttext` module). It requires **NumPy 2.3+**. PyPI may ship a wheel only for some platforms; otherwise pip/uv builds from source (needs a C++ toolchain).
+
+## Quick start
+
+```python
+from stackone_defender import create_prompt_defense
+
+# Tier 1 + Tier 2 are on by default. block_high_risk=True enables allow/block.
+defense = create_prompt_defense(block_high_risk=True)
+
+# Optional: preload ONNX to avoid first-call latency (requires [onnx] extra)
+defense.warmup_tier2()
+
+result = defense.defend_tool_result(tool_output, "gmail_get_message")
+
+if not result.allowed:
+    print(f"Blocked: risk={result.risk_level}, score={result.tier2_score}")
+    print(f"Detections: {', '.join(result.detections)}")
+else:
+    send_to_llm(result.sanitized)
+```
+
+## How it works
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/StackOneHQ/defender/main/assets/demo-dark.svg" />
+  <img src="https://raw.githubusercontent.com/StackOneHQ/defender/main/assets/demo-light.svg" alt="Defender flow: poisoned tool output is sanitized and evaluated; high-risk content can be blocked before the LLM" width="900" />
+</picture>
+
+`defend_tool_result()` runs two tiers:
+
+### Tier 1 — Pattern detection (sync, ~1 ms)
+
+- **Unicode normalization** — homoglyph resistance (e.g. Cyrillic `а` → ASCII `a`)
+- **Role stripping** — `SYSTEM:`, `ASSISTANT:`, `<system>`, `[INST]`, etc.
+- **Pattern removal** — phrases like “ignore previous instructions”
+- **Encoding detection** — suspicious Base64/URL-shaped payloads
+- **Boundary annotation** — `[UD-{id}]…[/UD-{id}]` wrappers around untrusted spans
+
+### Tier 2 — ML classification (ONNX)
+
+Packed-chunk MiniLM classifier (int8 ONNX ~22 MB, bundled):
+
+- Split text into sentences, pack to model-sized chunks, score chunks in batched ONNX calls
+- Catches paraphrased or novel injections missed by regex
+- Uses chunked batch inference to bound memory on large payloads
+
+### Optional SFE preprocessor
+
+- `use_sfe=True` enables a field-level FastText pass before Tier 1/Tier 2
+- Drops metadata-like leaves (IDs, enum-like strings) and keeps user-facing content
+- Fails open if the runtime/model is unavailable: payload continues unfiltered
+
+**Benchmarks** (F1 @ threshold 0.5):
+
+| Benchmark | F1 | Samples |
+|-----------|-----|--------|
+| Qualifire (in-distribution) | 0.8686 | ~1.5k |
+| xxz224 (out-of-distribution) | 0.8834 | ~22.5k |
+| jayavibhav (adversarial) | 0.9717 | ~1k |
+| **Average** | **0.9079** | ~25k |
+
+### `allowed` vs `risk_level`
+
+- Use **`allowed`** for gating when `block_high_risk=True`: `False` means do not pass `sanitized` to the model as-is.
+- **`risk_level`** is diagnostic: it starts at `default_risk_level` (default `"medium"`) and is **escalated** by Tier 1 / Tier 2 signals — not reduced. Use it for logging, not as the sole block signal unless you implement your own policy.
+
+| Level | Typical trigger |
+|-------|------------------|
+| `low` | No strong signals |
+| `medium` | Lighter pattern / sanitization signals |
+| `high` / `critical` | Strong injection patterns, encoding signals, or high Tier 2 score |
+
+## API
+
+### `create_prompt_defense(**kwargs)`
+
+```python
+defense = create_prompt_defense(
+    enable_tier1=True,
+    enable_tier2=True,
+    block_high_risk=False,
+    default_risk_level="medium",
+    tier2_fields=["subject", "body", "snippet"],  # optional: scope Tier 2 to these JSON keys
+    use_sfe=True,  # optional: enable semantic field extractor preprocessing
+    config={
+        "tier2": {
+            "high_risk_threshold": 0.8,
+            "tier2_fields": None,  # or list[str]; constructor tier2_fields wins if set
+        },
+    },
+)
+```
+
+### `defense.defend_tool_result(value, tool_name)`
+
+Runs Tier 1 sanitization on risky fields, then Tier 2 on extracted text (with optional field scoping). **Synchronous** — no `await`.
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass
+class DefenseResult:
+    allowed: bool
+    risk_level: RiskLevel
+    sanitized: Any
+    detections: list[str]
+    fields_sanitized: list[str]
+    patterns_by_field: dict[str, list[str]]
+    tier2_score: float | None = None
+    tier2_skip_reason: str | None = None
+    max_sentence: str | None = None
+    fields_dropped: list[str] = field(default_factory=list)
+    truncated_at_depth: bool | None = None
+    latency_ms: float = 0.0
+```
+
+### `defense.defend_tool_results(items)`
+
+```python
+results = defense.defend_tool_results([
+    {"value": email_data, "tool_name": "gmail_get_message"},
+    {"value": doc_data, "tool_name": "documents_get"},
+    {"value": pr_data, "tool_name": "github_get_pull_request"},
+])
+for r in results:
+    if not r.allowed:
+        print("Blocked:", ", ".join(r.fields_sanitized))
+```
+
+### `defense.analyze(text)`
+
+Tier 1 only — useful for debugging pattern hits without full tool-result traversal.
+
+### Tier 2 warmup
+
+```python
+defense = create_prompt_defense()
+defense.warmup_tier2()  # no-op if enable_tier2=False or ONNX extra missing
+```
+
+## Integration example
+
+```python
+from stackone_defender import create_prompt_defense
+
+defense = create_prompt_defense(block_high_risk=True)
+defense.warmup_tier2()
+
+def run_tool_and_defend(raw_result: dict, tool_name: str):
+    outcome = defense.defend_tool_result(raw_result, tool_name)
+    if not outcome.allowed:
+        return {"error": "Content blocked by safety filter", "risk_level": outcome.risk_level}
+    return outcome.sanitized
+
+# Example agent loop
+sanitized = run_tool_and_defend(gmail_api.get_message(msg_id), "gmail_get_message")
+```
+
+## Risky field detection
+
+Only **string** values under configured “risky” keys are scanned and sanitized. [`RiskyFieldConfig`](https://github.com/StackOneHQ/stackone-defender/blob/main/src/stackone_defender/types.py) provides global names/patterns plus **`tool_overrides`** (wildcard tool names → field list), same idea as the npm package.
+
+| Tool pattern | Scanned fields |
+|--------------|----------------|
+| `gmail_*`, `email_*` | subject, body, snippet, content |
+| `documents_*` | name, description, content, title |
+| `github_*` | name, title, body, description, message |
+| `hris_*` | name, notes, bio, description |
+| `ats_*` | name, notes, description, summary |
+| `crm_*` | name, description, notes, content |
+
+Otherwise the default list applies: `name`, `description`, `content`, `title`, `notes`, `summary`, `bio`, `body`, `text`, `message`, `comment`, `subject`, plus suffix patterns like `*_body`, `*_description`, etc. Structural keys such as `id`, `url`, `created_at` are not treated as risky by default.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

stackone_defender-0.6.2/README.md

@@ -0,0 +1,243 @@
+<div align="center">
+
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/StackOneHQ/defender/main/assets/banner-dark.svg" />
+    <img src="https://raw.githubusercontent.com/StackOneHQ/defender/main/assets/banner-light.svg" alt="Defender by StackOne — Indirect prompt injection protection for MCP tool calls" width="800" />
+  </picture>
+
+  <p>
+    <a href="https://pypi.org/project/stackone-defender/"><img src="https://img.shields.io/pypi/v/stackone-defender?style=flat-square&color=047B43&label=pypi" alt="PyPI version" /></a>
+    <a href="https://github.com/StackOneHQ/stackone-defender/releases"><img src="https://img.shields.io/github/v/release/StackOneHQ/stackone-defender?style=flat-square&color=047B43&label=release" alt="latest GitHub release" /></a>
+    <a href="https://github.com/StackOneHQ/stackone-defender/stargazers"><img src="https://img.shields.io/github/stars/StackOneHQ/stackone-defender?style=flat-square&color=047B43" alt="GitHub stars" /></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/pypi/l/stackone-defender?style=flat-square&color=047B43" alt="License" /></a>
+    <img src="https://img.shields.io/badge/Python-3.11+-047B43?style=flat-square" alt="Python 3.11+" />
+  </p>
+  <p>
+    <img src="https://img.shields.io/badge/model-22MB-047B43?style=flat-square" alt="Model size: 22MB" />
+    <img src="https://img.shields.io/badge/latency-~10ms-047B43?style=flat-square" alt="Latency: ~10ms" />
+    <img src="https://img.shields.io/badge/CPU--only-no%20GPU%20needed-047B43?style=flat-square" alt="CPU only" />
+    <img src="https://img.shields.io/badge/F1%20Score-90.8%25-047B43?style=flat-square" alt="F1 Score: 90.8%" />
+  </p>
+
+</div>
+
+---
+
+Indirect prompt injection defense for AI agents using tool calls (MCP, CLI, or direct APIs). Detects and neutralizes attacks hidden in tool results (emails, documents, PRs, etc.) before they reach your LLM.
+
+**Python package:** [`stackone-defender`](https://pypi.org/project/stackone-defender/) — aligned with [`@stackone/defender`](https://www.npmjs.com/package/@stackone/defender) on npm.
+
+## Installation
+
+**pip**
+
+```bash
+pip install stackone-defender
+```
+
+**uv**
+
+```bash
+uv add stackone-defender
+```
+
+**Tier 2 (ONNX)** — add extras:
+
+```bash
+pip install stackone-defender[onnx]
+# or: uv add "stackone-defender[onnx]"
+```
+
+The ONNX model (~22MB) is bundled in the wheel — no extra downloads at runtime.
+
+**SFE preprocessor (optional)** — add extras:
+
+```bash
+pip install stackone-defender[sfe]
+# or: uv add "stackone-defender[sfe]"
+```
+
+The `[sfe]` extra installs [`fasttext-ng`](https://pypi.org/project/fasttext-ng/) (provides the `fasttext` module). It requires **NumPy 2.3+**. PyPI may ship a wheel only for some platforms; otherwise pip/uv builds from source (needs a C++ toolchain).
+
+## Quick start
+
+```python
+from stackone_defender import create_prompt_defense
+
+# Tier 1 + Tier 2 are on by default. block_high_risk=True enables allow/block.
+defense = create_prompt_defense(block_high_risk=True)
+
+# Optional: preload ONNX to avoid first-call latency (requires [onnx] extra)
+defense.warmup_tier2()
+
+result = defense.defend_tool_result(tool_output, "gmail_get_message")
+
+if not result.allowed:
+    print(f"Blocked: risk={result.risk_level}, score={result.tier2_score}")
+    print(f"Detections: {', '.join(result.detections)}")
+else:
+    send_to_llm(result.sanitized)
+```
+
+## How it works
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/StackOneHQ/defender/main/assets/demo-dark.svg" />
+  <img src="https://raw.githubusercontent.com/StackOneHQ/defender/main/assets/demo-light.svg" alt="Defender flow: poisoned tool output is sanitized and evaluated; high-risk content can be blocked before the LLM" width="900" />
+</picture>
+
+`defend_tool_result()` runs two tiers:
+
+### Tier 1 — Pattern detection (sync, ~1 ms)
+
+- **Unicode normalization** — homoglyph resistance (e.g. Cyrillic `а` → ASCII `a`)
+- **Role stripping** — `SYSTEM:`, `ASSISTANT:`, `<system>`, `[INST]`, etc.
+- **Pattern removal** — phrases like “ignore previous instructions”
+- **Encoding detection** — suspicious Base64/URL-shaped payloads
+- **Boundary annotation** — `[UD-{id}]…[/UD-{id}]` wrappers around untrusted spans
+
+### Tier 2 — ML classification (ONNX)
+
+Packed-chunk MiniLM classifier (int8 ONNX ~22 MB, bundled):
+
+- Split text into sentences, pack to model-sized chunks, score chunks in batched ONNX calls
+- Catches paraphrased or novel injections missed by regex
+- Uses chunked batch inference to bound memory on large payloads
+
+### Optional SFE preprocessor
+
+- `use_sfe=True` enables a field-level FastText pass before Tier 1/Tier 2
+- Drops metadata-like leaves (IDs, enum-like strings) and keeps user-facing content
+- Fails open if the runtime/model is unavailable: payload continues unfiltered
+
+**Benchmarks** (F1 @ threshold 0.5):
+
+| Benchmark | F1 | Samples |
+|-----------|-----|--------|
+| Qualifire (in-distribution) | 0.8686 | ~1.5k |
+| xxz224 (out-of-distribution) | 0.8834 | ~22.5k |
+| jayavibhav (adversarial) | 0.9717 | ~1k |
+| **Average** | **0.9079** | ~25k |
+
+### `allowed` vs `risk_level`
+
+- Use **`allowed`** for gating when `block_high_risk=True`: `False` means do not pass `sanitized` to the model as-is.
+- **`risk_level`** is diagnostic: it starts at `default_risk_level` (default `"medium"`) and is **escalated** by Tier 1 / Tier 2 signals — not reduced. Use it for logging, not as the sole block signal unless you implement your own policy.
+
+| Level | Typical trigger |
+|-------|------------------|
+| `low` | No strong signals |
+| `medium` | Lighter pattern / sanitization signals |
+| `high` / `critical` | Strong injection patterns, encoding signals, or high Tier 2 score |
+
+## API
+
+### `create_prompt_defense(**kwargs)`
+
+```python
+defense = create_prompt_defense(
+    enable_tier1=True,
+    enable_tier2=True,
+    block_high_risk=False,
+    default_risk_level="medium",
+    tier2_fields=["subject", "body", "snippet"],  # optional: scope Tier 2 to these JSON keys
+    use_sfe=True,  # optional: enable semantic field extractor preprocessing
+    config={
+        "tier2": {
+            "high_risk_threshold": 0.8,
+            "tier2_fields": None,  # or list[str]; constructor tier2_fields wins if set
+        },
+    },
+)
+```
+
+### `defense.defend_tool_result(value, tool_name)`
+
+Runs Tier 1 sanitization on risky fields, then Tier 2 on extracted text (with optional field scoping). **Synchronous** — no `await`.
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass
+class DefenseResult:
+    allowed: bool
+    risk_level: RiskLevel
+    sanitized: Any
+    detections: list[str]
+    fields_sanitized: list[str]
+    patterns_by_field: dict[str, list[str]]
+    tier2_score: float | None = None
+    tier2_skip_reason: str | None = None
+    max_sentence: str | None = None
+    fields_dropped: list[str] = field(default_factory=list)
+    truncated_at_depth: bool | None = None
+    latency_ms: float = 0.0
+```
+
+### `defense.defend_tool_results(items)`
+
+```python
+results = defense.defend_tool_results([
+    {"value": email_data, "tool_name": "gmail_get_message"},
+    {"value": doc_data, "tool_name": "documents_get"},
+    {"value": pr_data, "tool_name": "github_get_pull_request"},
+])
+for r in results:
+    if not r.allowed:
+        print("Blocked:", ", ".join(r.fields_sanitized))
+```
+
+### `defense.analyze(text)`
+
+Tier 1 only — useful for debugging pattern hits without full tool-result traversal.
+
+### Tier 2 warmup
+
+```python
+defense = create_prompt_defense()
+defense.warmup_tier2()  # no-op if enable_tier2=False or ONNX extra missing
+```
+
+## Integration example
+
+```python
+from stackone_defender import create_prompt_defense
+
+defense = create_prompt_defense(block_high_risk=True)
+defense.warmup_tier2()
+
+def run_tool_and_defend(raw_result: dict, tool_name: str):
+    outcome = defense.defend_tool_result(raw_result, tool_name)
+    if not outcome.allowed:
+        return {"error": "Content blocked by safety filter", "risk_level": outcome.risk_level}
+    return outcome.sanitized
+
+# Example agent loop
+sanitized = run_tool_and_defend(gmail_api.get_message(msg_id), "gmail_get_message")
+```
+
+## Risky field detection
+
+Only **string** values under configured “risky” keys are scanned and sanitized. [`RiskyFieldConfig`](https://github.com/StackOneHQ/stackone-defender/blob/main/src/stackone_defender/types.py) provides global names/patterns plus **`tool_overrides`** (wildcard tool names → field list), same idea as the npm package.
+
+| Tool pattern | Scanned fields |
+|--------------|----------------|
+| `gmail_*`, `email_*` | subject, body, snippet, content |
+| `documents_*` | name, description, content, title |
+| `github_*` | name, title, body, description, message |
+| `hris_*` | name, notes, bio, description |
+| `ats_*` | name, notes, description, summary |
+| `crm_*` | name, description, notes, content |
+
+Otherwise the default list applies: `name`, `description`, `content`, `title`, `notes`, `summary`, `bio`, `body`, `text`, `message`, `comment`, `subject`, plus suffix patterns like `*_body`, `*_description`, etc. Structural keys such as `id`, `url`, `created_at` are not treated as risky by default.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

stackone_defender-0.6.2/models/minilm-full-aug/config.json

@@ -0,0 +1,30 @@
+{
+  "add_cross_attention": false,
+  "architectures": [
+    "BertModel"
+  ],
+  "attention_probs_dropout_prob": 0.1,
+  "bos_token_id": null,
+  "classifier_dropout": null,
+  "dtype": "float32",
+  "eos_token_id": null,
+  "gradient_checkpointing": false,
+  "hidden_act": "gelu",
+  "hidden_dropout_prob": 0.1,
+  "hidden_size": 384,
+  "initializer_range": 0.02,
+  "intermediate_size": 1536,
+  "is_decoder": false,
+  "layer_norm_eps": 1e-12,
+  "max_position_embeddings": 512,
+  "model_type": "bert",
+  "num_attention_heads": 12,
+  "num_hidden_layers": 6,
+  "pad_token_id": 0,
+  "position_embedding_type": "absolute",
+  "tie_word_embeddings": true,
+  "transformers_version": "5.3.0",
+  "type_vocab_size": 2,
+  "use_cache": true,
+  "vocab_size": 30522
+}