kvlr 1.0.0

Zero-Trust Middleware for Agentic Coding

🛡️ AgentArmor

Zero-Trust Security Middleware for AI-Generated Code

The layer between your AI coding tool and your production codebase.

📦 Install · 🚀 Quickstart · 📖 Docs · 🏛️ Examples · 🤝 Contribute

---

⚠️ The Problem Nobody Is Talking About

In 2026, developers ship millions of lines of AI-generated code every day. Cursor, Claude Code, GitHub Copilot, Windsurf — these tools are phenomenally productive.

But they have a dirty secret:

# ✅ This is what your AI agent confidently wrote for you
def get_user_profile(user_id):
    api_key = "sk-live_a8f3c2b1d4e5f6a7b8c9"     # 🔴 SECRET IN SOURCE CODE
    query = f"SELECT * FROM users WHERE id={user_id}" # 🔴 SQL INJECTION
    user_code = request.args.get("transform")
    result = eval(user_code)                          # 🔴 REMOTE CODE EXECUTION
    img_url = request.json.get("avatar")
    img = requests.get(img_url).content              # 🔴 SERVER-SIDE REQUEST FORGERY
    pw_hash = hashlib.md5(password.encode()).hexdigest() # 🔴 BROKEN CRYPTOGRAPHY
    return db.execute(query).fetchone()

This is not hypothetical. Every one of these patterns has been documented in production AI-generated code in 2025–2026. The code looks correct. It passes basic review. It ships.

AgentArmor catches all 5 vulnerabilities above — in under 10 milliseconds.

---

📊 By The Numbers

Stat	Value
🎯 Threat categories detected	19
📋 OWASP Top 10 categories covered	9 / 10
🧪 Tests passing	195 / 195
⚡ Avg. scan time	< 10ms
📦 Python versions supported	3.9 → 3.13
🏛️ Vulnerability museum cases	10
🔧 Zero external API calls	✅ 100% local

---

🚀 30-Second Quickstart

pip install kvlr

from agent_armor import AgentArmor

armor = AgentArmor()

# Paste any AI-generated code here
ai_code = '''
import hashlib, requests
api_key = "sk-live_a8f3c2b1d4e5"
query = f"SELECT * FROM users WHERE id={user_id}"
requests.get(user_supplied_url)
hashlib.md5(password).hexdigest()
'''

report = armor.process(ai_code, filename="generated.py")
print(f"Status:  {report.status}")           # → BLOCKED
print(f"Threats: {len(report.ast_findings)} found")  # → 3 found

🛡️  [AgentArmor] Intercepting AI-generated code...
🔍  [Stage 1] Secret detected: sk-live_a8f3c2b1d4e5 → replaced with os.getenv()
🌲  [Stage 2] CRITICAL: SQL injection via f-string at line 3
🌲  [Stage 2] HIGH:     SSRF — non-literal URL at line 4
🌲  [Stage 2] HIGH:     InsecureCryptography — hashlib.md5() at line 5
📋  [Stage 5] 2 policy violations

🛑  Status: BLOCKED  |  3 AST findings  |  1 secret scrubbed  |  2 policy violations

Or via the CLI:

kvlr scan my_ai_generated_file.py
kvlr scan my_ai_generated_file.py --report --output report.json
kvlr check-deps requirements.txt   # slopsquatting / dependency confusion

---

🤔 Why AgentArmor? Why Now?

The Old World	The AI-Agent World
Humans write code, humans review it	AI writes entire features unattended
Vulnerabilities are rare mistakes	Vulnerabilities are statistically guaranteed
SAST tools scan your code	AI code has no ownership, no blame, no accountability
Secrets accidentally committed	Secrets confidently hardcoded by agents with no env context
One dev, one file at a time	One prompt, 500 lines of code, shipped in 30 seconds

Traditional SAST tools were not built for this. They assume a human wrote the code and will read the warning. AgentArmor is built as middleware — it sits in the pipeline before the code ever reaches a human or a git commit.

Works with every AI coding tool

