cisco-ai-a2a-scanner 1.0.0

A comprehensive security scanner for Agent-to-Agent (A2A) protocol threats

A2A Security Scanner

Scan Agent-to-Agent (A2A) protocol implementations for security threats and vulnerabilities.

---

Overview

The A2A Security Scanner provides comprehensive security analysis for Agent-to-Agent protocol implementations. It combines static analysis, runtime monitoring, and AI-powered semantic detection to identify security threats across the A2A protocol stack.

Key Features

• Multiple Specialized Analyzers: YARA rules, spec validation, heuristics, LLM-powered detection, and endpoint testing
• Multiple Threat Categories: Complete coverage of A2A threat taxonomy
• REST API: Easy integration into CI/CD pipelines and applications
• CLI Tools: Command-line interface for manual security audits
• Agent Card Validation: A2A protocol compliance checking

---

Installation

Quick Install

Using UV (Recommended)

# Install UV
brew install uv
# or: curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/cisco-ai-defense/a2a-scanner.git
cd a2a-scanner

# Install dependencies
uv sync

# Verify installation
uv run a2a-scanner list-analyzers

Requirements

• Python: 3.11 or higher
• Package Manager: UV (recommended) or pip
• Optional: Azure OpenAI API key for LLM analyzer

---

Quick Start

Scan an Agent Card

# Scan a JSON agent card file
uv run a2a-scanner scan-card examples/sample_agent_cards/unsafe_agent.json

# Scan with specific analyzers
uv run a2a-scanner scan-card agent.json --analyzers yara,spec

# JSON output
uv run a2a-scanner scan-card agent.json --output results.json

Scan Source Code

# Scan a directory
uv run a2a-scanner scan-directory /path/to/agent/code

# Scan a single file
uv run a2a-scanner scan-file agent.py

# Scan with pattern
uv run a2a-scanner scan-directory ./agents --pattern "**/*.py"

Scan Live Agent Endpoint

# Scan a running agent
uv run a2a-scanner scan-endpoint https://agent.example.com/api

# With authentication
uv run a2a-scanner scan-endpoint https://agent.example.com/api --bearer-token "$TOKEN"

Note: You can omit uv run if you activate the virtual environment first with source .venv/bin/activate

🎮 Try Interactive Demo

Want to see the analyzers in action? Run the interactive demo:

# Interactive demo with sample data
uv run python examples/interactive_demo.py --dev

# Or use the comprehensive automated demo
uv run python examples/comprehensive_demo.py

The interactive demo lets you test all analyzers (YARA, Spec, Heuristic, LLM, Endpoint) with:

• Built-in sample malicious agent cards
• Live endpoint testing (try http://localhost:9998)
• Color-coded threat severity display
• Session summary with aggregate statistics

See Demonstrations section for full details.

---

Development Mode

For local development and testing, use the --dev flag to relax security checks:

What Dev Mode Does

When --dev is enabled, the scanner allows:

• Localhost URLs (http://localhost:8000)
• Private IP addresses (http://192.168.1.1, http://10.0.0.x)
• Self-signed SSL certificates (skips verification)
• HTTP connections (without flagging as insecure)

CLI Usage

# Scan local agent endpoint
uv run a2a-scanner --dev scan-endpoint http://localhost:8000

# Scan with debug logging
uv run a2a-scanner --dev --debug scan-endpoint http://localhost:9999

# Scan agent card from local URL
uv run a2a-scanner --dev scan-card agent.json

API Server with Dev Mode

# Enable dev mode via environment variable
export A2A_SCANNER_DEV_MODE=true

# Start API server
uv run a2a-scanner-api --reload

# Now all API requests allow localhost and skip SSL verification
curl -X POST http://localhost:8000/scan/endpoint \
  -H "Content-Type: application/json" \
  -d '{"endpoint_url": "http://localhost:8000"}'

Programmatic Usage

from a2ascanner.config.config import Config
from a2ascanner.core.scanner import Scanner

# Enable dev mode
config = Config(dev_mode=True)
scanner = Scanner(config)

# Scan localhost endpoint
result = await scanner.scan_endpoint("http://localhost:8000")

⚠️ Security Warning

DO NOT USE --dev IN PRODUCTION!

Dev mode disables critical security features:

• SSRF protection for localhost and private IPs
• SSL certificate verification
• Secure protocol enforcement

Use dev mode only in:

• Local development environments
• Internal testing networks
• CI/CD pipelines (isolated)

See DEV_MODE_GUIDE.md for complete documentation.

---

CLI Usage

The scanner provides several commands for different scanning scenarios:

Commands

• scan-card: Scan an agent card JSON file
• scan-file: Scan a single source code file
• scan-directory: Scan a directory of files
• scan-endpoint: Scan a live agent endpoint
• scan-registry: Scan agents from a registry
• list-analyzers: List available analyzers

Common Options

# Development mode (allows localhost, skips SSL verification)
--dev                       # Enable for local testing

# Debug and logging
--debug                     # Enable debug logging

# Select specific analyzers
--analyzers yara,spec,heuristic,llm,endpoint

# Output formats
--output results.json       # JSON output
--verbose                   # Detailed output

# Pattern matching
--pattern "*.py"           # File pattern matching

# Authentication
--bearer-token TOKEN       # Bearer token for endpoints
--no-verify-ssl            # Skip SSL verification (or use --dev)

Examples

Scan with YARA Rules Only

a2a-scanner scan-card agent.json --analyzers yara

Scan with LLM Analyzer

# Configure LLM (Azure OpenAI)
export A2A_SCANNER_LLM_PROVIDER=azure
export A2A_SCANNER_LLM_API_KEY=your-key
export A2A_SCANNER_LLM_MODEL=gpt-4
export A2A_SCANNER_LLM_BASE_URL=https://your-instance.openai.azure.com

# Scan with LLM
a2a-scanner scan-card agent.json --analyzers llm

Scan Multiple Files

# Scan all Python files in agents directory
a2a-scanner scan-directory ./agents --pattern "**/*.py"

---

API Server Usage

The API server provides a REST interface for integrating security scanning into applications and pipelines.

Start the Server

# Start on default port (8000)
a2a-scanner-api

# Custom host and port
a2a-scanner-api --host 0.0.0.0 --port 8080

# Development mode with auto-reload
a2a-scanner-api --reload

# Enable dev mode for local testing (allows localhost, skips SSL)
export A2A_SCANNER_DEV_MODE=true
a2a-scanner-api --reload

API Endpoints

Once running, the API provides:

• POST /scan/agent-card - Scan an agent card JSON
• POST /scan/source-code - Scan source code
• POST /scan/endpoint - Scan a live agent endpoint
• POST /scan/full - Full scan (all methods)
• GET /health - Health check endpoint
• GET / - API documentation

Example API Request

# Scan an agent card
curl -X POST http://localhost:8000/scan/agent-card \
  -H "Content-Type: application/json" \
  -d @agent_card.json

# Scan source code
curl -X POST http://localhost:8000/scan/source-code \
  -H "Content-Type: application/json" \
  -d '{"source_path": "/path/to/code"}'

Interactive API documentation is available at http://localhost:8000/docs when the server is running.

---

Threat Detection

The scanner detects threats across the entire A2A protocol stack:

Detection Methods

1. YARA Rules

Static pattern matching for detecting malicious patterns in agent cards, including agent impersonation, prompt injection, capability abuse, data exfiltration, routing manipulation, and tool poisoning attacks.

Location: a2ascanner/data/yara_rules/

2. Spec Analyzer

Validates A2A protocol compliance:

• Required field validation
• Data type checking
• URL format validation
• Skill structure verification
• Capability validation

3. Heuristic Analyzer

Logic-based detection:

• Suspicious URL patterns
• Cloud metadata access
• Command execution patterns
• Credential harvesting indicators

4. LLM Analyzer

AI-powered semantic analysis:

• Intent classification
• Context grounding
• Subtle manipulation detection
• Anomaly detection

5. Endpoint Analyzer

Dynamic security testing of running A2A agent endpoints to verify security posture and protocol compliance.

Security Checks:

• HTTPS enforcement - Verifies secure protocol usage (flags HTTP endpoints)
• Security headers validation - Checks for X-Content-Type-Options, X-Frame-Options, HSTS
• Agent card presence - Validates card exists at standard locations (/.well-known/agent-card.json)
• URL mismatch detection - Ensures agent card URL matches endpoint URL
• Health endpoint checks - Verifies /health or /healthz endpoints exist
• Network reachability - Tests endpoint accessibility and response time
• Protocol compliance - Validates A2A protocol adherence

Usage - CLI:

# Basic endpoint scan
uv run a2a-scanner scan-endpoint https://agent.example.com/api

# With authentication
uv run a2a-scanner scan-endpoint https://agent.example.com/api \
  --bearer-token "your-token-here"

# Scan with custom timeout
uv run a2a-scanner scan-endpoint https://agent.example.com/api \
  --timeout 60

# Local development endpoint (requires --dev flag)
uv run a2a-scanner --dev scan-endpoint http://localhost:8080

# Skip SSL verification (not recommended for production)
uv run a2a-scanner scan-endpoint https://agent.example.com/ \
  --no-verify-ssl

# Save results to JSON
uv run a2a-scanner scan-endpoint https://agent.example.com/api \
  --output results.json

Usage - Programmatic:

from a2ascanner.core.scanner import Scanner
from a2ascanner.config.config import Config
import asyncio

async def scan_agent_endpoint():
    # Create scanner instance
    config = Config(dev_mode=False)  # Set to True for localhost
    scanner = Scanner(config)
    
    # Scan endpoint
    result = await scanner.scan_endpoint(
        endpoint_url="https://agent.example.com/api",
        bearer_token="your-token",  # Optional
        timeout=30.0,               # Optional
        verify_ssl=True             # Optional
    )
    
    # Check results
    if result.threats:
        print(f"Found {len(result.threats)} security issues:")
        for threat in result.threats:
            print(f"  [{threat.severity}] {threat.summary}")
    else:
        print("Endpoint passed all security checks!")
    
    return result

# Run the scan
asyncio.run(scan_agent_endpoint())

Usage - API Server:

# Scan endpoint via REST API
curl -X POST http://localhost:8000/scan/endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://agent.example.com/api",
    "bearer_token": "your-token",
    "timeout": 30,
    "verify_ssl": true
  }'

Use Cases:

• Production audits - Regular security assessments of live agent endpoints
• CI/CD integration - Automated security checks before deployment
• Continuous monitoring - Periodic health and security validation
• Pre-deployment validation - Security verification before going live
• Compliance checking - Ensure endpoints meet security standards
• Registry validation - Verify agents in registry are properly configured

Common Issues Detected:

Issue	Severity	Description
Endpoint unreachable	HIGH	Agent endpoint is not responding or network error
Insecure HTTP	HIGH	Endpoint uses HTTP instead of HTTPS
Missing agent card	MEDIUM	No agent card found at standard locations
URL mismatch	MEDIUM	Agent card URL doesn't match endpoint URL
Missing security headers	MEDIUM	Missing X-Content-Type-Options, X-Frame-Options, or HSTS
No health endpoint	LOW	Missing /health or /healthz monitoring endpoint

Dev Mode for Local Testing:

When testing local development endpoints, use --dev flag:

# .github/workflows/security-scan.yml
name: A2A Security Scan

on:
  push:
    branches: [main]
  pull_request:

jobs:
  endpoint-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install A2A Scanner
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          uv sync
      
      - name: Scan endpoint
        run: |
          uv run a2a-scanner scan-endpoint \
            ${{ secrets.AGENT_ENDPOINT_URL }} \
            --bearer-token ${{ secrets.AGENT_TOKEN }} \
            --output scan-results.json
      
      - name: Upload results
        uses: actions/upload-artifact@v3
        with:
          name: security-scan-results
          path: scan-results.json

---

Configuration

Environment Variables

Configure the scanner using environment variables:

# LLM Analyzer Configuration
export A2A_SCANNER_LLM_PROVIDER=azure      # azure or openai
export A2A_SCANNER_LLM_API_KEY=your-key
export A2A_SCANNER_LLM_MODEL=gpt-4
export A2A_SCANNER_LLM_BASE_URL=https://your-instance.openai.azure.com
export A2A_SCANNER_LLM_API_VERSION=2025-01-01-preview

# API Server Configuration
export A2A_SCANNER_API_HOST=0.0.0.0
export A2A_SCANNER_API_PORT=8000

# Proxy Configuration
export A2A_SCANNER_PROXY_PORT=8080

Configuration File

Alternatively, use a .env file in the project root:

cp .env.example .env
# Edit .env with your configuration

---

Testing

Validate Installation

# List available analyzers
a2a-scanner list-analyzers

# Run health check
curl http://localhost:8000/health

Test on Sample Agents

# Scan safe agent card
a2a-scanner scan-card examples/sample_agent_cards/safe_agent.json

# Scan unsafe agent card
a2a-scanner scan-card examples/sample_agent_cards/unsafe_agent.json

Run Test Suite

Using UV (Recommended)

# Install test dependencies
uv pip install pytest pytest-asyncio pytest-cov

# Run all tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=a2ascanner --cov-report=term

# Run specific test file
uv run pytest tests/test_api.py -v

Using pip

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=a2ascanner --cov-report=term

---

For Developers

Demonstrations

Comprehensive Analyzer Demo

Location: examples/comprehensive_demo.py

All-in-one demonstration showcasing all analyzers with professional terminal output.

# Full interactive demo
uv run python examples/comprehensive_demo.py

# Quick mode (no pauses)
uv run python examples/comprehensive_demo.py --quick

# Test specific analyzer
uv run python examples/comprehensive_demo.py --analyzer yara

Interactive Analyzer Demo

Location: examples/interactive_demo.py

Hands-on interactive demo where you provide the data to scan.

# Run interactive demo with dev mode (for localhost testing)
uv run python examples/interactive_demo.py --dev

# Run without dev mode (production testing)
uv run python examples/interactive_demo.py

Available Analyzers:

1. YARA - Pattern-based threat detection using compiled YARA rules
2. Spec - A2A protocol compliance validation (required fields, formats, structures)
3. Heuristic - Logic-based security checks (URL patterns, superlative language)
4. Endpoint - Live endpoint security audit (HTTPS, headers, health checks)
5. LLM - AI-powered semantic analysis (requires API key configuration)

Input Options:

• Agent Cards: File path, direct JSON input, URL fetch, or sample malicious card
• Endpoints: Custom URL with dev mode option for localhost testing

Example Session:

$ uv run python examples/interactive_demo.py --dev

Select analyzer to test:
  1. YARA      - Pattern-based threat detection
  2. Spec      - A2A protocol compliance
  3. Heuristic - Logic-based security checks
  4. Endpoint  - Live endpoint security audit

Your choice [1-4]: 2

How would you like to provide the agent card?
  1. Path to JSON file
  2. Direct JSON input
  3. URL to fetch agent card
  4. Use sample malicious agent card

Your choice [1-4]: 4

Results from SPEC Analyzer:
⚠️  Found 3 potential threat(s):
  • HIGH: Missing required field 'skills'
  • MEDIUM: Invalid capabilities type
  • LOW: Missing 'id' field

Static Analysis Examples

See the examples/ directory for static file analysis:

• Malicious agent card examples - Various spoofing techniques
• Tool poisoning demonstrations - Malicious tool definitions
• Registry poisoning examples - Mass registration attacks

Example threat files include:

• tool_poison.py - Tool poisoning with exfiltration
• context_poison_writer.py - Context contamination
• judge_persuade.py - Routing manipulation

---

🛠️ Development

Setup Development Environment

# Clone repository
git clone https://github.com/cisco-ai-defense/a2a-scanner.git
cd a2a-scanner

# Install UV
brew install uv
# or: curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies
uv sync

# Add development dependencies
uv add --dev pytest pytest-asyncio pytest-cov

# Verify installation
uv run a2a-scanner list-analyzers

Running Tests

# Run all tests
uv run pytest tests/ -q

# Verbose output
uv run pytest tests/ -v

# With coverage report
uv run pytest tests/ --cov=a2ascanner --cov-report=term-missing

# Run specific test categories
uv run pytest tests/test_api.py          # API tests
uv run pytest tests/test_analyzers.py    # Analyzer tests
uv run pytest tests/test_yara.py         # YARA rule tests
uv run pytest tests/test_heuristic.py    # Heuristic tests

Managing Dependencies

# Add a runtime dependency
uv add <package-name>

# Add a development dependency
uv add --dev <package-name>

# Update all dependencies
uv sync --upgrade

# Remove a dependency
uv remove <package-name>

About UV

UV is a fast Python package manager and environment manager written in Rust:

• Fast dependency resolution (10-100x faster than pip)
• Reproducible builds with lock files
• Smart caching system
• Automatic environment management
• Built-in Python version management

Common Commands

# Run commands without activating venv
uv run <command>

# Examples
uv run a2a-scanner scan-card test.json
uv run pytest tests/
uv run python script.py

# Sync environment
uv sync

# Show installed packages
uv pip list

# Lock dependencies
uv lock

Manual Environment Activation

If you prefer traditional activation:

source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Then use commands directly
a2a-scanner scan-card test.json
pytest tests/

---

Documentation

For detailed documentation, see the docs/ directory:

• CONTRIBUTING.md - Contribution guidelines
• DEV_MODE_GUIDE.md - Development mode documentation
• docs/architecture.md - System architecture
• docs/analyzer_guide.md - Analyzer implementation guide
• docs/usage_guide.md - Comprehensive usage guide
• docs/testing_guide.md - Testing documentation
• docs/a2a-threats-taxonomy.md - A2A threat taxonomy reference
• docs/scanner_placement_guide.md - Scanner placement strategies

---

Contact Cisco for AI Defense

For enterprise-grade A2A security solutions and support:

Cisco AI Defense: https://www.cisco.com/site/us/en/products/security/ai-defense/index.html

---

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Copyright 2025 Cisco Systems, Inc. and its affiliates

---

Related Projects

• A2A Protocol - Official A2A specification
• A2A Samples - Example agent implementations
• Cisco AI Defense A2A Scanner - Agent-to-Agent (A2A) Protocol Scanner

---

About

A2A Security Scanner provides comprehensive security analysis for Agent-to-Agent protocol implementations, combining static analysis, runtime monitoring, and AI-powered detection to identify vulnerabilities across the A2A protocol stack.

Topics

security ai a2a agents yara llm threat-detection

---

Project Link: https://github.com/cisco-ai-defense/a2a-scanner