{"skill":{"slug":"agentshield-audit","displayName":"Agentshield Audit","summary":"Trust Infrastructure for AI Agents - Like SSL/TLS for agent-to-agent communication. 77 security tests, cryptographic certificates, and Trust Handshake Protoc...","description":"---\nname: agentshield\nversion: 1.0.31\ndescription: Trust Infrastructure for AI Agents - Like SSL/TLS for agent-to-agent communication. 77 security tests, cryptographic certificates, and Trust Handshake Protocol for establishing secure channels between agents. Explicit whitelist sanitization + dry-run mode for transparency.\ntriggers: [\"audit my agent\", \"get security certificate\", \"verify agent\", \"activate AgentShield\", \"security audit\", \"trust handshake\", \"verify peer agent\"]\n---\n\n# AgentShield - Trust Infrastructure for AI Agents\n\n**The trust layer for the agent economy. Like SSL/TLS, but for AI agents.**\n\n🔐 **Cryptographic Identity** - Ed25519 signing keys  \n🤝 **Trust Handshake Protocol** - Mutual verification before communication  \n📋 **Public Trust Registry** - Reputation scores & track records  \n✅ **77 Security Tests** - Comprehensive vulnerability assessment\n\n**🔒 Privacy Disclosure:** See [PRIVACY.md](PRIVACY.md) for detailed data handling information.\n\n---\n\n## 🌐 Framework Compatibility\n\nAgentShield works with **any AI agent framework** — no adapter required.\n\n| Framework | Status | Notes |\n|-----------|--------|-------|\n| **OpenClaw** | ✅ Full support | Auto-detects IDENTITY.md |\n| **Hermes Agent** | ✅ Full support | Auto-detects `~/.hermes/` — see [HERMES.md](HERMES.md) |\n| **n8n** | ✅ Auto-detected | Detects `~/.n8n/` |\n| **LangChain** | ✅ Manual | `--name MyAgent --platform langchain` |\n| **CLI / Custom** | ✅ Manual | `--name MyAgent --platform cli` |\n\nBoth OpenClaw and Hermes use the [agentskills.io](https://agentskills.io) open standard — skills install and run identically on both platforms.\n\n---\n\n## 🎯 The Problem\n\nAgents need to communicate with other agents (API calls, data sharing, task delegation). But **how do you know if another agent is trustworthy?**\n\n- Has it been compromised?\n- Is it leaking data?\n- Can you trust its responses?\n\nWithout a trust layer, agent-to-agent communication is like HTTP without SSL - **unsafe and unverifiable**.\n\n---\n\n## 💡 The Solution: Trust Infrastructure\n\nAgentShield provides the **trust layer** for agent-to-agent communication:\n\n### 1. Cryptographic Identity\n- **Ed25519 key pairs** - Industry-standard cryptography\n- **Private keys stay local** - Never transmitted\n- **Public key certificates** - Signed by AgentShield\n\n### 2. Security Audit (77 Tests)\n**52 Live Attack Vectors:**\nTests defense against instruction manipulation, encoding schemes, and social engineering\nacross 6 languages. All attack patterns are stored locally in agentshield_attack_patterns.json\n(not embedded in documentation).\n\n**25 Static Security Checks:**\n- Input sanitization\n- Output DLP (data leak prevention)\n- Tool sandboxing\n- Secret scanning\n- Supply chain security\n\n**Result:** Security score (0-100) + Tier (VULNERABLE → HARDENED)\n\n**Privacy:** Tests run 100% locally - only pass/fail scores sent to API (no prompts/responses)\n\n### 3. Trust Handshake Protocol\n**Agent A wants to communicate with Agent B:**\n\n```bash\n# Step 1: Both agents get certified\npython3 initiate_audit.py --auto\n\n# Step 2: Agent A initiates handshake with Agent B\npython3 handshake.py --target agent_B_id\n\n# Step 3: Both agents sign challenges\n# (Automatic in v1.0.13+)\n\n# Step 4: Receive shared session key\n# → Now you can communicate securely!\n```\n\n**What you get:**\n- ✅ Mutual verification (both agents are who they claim to be)\n- ✅ Shared session key (for encrypted communication)\n- ✅ Trust score boost (+5 for successful handshakes)\n- ✅ Public track record (handshake history)\n\n### 4. Public Trust Registry\n- **Searchable database** of all certified agents\n- **Reputation scores** based on audits, handshakes, and time\n- **Trust tiers:** UNVERIFIED → BASIC → VERIFIED → TRUSTED\n- **Revocation list (CRL)** - Compromised agents get flagged\n\n---\n\n## 🚀 Quick Start\n\n### Install\n```bash\nclawhub install agentshield\n\n# Install Python dependencies (required!)\npip3 install -r requirements.txt\ncd ~/.openclaw/workspace/skills/agentshield*/\n```\n\n### Get Certified (77 Security Tests)\n```bash\n# RECOMMENDED: Dry-run first (see what would be submitted)\npython3 initiate_audit.py --auto --dry-run\n\n# After verifying payload: Run for real\npython3 initiate_audit.py --auto\n\n# Or manual (no file reads):\npython3 initiate_audit.py --name \"MyAgent\" --platform telegram\n```\n\n**Output:**\n- ✅ Agent ID: `agent_xxxxx`\n- ✅ Security Score: XX/100\n- ✅ Tier: PATTERNS_CLEAN / HARDENED / etc.\n- ✅ Certificate (90-day validity)\n\n### Verify Another Agent\n```bash\npython3 verify_peer.py agent_yyyyy\n```\n\n### Trust Handshake with Another Agent\n```bash\n# Initiate handshake\npython3 handshake.py --target agent_yyyyy\n\n# Result: Shared session key for encrypted communication\n```\n\n---\n\n## 📋 Use Cases\n\n### 1. Agent-to-Agent API Calls\n**Before:** Agent A calls Agent B's API - no way to verify B's integrity  \n**With AgentShield:** Agent A checks Agent B's certificate + handshake → Verified communication\n\n### 2. Multi-Agent Task Delegation\n**Before:** Orchestrator spawns sub-agents - can't verify they're safe  \n**With AgentShield:** All sub-agents certified → Orchestrator knows they're trusted\n\n### 3. Agent Marketplaces\n**Before:** Download random agents from the internet - no trust guarantees  \n**With AgentShield:** Browse Trust Registry → Only hire VERIFIED agents\n\n### 4. Data Sharing Between Agents\n**Before:** Share sensitive data with another agent - hope it doesn't leak  \n**With AgentShield:** Handshake → Encrypted session key → Secure data transfer\n\n---\n\n## 🛡️ Security Architecture\n\n### Privacy-First Design\n\n✅ **All 77 tests run locally** - Your system prompts NEVER leave your device  \n✅ **Private keys stay local** - Only public keys transmitted  \n✅ **Human-in-the-Loop** - Explicit consent before reading IDENTITY.md/SOUL.md  \n✅ **No environment scanning** - Doesn't scan for API tokens  \n\n**What goes to the server:**\n- Public key (Ed25519)\n- Agent name & platform\n- Test scores (passed/failed summary)\n\n**What stays local:**\n- Private key\n- System prompts\n- Configuration files\n- Detailed test results\n\n### Environment Variables (Optional)\n```bash\nAGENTSHIELD_API=https://agentshield.live  # API endpoint\nAGENT_NAME=MyAgent                        # Override auto-detection\nOPENCLAW_AGENT_NAME=MyAgent               # OpenClaw standard\n```\n\n---\n\n## 📊 What You Get\n\n### Certificate (90-day validity)\n```json\n{\n  \"agent_id\": \"agent_xxxxx\",\n  \"public_key\": \"...\",\n  \"security_score\": 85,\n  \"tier\": \"PATTERNS_CLEAN\",\n  \"issued_at\": \"2026-03-10\",\n  \"expires_at\": \"2026-06-08\"\n}\n```\n\n### Trust Registry Entry\n- ✅ Public verification URL: `agentshield.live/verify/agent_xxxxx`\n- ✅ Trust score (0-100) based on:\n  - Age (longer = more trust)\n  - Verification count\n  - Handshake success rate\n  - Days active\n- ✅ Tier: UNVERIFIED → BASIC → VERIFIED → TRUSTED\n\n### Handshake Proof\n```json\n{\n  \"handshake_id\": \"hs_xxxxx\",\n  \"requester\": \"agent_A\",\n  \"target\": \"agent_B\",\n  \"status\": \"completed\",\n  \"session_key\": \"...\",\n  \"completed_at\": \"2026-03-10T20:00:00Z\"\n}\n```\n\n---\n\n## 🔧 Scripts Included\n\n| Script | Purpose |\n|--------|---------|\n| `initiate_audit.py` | Run 77 security tests & get certified |\n| `handshake.py` | Trust handshake with another agent |\n| `verify_peer.py` | Check another agent's certificate |\n| `show_certificate.py` | Display your certificate |\n| `agentshield_tester.py` | Standalone test suite (advanced) |\n\n---\n\n## 🌐 API Endpoints\n\n**Base URL:** `https://agentshield.live/api`\n\n### 1. Agent Audit Flow\n```\nPOST /agent-audit/initiate\n  → Initiate audit session\n  → Input: {agent_name, platform, public_key}\n  → Output: {audit_id, challenge}\n\nPOST /agent-audit/challenge\n  → Complete challenge-response authentication\n  → Input: {audit_id, challenge_response (signed)}\n  → Output: {authenticated: true}\n\nPOST /agent-audit/complete\n  → Submit test results & receive certificate\n  → Input: {audit_id, test_results}\n  → Output: {certificate, agent_id, expires_at}\n```\n\n### 2. Certificate Operations\n```\nGET /certificate/verify/{agent_id}\n  → Verify another agent's certificate\n  → Output: {valid, score, tier, issued_at, expires_at}\n\nGET /api/public-key\n  → Get AgentShield's public signing key\n  → Output: {public_key (Ed25519, base64)}\n```\n\n### 3. Trust Handshake\n```\nPOST /handshake/initiate\n  → Start Trust Handshake with another agent\n  → Input: {requester_id, target_id}\n  → Output: {handshake_id, challenges}\n\nPOST /handshake/complete\n  → Complete handshake with signed challenges\n  → Input: {handshake_id, signatures}\n  → Output: {session_key, trust_boost}\n```\n\n### Rate Limits\n- Audits: 1 per hour per IP\n- Handshakes: 10 per hour per agent\n- Verifications: Unlimited (read-only)\n\n**All endpoints require HTTPS. No API keys needed.**\n\n---\n\n## 🌐 Trust Handshake Protocol (Technical)\n\n### Flow\n1. **Initiate:** Agent A → Server: \"I want to handshake with Agent B\"\n2. **Challenge:** Server generates random challenges for both agents\n3. **Sign:** Both agents sign their challenges with private keys\n4. **Verify:** Server verifies signatures with public keys\n5. **Complete:** Server generates shared session key\n6. **Trust Boost:** Both agents +5 trust score\n\n### Cryptography\n- **Algorithm:** Ed25519 (curve25519)\n- **Key Size:** 256-bit\n- **Signature:** Deterministic (same message = same signature)\n- **Session Key:** AES-256 compatible\n\n---\n\n## 🚀 Roadmap\n\n**Current (v1.0.31):**\n- ✅ 77 security tests\n- ✅ Ed25519 certificates\n- ✅ Trust Handshake Protocol\n- ✅ Public Trust Registry\n- ✅ CRL (Certificate Revocation List)\n- ✅ Explicit whitelist sanitization (test IDs only)\n- ✅ Dry-run mode for transparency\n\n**Coming Soon:**\n- ⏳ Auto re-audit (when prompts change)\n- ⏳ Negative event reporting\n- ⏳ Fleet management (multi-agent dashboard)\n- ⏳ Trust badges for messaging platforms\n\n---\n\n## 📖 Learn More\n\n- **Website:** https://agentshield.live\n- **GitHub:** https://github.com/bartelmost/agentshield\n- **API Docs:** https://agentshield.live/docs\n- **ClawHub:** https://clawhub.ai/bartelmost/agentshield\n\n---\n\n## 🎯 TL;DR\n\n**AgentShield is SSL/TLS for AI agents.**\n\nGet certified → Verify others → Establish trust handshakes → Communicate securely.\n\n```bash\n# 1. Get certified\npython3 initiate_audit.py --auto\n\n# 2. Handshake with another agent\npython3 handshake.py --target agent_xxxxx\n\n# 3. Verify others\npython3 verify_peer.py agent_yyyyy\n```\n\n**Building the trust layer for the agent economy.** 🛡️\n\n---\n\n## 🔐 Privacy & Security Guarantees (v1.0.31+)\n\n**✅ EXPLICIT WHITELIST (What Gets Sent):**\n- Test IDs (e.g. \"PI-001\", \"SS-003\")\n- Pass/fail boolean per test\n- Category names (e.g. \"prompt_injection\")\n- Summary counts (passed/failed/total)\n- Agent metadata (name, platform, version)\n- Public key (Ed25519, for certificate signing)\n\n**❌ NEVER SENT (Explicitly Excluded):**\n- ✅ Your system prompt\n- ✅ Attack test inputs/payloads (e.g. \"ignore previous instructions\")\n- ✅ Attack test outputs/responses\n- ✅ Evidence snippets (base64 matches, pattern findings)\n- ✅ Error messages from test execution\n- ✅ Tool configurations\n- ✅ File paths or workspace structure\n- ✅ Private keys (Ed25519, stay local in ~/.agentshield/)\n\n**🔍 Code-Level Enforcement:**\n- See `audit_client.py` line 108: `_sanitize_test_details()` whitelist\n- Payloads/responses/evidence explicitly dropped (line 130-136 comments)\n- Dry-run mode: `--dry-run` flag shows exact payload before submission\n\n**Verification:**\n```bash\n# See what WOULD be submitted (no API call)\npython3 initiate_audit.py --auto --dry-run\n```\n\nAll code is open-source: [github.com/bartelmost/agentshield](https://github.com/bartelmost/agentshield)\n\n---\n\n## 🔒 Data Transmission Transparency\n\n### What Gets Sent to AgentShield API\n\n**During Audit Submission:**\n```json\n{\n  \"agent_name\": \"YourAgent\",\n  \"platform\": \"telegram\",\n  \"public_key\": \"base64_encoded_ed25519_public_key\",\n  \"test_results\": {\n    \"score\": 85,\n    \"tests_passed\": 74,\n    \"tests_total\": 77,\n    \"tier\": \"PATTERNS_CLEAN\",\n    \"failed_tests\": [\"test_name_1\", \"test_name_2\"]\n  }\n}\n```\n\n**What is NOT sent:**\n- ❌ Full test output/logs\n- ❌ Your prompts or system messages\n- ❌ IDENTITY.md or SOUL.md file contents\n- ❌ Private keys (stay in `~/.agentshield/agent.key`)\n- ❌ Workspace files or memory\n\n**API Endpoint:**\n- Primary: `https://agentshield.live/api` (proxies to Heroku backend)\n- All traffic over HTTPS (TLS 1.2+)\n\n---\n\n## 🛡️ Consent & Privacy\n\n**File Read Consent (v1.0.30+):**\n1. ✅ Explicit consent prompt BEFORE reading IDENTITY.md/SOUL.md\n2. User sees: \"🔐 PRIVACY CONSENT - Read IDENTITY.md for agent name? [Y/n]\"\n3. If declined: Exits with message \"Please run with: --name 'YourAgentName'\"\n4. If approved: Only name/platform extracted (not full file content)\n\n**⚠️ Automation Mode (--yes flag) - v1.0.31+:**\n\nThe `--yes` flag is designed for **CI/CD and pre-audited environments ONLY**.\n\n**When to use:**\n- ✅ Sandboxed test agents (no real secrets)\n- ✅ CI/CD pipelines (after manual code review + dry-run)\n- ✅ Agents you've already audited manually\n\n**When NOT to use:**\n- ❌ Production agents with real secrets\n- ❌ Agents handling sensitive user data\n- ❌ First-time audit (always use manual mode first!)\n\n**Why?** The --yes flag bypasses ALL consent prompts. While the code includes \nexplicit sanitization (see audit_client.py line 108+), we recommend:\n\n1. Run `--dry-run` first to inspect payload\n2. Manually review audit_client.py whitelist\n3. Only then use `--yes` for automation\n\n**Best Practice:**\n```bash\n# Step 1: Dry-run to see payload\npython3 initiate_audit.py --auto --dry-run\n\n# Step 2: Review output, verify sanitization\n# (Should only show test IDs + pass/fail, no payloads)\n\n# Step 3: If satisfied, run for real\npython3 initiate_audit.py --auto\n\n# Step 4: For CI/CD, add --yes ONLY after manual verification\npython3 initiate_audit.py --auto --yes\n```\n\n**Privacy-First Mode:**\n```bash\nexport AGENTSHIELD_NO_AUTO_DETECT=1\npython initiate_audit.py --name \"MyBot\" --platform \"telegram\"\n```\n→ Zero file reads, manual input only\n\nSee [PRIVACY.md](PRIVACY.md) for complete data handling documentation.\n\n","tags":{"latest":"1.0.35","agent-security":"1.0.2","agents":"1.0.3","ai-safety":"1.0.3","api-security":"1.0.3","audit":"1.0.4","certificates":"1.0.4","code-scan":"1.0.1","compliance":"1.0.3","cryptography":"1.0.4","ed25519":"1.0.3","eu-ai-act":"1.0.3","human-in-the-loop":"1.0.2","identity":"1.0.3","llm-security":"1.0.3","privacy":"1.0.2","privacy-first":"1.0.2","prompt-injection":"1.0.2","rate-limiting":"1.0.3","secret-scanning":"1.0.3","security":"1.0.4","token-optimizer":"1.0.1","trust":"1.0.4","v6.0":"1.0.1","verification":"1.0.3"},"stats":{"comments":2,"downloads":1878,"installsAllTime":4,"installsCurrent":4,"stars":0,"versions":35},"createdAt":1771631558614,"updatedAt":1780476844045},"latestVersion":{"version":"1.0.35","createdAt":1780476844045,"changelog":"No user-facing Hermes Agent support: Added HERMES.md integration guide, \nHermes to platform list and tags, auto-detection for ~/.hermes/. \nFramework compatibility table added to SKILL.md.\nWorks out-of-the-box with both OpenClaw and Hermes Agent.\nchanges in this release; no file changes detected.","license":"MIT-0"},"metadata":null,"owner":{"handle":"bartelmost","userId":"s1709g2t9ptwbe5z1grvhq0ak583gvmb","displayName":"bartelmost","image":"https://avatars.githubusercontent.com/u/131160940?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780480694463}}