Tool	How to integrate
Cursor / Windsurf	Run armor scan in a pre-commit hook
Claude Code	Wrap your agent's output through AgentArmor().process()
GitHub Copilot	CI/CD gate via the GitHub Actions workflow (included)
LangChain / CrewAI agents	Use as middleware in your agent pipeline
MCP servers	Drop-in armor mcp-proxy --port 8080
Any LLM	Python API — 3 lines of code

---

🔒 What AgentArmor Catches

Severity: 🚨 CRITICAL

These will get you breached. AgentArmor blocks code with these patterns:

Pattern	Example	Why It's Dangerous
SQL Injection	f"SELECT * WHERE id={uid}"	Full database dump / destruction
Code Execution	eval(user_input)	Remote code execution on your server
Unsanitized data → dangerous sink	input() → subprocess.run()	RCE via crafted user input

Severity: 🔴 HIGH

These will get you breached eventually. AgentArmor warns with remediation:

Pattern	Example	OWASP
SSRF	requests.get(user_url)	A10
Command Injection	os.system(f"ping {host}")	A03
Insecure Crypto	hashlib.md5(password)	A02
Secrets in code	api_key = "sk-live_..."	A02
YAML RCE	yaml.load(data) no Loader	A08
Pickle RCE	pickle.loads(data)	A08
JWT Algorithm None	jwt.decode(tok, algs=[])	A02
BOLA/IDOR	WHERE id=? no user scope	A01
Admin route no auth	@app.route("/admin") bare	A07
Dependency confusion	pip install internal-tool	A08

Severity: 🟡 MEDIUM / 🔵 LOW

Best-practice enforcement: missing error handling, bare except:, assert for security checks, hardcoded debug flags, private IPs in config.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Your AI Coding Tool                        │
│         (Cursor · Claude Code · Copilot · LangChain)            │
└─────────────────────────────┬───────────────────────────────────┘
                              │  AI-generated code (raw)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ⚡ AgentArmor Pipeline                        │
│                                                                 │
│  Stage 1  ┌─────────────────────────────────────────────────┐  │
│           │  🔑 Secret Scrubber                              │  │
│           │  Regex + Shannon entropy — 13 secret types       │  │
│           │  Replaces with os.getenv() calls automatically   │  │
│           └──────────────────────────┬──────────────────────┘  │
│  Stage 2                             ▼                          │
│           ┌─────────────────────────────────────────────────┐  │
│           │  🌲 AST Hardening Engine                         │  │
│           │  True structural analysis — not just grep        │  │
│           │  Detects 12 threat patterns at the syntax tree   │  │
│           └──────────────────────────┬──────────────────────┘  │
│  Stage 3                             ▼                          │
│           ┌─────────────────────────────────────────────────┐  │
│           │  📊 DTG Engine (Data Transformation Graph)       │  │
│           │  Traces tainted data: sources → sanitisers → sinks │ │
│           │  Auto-injects Pydantic validation schemas        │  │
│           └──────────────────────────┬──────────────────────┘  │
│  Stage 4                             ▼                          │
│           ┌─────────────────────────────────────────────────┐  │
│           │  📦 Slopsquatting Guard                          │  │
│           │  Real-time PyPI/npm registry validation          │  │
│           │  Typosquatting detection via edit distance       │  │
│           └──────────────────────────┬──────────────────────┘  │
│  Stage 5                             ▼                          │
│           ┌─────────────────────────────────────────────────┐  │
│           │  📋 Semantic Policy Engine (10 built-in rules)   │  │
│           │  BOLA · debug=True · no-auth admin · JWT alg     │  │
│           └──────────────────────────┬──────────────────────┘  │
│  Stage 6                             ▼                          │
│           ┌─────────────────────────────────────────────────┐  │
│           │  🔗 Shadow-Chain Attestation                     │  │
│           │  SHA-256 signs security invariants in code       │  │
│           │  Detects if a human/AI later removes auth checks │  │
│           └──────────────────────────┬──────────────────────┘  │
└─────────────────────────────┬────────┴─────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
         ✅ APPROVED     ⚠️  WARNED       🛑 BLOCKED
      (attested + signed) (report only)  (pipeline halted)

