Trust Infrastructure for AI Agents - Like SSL/TLS for agent-to-agent communication. 77 security tests, cryptographic certificates, and Trust Handshake Protoc...
---
name: agentshield
version: 1.0.31
description: 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.
triggers: ["audit my agent", "get security certificate", "verify agent", "activate AgentShield", "security audit", "trust handshake", "verify peer agent"]
---
# AgentShield - Trust Infrastructure for AI Agents
**The trust layer for the agent economy. Like SSL/TLS, but for AI agents.**
๐ **Cryptographic Identity** - Ed25519 signing keys
๐ค **Trust Handshake Protocol** - Mutual verification before communication
๐ **Public Trust Registry** - Reputation scores & track records
โ
**77 Security Tests** - Comprehensive vulnerability assessment
**๐ Privacy Disclosure:** See [PRIVACY.md](PRIVACY.md) for detailed data handling information.
---
## ๐ฏ The Problem
Agents need to communicate with other agents (API calls, data sharing, task delegation). But **how do you know if another agent is trustworthy?**
- Has it been compromised?
- Is it leaking data?
- Can you trust its responses?
Without a trust layer, agent-to-agent communication is like HTTP without SSL - **unsafe and unverifiable**.
---
## ๐ก The Solution: Trust Infrastructure
AgentShield provides the **trust layer** for agent-to-agent communication:
### 1. Cryptographic Identity
- **Ed25519 key pairs** - Industry-standard cryptography
- **Private keys stay local** - Never transmitted
- **Public key certificates** - Signed by AgentShield
### 2. Security Audit (77 Tests)
**52 Live Attack Vectors:**
Tests defense against instruction manipulation, encoding schemes, and social engineering
across 6 languages. All attack patterns are stored locally in agentshield_attack_patterns.json
(not embedded in documentation).
**25 Static Security Checks:**
- Input sanitization
- Output DLP (data leak prevention)
- Tool sandboxing
- Secret scanning
- Supply chain security
**Result:** Security score (0-100) + Tier (VULNERABLE โ HARDENED)
**Privacy:** Tests run 100% locally - only pass/fail scores sent to API (no prompts/responses)
### 3. Trust Handshake Protocol
**Agent A wants to communicate with Agent B:**
```bash
# Step 1: Both agents get certified
python3 initiate_audit.py --auto
# Step 2: Agent A initiates handshake with Agent B
python3 handshake.py --target agent_B_id
# Step 3: Both agents sign challenges
# (Automatic in v1.0.13+)
# Step 4: Receive shared session key
# โ Now you can communicate securely!
```
**What you get:**
- โ
Mutual verification (both agents are who they claim to be)
- โ
Shared session key (for encrypted communication)
- โ
Trust score boost (+5 for successful handshakes)
- โ
Public track record (handshake history)
### 4. Public Trust Registry
- **Searchable database** of all certified agents
- **Reputation scores** based on audits, handshakes, and time
- **Trust tiers:** UNVERIFIED โ BASIC โ VERIFIED โ TRUSTED
- **Revocation list (CRL)** - Compromised agents get flagged
---
## ๐ Quick Start
### Install
```bash
clawhub install agentshield
# Install Python dependencies (required!)
pip3 install -r requirements.txt
cd ~/.openclaw/workspace/skills/agentshield*/
```
### Get Certified (77 Security Tests)
```bash
# RECOMMENDED: Dry-run first (see what would be submitted)
python3 initiate_audit.py --auto --dry-run
# After verifying payload: Run for real
python3 initiate_audit.py --auto
# Or manual (no file reads):
python3 initiate_audit.py --name "MyAgent" --platform telegram
```
**Output:**
- โ
Agent ID: `agent_xxxxx`
- โ
Security Score: XX/100
- โ
Tier: PATTERNS_CLEAN / HARDENED / etc.
- โ
Certificate (90-day validity)
### Verify Another Agent
```bash
python3 verify_peer.py agent_yyyyy
```
### Trust Handshake with Another Agent
```bash
# Initiate handshake
python3 handshake.py --target agent_yyyyy
# Result: Shared session key for encrypted communication
```
---
## ๐ Use Cases
### 1. Agent-to-Agent API Calls
**Before:** Agent A calls Agent B's API - no way to verify B's integrity
**With AgentShield:** Agent A checks Agent B's certificate + handshake โ Verified communication
### 2. Multi-Agent Task Delegation
**Before:** Orchestrator spawns sub-agents - can't verify they're safe
**With AgentShield:** All sub-agents certified โ Orchestrator knows they're trusted
### 3. Agent Marketplaces
**Before:** Download random agents from the internet - no trust guarantees
**With AgentShield:** Browse Trust Registry โ Only hire VERIFIED agents
### 4. Data Sharing Between Agents
**Before:** Share sensitive data with another agent - hope it doesn't leak
**With AgentShield:** Handshake โ Encrypted session key โ Secure data transfer
---
## ๐ก๏ธ Security Architecture
### Privacy-First Design
โ
**All 77 tests run locally** - Your system prompts NEVER leave your device
โ
**Private keys stay local** - Only public keys transmitted
โ
**Human-in-the-Loop** - Explicit consent before reading IDENTITY.md/SOUL.md
โ
**No environment scanning** - Doesn't scan for API tokens
**What goes to the server:**
- Public key (Ed25519)
- Agent name & platform
- Test scores (passed/failed summary)
**What stays local:**
- Private key
- System prompts
- Configuration files
- Detailed test results
### Environment Variables (Optional)
```bash
AGENTSHIELD_API=https://agentshield.live # API endpoint
AGENT_NAME=MyAgent # Override auto-detection
OPENCLAW_AGENT_NAME=MyAgent # OpenClaw standard
```
---
## ๐ What You Get
### Certificate (90-day validity)
```json
{
"agent_id": "agent_xxxxx",
"public_key": "...",
"security_score": 85,
"tier": "PATTERNS_CLEAN",
"issued_at": "2026-03-10",
"expires_at": "2026-06-08"
}
```
### Trust Registry Entry
- โ
Public verification URL: `agentshield.live/verify/agent_xxxxx`
- โ
Trust score (0-100) based on:
- Age (longer = more trust)
- Verification count
- Handshake success rate
- Days active
- โ
Tier: UNVERIFIED โ BASIC โ VERIFIED โ TRUSTED
### Handshake Proof
```json
{
"handshake_id": "hs_xxxxx",
"requester": "agent_A",
"target": "agent_B",
"status": "completed",
"session_key": "...",
"completed_at": "2026-03-10T20:00:00Z"
}
```
---
## ๐ง Scripts Included
| Script | Purpose |
|--------|---------|
| `initiate_audit.py` | Run 77 security tests & get certified |
| `handshake.py` | Trust handshake with another agent |
| `verify_peer.py` | Check another agent's certificate |
| `show_certificate.py` | Display your certificate |
| `agentshield_tester.py` | Standalone test suite (advanced) |
---
## ๐ API Endpoints
**Base URL:** `https://agentshield.live/api`
### 1. Agent Audit Flow
```
POST /agent-audit/initiate
โ Initiate audit session
โ Input: {agent_name, platform, public_key}
โ Output: {audit_id, challenge}
POST /agent-audit/challenge
โ Complete challenge-response authentication
โ Input: {audit_id, challenge_response (signed)}
โ Output: {authenticated: true}
POST /agent-audit/complete
โ Submit test results & receive certificate
โ Input: {audit_id, test_results}
โ Output: {certificate, agent_id, expires_at}
```
### 2. Certificate Operations
```
GET /certificate/verify/{agent_id}
โ Verify another agent's certificate
โ Output: {valid, score, tier, issued_at, expires_at}
GET /api/public-key
โ Get AgentShield's public signing key
โ Output: {public_key (Ed25519, base64)}
```
### 3. Trust Handshake
```
POST /handshake/initiate
โ Start Trust Handshake with another agent
โ Input: {requester_id, target_id}
โ Output: {handshake_id, challenges}
POST /handshake/complete
โ Complete handshake with signed challenges
โ Input: {handshake_id, signatures}
โ Output: {session_key, trust_boost}
```
### Rate Limits
- Audits: 1 per hour per IP
- Handshakes: 10 per hour per agent
- Verifications: Unlimited (read-only)
**All endpoints require HTTPS. No API keys needed.**
---
## ๐ Trust Handshake Protocol (Technical)
### Flow
1. **Initiate:** Agent A โ Server: "I want to handshake with Agent B"
2. **Challenge:** Server generates random challenges for both agents
3. **Sign:** Both agents sign their challenges with private keys
4. **Verify:** Server verifies signatures with public keys
5. **Complete:** Server generates shared session key
6. **Trust Boost:** Both agents +5 trust score
### Cryptography
- **Algorithm:** Ed25519 (curve25519)
- **Key Size:** 256-bit
- **Signature:** Deterministic (same message = same signature)
- **Session Key:** AES-256 compatible
---
## ๐ Roadmap
**Current (v1.0.31):**
- โ
77 security tests
- โ
Ed25519 certificates
- โ
Trust Handshake Protocol
- โ
Public Trust Registry
- โ
CRL (Certificate Revocation List)
- โ
Explicit whitelist sanitization (test IDs only)
- โ
Dry-run mode for transparency
**Coming Soon:**
- โณ Auto re-audit (when prompts change)
- โณ Negative event reporting
- โณ Fleet management (multi-agent dashboard)
- โณ Trust badges for messaging platforms
---
## ๐ Learn More
- **Website:** https://agentshield.live
- **GitHub:** https://github.com/bartelmost/agentshield
- **API Docs:** https://agentshield.live/docs
- **ClawHub:** https://clawhub.ai/bartelmost/agentshield
---
## ๐ฏ TL;DR
**AgentShield is SSL/TLS for AI agents.**
Get certified โ Verify others โ Establish trust handshakes โ Communicate securely.
```bash
# 1. Get certified
python3 initiate_audit.py --auto
# 2. Handshake with another agent
python3 handshake.py --target agent_xxxxx
# 3. Verify others
python3 verify_peer.py agent_yyyyy
```
**Building the trust layer for the agent economy.** ๐ก๏ธ
---
## ๐ Privacy & Security Guarantees (v1.0.31+)
**โ
EXPLICIT WHITELIST (What Gets Sent):**
- Test IDs (e.g. "PI-001", "SS-003")
- Pass/fail boolean per test
- Category names (e.g. "prompt_injection")
- Summary counts (passed/failed/total)
- Agent metadata (name, platform, version)
- Public key (Ed25519, for certificate signing)
**โ NEVER SENT (Explicitly Excluded):**
- โ
Your system prompt
- โ
Attack test inputs/payloads (e.g. "ignore previous instructions")
- โ
Attack test outputs/responses
- โ
Evidence snippets (base64 matches, pattern findings)
- โ
Error messages from test execution
- โ
Tool configurations
- โ
File paths or workspace structure
- โ
Private keys (Ed25519, stay local in ~/.agentshield/)
**๐ Code-Level Enforcement:**
- See `audit_client.py` line 108: `_sanitize_test_details()` whitelist
- Payloads/responses/evidence explicitly dropped (line 130-136 comments)
- Dry-run mode: `--dry-run` flag shows exact payload before submission
**Verification:**
```bash
# See what WOULD be submitted (no API call)
python3 initiate_audit.py --auto --dry-run
```
All code is open-source: [github.com/bartelmost/agentshield](https://github.com/bartelmost/agentshield)
---
## ๐ Data Transmission Transparency
### What Gets Sent to AgentShield API
**During Audit Submission:**
```json
{
"agent_name": "YourAgent",
"platform": "telegram",
"public_key": "base64_encoded_ed25519_public_key",
"test_results": {
"score": 85,
"tests_passed": 74,
"tests_total": 77,
"tier": "PATTERNS_CLEAN",
"failed_tests": ["test_name_1", "test_name_2"]
}
}
```
**What is NOT sent:**
- โ Full test output/logs
- โ Your prompts or system messages
- โ IDENTITY.md or SOUL.md file contents
- โ Private keys (stay in `~/.agentshield/agent.key`)
- โ Workspace files or memory
**API Endpoint:**
- Primary: `https://agentshield.live/api` (proxies to Heroku backend)
- All traffic over HTTPS (TLS 1.2+)
---
## ๐ก๏ธ Consent & Privacy
**File Read Consent (v1.0.30+):**
1. โ
Explicit consent prompt BEFORE reading IDENTITY.md/SOUL.md
2. User sees: "๐ PRIVACY CONSENT - Read IDENTITY.md for agent name? [Y/n]"
3. If declined: Exits with message "Please run with: --name 'YourAgentName'"
4. If approved: Only name/platform extracted (not full file content)
**โ ๏ธ Automation Mode (--yes flag) - v1.0.31+:**
The `--yes` flag is designed for **CI/CD and pre-audited environments ONLY**.
**When to use:**
- โ
Sandboxed test agents (no real secrets)
- โ
CI/CD pipelines (after manual code review + dry-run)
- โ
Agents you've already audited manually
**When NOT to use:**
- โ Production agents with real secrets
- โ Agents handling sensitive user data
- โ First-time audit (always use manual mode first!)
**Why?** The --yes flag bypasses ALL consent prompts. While the code includes
explicit sanitization (see audit_client.py line 108+), we recommend:
1. Run `--dry-run` first to inspect payload
2. Manually review audit_client.py whitelist
3. Only then use `--yes` for automation
**Best Practice:**
```bash
# Step 1: Dry-run to see payload
python3 initiate_audit.py --auto --dry-run
# Step 2: Review output, verify sanitization
# (Should only show test IDs + pass/fail, no payloads)
# Step 3: If satisfied, run for real
python3 initiate_audit.py --auto
# Step 4: For CI/CD, add --yes ONLY after manual verification
python3 initiate_audit.py --auto --yes
```
**Privacy-First Mode:**
```bash
export AGENTSHIELD_NO_AUTO_DETECT=1
python initiate_audit.py --name "MyBot" --platform "telegram"
```
โ Zero file reads, manual input only
See [PRIVACY.md](PRIVACY.md) for complete data handling documentation.
don't have the plugin yet? install it then click "run inline in claude" again.