prompt-armor 0.1.0__tar.gz

prompt_armor-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug Report
+about: Report a bug in prompt-armor
+title: "[Bug] "
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To Reproduce**
+```python
+from prompt_armor import analyze
+result = analyze("your prompt here")
+# Expected: ...
+# Actual: ...
+```
+
+**Environment**
+- OS: [e.g., macOS, Ubuntu]
+- Python version: [e.g., 3.12]
+- prompt-armor version: [e.g., 0.1.0]
+- ML model installed: [yes/no]
+
+**Additional context**
+Any other relevant information.

prompt_armor-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature Request
+about: Suggest an improvement
+title: "[Feature] "
+labels: enhancement
+---
+
+**Problem**
+What problem does this solve?
+
+**Proposed Solution**
+What would you like to happen?
+
+**Alternatives Considered**
+Any other approaches you've thought about.

prompt_armor-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What does this PR do?
+
+Brief description.
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] New attack samples / regex rules
+- [ ] Documentation
+- [ ] Performance improvement
+
+## Checklist
+
+- [ ] Tests pass (`pytest tests/ -v`)
+- [ ] Lint passes (`ruff check src/ tests/`)
+- [ ] Benchmark updated if detection logic changed
+- [ ] Documentation updated if needed

prompt_armor-0.1.0/.github/workflows/benchmark.yml

@@ -0,0 +1,36 @@
+name: Benchmark
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install -e ".[dev,ml]"
+
+      - name: Run benchmark
+        run: |
+          source .venv/bin/activate
+          python tests/benchmark/run_benchmark.py --output benchmark_results.json
+
+      - name: Upload results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark_results.json

prompt_armor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e ".[dev,ml,mcp]"
+
+      - name: Lint
+        run: |
+          source .venv/bin/activate
+          ruff check src/ tests/
+
+      - name: Format check
+        run: |
+          source .venv/bin/activate
+          ruff format --check src/ tests/
+
+      - name: Type check
+        run: |
+          source .venv/bin/activate
+          mypy src/prompt_armor/ --ignore-missing-imports
+
+      - name: Unit tests
+        run: |
+          source .venv/bin/activate
+          pytest tests/unit/ -v --tb=short
+
+      - name: Integration tests
+        run: |
+          source .venv/bin/activate
+          pytest tests/integration/ -v --tb=short

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

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

