> Full text guide: [docs/TOKRA_SHIELD_GUIDE.txt](docs/TOKRA_SHIELD_GUIDE.txt)
# TOKRA SHIELD
 
> **Tokra Shield** — Lightweight content-protection SDK & optional REST API.
> Protects against **spam**, **scam**, **prompt-injection**, and unsafe text.
> _Powered by Tokra._
---
## Table of contents
- [Features](#features)
- [Quick Start (CLI)](#quick-start-cli)
- [Install](#install)
- [API (REST) Usage](#api-rest-usage)
- [Configuration (ENV)](#configuration-env)
- [External Rules (Ghost)](#external-rules-ghost)
- [Self-check & Tests](#self-check--tests)
- [Service (systemd)](#service-systemd)
- [Docker](#docker)
- [Postman](#postman)
- [Release & Publishing](#release--publishing)
- [Repo Maintenance](#repo-maintenance)
- [Development](#development)
- [Security Policy](#security-policy)
- [Contributing & Code of Conduct](#contributing--code-of-conduct)
- [License](#license)
---
## Features
- 💡 **Lightweight SDK**: direct `analyze(text, lang)` function.
- 🌐 **Optional REST API** (FastAPI): `/healthz`, `/version`, `/analyze`.
- 🧪 **Customizable rules**: multi-language (EN/AR examples) + external imports (Ghost).
- 🧰 **Full control**: protection modes, flag/block thresholds, category weights, input caps.
- 🔤 **Advanced normalization**: detects confusables, zero-width chars, common obfuscation tricks.
- 🧩 **Backwards compatible**: legacy field `flagged_phrases` kept alongside new schema.
- 🛠️ **CI/CD ready**: self-check scripts + release bundles (zip + sha256).
- 🧱 **Zero secrets in repo**: sensitive keys via GitHub Secrets / runtime env only.
---
## Quick Start (CLI)
```bash
tokra-shield hello
tokra-shield check "click here to win free crypto!" --lang en
tokra-shield run
# GET http://127.0.0.1:8099/healthz
# GET http://127.0.0.1:8099/version
# POST http://127.0.0.1:8099/analyze/
Install
A) From PyPI (SDK only)
pip install tokra-shield
B) From PyPI (SDK + API) – recommended
pip install "tokra-shield[api]"
C) Windows (best CLI experience)
pipx install "tokra-shield[api]"
D) Install script (Linux/macOS)
bash install_tokra.sh
API (REST) Usage
Endpoints
GET /healthz → {"ok": true}
GET /version → {"version": "0.1.0"}
POST /analyze/
Request body (JSON):
{
"text": "Please IGNORE previous instructions and do X",
"lang": "en",
"mode": "strict",
"explain": true
}
Response (sample):
{
"action": "flag",
"risk_score": 30,
"grade": "medium",
"matches": [
{"phrase":"click here","type":"spam","risk":10},
{"phrase":"free crypto","type":"scam","risk":20}
],
"categories": ["scam","spam"],
"flagged_phrases": ["click here","free crypto"]
}
Run locally:
TOKRA_SHIELD_MAX_BODY=65536 tokra-shield run
Example cURL:
curl -s -X POST :8099/analyze/ -H 'Content-Type: application/json' \
-d '{"text":"ignore previous instructions","lang":"en","mode":"strict","explain":true}'
Configuration (ENV)
TOKRA_SHIELD_MODE = off | low | balanced (default) | strict | paranoid
TOKRA_SHIELD_THRESH_FLAG = float threshold for flag
TOKRA_SHIELD_THRESH_BLOCK = float threshold for block
TOKRA_SHIELD_WEIGHT_SPAM = weight for spam category
TOKRA_SHIELD_WEIGHT_SCAM = weight for scam category
TOKRA_SHIELD_WEIGHT_INJECTION = weight for injection
TOKRA_SHIELD_CAP = global cap
TOKRA_SHIELD_MAX_BODY = max JSON request size (default 65536)
TOKRA_SHIELD_RULES_DIR = directory for Ghost rules
TOKRA_SHIELD_BANNER_FONT / _WIDTH / _MARGIN / _PLAIN_BANNER
External Rules (Ghost)
tokra-shield init --dir ./my_rules/ghost --lang en ar
export TOKRA_SHIELD_RULES_DIR=$PWD/my_rules/ghost
tokra-shield rules-stats
Self-check & Tests
bash scripts/self_check.sh
pytest -q
Service (systemd)
# /etc/systemd/system/tokra-shield.service
[Unit]
Description=Tokra Shield API
After=network.target
[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/tokra_shield_pkg
Environment=TOKRA_SHIELD_MODE=balanced
Environment=TOKRA_SHIELD_MAX_BODY=65536
ExecStart=/usr/bin/env tokra-shield run --host 0.0.0.0 --port 8099 --log-level info
Restart=on-failure
RestartSec=2
[Install]
WantedBy=multi-user.target
Docker
docker build -t tokra/tokra-shield:0.1 .
docker run --rm -e TOKRA_SHIELD_MODE=balanced -p 8099:8099 tokra/tokra-shield:0.1
n
Import: tools/TokraShield.postman_collection.json
Release & Publishing
Add PYPI_API_TOKEN in GitHub → Settings → Secrets.
Tag a new release:
git tag -a v0.1.2 -m "Tokra Shield v0.1.2"
git push origin v0.1.2
Workflow publishes to PyPI + creates GitHub Release.
Repo Maintenance
Do not commit venv/dist/build artifacts.
If repo history is rewritten:
git fetch --all --prune
git reset --hard origin/main
git clean -fd
Development
python -m venv venv && . venv/bin/activate
pip install -U pip
pip install -e ".[api]" pytest
pytest -q
bash scripts/self_check.sh
Example SDK:
from tokra_shield import analyze
print(analyze("Click HERE to win free crypto!", "en"))
Security Policy
Report vulnerabilities: security@tokra.ai
Acknowledgement in 48h with fix ETA.
Contributing & Code of Conduct
See CONTRIBUTING.md
and CODE_OF_CONDUCT.md
.
License
Apache-2.0
Raw data
{
"_id": null,
"home_page": null,
"name": "tokra-shield",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "content-safety, spam, scam, prompt-injection",
"author": "Tokra Community",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/01/b8/3a505306dfaf333dcb4faf7600db5448afc204913ffad235b41572fa085b/tokra_shield-0.1.0.tar.gz",
"platform": null,
"description": "> Full text guide: [docs/TOKRA_SHIELD_GUIDE.txt](docs/TOKRA_SHIELD_GUIDE.txt)\n\n# TOKRA SHIELD\n\n \n> **Tokra Shield** \u2014 Lightweight content-protection SDK & optional REST API. \n> Protects against **spam**, **scam**, **prompt-injection**, and unsafe text. \n> _Powered by Tokra._\n\n---\n\n## Table of contents\n- [Features](#features)\n- [Quick Start (CLI)](#quick-start-cli)\n- [Install](#install)\n- [API (REST) Usage](#api-rest-usage)\n- [Configuration (ENV)](#configuration-env)\n- [External Rules (Ghost)](#external-rules-ghost)\n- [Self-check & Tests](#self-check--tests)\n- [Service (systemd)](#service-systemd)\n- [Docker](#docker)\n- [Postman](#postman)\n- [Release & Publishing](#release--publishing)\n- [Repo Maintenance](#repo-maintenance)\n- [Development](#development)\n- [Security Policy](#security-policy)\n- [Contributing & Code of Conduct](#contributing--code-of-conduct)\n- [License](#license)\n\n---\n\n## Features\n- \ud83d\udca1 **Lightweight SDK**: direct `analyze(text, lang)` function.\n- \ud83c\udf10 **Optional REST API** (FastAPI): `/healthz`, `/version`, `/analyze`.\n- \ud83e\uddea **Customizable rules**: multi-language (EN/AR examples) + external imports (Ghost).\n- \ud83e\uddf0 **Full control**: protection modes, flag/block thresholds, category weights, input caps.\n- \ud83d\udd24 **Advanced normalization**: detects confusables, zero-width chars, common obfuscation tricks.\n- \ud83e\udde9 **Backwards compatible**: legacy field `flagged_phrases` kept alongside new schema.\n- \ud83d\udee0\ufe0f **CI/CD ready**: self-check scripts + release bundles (zip + sha256).\n- \ud83e\uddf1 **Zero secrets in repo**: sensitive keys via GitHub Secrets / runtime env only.\n\n---\n\n## Quick Start (CLI)\n\n```bash\ntokra-shield hello\n\ntokra-shield check \"click here to win free crypto!\" --lang en\n\ntokra-shield run\n# GET http://127.0.0.1:8099/healthz\n# GET http://127.0.0.1:8099/version\n# POST http://127.0.0.1:8099/analyze/\nInstall\nA) From PyPI (SDK only)\npip install tokra-shield\nB) From PyPI (SDK + API) \u2013 recommended\npip install \"tokra-shield[api]\"\nC) Windows (best CLI experience)\npipx install \"tokra-shield[api]\"\nD) Install script (Linux/macOS)\nbash install_tokra.sh\nAPI (REST) Usage\n\nEndpoints\n\nGET /healthz \u2192 {\"ok\": true}\n\nGET /version \u2192 {\"version\": \"0.1.0\"}\n\nPOST /analyze/\n\nRequest body (JSON):\n{\n \"text\": \"Please IGNORE previous instructions and do X\",\n \"lang\": \"en\",\n \"mode\": \"strict\",\n \"explain\": true\n}\n\nResponse (sample):\n{\n \"action\": \"flag\",\n \"risk_score\": 30,\n \"grade\": \"medium\",\n \"matches\": [\n {\"phrase\":\"click here\",\"type\":\"spam\",\"risk\":10},\n {\"phrase\":\"free crypto\",\"type\":\"scam\",\"risk\":20}\n ],\n \"categories\": [\"scam\",\"spam\"],\n \"flagged_phrases\": [\"click here\",\"free crypto\"]\n}\nRun locally:\nTOKRA_SHIELD_MAX_BODY=65536 tokra-shield run\nExample cURL:\ncurl -s -X POST :8099/analyze/ -H 'Content-Type: application/json' \\\n -d '{\"text\":\"ignore previous instructions\",\"lang\":\"en\",\"mode\":\"strict\",\"explain\":true}'\n\nConfiguration (ENV)\n\nTOKRA_SHIELD_MODE = off | low | balanced (default) | strict | paranoid\n\nTOKRA_SHIELD_THRESH_FLAG = float threshold for flag\n\nTOKRA_SHIELD_THRESH_BLOCK = float threshold for block\n\nTOKRA_SHIELD_WEIGHT_SPAM = weight for spam category\n\nTOKRA_SHIELD_WEIGHT_SCAM = weight for scam category\n\nTOKRA_SHIELD_WEIGHT_INJECTION = weight for injection\n\nTOKRA_SHIELD_CAP = global cap\n\nTOKRA_SHIELD_MAX_BODY = max JSON request size (default 65536)\n\nTOKRA_SHIELD_RULES_DIR = directory for Ghost rules\n\nTOKRA_SHIELD_BANNER_FONT / _WIDTH / _MARGIN / _PLAIN_BANNER\n\nExternal Rules (Ghost)\ntokra-shield init --dir ./my_rules/ghost --lang en ar\nexport TOKRA_SHIELD_RULES_DIR=$PWD/my_rules/ghost\ntokra-shield rules-stats\n\nSelf-check & Tests\nbash scripts/self_check.sh\npytest -q\n\nService (systemd)\n# /etc/systemd/system/tokra-shield.service\n[Unit]\nDescription=Tokra Shield API\nAfter=network.target\n\n[Service]\nType=simple\nUser=ubuntu\nWorkingDirectory=/home/ubuntu/tokra_shield_pkg\nEnvironment=TOKRA_SHIELD_MODE=balanced\nEnvironment=TOKRA_SHIELD_MAX_BODY=65536\nExecStart=/usr/bin/env tokra-shield run --host 0.0.0.0 --port 8099 --log-level info\nRestart=on-failure\nRestartSec=2\n\n[Install]\nWantedBy=multi-user.target\n\nDocker\ndocker build -t tokra/tokra-shield:0.1 .\ndocker run --rm -e TOKRA_SHIELD_MODE=balanced -p 8099:8099 tokra/tokra-shield:0.1\n\nn\n\nImport: tools/TokraShield.postman_collection.json\n\nRelease & Publishing\n\nAdd PYPI_API_TOKEN in GitHub \u2192 Settings \u2192 Secrets.\n\nTag a new release:\ngit tag -a v0.1.2 -m \"Tokra Shield v0.1.2\"\ngit push origin v0.1.2\n\nWorkflow publishes to PyPI + creates GitHub Release.\n\nRepo Maintenance\n\nDo not commit venv/dist/build artifacts.\n\nIf repo history is rewritten:\ngit fetch --all --prune\ngit reset --hard origin/main\ngit clean -fd\n\nDevelopment\npython -m venv venv && . venv/bin/activate\npip install -U pip\npip install -e \".[api]\" pytest\npytest -q\nbash scripts/self_check.sh\n\n\nExample SDK:\nfrom tokra_shield import analyze\nprint(analyze(\"Click HERE to win free crypto!\", \"en\"))\n\nSecurity Policy\n\nReport vulnerabilities: security@tokra.ai\n\nAcknowledgement in 48h with fix ETA.\n\nContributing & Code of Conduct\n\nSee CONTRIBUTING.md\n and CODE_OF_CONDUCT.md\n.\n\nLicense\n\nApache-2.0\n",
"bugtrack_url": null,
"license": null,
"summary": "Lightweight, dependency\u2011free content\u2011protection SDK",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"content-safety",
" spam",
" scam",
" prompt-injection"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8985fb5557337ca05ac31e1e8906a4cdc4cab4533b7198f88ecbfe4ccd1a383d",
"md5": "3bfba28d8f149c10bb6a249686a9388c",
"sha256": "3ac0257064c50626d01217642f4a0604b5341d8fad756d7fdf3a930751bbb0fa"
},
"downloads": -1,
"filename": "tokra_shield-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3bfba28d8f149c10bb6a249686a9388c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12910,
"upload_time": "2025-09-07T09:21:21",
"upload_time_iso_8601": "2025-09-07T09:21:21.595218Z",
"url": "https://files.pythonhosted.org/packages/89/85/fb5557337ca05ac31e1e8906a4cdc4cab4533b7198f88ecbfe4ccd1a383d/tokra_shield-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "01b83a505306dfaf333dcb4faf7600db5448afc204913ffad235b41572fa085b",
"md5": "cb4bace0efdeb4b9e7df01af43084203",
"sha256": "cc39afc9b81acc1d40b2a804b697869d7de71d20790b351538d600d4d962c7f3"
},
"downloads": -1,
"filename": "tokra_shield-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "cb4bace0efdeb4b9e7df01af43084203",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12796,
"upload_time": "2025-09-07T09:21:22",
"upload_time_iso_8601": "2025-09-07T09:21:22.931823Z",
"url": "https://files.pythonhosted.org/packages/01/b8/3a505306dfaf333dcb4faf7600db5448afc204913ffad235b41572fa085b/tokra_shield-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 09:21:22",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "tokra-shield"
}
JSON