Skip to content

improve parsing data #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tyagian merged 2 commits into from
May 3, 2026
Merged

improve parsing data #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
be83a80
improve parsing data
tyagian May 3, 2026
933c0b8
fix
tyagian May 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
336 changes: 8 additions & 328 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,17 @@ SentinelGuard provides 36 security scanners, enterprise-grade PII detection, adv

## Features

- **19 Prompt Scanners** - Injection detection, PII, toxicity, secrets, supply chain, data poisoning, and more
- **17 Output Scanners** - Bias, data leakage, XSS/SQLi sanitization, excessive agency, system prompt leakage, misinformation, and more
- **OWASP LLM Top 10 (2025)** - Full compliance with built-in compliance checker and reporting
- **Presidio PII Integration** - Enterprise-grade detection with 50+ entity types
- **Adversarial Detection** - Multi-method attack detection (perturbation, semantic, statistical, embedding)
- **Embedding Guardrails** - Semantic topic enforcement using vector embeddings
- **FastAPI Server** - REST API for integration with any stack
- **CLI Tool** - Command-line scanning and configuration
- **Async Support** - Full async/await support for high-performance applications
- **Configuration System** - YAML/JSON configs with presets (minimal, standard, strict)
- **Jupyter Notebooks** - Interactive examples for all features
- **19 Prompt Scanners** — Injection detection, PII, toxicity, secrets, supply chain, data poisoning, and more
- **17 Output Scanners** — Bias, data leakage, XSS/SQLi sanitization, excessive agency, system prompt leakage, misinformation, and more
- **OWASP LLM Top 10 (2025)** — Full compliance with built-in compliance checker and reporting
- **PII Detection & Anonymization** — Enterprise-grade detection with 30+ entity types and multiple anonymization strategies
- **Adversarial Detection** — Multi-method attack detection (perturbation, semantic, statistical, embedding)
- **Secrets Detection** — API keys, tokens, passwords, credentials via pattern matching and entropy analysis
- **Async Support** — Full async/await support for high-performance applications
- **Configuration System** — YAML/JSON configs with presets (minimal, standard, strict)

## OWASP LLM Top 10 (2025) Coverage

SentinelGuard provides **complete coverage** of all OWASP LLM Top 10 vulnerability categories:

| OWASP ID | Vulnerability | Scanners | Risk Level |
|----------|--------------|----------|------------|
| **LLM01** | Prompt Injection | `prompt_injection`, `invisible_text`, `ban_code` | CRITICAL |
Expand Down Expand Up @@ -55,21 +50,7 @@ print(report.summary())
## Installation

```bash
# Basic
pip install sentinelguard

# All features
pip install sentinelguard[all]

# Specific features
pip install sentinelguard[pii] # Presidio PII detection
pip install sentinelguard[adversarial] # Adversarial detection models
pip install sentinelguard[advanced] # Embeddings + transformers
pip install sentinelguard[api] # FastAPI server
pip install sentinelguard[monitoring] # OpenTelemetry metrics

# spaCy model for PII (if using Presidio)
python -m spacy download en_core_web_sm
```