prompt_armor-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# Models (distributed via download-on-first-use, too large for git)
+src/prompt_armor/data/models/*.onnx
+src/prompt_armor/data/models/*.bin
+src/prompt_armor/data/models/*.npy
+src/prompt_armor/data/models/*.json
+!src/prompt_armor/data/models/.gitkeep
+
+# Script outputs (generated, not tracked)
+scripts/*.json
+
+# mkdocs build output
+site/
+
+# Environment
+.env
+.env.local

prompt_armor-0.1.0/.prompt-armor.yml

@@ -0,0 +1,20 @@
+# prompt-armor configuration
+# See: https://github.com/prompt-armor/prompt-armor
+
+# Layer weights (must sum to ~1.0 for available layers)
+weights:
+  l1_regex: 0.20
+  l2_classifier: 0.30
+  l3_similarity: 0.30
+  l4_structural: 0.20
+
+# Decision thresholds
+thresholds:
+  allow_below: 0.3     # Score below this = ALLOW
+  block_above: 0.7     # Score above this = BLOCK
+  hard_block: 0.95     # Any single layer above this = instant BLOCK
+  min_confidence: 0.5   # Below this confidence = needs_council
+
+# Fusion parameters
+convergence_boost: 0.10    # Score boost when layers agree
+divergence_penalty: 0.15   # Confidence penalty when layers disagree

prompt_armor-0.1.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to prompt-armor will be documented in this file.
+
+## [0.1.1] - 2026-03-20
+
+### Security
+- Thread-safe singleton initialization (double-checked locking) — fixes race condition
+- Context manager support on LiteEngine (`with LiteEngine() as engine:`)
+- atexit handler for ThreadPoolExecutor cleanup — prevents thread leaks
+- Fail-open layer setup — broken layers are disabled instead of crashing the engine
+- Fix `concurrent.futures.TimeoutError` handling on Python 3.10
+- Pin L2 model download by commit SHA — supply chain hardening
+- Remove `trust_remote_code=True` from all dataset scripts
+- Path traversal validation on `rules_path` / `attacks_path` in config
+- Scrub PII from known_attacks.jsonl (emails, usernames)
+- Fix ReDoS patterns (JB-003 bounded quantifier, DE-003 backtracking)
+- Fix overly broad ML-ES-003 Spanish pattern (require 'ahora' prefix)
+
+### Changed
+- Frozen dataclasses now use `tuple` instead of `list` for true immutability
+- Shared `CATEGORY_MAP` in models.py (DRY: was duplicated in L1 and L3)
+- Shared `ShieldResult.to_dict()` method (DRY: was duplicated in CLI and MCP)
+- Pre-compiled fiction/educational context patterns in L1 (was recompiling per call)
+- Replace `assert isinstance` with proper `TypeError` raises
+- CI triggers on `dev` branch, uses correct Python version from matrix
+- Catch `Exception` (not just `ImportError`) when loading optional layers
+
+### Added
+- `ShieldResult.to_dict()` method for JSON serialization
+- `LiteEngine.__enter__` / `__exit__` context manager protocol
+- Input type validation (`TypeError` on non-str input)
+- Git workflow documentation in CLAUDE.md
+
+## [0.1.0] - 2026-03-19
+
+### Added
+- 4-layer parallel analysis engine (L1 Regex, L2 DeBERTa Classifier, L3 Semantic Similarity, L4 Structural)
+- Trained logistic regression meta-classifier for score fusion
+- Sliding window segmentation for compound injection detection
+- Unicode NFKC normalization + zero-width character stripping
+- Multilingual regex rules (DE, ES, FR, PT)
+- Multilingual embedding model (paraphrase-multilingual-MiniLM-L12-v2) for L3
+- CLI with `analyze`, `scan`, `config` commands and semantic exit codes
+- MCP Server with `analyze_prompt` tool
+- Per-layer timeout (2s) and fail-open error handling
+- Input length guard (50K chars) and segment cap (10)
+- Public benchmark dataset (258 benign + 97 malicious from deepset, TrustAIRLab, Lakera Gandalf)
+- YAML configuration (`.prompt-armor.yml`)
+- 103 tests (unit + integration)
+- GitHub Actions CI (tests, benchmark, publish)
+
+### Benchmark Results
+- Held-out F1: 93.0% (30% test set, never seen during training)
+- Full dataset: Precision 79.8%, Recall 93.8%, F1 86.3%
+- Average latency: ~19ms

prompt_armor-0.1.0/CLAUDE.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+prompt-armor is an open-core LLM prompt security analysis tool. It detects prompt injections, jailbreaks, and other attacks against LLMs. The Lite engine runs 4 analysis layers in parallel, fuses scores via a trained meta-classifier, and returns decisions in ~19ms offline.
+
+## Commands
+
+```bash
+# Install (editable, with all extras)
+pip install -e ".[dev,mcp]"
+
+# Run tests
+pytest tests/ -v
+pytest tests/unit/ -v                    # unit only
+pytest tests/unit/test_l1_regex.py -v    # single file
+pytest -k "test_detects_injection" -v    # single test by name
+
+# Lint & format
+ruff check src/ tests/
+ruff format src/ tests/
+mypy src/prompt_armor/
+
+# CLI
+prompt-armor analyze "some prompt"
+prompt-armor analyze --file prompt.txt --json
+prompt-armor scan --dir ./prompts/ --format table
+
+# Benchmark
+python tests/benchmark/run_benchmark.py
+
+# MCP Server
+prompt-armor-mcp
+
+# Retrain fusion meta-classifier (after changing layers or dataset)
+python scripts/dump_layer_scores.py
+python scripts/train_fusion.py
+
+# Rebuild attack database from public sources
+python scripts/build_attack_db.py
+```
+
+## Architecture
+
+```
+INPUT → NORMALIZE → SEGMENT (if >150 words) → [L1 | L2 | L3 | L4] → META-CLASSIFIER → GATE → OUTPUT
+```
+
+The core pipeline runs 4 analysis layers **in parallel** via `ThreadPoolExecutor`, feeds scores into a trained logistic regression meta-classifier, and applies decision thresholds:
+
+- **`engine.py` (LiteEngine)** — Orchestrates: Unicode normalization, sliding window segmentation, parallel layer dispatch, per-layer timeout (2s) with fail-open.
+- **`layers/l1_regex.py`** — 40+ English + 20 multilingual (DE/ES/FR/PT) weighted regex rules. Context modifier exploit hardened (high scores not dampened).
+- **`layers/l2_classifier.py`** — DeBERTa-v3-xsmall (22M params, ONNX) with score calibration. Auto-downloads from HuggingFace on first use. Falls back to keyword heuristic.
+- **`layers/l3_similarity.py`** — paraphrase-multilingual-MiniLM-L12-v2 + FAISS cosine similarity against 1,151 known attacks.
+- **`layers/l4_structural.py`** — Deterministic: imperative verb ratios, delimiter injection, encoding tricks, expanded role assignment with benign whitelist.
+- **`fusion.py`** — Trained LogisticRegression meta-classifier (9 features: 4 layer scores + max + min + interactions + n_above_0.1). L3/L4 coefficients clamped to 0 to prevent exploitation.
+- **`models.py`** — Frozen dataclasses: `ShieldResult`, `LayerResult`, `Evidence`, `Decision`, `Category`.
+- **`config.py`** — Pydantic models for YAML config (`.prompt-armor.yml`).
+
+### Key conventions
+
+- **dataclass for output types, Pydantic for config only**
+- **Layers are CPU-bound** — ThreadPoolExecutor (not asyncio) because ONNX/FAISS/numpy release the GIL
+- **Public API is `prompt_armor.analyze()`** — lazy-initialized in `__init__.py`
+- **CLI exit codes** — 0=allow, 1=warn, 2=block, 3=error
+- **MCP server is Python** — Uses `mcp` SDK (FastMCP)
+- **Meta-classifier coefficients are hardcoded in fusion.py** — retrain via `scripts/train_fusion.py` if layers or dataset change
+- **L2 model auto-downloads** — from HuggingFace Hub on first use (~83MB)
+
+### Data files
+
+- `data/rules/default_rules.yml` — L1 regex rules (EN + DE/ES/FR/PT)
+- `data/attacks/known_attacks.jsonl` — L3 attack DB (1,151 entries)
+- `data/models/` — L2 ONNX model (auto-downloaded, not in git)
+
+## Git Workflow (MANDATORY)
+
+### Branches
+| Branch | Role |
+|--------|------|
+| `main` | Production — never commit directly |
+| `dev` | Staging — receives merges from feature branches via PR |
+| `feature/*`, `fix/*`, `refactor/*`, `chore/*`, `docs/*` | Work branches — always branch from `dev` |
+| `hotfix/*` | Emergency fixes — branch from `main`, PR to `main`, then sync `dev` |
+
+### Flow
+1. Branch from `dev`: `git checkout dev && git pull && git checkout -b feature/name`
+2. Atomic commits with Conventional Commits: `type(scope): description`
+3. Push and PR to `dev`: `git push -u origin feature/name && gh pr create --base dev`
+4. Squash merge feature → dev
+5. When ready for release: PR `dev` → `main` with merge commit (not squash)
+6. Tag on `main`: `git tag -a vX.Y.Z -m "..."` && `git push origin vX.Y.Z`
+
+### Commit Format
+```
+type(scope): description in English, imperative mood, no period
+```
+Types: `feat`, `fix`, `refactor`, `style`, `docs`, `test`, `chore`, `perf`, `ci`
+
+### Strict Rules
+- NEVER commit directly to `main` or `dev`
+- NEVER force-push to `main`
+- NEVER PR a feature directly to `main` (only hotfix)
+- Squash merge: `feature/*` → `dev`
+- Merge commit: `dev` → `main`
+- One commit = one logical change

prompt_armor-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to prompt-armor
+
+Thanks for your interest in contributing! Here's how you can help.
+
+## Quick Start
+
+```bash
+git clone https://github.com/prompt-armor/prompt-armor
+cd prompt-armor
+pip install -e ".[dev,ml,mcp]"
+pytest tests/ -v
+```
+
+## Ways to Contribute
+
+### Add Attack Samples (Easiest)
+
+The most impactful contribution is expanding the attack database. Add entries to:
+
+- `src/prompt_armor/data/attacks/known_attacks.jsonl` — Known attack prompts for L3 similarity matching
+- `tests/benchmark/dataset/malicious.jsonl` — Labeled attack prompts for benchmarking
+
+Format:
+```json
+{"text": "the attack prompt", "category": "prompt_injection", "source": "your_source"}
+```
+
+Categories: `prompt_injection`, `jailbreak`, `identity_override`, `system_prompt_leak`, `instruction_bypass`, `data_exfiltration`, `encoding_attack`, `social_engineering`
+
+### Add Regex Rules
+
+Add patterns to `src/prompt_armor/data/rules/default_rules.yml`. Each rule needs:
+- Unique ID (e.g., `PI-011` for prompt injection rule 11)
+- Regex pattern (case-insensitive by default)
+- Category, weight (0.0-1.0), and description
+
+Multilingual rules are welcome (DE, ES, FR, PT, and any other language).
+
+### Bug Fixes and Improvements
+
+1. Fork the repo
+2. Create a branch (`git checkout -b fix/your-fix`)
+3. Make your changes
+4. Ensure tests pass: `pytest tests/ -v`
+5. Ensure lint passes: `ruff check src/ tests/`
+6. Submit a PR
+
+## Development
+
+```bash
+# Run tests
+pytest tests/ -v
+
+# Run a single test
+pytest tests/unit/test_l1_regex.py -v
+
+# Lint
+ruff check src/ tests/
+
+# Format
+ruff format src/ tests/
+
+# Type check
+mypy src/prompt_armor/
+
+# Run benchmark
+python tests/benchmark/run_benchmark.py
+```
+
+## Code Style
+
+- Python 3.10+
+- Formatted with `ruff`
+- Type hints on all public functions
+- `dataclass(frozen=True, slots=True)` for result types
+- `Pydantic` only for config validation
+
+## Pull Request Guidelines
+
+- Keep PRs focused — one feature or fix per PR
+- Add tests for new functionality
+- Update the benchmark if you change detection logic
+- Run `ruff check` and `pytest` before submitting

prompt_armor-0.1.0/LICENSE

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

prompt_armor-0.1.0/Makefile

@@ -0,0 +1,29 @@
+.PHONY: install test lint format typecheck bench docs clean
+
+install:
+	pip install -e ".[dev,mcp]"
+
+test:
+	pytest tests/ -v
+
+test-unit:
+	pytest tests/unit/ -v
+
+lint:
+	ruff check src/ tests/
+
+format:
+	ruff format src/ tests/
+
+typecheck:
+	mypy src/llm_shield/
+
+bench:
+	python tests/benchmark/run_benchmark.py
+
+docs:
+	mkdocs serve
+
+clean:
+	rm -rf build/ dist/ *.egg-info .pytest_cache .mypy_cache .ruff_cache htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true