---

✨ Feature Overview

🔑 Secret Scrubber 13+ secret types (AWS, OpenAI, GitHub, Stripe…) Shannon entropy analysis for unknown secrets Auto-replaces with os.getenv() — non-breaking 🌲 AST Hardening Engine Structural analysis (not grep) via Python ast 12 threat patterns: eval, SQL injection, SSRF, ReDoS, insecure crypto, YAML RCE, command injection, pickle, and more Works on syntactically correct and broken code 📊 DTG Engine Traces tainted data: input() → sanitiser? → db.execute() Auto-injects Pydantic validation schemas on flagged flows

🔗 Shadow-Chain Attestation (novel) SHA-256 signs security invariants as embedded comments Breaking the if user.is_admin: guard → chain invalidated CI/CD integration blocks tampered code from deploying 📦 Slopsquatting Guard Real-time PyPI/npm validation Flags packages < 1,000 downloads or < 7 days old Typosquatting via Levenshtein edit distance 🚦 MCP Security Proxy Intercepts Model Context Protocol tool calls Prevents path traversal, domain isolation violations Rate limiting per agent identity 📋 Semantic Policy Engine 10 built-in rules (BOLA, JWT, debug mode, admin auth…) Fully extensible — subclass Rule to add your own

📋 Policy Engine Rules

Rule	ID	Severity	Detects
Sensitive Path Write	RULE-001	CRITICAL	open('/etc/passwd', 'w')
Delete Without User ID	RULE-002	CRITICAL	DELETE ops without ownership scope
Domain Isolation	RULE-003	HIGH	Frontend code reading backend env vars
Admin Endpoint Auth	RULE-004	HIGH	/admin routes missing auth decorator
JWT Algorithm Required	RULE-005	HIGH	jwt.decode() without algorithms=
Insecure Cryptography	RULE-007	HIGH	hashlib.md5/sha1, PyCryptodome DES/ARC4
SSRF	RULE-008	HIGH	HTTP calls with dynamic (user-controlled) URLs
Broken Object-Level Auth	RULE-009	HIGH	WHERE id = ? without ownership column
Insecure Design	RULE-010	CRITICAL	debug=True, hardcoded secrets, private IPs

---

📦 Installation

# Option 1: PyPI (recommended)
pip install kvlr

# Option 2: Latest from source
git clone https://github.com/TanmayD03/Agent-Armor.git
cd kvlr
pip install -e .

Verify:

armor --version
# AgentArmor 1.0.0

---

🔧 Usage

CLI

# Scan a Python file for vulnerabilities
kvlr scan suspicious_code.py

# Scan with detailed JSON report
kvlr scan suspicious_code.py --report --output report.json

# Verify attestation integrity (CI/CD use)
armor verify suspicious_code.py --hash a3f9b2c1...

# Validate dependencies against PyPI/npm
kvlr check-deps requirements.txt

# Run the Vulnerability Museum demo
armor museum

# Start the MCP Security Proxy server
armor mcp-proxy --port 8080

# Show shadow-chain history for a file
armor history suspicious_code.py

Python API

from agent_armor import AgentArmor
from agent_armor.core.ast_hardener import ASTHardener
from agent_armor.core.policy_engine import PolicyEngine

# ── Full pipeline ────────────────────────────────────────────
armor = AgentArmor()

ai_code = '''
import hashlib, requests, yaml
from flask import Flask, request, jsonify

app = Flask(__name__)
app.secret_key = "hardcoded-secret"       # RULE-010

@app.route("/profile/<int:uid>")
def get_profile(uid):
    cfg = yaml.load(request.json["cfg"])   # yaml RCE
    url = request.json["avatar"]
    img = requests.get(url).content        # SSRF
    pw  = hashlib.md5(b"pass").hexdigest() # weak hash
    row = db.execute(
        "SELECT * FROM users WHERE id = ?",
        (uid,)                             # BOLA
    ).fetchone()
    return jsonify(dict(row))

if __name__ == "__main__":
    app.run(debug=True)                    # RULE-010
'''

