Content
# A2AS PoC - Agent-to-Agent Security Framework
A modern proof-of-concept implementation of the A2AS (Agent-to-Agent Security) framework demonstrating Behavior Certificates, Authenticated Prompts, Security Boundaries, and Enforcement Gates. Inspired by the [A2AS Paper](https://www.a2as.org/).
## 🚀 Modern Tech Stack
- **Node.js 22** - Latest LTS with performance improvements
- **TypeScript 5.4** - Full type safety and modern language features
- **Vitest** - Fast testing framework with UI support
- **ESLint + Prettier** - Code quality and formatting
- **Zod** - Runtime type validation
- **Winston** - Structured logging
- **ES Modules** - Modern JavaScript module system
## Overview
This PoC shows how to secure LLM agents by:
- **Behavior Certificates**: Define what actions an agent is allowed to perform
- **Authenticated Prompts**: HMAC-signed prompts to prevent tampering
- **Enforcement Proxy**: Blocks malicious actions even if LLM outputs them
- **In-Context Defenses**: Structured context to guide LLM behavior
- **Policy Engine**: Pattern-based policy evaluation
## Quick Start
### Prerequisites
- Node.js 22+
- npm 10+
### Installation
```bash
npm install
```
### Development
```bash
# Run in development mode with hot reload
npm run dev
# Type checking
npm run type-check
# Linting and formatting
npm run lint
npm run format
```
### Testing
```bash
# Run tests
npm run test
# Run tests in watch mode
npm run test:watch
# Run tests with UI
npm run test:ui
```
### Production
```bash
# Build TypeScript
npm run build
# Run demo with Mock LLM
npm run start
# Run with Real LLM (Optional)
export OPENAI_API_KEY=your_key_here
npm run run-llm
```
## Architecture
```
User Prompt → Controller → LLM Adapter → Enforcement Proxy → Action Execution
↓ ↓ ↓ ↓
Signature Context JSON Action Policy Check
Verification Building Parsing + Sandbox
```
## Behavior Certificate Format
Located in `certs/demo-agent-1.json`:
```json
{
"agent_id": "demo-agent-1",
"secret": "demo-secret-please-change",
"allowed_tools": {
"fs": {
"read": ["./workspace/**"],
"write": ["./workspace/**"]
},
"http": {
"GET": ["https://api.github.com/*"]
},
"shell": []
},
"deny_patterns": ["aws", "ssh", "id_rsa", "PRIVATE_KEY", "rm -rf"],
"max_filesize_bytes": 1048576,
"require_human_before_sensitive_write": true
}
```
## Security Features
- **HMAC-SHA256** prompt signing
- **Path allowlisting** for file operations
- **Pattern-based exfiltration detection**
- **Shell command sandboxing**
- **Human escalation** for sensitive operations
- **Structured logging** with secret masking
## Test Scenarios
The adversarial test harness includes:
1. `rm -rf /` shell execution → **DENY**
2. Reading `~/.aws/credentials` → **DENY**
3. HTTP GET to `api.github.com` → **ALLOW** (mock)
4. Base64 obfuscated instructions → **DENY**
5. Sensitive write operations → **ESCALATE**
## File Structure
```
├── src/
│ ├── controller.js # Main coordinator
│ ├── enforcement.js # Enforcement proxy
│ ├── policy.js # Policy evaluator
│ ├── llm-adapter/
│ │ ├── mock-llm.js # Mock LLM for testing
│ │ └── openai-adapter.js # Optional OpenAI adapter
│ └── utils/
│ ├── signer.js # HMAC signing utilities
│ ├── parser.js # LLM output parser
│ └── sandbox-exec.js # Safe execution wrapper
├── certs/
│ └── demo-agent-1.json # Behavior Certificate
├── tests/
│ └── adversarial-tests.js # Test harness
├── examples/
│ └── sample-signed-prompt.json
└── logs/ # JSONL action logs
```
## Limitations & Next Steps
### Current Limitations
- **PoC Only**: Not production-ready
- **Mock Execution**: Real shell commands are simulated
- **Simple PKI**: Uses shared secrets, not certificates
- **Basic Sandboxing**: Limited process isolation
- **No Human Review UI**: Escalation goes to file
### Next Steps
- Implement proper PKI with X.509 certificates
- Add container-based sandboxing
- Build human review dashboard
- Add metrics and monitoring
- Implement distributed policy management
- Add more sophisticated pattern matching
## Security Warning
⚠️ **This is a proof-of-concept only. Do not use in production or with real secrets.**
## Examples
### Generate Signed Prompt
```bash
npm run sign-prompt "List files in workspace"
```
### Sample Output
```json
{
"prompt": "List files in workspace",
"agent_id": "demo-agent-1",
"signature": "a1b2c3d4...",
"timestamp": "2024-01-01T00:00:00Z"
}
```
