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 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:

# 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

clawhub install agentshield

# Install Python dependencies (required!)
pip3 install -r requirements.txt
cd ~/.openclaw/workspace/skills/agentshield*/

Get Certified (77 Security Tests)

# 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

python3 verify_peer.py agent_yyyyy

Trust Handshake with Another Agent

# 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)

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)

{
  "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

{
  "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

Initiate: Agent A → Server: "I want to handshake with Agent B"
Challenge: Server generates random challenges for both agents
Sign: Both agents sign their challenges with private keys
Verify: Server verifies signatures with public keys
Complete: Server generates shared session key
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.

# 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:

# See what WOULD be submitted (no API call)
python3 initiate_audit.py --auto --dry-run

All code is open-source: github.com/bartelmost/agentshield

🔒 Data Transmission Transparency

What Gets Sent to AgentShield API

During Audit Submission:

{
  "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+):

✅ Explicit consent prompt BEFORE reading IDENTITY.md/SOUL.md
User sees: "🔐 PRIVACY CONSENT - Read IDENTITY.md for agent name? [Y/n]"
If declined: Exits with message "Please run with: --name 'YourAgentName'"
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:

Run --dry-run first to inspect payload
Manually review audit_client.py whitelist
Only then use --yes for automation

Best Practice:

# 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:

export AGENTSHIELD_NO_AUTO_DETECT=1
python initiate_audit.py --name "MyBot" --platform "telegram"

→ Zero file reads, manual input only

See PRIVACY.md for complete data handling documentation.