report = armor.process(ai_code, filename="profile.py")
print(f"Status:   {report.status}")           # BLOCKED
print(f"AST:      {len(report.ast_findings)} findings")
print(f"Policy:   {len(report.policy_violations)} violations")
print(f"Secrets:  {len(report.secret_findings)} secrets scrubbed")

# ── Individual engines ───────────────────────────────────────
# AST Hardener — structural analysis
h = ASTHardener()
for f in h.analyze("import hashlib\nh = hashlib.md5(data)\n"):
    print(f"  [{f.severity}] {f.node_type}: {f.description}")
# → [HIGH] InsecureCryptography: hashlib.md5() uses a broken algorithm...

# Policy Engine — semantic rules
p = PolicyEngine()
for v in p.evaluate('app.run(debug=True)\n', "app.py"):
    print(f"  [{v.severity}] {v.rule_id}: {v.description}")
# → [CRITICAL] RULE-010-INSECURE-DESIGN: debug=True enables the interactive debugger...

Expected Output

🛡️  [AgentArmor] Intercepting AI-generated code...
🔍 [Stage 1/5] Scanning for hardcoded secrets...
   ⚠️  Found 1 secret(s). Replacing with env var references.
🌲 [Stage 2/5] Running AST security analysis...
   🚨 CRITICAL [line 6]: SQL injection via f-string in .execute()
   🚨 CRITICAL [line 8]: Dangerous sink → eval()
📊 [Stage 3/5] Analyzing data transformation graph...
   ⚠️  Unsanitized flow: request.args → eval() [CRITICAL]
📦 [Stage 4/5] Validating package dependencies...
📋 [Stage 5/5] Enforcing security policies...
🛑 [AgentArmor] Code BLOCKED by Zero-Trust policy.

Status: BLOCKED
Critical issues: 3
Attestation: BLOCKED

---

🔍 Detection Coverage

AgentArmor covers all OWASP Top 10 2021 categories relevant to AI-generated code:

Detection	Engine	Severity	OWASP Category
SQL Injection (f-string / % in .execute())	AST	CRITICAL	A03 Injection
eval() / exec() / __import__()	AST	CRITICAL	A03 Injection
os.system() / subprocess shell=True	AST	HIGH	A03 Injection
pickle.loads() / marshal.loads()	AST	HIGH	A08 Software Integrity
yaml.load() without Loader=	AST	HIGH	A08 Software Integrity
hashlib.md5 / sha1 / new("md5")	AST + Policy	HIGH	A02 Crypto Failures
requests.get(user_url) — SSRF	AST + Policy	HIGH	A10 SSRF
re.compile(r"(a+)+") — ReDoS	AST	HIGH	A06 Vulnerable Components
Hardcoded secrets / API keys / tokens	Secret Scrubber	HIGH	A02 Crypto Failures
assert for security checks	AST	MEDIUM	A07 Auth Failures
Missing try/except on I/O	AST	MEDIUM	A09 Logging Failures
Sensitive path writes (/etc, ~/.ssh)	Policy RULE-001	HIGH	A01 Broken Access
Delete without user_id scope	Policy RULE-002	HIGH	A01 Broken Access
Admin routes missing auth	Policy RULE-004	HIGH	A07 Auth Failures
jwt.decode() without algorithms=	Policy RULE-005	HIGH	A02 Crypto Failures
WHERE id=? without ownership column (BOLA/IDOR)	Policy RULE-009	HIGH	A01 Broken Access
debug=True / hardcoded secret_key / private IP	Policy RULE-010	CRITICAL	A05 Misconfig
Typosquatting / sloppy package names	Slopsquatting	HIGH	A08 Software Integrity
Unsanitized input → dangerous sink (DTG)	DTG Engine	CRITICAL	A03 Injection

---

⚡ Interactive Examples