## Quick Start
Expand Down Expand Up @@ -133,307 +114,6 @@ config = GuardConfig(
guard = SentinelGuard(config=config)
```

### Builder Pattern

```python
guard = SentinelGuard()
guard.use("prompt_injection", on="prompt", threshold=0.7)
guard.use("pii", on="both", threshold=0.5)
guard.use("toxicity", on="prompt", threshold=0.7)
guard.use("bias", on="output", threshold=0.5)
guard.use("data_leakage", on="output", threshold=0.5)
guard.use("output_sanitization", on="output", threshold=0.3)
```

### Full Pipeline

```python
guard = SentinelGuard.minimal()

# Scan input
prompt_result = guard.scan_prompt(user_input)
if not prompt_result.is_valid:
return "Input blocked"

# Call your LLM
llm_output = call_llm(user_input)

# Scan output
output_result = guard.scan_output(llm_output, prompt=user_input)
if not output_result.is_valid:
return "Output blocked"

return llm_output
```

### YAML Configuration

```yaml
# sentinelguard.yaml
mode: strict
fail_fast: true
prompt_scanners:
prompt_injection:
enabled: true
threshold: 0.5
pii:
enabled: true
threshold: 0.3
supply_chain:
enabled: true
threshold: 0.4
data_poisoning:
enabled: true
threshold: 0.4
output_scanners:
data_leakage:
enabled: true
threshold: 0.5
output_sanitization:
enabled: true
threshold: 0.3
excessive_agency:
enabled: true
threshold: 0.4
```

```python
guard = SentinelGuard.from_config("sentinelguard.yaml")
```

## Scanners

### Prompt Scanners (19)

| Scanner | OWASP | Description |
|---------|-------|-------------|
| `prompt_injection` | LLM01 | Detects injection attempts (patterns, heuristics, optional model) |
| `pii` | LLM02 | Detects PII with Presidio integration (50+ entity types) |
| `secrets` | LLM02 | Finds API keys, tokens, passwords (12+ pattern types) |
| `toxicity` | LLM04 | Identifies toxic/hateful content |
| `gibberish` | - | Detects nonsense/random text |
| `invisible_text` | LLM01 | Finds zero-width Unicode and hidden characters |
| `code` | - | Detects code snippets (Python, JS, SQL, Shell, etc.) |
| `ban_topics` | - | Blocks specific topics via keyword matching |
| `ban_competitors` | - | Prevents competitor brand mentions |
| `ban_substrings` | - | Blocks specific phrases/substrings |
| `ban_code` | LLM01,06 | Prevents code injection (eval, exec, system) |
| `anonymize` | LLM02 | Detects and replaces PII with anonymized tokens |
| `language` | - | Detects language, enforces allowed languages |
| `regex` | - | Custom regex pattern matching (allow/deny) |
| `sentiment` | - | Analyzes sentiment, blocks negative content |
| `token_limit` | LLM10 | Enforces token/character limits |
| `unbounded_consumption` | LLM10 | Detects resource exhaustion attacks (DoS, recursion) |
| `supply_chain` | LLM03 | Detects untrusted models, malicious packages, deserialization |
| `data_poisoning` | LLM04 | Detects training data injection, backdoors, knowledge corruption |

### Output Scanners (17)

| Scanner | OWASP | Description |
|---------|-------|-------------|
| `bias` | - | Detects biased language (gender, racial, age, etc.) |
| `relevance` | - | Checks prompt-output relevance via keyword overlap |
| `factual_consistency` | LLM09 | Detects internal contradictions |
| `sensitive` | LLM07 | Finds leaked system info (paths, IPs, prompts) |
| `malicious_urls` | LLM05 | Detects phishing/suspicious URLs |
| `no_refusal` | - | Detects LLM refusal patterns |
| `reading_time` | - | Estimates and limits reading time |
| `json` | LLM05 | Validates JSON structure and required fields |
| `language_same` | - | Ensures output language matches prompt |
| `url_reachability` | - | Checks if URLs are reachable |
| `deanonymize` | LLM02 | Reverses anonymization using mapping |
| `data_leakage` | LLM02 | Detects PII, financial, medical, credential exposure |
| `excessive_agency` | LLM06 | Detects unauthorized code execution, file ops, privilege escalation |
| `misinformation` | LLM09 | Detects hallucination, fake citations, fabricated statistics |
| `output_sanitization` | LLM05 | Detects XSS, SQL injection, command injection, SSRF, path traversal |
| `system_prompt_leakage` | LLM07 | Detects system prompt echo, config leak, API key exposure |
| `vector_weakness` | LLM08 | Detects RAG poisoning, embedding manipulation, data extraction |

## Advanced Features

### PII Detection (Presidio)

```python
from sentinelguard.pii import PIIDetector, PIIAnonymizer

detector = PIIDetector(
language="en",
entities=["EMAIL", "PHONE", "CREDIT_CARD", "SSN"],
score_threshold=0.5,
)
entities = detector.detect("Email: john@example.com, SSN: 123-45-6789")

anonymizer = PIIAnonymizer(default_strategy="replace")
result = anonymizer.anonymize(text, entities)
# "Email: <EMAIL_ADDRESS>, SSN: <US_SSN>"
```

Strategies: `replace`, `mask`, `hash`, `redact`, `fake`

### Adversarial Detection

```python
from sentinelguard.adversarial import AdversarialDetector, AdversarialDefender

detector = AdversarialDetector(
threshold=0.7,
config={"methods": ["perturbation", "semantic", "statistical"]},
)
result = detector.detect(text, original=clean_text)

defender = AdversarialDefender()
cleaned = defender.defend(adversarial_text)
```

### Embedding Guardrails

```python
from sentinelguard.embeddings import EmbeddingGuardrail

guardrail = EmbeddingGuardrail()
guardrail.add_allowed_topics({
"support": ["How can I help?", "Order questions"],
})
guardrail.add_banned_topics({
"medical": ["Diagnose condition", "Medication advice"],
})

result = guardrail.check("Where is my order?")
print(result.is_allowed) # True
```

## API Server

```bash
# Start server
sentinelguard serve --port 8000

# Or programmatically
from sentinelguard.api import create_app
app = create_app()
```

Endpoints:
- `POST /scan/prompt` - Scan prompt text
- `POST /scan/output` - Scan output text
- `POST /validate` - Validate prompt + output
- `GET /scanners` - List available scanners
- `GET /health` - Health check
- `GET /docs` - Interactive API docs

## CLI

```bash
# Scan a prompt
sentinelguard scan prompt "Your text here"

# Scan with JSON output
sentinelguard scan prompt "Text" --format json

# Scan with custom config
sentinelguard scan prompt "Text" --config sentinelguard.yaml

# List scanners
sentinelguard scanners list

# Create config file
sentinelguard config init --preset strict

# Start API server
sentinelguard serve --port 8000
```

## Custom Scanners

```python
from sentinelguard import BaseScanner, ScanResult, RiskLevel, register_scanner

@register_scanner
class MyCustomScanner(BaseScanner):
scanner_name = "my_scanner"
scanner_type = "both" # "prompt", "output", or "both"

def scan(self, text, **kwargs):
# Your logic here
is_safe = "bad_word" not in text.lower()
return ScanResult(
is_valid=is_safe,
score=0.0 if is_safe else 1.0,
risk_level=RiskLevel.LOW if is_safe else RiskLevel.HIGH,
details={"custom": "data"},
)

# Use it
guard = SentinelGuard()
guard.use("my_scanner", on="prompt")
```

## Async Support

```python
import asyncio
from sentinelguard import SentinelGuard

async def main():
guard = SentinelGuard.minimal()
result = await guard.scan_prompt_async("Hello world")
print(result.is_valid)

asyncio.run(main())
```

## Examples

### Python Scripts
- `examples/basic_usage.py` - Core scanning functionality
- `examples/pii_detection.py` - PII detection and anonymization
- `examples/adversarial_detection.py` - Adversarial attack detection
- `examples/embedding_guardrails.py` - Embedding-based topic enforcement

### Jupyter Notebooks
- `examples/01_basic_usage.ipynb` - Interactive guide to core features
- `examples/02_owasp_security.ipynb` - OWASP LLM Top 10 coverage with examples
- `examples/03_pii_detection.ipynb` - PII detection, anonymization, and data leakage prevention
- `examples/04_adversarial_detection.ipynb` - Adversarial attack detection and defense

## Comparison

| Feature | SentinelGuard | LLM-Guard | Guardrails AI | NeMo Guardrails |
|---------|:---:|:---:|:---:|:---:|
| Prompt Scanners | 19 | 15 | Hub | 5 |
| Output Scanners | 17 | 15 | Hub | 5 |
| OWASP LLM Top 10 | Full (10/10) | Partial | - | - |
| PII (Presidio) | 50+ entities | Basic | Via Hub | - |
| Adversarial Detection | Multi-method | - | - | - |
| Embedding Guardrails | Full | - | - | Limited |
| Compliance Checker | Built-in | - | - | - |
| API Server | FastAPI | Yes | Yes | Yes |
| CLI Tool | Yes | Limited | Yes | - |
| Async Support | Full | Partial | Full | Yes |
| Jupyter Notebooks | Yes | - | Yes | - |
| Custom Scanners | Easy | Medium | Hub | Medium |

## Project Structure

```
sentinelguard/
├── sentinelguard/
│ ├── core/ # Framework (scanner, config, guard, pipeline)
│ ├── scanners/
│ │ ├── prompt/ # 19 prompt scanners (OWASP-aligned)
│ │ └── output/ # 17 output scanners (OWASP-aligned)
│ ├── owasp.py # OWASP LLM Top 10 mapping & compliance
│ ├── pii/ # Presidio PII module
│ ├── adversarial/ # Adversarial detection
│ ├── embeddings/ # Embedding guardrails
│ ├── api/ # FastAPI server
│ └── cli/ # CLI tool
├── examples/ # Python scripts + Jupyter notebooks
├── configs/ # Configuration templates
├── tests/ # Test suite (incl. OWASP scanner tests)
└── docs/ # Documentation
```

## License

MIT License - see [LICENSE](LICENSE) for details.
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "sentinelguard"
version = "0.0.4"
version = "0.0.5"
description = "A comprehensive, production-ready LLM security and guardrails framework"
readme = "README.md"
license = {text = "MIT"}
Expand Down
2 changes: 1 addition & 1 deletion sentinelguard/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
guard = SentinelGuard(config=config)
"""

__version__ = "0.0.4"
__version__ = "0.0.5"
__author__ = "SentinelGuard Contributors"

from sentinelguard.core.guard import SentinelGuard
Expand Down
Loading
Loading