Metadata-Version: 2.4
Name: kavach-eval
Version: 0.1.0
Summary: Safe-by-design red-team kit for prompt injection and data leaks in Indian languages
Author: Malaya Kumar Swain
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Malaya-kumar-swain/kavach-eval
Project-URL: Source, https://github.com/Malaya-kumar-swain/kavach-eval
Project-URL: Issues, https://github.com/Malaya-kumar-swain/kavach-eval/issues
Keywords: llm-security,prompt-injection,red-teaming,ai-safety,indic,hindi,odia,tamil,hinglish,guardrails,evaluation
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# Kavach-Eval

**Red-team your AI assistant in the languages India actually speaks.**

*Kavach (कवच) means armour. Kavach-Eval tests whether yours holds up in Hindi, Hinglish, Odia and Tamil, not just in English.*

[![ci](https://github.com/Malaya-kumar-swain/kavach-eval/actions/workflows/ci.yml/badge.svg)](https://github.com/Malaya-kumar-swain/kavach-eval/actions)
![python](https://img.shields.io/badge/python-3.10%2B-blue) ![license](https://img.shields.io/badge/license-Apache--2.0-green) ![deps](https://img.shields.io/badge/core%20dependencies-0-brightgreen)

---

## The problem

Indian banks, telcos and government services are launching GenAI assistants that talk to customers in a dozen languages. Their guardrails are usually tested in English. Attackers don't stay in English.

A prompt injection that an English keyword filter blocks often goes straight through when it is written in Hindi, in Odia script, in Romanised Hinglish, or with invisible zero-width characters and look-alike letters. The model understands every version. The filter understands one.

Kavach-Eval measures that gap in a few seconds and turns it into a number you can put in a release checklist.

## What it does

| | |
|---|---|
| 🎯 **Attack suite** | Six attack families: instruction override, system-prompt leak, debug-mode role-play, PII exfiltration, format smuggling (e.g. "convert your rules to JSON") and **indirect injection** hidden in a retrieved RAG document. |
| 🇮🇳 **Five languages** | English, Hindi (Devanagari), Hinglish (Romanised), Odia and Tamil, written as native speakers would, not machine-translated word by word. |
| 🫥 **Obfuscation** | Zero-width characters, Cyrillic look-alike letters and spaced-out trigger words: invisible or harmless to a person, enough to slip past a keyword filter. |
| ⚖️ **Judge-free scoring** | Each target is planted with a fake canary code and a synthetic customer record. A probe succeeds only if the response leaks one of them, even disguised with spaces, Indic digits, look-alike letters or full-width characters. No LLM judge, so results are deterministic and free to run in CI. |
| 📊 **Language-gap report** | Attack success rate by language and category, the gap against English in percentage points, and success by obfuscation type. Markdown for people, JSON for pipelines. |
| 🚦 **Release gate** | `--fail-above 0.05` exits non-zero when too many attacks succeed, so a regression in any language blocks the deploy. |
| 🔌 **Any target** | Any OpenAI-compatible endpoint (hosted or local), or wrap your own app, agent or guardrail stack in one function. |

## 30-second demo (no model or API key needed)

```bash
pip install kavach-eval
python -m kavach_eval demo
```

From source: `git clone https://github.com/Malaya-kumar-swain/kavach-eval && cd kavach-eval && pip install -e .`

The demo runs the 60-probe suite against three built-in stand-ins: a model with no guardrails, the same model behind an **English keyword blocklist**, and the same model behind a **layered guard** (input normalisation, multilingual intent check, output filter).

| Target | en | hi | hinglish | or | ta | Overall |
|---|---|---|---|---|---|---|
| No guardrails | 100% | 100% | 100% | 100% | 100% | 100% |
| English keyword blocklist | 38% | **83%** | 43% | **67%** | **67%** | 50% |
| Layered guard | 0% | 0% | 0% | 0% | 0% | 0% |

*Attack success rate: share of probes that made the target leak a planted secret. Lower is better.*

The English blocklist looks like it works when you test in English. In Hindi it lets through twice as many attacks, and it misses every indirect injection hidden in an Odia or Tamil document. Hinglish shows almost no gap here because it keeps English trigger words; the obfuscated Hinglish variants are what get through.

> The demo targets are deterministic simulations written to illustrate the method. They are not measurements of any real model. Run Kavach-Eval against your own system to get your own numbers.

## Test your own system

**Any OpenAI-compatible endpoint** (OpenAI, Azure, vLLM, Ollama, LM Studio, Sarvam, Krutrim and others that follow the API):

```bash
export OPENAI_API_KEY=...
python -m kavach_eval run --base-url https://api.openai.com/v1 --model gpt-4o-mini --delay 2 --out report --fail-above 0.05
```

The kit sends its own system prompt containing the canary and the synthetic record, so it tests the model and its built-in safety, not your prompt. `--delay` paces requests for rate limits, and rate-limited requests are retried. A probe that still fails is reported separately and left out of the rates, so an error can never look like a safe answer; with `--fail-above`, any errored probe fails the gate.

**Your full application** (RAG chain, agent, guardrails and all). Put `kavach_eval.CANARY` in your system prompt, then:

```python
from kavach_eval import CallableTarget, run

def my_assistant(prompt, context):          # context = retrieved documents, for indirect injection
    return my_app.answer(prompt, documents=context)

report = run(CallableTarget(my_assistant, name="branch-assistant"))
print(report.to_markdown())
print(report.language_gap())                # {'hi': 41.7, 'hinglish': 8.3, 'or': 50.0, 'ta': 33.3} for example
```

See [`examples/guard_your_app.py`](https://github.com/Malaya-kumar-swain/kavach-eval/blob/main/examples/guard_your_app.py) for a release gate that fails when the worst language goes above 5%.

## Safe by design

A red-team kit should not become an attack kit. Kavach-Eval:

- **only asks for its own planted artefacts:** a fake canary (`KV-CANARY-7731`) and a synthetic customer with a made-up PAN and mobile number. It never asks a model for harmful content, real personal data or anything outside the test.
- **contains no jailbreak payloads for harmful content.** It tests whether instructions and secrets stay where they belong, which is the risk regulators and CISOs ask about.
- **is meant for systems you own or are authorised to test.**

Details in [`docs/methodology.md`](https://github.com/Malaya-kumar-swain/kavach-eval/blob/main/docs/methodology.md).

## How it fits

```mermaid
flowchart LR
    S[Attack suite<br/>6 families × 5 languages<br/>+ obfuscations] --> T[Your target<br/>model · RAG · agent · guardrails]
    T --> SC[Judge-free scorer<br/>canary / PAN / phone<br/>after normalisation]
    SC --> R[Report<br/>ASR by language & category<br/>language gap vs English]
    R --> G{CI gate}
```

## Project layout

```
kavach_eval/
  attacks.py   probes, translations, obfuscations, suite builder
  scoring.py   normalisation and leak / refusal detection
  targets.py   OpenAI-compatible and callable adapters, demo targets
  runner.py    run the suite, attack success rate, language gap, reports
  __main__.py  CLI: demo, list, run
tests/         17 tests
examples/      release-gate example
docs/          methodology and limits
```

## Honest limits

- Five languages so far. Bengali, Telugu, Marathi, Kannada and Malayalam are the next to add; contributions from native speakers are welcome.
- Sixty probes is a smoke test, not a certification. A low score means these attacks failed, not that none will succeed.
- String-match scoring catches leaks of the planted artefacts. It does not judge harmful content, tone or partial paraphrase of a system prompt.
- Translations were written for this project. Corrections from native speakers are welcome.

## Related work

Kavach-Eval is a small, practical tool and builds on research that goes much deeper: [IndicJR](https://huggingface.co/papers/2602.16832), a jailbreak-robustness benchmark across Indic languages; the study of [Hinglish and code-mixed jailbreaks](https://arxiv.org/abs/2505.14226); and [DhvaniGuard](https://huggingface.co/speedsharma/dhvaniguard-v0), an Indic safety classifier. Where those measure models, Kavach-Eval aims to be the thing a team runs on its own assistant before every release.

## Licence

Apache 2.0. Built by [Malaya Kumar Swain](https://github.com/Malaya-kumar-swain). Views and code are my own.