python examples/quickstart.py                    # all 10 categories
python examples/quickstart.py --section crypto   # insecure cryptography
python examples/quickstart.py --section ssrf     # SSRF detection
python examples/quickstart.py --section redos    # catastrophic ReDoS
python examples/quickstart.py --section pipeline # kitchen-sink demo

Each section shows: vulnerable code → live detection output → hardened fix.

---

🏛️ Vulnerability Museum

The vulnerability_museum/ folder contains real examples of AI-generated vulnerable code and how AgentArmor fixes each one:

#	Vulnerability	OWASP 2021	CVSS	AgentArmor Fix
01	SQL Injection	A03 Injection	9.8	Parameterised queries auto-injected
02	eval() Code Injection	A03 Injection	10.0	Code blocked + refactor guide
03	Secret Key Exposure	A02 Crypto Failures	9.1	Env var replacement
04	OS Command Injection	A03 Injection	9.8	subprocess list-form hardening
05	Dependency Confusion	A08 Software Integrity	8.1	Slopsquatting guard blocks install
06	Missing Auth on Admin Route	A07 Auth Failures	9.1	Auth decorator enforcement
07	JWT Algorithm None	A02 Crypto Failures	8.8	algorithms= parameter required
08	Delete Without User ID	A01 Broken Access	8.1	Ownership scope enforced
09	Insecure Cryptography	A02 Crypto Failures	7.5	scrypt / SHA-256 replacement
10	SSRF	A10 SSRF	8.6	Allowlist URL validation

# Run the museum demo
armor museum

---

🔬 Research Foundation

AgentArmor is grounded in published 2025–2026 security research — not just intuition:

Concept	Source	AgentArmor Implementation
Semantic Over-Confidence Mitigation	LLM Security Survey, 2025	AST-level missing error handling detection
Formal Invariant Verification	Mitsubishi Rapid Formal Verification, 2025	RULE-002: delete ops require user_id guard
Data Transformation Graph (DTG) Analysis	DTG Security, 2026	Tainted data source→sanitiser→sink tracing
Shadow-Chain Attestation	Novel — AgentArmor (2026)	SHA-256 invariant signing on every scan
Slopsquatting / AI Dependency Confusion	AI Supply Chain Research, 2025	Real-time registry + entropy validation
BOLA/IDOR in AI code	OWASP API Security 2023	RULE-009: ownership column enforcement

---

🎖️ The "Secure-by-Agent" Badge

Add this to your README to show your codebase is AgentArmor-protected:

[![AgentArmor Protected](https://img.shields.io/badge/AgentArmor-Attested%20%26%20Secure-brightgreen)](https://github.com/yourusername/kvlr)

---

👤 Author

Tanmay Dikey

• 📧 [e-mail]
• 🐙 github.com/tanmaydikey
• 💼 github.com/TanmayD03/Agent-Armor

---

🎖️ Add the Badge to Your Project

Show the world your codebase is AgentArmor-protected:

[![AgentArmor Protected](https://img.shields.io/badge/AgentArmor-Attested%20%26%20Secure-brightgreen)](https://github.com/TanmayD03/Agent-Armor)

---

🤝 Contributing

Contributions are welcome! The most impactful things you can add:

• 🆕 New detection rules — found a pattern that AI generates dangerously? Open a PR
• 🏛️ Vulnerability museum cases — real AI-generated vulnerable code examples
• 🌍 Language support — AgentArmor currently covers Python; JS/TS is next
• 📖 Documentation — examples, blog posts, case studies

See CONTRIBUTING.md for the full guide, including how to add a new detection rule in under 30 lines of code.

---

👤 Author

Tanmay Dikey — Security researcher & the mind behind AgentArmor

---

📄 License

MIT License — Copyright (c) 2026 Tanmay Dikey — see LICENSE for details.

---

If AgentArmor has saved you from a vulnerability, please ⭐ star the repo.

It's the best way to help other developers find this tool before their AI agent ships something dangerous.

---

"The question is no longer whether AI will write your code. The question is whether anyone is checking its work."

— Tanmay Dikey, 2026