# Requirements: Meshulash Guard

**Defined:** 2026-02-26
**Core Value:** Developers can protect their LLM applications from PII leakage, toxic content, jailbreaks, and cyber threats with a single pip install and a few lines of Python.

## v1 Requirements

### SDK Core

- [x] **SDK-01**: Guard class accepts server_url and api_key, manages HTTP connection to security server
- [x] **SDK-02**: Guard.scan_input(text, scanners) sends translated guardline_specs to server and returns structured result
- [x] **SDK-03**: Guard.scan_output() method signature defined (raises NotImplementedError with "coming in v2" message)
- [x] **SDK-04**: BaseScanner abstract class with to_guardline_spec() method that translates developer config to server guardline format
- [x] **SDK-05**: BaseNormalizer abstract class with to_normalizer_spec() method defined for v2 extensibility
- [x] **SDK-06**: Structured result type with status, processed_text, placeholders, level, per-scanner breakdown, risk_categories
- [x] **SDK-07**: Action enum with REPLACE, BLOCK, LOG values mapping to server PolicyAction
- [x] **SDK-08**: Condition enum with ANY, ALL, K_OF, CONTEXTUAL values mapping to server gating conditions

### Scanners

- [x] **SCAN-01**: PIIScanner with scoped PIILabel enum covering all 53 canonical labels from server label registry
- [x] **SCAN-02**: PIIScanner supports risk bundle shortcuts (PII, PHI, PCI, SECRETS, TECH) as predefined label groups
- [x] **SCAN-03**: TopicScanner with scoped TopicLabel enum, SDK maps labels to topic TC head internally
- [x] **SCAN-04**: ToxicityScanner with scoped ToxicityLabel enum, SDK maps labels to hate_speech TC head internally
- [x] **SCAN-05**: CyberScanner with scoped CyberLabel enum, SDK maps labels to cysecbench TC head internally
- [x] **SCAN-06**: JailbreakScanner with scoped JailbreakLabel enum, SDK maps labels to jailbreak TC head internally
- [x] **SCAN-07**: Each scanner accepts action, condition, threshold, and allowlist configuration

### Vault

- [x] **VAULT-01**: Placeholder cache stores placeholder dictionaries from scan_input() results, session-scoped on Guard instance
- [x] **VAULT-02**: Guard.deanonymize(text) replaces placeholders with originals client-side, no server round-trip
- [x] **VAULT-03**: Guard.clear_cache() resets the placeholder session

### Server

- [x] **SRV-01**: New POST /api/security/scan endpoint accepting JSON body with text + guardline_specs inline
- [x] **SRV-02**: Endpoint returns per-scanner result breakdown (which scanners triggered, per-scanner detection details)
- [x] **SRV-03**: Endpoint supports JSON content-type (not just multipart/form-data)
- [x] **SRV-04**: Endpoint uses X-Api-Key header authentication

### Packaging

- [x] **PKG-01**: pyproject.toml with PEP 517/518 build system, pip-installable
- [x] **PKG-02**: Package named meshulash-guard, importable as meshulash_guard

### Documentation

- [x] **DOC-01**: MkDocs site with Material theme, deployable to custom domain
- [x] **DOC-02**: Installation and quickstart guide
- [x] **DOC-03**: Scanner reference: each scanner with labels, actions, conditions, code examples
- [x] **DOC-04**: Engine reference: what each label detects, detection sources, which validators auto-run
- [x] **DOC-05**: Deanonymize workflow guide (placeholder cache → LLM → restore)

## v2 Requirements

### Normalizers

- **NORM-01**: Server-side normalizer registry with per-request configuration
- **NORM-02**: Unicode normalization (NFC/NFKC/NFD/NFKD)
- **NORM-03**: Invisible text stripping (zero-width chars, PUA range, Unicode tag blocks)
- **NORM-04**: Homoglyph normalization (Cyrillic/lookalike → ASCII)
- **NORM-05**: Encoding detection and decode (base64, URL encoding, HTML entities)

### New Scanners

- **NSCAN-01**: SecretsScanner — entropy analysis + known API key format patterns
- **NSCAN-02**: LanguageScanner — detect and restrict allowed languages
- **NSCAN-03**: CodeScanner — detect code blocks in prompts
- **NSCAN-04**: SentimentScanner — flag excessively negative or hostile tone
- **NSCAN-05**: GibberishScanner — random/meaningless/adversarial noise detection
- **NSCAN-06**: BanSubstringsScanner — configurable substring block lists

### Output Scanning

- **OUT-01**: Server endpoint accepting prompt + output for context-aware output scanning
- **OUT-02**: RelevanceScanner — cosine similarity between output and prompt
- **OUT-03**: LanguageConsistencyScanner — verify output language matches input
- **OUT-04**: MaliciousURLScanner — extract and classify URLs in output
- **OUT-05**: NoRefusalScanner — detect if model refused the request
- **OUT-06**: OutputPIIScanner — detect PII/sensitive entities in model response

## Out of Scope

| Feature | Reason |
|---------|--------|
| Engine logic in SDK | All ML/NER/regex/validation runs server-side; SDK is a client wrapper |
| REST API documentation | Existing API deprecated; SDK is the primary interface |
| File scanning via SDK | Server supports PDF but SDK text-only in v1 |
| OAuth/JWT auth in SDK | API key sufficient for v1 customer use cases |
| Custom regex via SDK | Developers can't define custom regex patterns in v1 |
| Streaming LLM scanning | Chunk-by-chunk scanning is future work |
| Guardrails Hub marketplace | Community-contributed scanners not in scope |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| SDK-01 | Phase 1 | Complete |
| SDK-02 | Phase 2 | Complete |
| SDK-03 | Phase 2 | Complete |
| SDK-04 | Phase 1 | Complete |
| SDK-05 | Phase 1 | Complete |
| SDK-06 | Phase 1 | Complete |
| SDK-07 | Phase 1 | Complete |
| SDK-08 | Phase 1 | Complete |
| SCAN-01 | Phase 2 | Complete |
| SCAN-02 | Phase 2 | Complete |
| SCAN-03 | Phase 2 | Complete |
| SCAN-04 | Phase 2 | Complete |
| SCAN-05 | Phase 2 | Complete |
| SCAN-06 | Phase 2 | Complete |
| SCAN-07 | Phase 2 | Complete |
| VAULT-01 | Phase 3 | Complete |
| VAULT-02 | Phase 3 | Complete |
| VAULT-03 | Phase 3 | Complete |
| SRV-01 | Phase 1 | Complete |
| SRV-02 | Phase 1 | Complete |
| SRV-03 | Phase 1 | Complete |
| SRV-04 | Phase 1 | Complete |
| PKG-01 | Phase 1 | Complete |
| PKG-02 | Phase 1 | Complete |
| DOC-01 | Phase 4 | Complete |
| DOC-02 | Phase 4 | Complete |
| DOC-03 | Phase 4 | Complete |
| DOC-04 | Phase 4 | Complete |
| DOC-05 | Phase 4 | Complete |

**Coverage:**
- v1 requirements: 29 total
- Mapped to phases: 29
- Unmapped: 0

---
*Requirements defined: 2026-02-26*
*Last updated: 2026-02-26 after roadmap creation*
