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

Prerequisites

Python 3.11+
uv (Python package manager) - recommended
LLM Provider API Key (optional, for LLM analyzer)

Installing as a CLI Tool

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

uv tool install --python 3.13 cisco-ai-a2a-scanner

# Verify installation
a2a-scanner list-analyzers

Alternatively, you can install from source:

uv tool install --python 3.13 --from git+https://github.com/cisco-ai-defense/a2a-scanner cisco-ai-a2a-scanner

# Verify installation
a2a-scanner list-analyzers

Installing for Local Development

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

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# or: brew install uv

uv sync

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

# Verify installation
a2a-scanner list-analyzers

Install as a Dependency in Other Projects

Add A2A Scanner as a dependency using uv. From your project root (initialize with uv if needed):

uv init  # if not already done
uv add cisco-ai-a2a-scanner
# then activate the virtual environment:
# macOS and Linux: source .venv/bin/activate
# Windows CMD: .venv\Scripts\activate
# Windows PWSH: .venv\Scripts\Activate.ps1
uv sync

The module name is a2ascanner. Import this module with:

# import everything (not recommended)
import a2ascanner

# selective imports (recommended). For example:
from a2ascanner import Scanner, Config
from a2ascanner.core.models import ThreatSeverity

Quick Start

Scan an Agent Card

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

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

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

Scan Source Code

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

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

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

Scan Live Agent Endpoint

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

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

🎮 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
a2a-scanner --dev scan-endpoint http://localhost:8000

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

# Scan agent card from local URL
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
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
a2a-scanner scan-endpoint https://agent.example.com/api

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

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

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

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

# Save results to JSON
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: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
      
      - name: Install A2A Scanner
        run: uv tool install --python 3.13 cisco-ai-a2a-scanner
      
      - name: Scan endpoint
        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

# Run all tests
pytest tests/

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

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

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:

YARA - Pattern-based threat detection using compiled YARA rules
Spec - A2A protocol compliance validation (required fields, formats, structures)
Heuristic - Logic-based security checks (URL patterns, superlative language)
Endpoint - Live endpoint security audit (HTTPS, headers, health checks)
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 (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# or: brew install uv

# Sync dependencies
uv sync

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

# Verify installation
a2a-scanner list-analyzers

Running Tests

After activating the virtual environment (source .venv/bin/activate):

# Run all tests
pytest tests/ -q

# Verbose output
pytest tests/ -v

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

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

Note: You can also use uv run pytest tests/ without activating the virtual environment.

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

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

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

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.

Related Projects

A2A Protocol - Official A2A specification
A2A Samples - Example agent implementations

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

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
a2ascanner		a2ascanner
docs		docs
examples		examples
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEV_MODE_GUIDE.md		DEV_MODE_GUIDE.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

cisco-ai-defense/a2a-scanner

Folders and files

Latest commit

History

Repository files navigation

A2A Security Scanner

Overview

Key Features

Installation

Prerequisites

Installing as a CLI Tool

Installing for Local Development

Install as a Dependency in Other Projects

Quick Start

Scan an Agent Card

Scan Source Code

Scan Live Agent Endpoint

🎮 Try Interactive Demo

Development Mode

What Dev Mode Does

CLI Usage

API Server with Dev Mode

Programmatic Usage

⚠️ Security Warning

CLI Usage

Commands

Common Options

Examples

Scan with YARA Rules Only

Scan with LLM Analyzer

Scan Multiple Files

API Server Usage

Start the Server

API Endpoints

Example API Request

Threat Detection

Detection Methods

1. YARA Rules

2. Spec Analyzer

3. Heuristic Analyzer

4. LLM Analyzer

5. Endpoint Analyzer

Configuration

Environment Variables

Configuration File

Testing

Validate Installation

Test on Sample Agents

Run Test Suite

For Developers

Demonstrations

Comprehensive Analyzer Demo

Interactive Analyzer Demo

Static Analysis Examples

🛠️ Development

Setup Development Environment

Running Tests

Managing Dependencies

About UV

Common Commands

Documentation

Contact Cisco for AI Defense

License

Related Projects

About

Topics

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Uh oh!