From e797654c11687826054e687e48a2d2b5c4caf319 Mon Sep 17 00:00:00 2001 From: Sanket Mendapara Date: Thu, 11 Dec 2025 11:02:40 -0800 Subject: [PATCH 1/5] updating package installation instructions --- README.md | 181 ++++++++++++++++++++++++------------------ docs/testing_guide.md | 49 ++++++++++-- docs/usage_guide.md | 45 ++++++++--- 3 files changed, 180 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 19d41ec..facefe3 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/) +[![PyPI](https://img.shields.io/pypi/v/cisco-ai-a2a-scanner)](https://pypi.org/project/cisco-ai-a2a-scanner/) [![UV](https://img.shields.io/badge/uv-compatible-green)](https://github.com/astral-sh/uv) **Scan Agent-to-Agent (A2A) protocol implementations for security threats and vulnerabilities.** @@ -24,31 +25,62 @@ The A2A Security Scanner provides comprehensive security analysis for Agent-to-A ## Installation -### Quick Install +### Prerequisites -**Using UV (Recommended)** +- Python 3.11+ +- uv (Python package manager) - recommended +- LLM Provider API Key (optional, for LLM analyzer) + +### Installing from PyPI + +**Using uv (Recommended)** ```bash # Install UV brew install uv # or: curl -LsSf https://astral.sh/uv/install.sh | sh -# Clone the repository +uv venv -p /path/to/your/choice/of/venv/directory +source /path/to/your/choice/of/venv/directory/bin/activate +uv pip install cisco-ai-a2a-scanner + +# Verify installation +a2a-scanner list-analyzers +``` + +**Using pip** + +```bash +pip install cisco-ai-a2a-scanner + +# Verify installation +a2a-scanner list-analyzers +``` + +### Installing from Source + +```bash git clone https://github.com/cisco-ai-defense/a2a-scanner.git cd a2a-scanner -# Install dependencies +# Install UV (if not already installed) +brew install uv +# or: curl -LsSf https://astral.sh/uv/install.sh | sh + +# Install with uv sync (recommended) uv sync # Verify installation uv run a2a-scanner list-analyzers -``` -### Requirements +# Or install with uv venv + pip +uv venv -p /path/to/your/choice/of/venv/directory +source /path/to/your/choice/of/venv/directory/bin/activate +uv pip install -e . -- **Python**: 3.11 or higher -- **Package Manager**: UV (recommended) or pip -- **Optional**: Azure OpenAI API key for LLM analyzer +# Alternatively, using pip +pip install -e . +``` --- @@ -90,7 +122,7 @@ uv run a2a-scanner scan-endpoint https://agent.example.com/api 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` +> **Note**: After activating your virtual environment or installing via pip, you can run commands directly without the `uv run` prefix (e.g., `a2a-scanner scan-card agent.json`). ### 🎮 Try Interactive Demo @@ -468,14 +500,24 @@ jobs: 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: | - curl -LsSf https://astral.sh/uv/install.sh | sh - uv sync + uv venv .venv + source .venv/bin/activate + uv pip install cisco-ai-a2a-scanner - name: Scan endpoint run: | - uv run a2a-scanner scan-endpoint \ + source .venv/bin/activate + a2a-scanner scan-endpoint \ ${{ secrets.AGENT_ENDPOINT_URL }} \ --bearer-token ${{ secrets.AGENT_TOKEN }} \ --output scan-results.json @@ -546,33 +588,19 @@ a2a-scanner scan-card examples/sample_agent_cards/unsafe_agent.json ### Run Test Suite -**Using UV (Recommended)** - -```bash -# 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** - ```bash # Install test dependencies pip install pytest pytest-asyncio pytest-cov +# or: uv pip install pytest pytest-asyncio pytest-cov # 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 ``` --- @@ -671,6 +699,8 @@ Example threat files include: ### Setup Development Environment +**Using uv (Recommended)** + ```bash # Clone repository git clone https://github.com/cisco-ai-defense/a2a-scanner.git @@ -680,49 +710,69 @@ cd a2a-scanner brew install uv # or: curl -LsSf https://astral.sh/uv/install.sh | sh -# Sync dependencies -uv sync +# Create virtual environment and install +uv venv -p .venv +source .venv/bin/activate +uv pip install -e . -# Add development dependencies -uv add --dev pytest pytest-asyncio pytest-cov +# Verify installation +a2a-scanner list-analyzers +``` + +**Using pip** + +```bash +# Clone repository +git clone https://github.com/cisco-ai-defense/a2a-scanner.git +cd a2a-scanner + +# Create virtual environment +python -m venv .venv +source .venv/bin/activate # Linux/macOS +# .venv\Scripts\activate # Windows + +# Install in development mode +pip install -e . # Verify installation -uv run a2a-scanner list-analyzers +a2a-scanner list-analyzers ``` ### Running Tests ```bash +# Install test dependencies +pip install pytest pytest-asyncio pytest-cov +# or: uv pip install pytest pytest-asyncio pytest-cov + # Run all tests -uv run pytest tests/ -q +pytest tests/ -q # Verbose output -uv run pytest tests/ -v +pytest tests/ -v # With coverage report -uv run pytest tests/ --cov=a2ascanner --cov-report=term-missing +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 +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 ``` ### Managing Dependencies ```bash -# Add a runtime dependency -uv add - -# Add a development dependency -uv add --dev - -# Update all dependencies -uv sync --upgrade +# Using uv +uv pip install +uv pip install --upgrade +uv pip list -# Remove a dependency -uv remove +# Using pip +pip install +pip install --upgrade +pip list ``` ### About UV @@ -738,35 +788,14 @@ UV is a fast Python package manager and environment manager written in Rust: ### Common Commands ```bash -# Run commands without activating venv -uv run - -# 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: - -```bash +# 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 ``` --- diff --git a/docs/testing_guide.md b/docs/testing_guide.md index 7b2b329..38cc0e7 100644 --- a/docs/testing_guide.md +++ b/docs/testing_guide.md @@ -8,13 +8,36 @@ This guide shows you how to run and test the A2A Scanner using the example threa ### 1. Install the Scanner +**Using uv (Recommended)** + ```bash -cd a2a-scanner +# Installing from PyPI (recommended) +uv venv -p /path/to/your/choice/of/venv/directory +source /path/to/your/choice/of/venv/directory/bin/activate +uv pip install cisco-ai-a2a-scanner -# Install with uv (recommended) +# Or install from source with uv sync +git clone https://github.com/cisco-ai-defense/a2a-scanner.git +cd a2a-scanner uv sync -# Or install with pip +# Or install from source with uv venv + pip +git clone https://github.com/cisco-ai-defense/a2a-scanner.git +cd a2a-scanner +uv venv -p /path/to/your/choice/of/venv/directory +source /path/to/your/choice/of/venv/directory/bin/activate +uv pip install -e . +``` + +**Using pip** + +```bash +# Installing from PyPI +pip install cisco-ai-a2a-scanner + +# Or install from source +git clone https://github.com/cisco-ai-defense/a2a-scanner.git +cd a2a-scanner pip install -e . ``` @@ -262,9 +285,15 @@ a2a-scanner scan-file examples/a2a_threat_files/judge_persuade.py ### Issue: Command not found ```bash -# Solution: Install the package -uv sync -# Or +# Solution: Install the package from PyPI using uv +uv venv .venv +source .venv/bin/activate +uv pip install cisco-ai-a2a-scanner + +# Or using pip +pip install cisco-ai-a2a-scanner + +# Or from source pip install -e . ``` @@ -354,12 +383,18 @@ jobs: with: python-version: '3.12' + - name: Install uv + run: curl -LsSf https://astral.sh/uv/install.sh | sh + - name: Install scanner run: | - pip install -e . + uv venv .venv + source .venv/bin/activate + uv pip install cisco-ai-a2a-scanner - name: Scan for threats run: | + source .venv/bin/activate a2a-scanner scan-directory examples/a2a_threat_files -a yara -a pattern ``` diff --git a/docs/usage_guide.md b/docs/usage_guide.md index f840fe1..9534e3f 100644 --- a/docs/usage_guide.md +++ b/docs/usage_guide.md @@ -4,27 +4,41 @@ ### Prerequisites -- Python 3.11 or higher -- pip or uv package manager +- Python 3.11+ +- uv (Python package manager) - recommended -### Install from PyPI +### Installing from PyPI + +**Using uv (Recommended)** ```bash -pip install a2a-scanner +uv venv -p /path/to/your/choice/of/venv/directory +source /path/to/your/choice/of/venv/directory/bin/activate +uv pip install cisco-ai-a2a-scanner ``` -### Install from source +**Using pip** ```bash -git clone https://github.com/your-org/a2a-scanner.git -cd a2a-scanner -pip install -e . +pip install cisco-ai-a2a-scanner ``` -### Install with development dependencies +### Installing from Source ```bash -pip install -e ".[dev]" +git clone https://github.com/cisco-ai-defense/a2a-scanner.git +cd a2a-scanner + +# Install with uv sync (recommended - uses lockfile for reproducible builds) +uv sync + +# Or install with uv venv + pip +uv venv -p /path/to/your/choice/of/venv/directory +source /path/to/your/choice/of/venv/directory/bin/activate +uv pip install -e . + +# Or using pip +pip install -e . ``` ## Configuration @@ -392,15 +406,22 @@ jobs: - uses: actions/checkout@v2 - name: Set up Python - uses: actions/setup-python@v2 + 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 scanner - run: pip install a2a-scanner + run: | + uv venv .venv + source .venv/bin/activate + uv pip install cisco-ai-a2a-scanner - name: Scan agent cards run: | + source .venv/bin/activate a2a-scanner scan-directory agents/ -o results/ - name: Check for high severity From 112cbff1e6408cf6b2ee6ab6c2bd51d9cb4471ba Mon Sep 17 00:00:00 2001 From: Sanket Mendapara Date: Thu, 11 Dec 2025 11:51:12 -0800 Subject: [PATCH 2/5] Updating uv tools commands --- README.md | 153 ++++++++++++++++++++---------------------- docs/testing_guide.md | 58 +++++++--------- docs/usage_guide.md | 74 +++++++++++++------- 3 files changed, 148 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index facefe3..8f049bb 100644 --- a/README.md +++ b/README.md @@ -31,33 +31,29 @@ The A2A Security Scanner provides comprehensive security analysis for Agent-to-A - uv (Python package manager) - recommended - LLM Provider API Key (optional, for LLM analyzer) -### Installing from PyPI - -**Using uv (Recommended)** +### Installing as a CLI Tool ```bash # Install UV brew install uv # or: curl -LsSf https://astral.sh/uv/install.sh | sh -uv venv -p /path/to/your/choice/of/venv/directory -source /path/to/your/choice/of/venv/directory/bin/activate -uv pip install cisco-ai-a2a-scanner +uv tool install --python 3.13 cisco-ai-a2a-scanner # Verify installation a2a-scanner list-analyzers ``` -**Using pip** +Alternatively, you can install from source: ```bash -pip install cisco-ai-a2a-scanner +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 from Source +### Installing for Local Development ```bash git clone https://github.com/cisco-ai-defense/a2a-scanner.git @@ -67,19 +63,39 @@ cd a2a-scanner brew install uv # or: curl -LsSf https://astral.sh/uv/install.sh | sh -# Install with uv sync (recommended) uv sync +# Activate virtual environment +source .venv/bin/activate # Linux/macOS +# .venv\Scripts\activate # Windows + # Verify installation -uv run a2a-scanner list-analyzers +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): + +```bash +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: -# Or install with uv venv + pip -uv venv -p /path/to/your/choice/of/venv/directory -source /path/to/your/choice/of/venv/directory/bin/activate -uv pip install -e . +```python +# import everything (not recommended) +import a2ascanner -# Alternatively, using pip -pip install -e . +# selective imports (recommended). For example: +from a2ascanner import Scanner, Config +from a2ascanner.core.models import ThreatSeverity ``` --- @@ -90,40 +106,38 @@ pip install -e . ```bash # Scan a JSON agent card file -uv run a2a-scanner scan-card examples/sample_agent_cards/unsafe_agent.json +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 +a2a-scanner scan-card agent.json --analyzers yara,spec # JSON output -uv run a2a-scanner scan-card agent.json --output results.json +a2a-scanner scan-card agent.json --output results.json ``` ### Scan Source Code ```bash # Scan a directory -uv run a2a-scanner scan-directory /path/to/agent/code +a2a-scanner scan-directory /path/to/agent/code # Scan a single file -uv run a2a-scanner scan-file agent.py +a2a-scanner scan-file agent.py # Scan with pattern -uv run a2a-scanner scan-directory ./agents --pattern "**/*.py" +a2a-scanner scan-directory ./agents --pattern "**/*.py" ``` ### Scan Live Agent Endpoint ```bash # Scan a running agent -uv run a2a-scanner scan-endpoint https://agent.example.com/api +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" +a2a-scanner scan-endpoint https://agent.example.com/api --bearer-token "$TOKEN" ``` -> **Note**: After activating your virtual environment or installing via pip, you can run commands directly without the `uv run` prefix (e.g., `a2a-scanner scan-card agent.json`). - ### 🎮 Try Interactive Demo Want to see the analyzers in action? Run the interactive demo: @@ -162,13 +176,13 @@ When `--dev` is enabled, the scanner allows: ```bash # Scan local agent endpoint -uv run a2a-scanner --dev scan-endpoint http://localhost:8000 +a2a-scanner --dev scan-endpoint http://localhost:8000 # Scan with debug logging -uv run a2a-scanner --dev --debug scan-endpoint http://localhost:9999 +a2a-scanner --dev --debug scan-endpoint http://localhost:9999 # Scan agent card from local URL -uv run a2a-scanner --dev scan-card agent.json +a2a-scanner --dev scan-card agent.json ``` ### API Server with Dev Mode @@ -178,7 +192,7 @@ uv run a2a-scanner --dev scan-card agent.json export A2A_SCANNER_DEV_MODE=true # Start API server -uv run a2a-scanner-api --reload +a2a-scanner-api --reload # Now all API requests allow localhost and skip SSL verification curl -X POST http://localhost:8000/scan/endpoint \ @@ -392,25 +406,25 @@ Dynamic security testing of running A2A agent endpoints to verify security postu ```bash # Basic endpoint scan -uv run a2a-scanner scan-endpoint https://agent.example.com/api +a2a-scanner scan-endpoint https://agent.example.com/api # With authentication -uv run a2a-scanner scan-endpoint https://agent.example.com/api \ +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 \ +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 +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/ \ +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 \ +a2a-scanner scan-endpoint https://agent.example.com/api \ --output results.json ``` @@ -509,14 +523,10 @@ jobs: run: curl -LsSf https://astral.sh/uv/install.sh | sh - name: Install A2A Scanner - run: | - uv venv .venv - source .venv/bin/activate - uv pip install cisco-ai-a2a-scanner + run: uv tool install --python 3.13 cisco-ai-a2a-scanner - name: Scan endpoint run: | - source .venv/bin/activate a2a-scanner scan-endpoint \ ${{ secrets.AGENT_ENDPOINT_URL }} \ --bearer-token ${{ secrets.AGENT_TOKEN }} \ @@ -589,10 +599,6 @@ a2a-scanner scan-card examples/sample_agent_cards/unsafe_agent.json ### Run Test Suite ```bash -# Install test dependencies -pip install pytest pytest-asyncio pytest-cov -# or: uv pip install pytest pytest-asyncio pytest-cov - # Run all tests pytest tests/ @@ -699,52 +705,31 @@ Example threat files include: ### Setup Development Environment -**Using uv (Recommended)** - ```bash # Clone repository git clone https://github.com/cisco-ai-defense/a2a-scanner.git cd a2a-scanner -# Install UV +# Install UV (if not already installed) brew install uv # or: curl -LsSf https://astral.sh/uv/install.sh | sh -# Create virtual environment and install -uv venv -p .venv -source .venv/bin/activate -uv pip install -e . - -# Verify installation -a2a-scanner list-analyzers -``` - -**Using pip** - -```bash -# Clone repository -git clone https://github.com/cisco-ai-defense/a2a-scanner.git -cd a2a-scanner +# Sync dependencies +uv sync -# Create virtual environment -python -m venv .venv +# Activate virtual environment source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows -# Install in development mode -pip install -e . - # Verify installation a2a-scanner list-analyzers ``` ### Running Tests -```bash -# Install test dependencies -pip install pytest pytest-asyncio pytest-cov -# or: uv pip install pytest pytest-asyncio pytest-cov +After activating the virtual environment (`source .venv/bin/activate`): +```bash # Run all tests pytest tests/ -q @@ -761,18 +746,22 @@ 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 ```bash -# Using uv -uv pip install -uv pip install --upgrade -uv pip list - -# Using pip -pip install -pip install --upgrade -pip list +# Add a runtime dependency +uv add + +# Add a development dependency +uv add --dev + +# Update all dependencies +uv sync --upgrade + +# Remove a dependency +uv remove ``` ### About UV diff --git a/docs/testing_guide.md b/docs/testing_guide.md index 38cc0e7..4455778 100644 --- a/docs/testing_guide.md +++ b/docs/testing_guide.md @@ -8,43 +8,44 @@ This guide shows you how to run and test the A2A Scanner using the example threa ### 1. Install the Scanner -**Using uv (Recommended)** +**Installing as a CLI Tool** ```bash -# Installing from PyPI (recommended) -uv venv -p /path/to/your/choice/of/venv/directory -source /path/to/your/choice/of/venv/directory/bin/activate -uv pip install cisco-ai-a2a-scanner +# Install UV +brew install uv +# or: curl -LsSf https://astral.sh/uv/install.sh | sh -# Or install from source with uv sync -git clone https://github.com/cisco-ai-defense/a2a-scanner.git -cd a2a-scanner -uv sync - -# Or install from source with uv venv + pip -git clone https://github.com/cisco-ai-defense/a2a-scanner.git -cd a2a-scanner -uv venv -p /path/to/your/choice/of/venv/directory -source /path/to/your/choice/of/venv/directory/bin/activate -uv pip install -e . +uv tool install --python 3.13 cisco-ai-a2a-scanner ``` -**Using pip** +Alternatively, you can install from source: ```bash -# Installing from PyPI -pip install cisco-ai-a2a-scanner +uv tool install --python 3.13 --from git+https://github.com/cisco-ai-defense/a2a-scanner cisco-ai-a2a-scanner +``` -# Or install from source +**Installing for Local Development** + +```bash git clone https://github.com/cisco-ai-defense/a2a-scanner.git cd a2a-scanner -pip install -e . + +# Install UV (if not already installed) +brew install uv +# or: curl -LsSf https://astral.sh/uv/install.sh | sh + +uv sync + +# Activate virtual environment +source .venv/bin/activate # Linux/macOS +# .venv\Scripts\activate # Windows ``` ### 2. Verify Installation ```bash # Check CLI is available +a2a-scanner list-analyzers a2a-scanner --help # Should show available commands: @@ -285,10 +286,8 @@ a2a-scanner scan-file examples/a2a_threat_files/judge_persuade.py ### Issue: Command not found ```bash -# Solution: Install the package from PyPI using uv -uv venv .venv -source .venv/bin/activate -uv pip install cisco-ai-a2a-scanner +# Solution: Install the package from PyPI using uv (recommended) +uv tool install --python 3.13 cisco-ai-a2a-scanner # Or using pip pip install cisco-ai-a2a-scanner @@ -387,15 +386,10 @@ jobs: run: curl -LsSf https://astral.sh/uv/install.sh | sh - name: Install scanner - run: | - uv venv .venv - source .venv/bin/activate - uv pip install cisco-ai-a2a-scanner + run: uv tool install --python 3.13 cisco-ai-a2a-scanner - name: Scan for threats - run: | - source .venv/bin/activate - a2a-scanner scan-directory examples/a2a_threat_files -a yara -a pattern + run: a2a-scanner scan-directory examples/a2a_threat_files -a yara -a pattern ``` --- diff --git a/docs/usage_guide.md b/docs/usage_guide.md index 9534e3f..29836c6 100644 --- a/docs/usage_guide.md +++ b/docs/usage_guide.md @@ -7,38 +7,71 @@ - Python 3.11+ - uv (Python package manager) - recommended -### Installing from PyPI - -**Using uv (Recommended)** +### Installing as a CLI Tool ```bash -uv venv -p /path/to/your/choice/of/venv/directory -source /path/to/your/choice/of/venv/directory/bin/activate -uv pip install cisco-ai-a2a-scanner +# Install UV +brew install uv +# or: curl -LsSf https://astral.sh/uv/install.sh | sh + +uv tool install --python 3.13 cisco-ai-a2a-scanner + +# Verify installation +a2a-scanner list-analyzers ``` -**Using pip** +Alternatively, you can install from source: ```bash -pip install cisco-ai-a2a-scanner +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 from Source +### Installing for Local Development ```bash git clone https://github.com/cisco-ai-defense/a2a-scanner.git cd a2a-scanner -# Install with uv sync (recommended - uses lockfile for reproducible builds) +# Install UV (if not already installed) +brew install uv +# or: curl -LsSf https://astral.sh/uv/install.sh | sh + +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): + +```bash +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 +``` -# Or install with uv venv + pip -uv venv -p /path/to/your/choice/of/venv/directory -source /path/to/your/choice/of/venv/directory/bin/activate -uv pip install -e . +The module name is `a2ascanner`. Import this module with: -# Or using pip -pip install -e . +```python +# import everything (not recommended) +import a2ascanner + +# selective imports (recommended). For example: +from a2ascanner import Scanner, Config +from a2ascanner.core.models import ThreatSeverity ``` ## Configuration @@ -414,15 +447,10 @@ jobs: run: curl -LsSf https://astral.sh/uv/install.sh | sh - name: Install scanner - run: | - uv venv .venv - source .venv/bin/activate - uv pip install cisco-ai-a2a-scanner + run: uv tool install --python 3.13 cisco-ai-a2a-scanner - name: Scan agent cards - run: | - source .venv/bin/activate - a2a-scanner scan-directory agents/ -o results/ + run: a2a-scanner scan-directory agents/ -o results/ - name: Check for high severity run: | From 2f5909697341a3857c3f5c9848ab25139d8bed05 Mon Sep 17 00:00:00 2001 From: Sanket Mendapara Date: Thu, 11 Dec 2025 11:51:54 -0800 Subject: [PATCH 3/5] Removing upper python version bound --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index fc1b363..0c60a51 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,7 +10,7 @@ authors = [ {name = "Cisco"}, ] readme = "README.md" -requires-python = ">=3.11,<3.14" +requires-python = ">=3.11" classifiers = [ "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", From 42c486a2438f338f3e6785080f952b7c1bf58069 Mon Sep 17 00:00:00 2001 From: Sanket Mendapara Date: Thu, 11 Dec 2025 11:56:45 -0800 Subject: [PATCH 4/5] Updating uv install instructions --- README.md | 12 ++++++------ docs/testing_guide.md | 8 ++++---- docs/usage_guide.md | 8 ++++---- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 8f049bb..bee49a1 100644 --- a/README.md +++ b/README.md @@ -35,8 +35,8 @@ The A2A Security Scanner provides comprehensive security analysis for Agent-to-A ```bash # Install UV -brew install uv -# or: curl -LsSf https://astral.sh/uv/install.sh | sh +curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv uv tool install --python 3.13 cisco-ai-a2a-scanner @@ -60,8 +60,8 @@ git clone https://github.com/cisco-ai-defense/a2a-scanner.git cd a2a-scanner # Install UV (if not already installed) -brew install uv -# or: curl -LsSf https://astral.sh/uv/install.sh | sh +curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv uv sync @@ -711,8 +711,8 @@ git clone https://github.com/cisco-ai-defense/a2a-scanner.git cd a2a-scanner # Install UV (if not already installed) -brew install uv -# or: curl -LsSf https://astral.sh/uv/install.sh | sh +curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv # Sync dependencies uv sync diff --git a/docs/testing_guide.md b/docs/testing_guide.md index 4455778..ee8b52b 100644 --- a/docs/testing_guide.md +++ b/docs/testing_guide.md @@ -12,8 +12,8 @@ This guide shows you how to run and test the A2A Scanner using the example threa ```bash # Install UV -brew install uv -# or: curl -LsSf https://astral.sh/uv/install.sh | sh +curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv uv tool install --python 3.13 cisco-ai-a2a-scanner ``` @@ -31,8 +31,8 @@ git clone https://github.com/cisco-ai-defense/a2a-scanner.git cd a2a-scanner # Install UV (if not already installed) -brew install uv -# or: curl -LsSf https://astral.sh/uv/install.sh | sh +curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv uv sync diff --git a/docs/usage_guide.md b/docs/usage_guide.md index 29836c6..e6ee495 100644 --- a/docs/usage_guide.md +++ b/docs/usage_guide.md @@ -11,8 +11,8 @@ ```bash # Install UV -brew install uv -# or: curl -LsSf https://astral.sh/uv/install.sh | sh +curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv uv tool install --python 3.13 cisco-ai-a2a-scanner @@ -36,8 +36,8 @@ git clone https://github.com/cisco-ai-defense/a2a-scanner.git cd a2a-scanner # Install UV (if not already installed) -brew install uv -# or: curl -LsSf https://astral.sh/uv/install.sh | sh +curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv uv sync From 51dd0ed539d872401c2ccf224bb0d600eb41afbf Mon Sep 17 00:00:00 2001 From: Sanket Mendapara Date: Thu, 11 Dec 2025 11:59:40 -0800 Subject: [PATCH 5/5] Updating links --- README.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index bee49a1..f28a5dd 100644 --- a/README.md +++ b/README.md @@ -228,7 +228,7 @@ Use dev mode only in: - Internal testing networks - CI/CD pipelines (isolated) -See [`DEV_MODE_GUIDE.md`](DEV_MODE_GUIDE.md) for complete documentation. +See [`DEV_MODE_GUIDE.md`](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/DEV_MODE_GUIDE.md) for complete documentation. --- @@ -791,16 +791,16 @@ python script.py ## Documentation -For detailed documentation, see the `docs/` directory: +For detailed documentation, see the [docs/](https://github.com/cisco-ai-defense/a2a-scanner/tree/main/docs) directory: -- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution guidelines -- **[DEV_MODE_GUIDE.md](./DEV_MODE_GUIDE.md)** - Development mode documentation -- **[docs/architecture.md](./docs/architecture.md)** - System architecture -- **[docs/analyzer_guide.md](./docs/analyzer_guide.md)** - Analyzer implementation guide -- **[docs/usage_guide.md](./docs/usage_guide.md)** - Comprehensive usage guide -- **[docs/testing_guide.md](./docs/testing_guide.md)** - Testing documentation -- **[docs/a2a-threats-taxonomy.md](./docs/a2a-threats-taxonomy.md)** - A2A threat taxonomy reference -- **[docs/scanner_placement_guide.md](./docs/scanner_placement_guide.md)** - Scanner placement strategies +- **[CONTRIBUTING.md](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/CONTRIBUTING.md)** - Contribution guidelines +- **[DEV_MODE_GUIDE.md](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/DEV_MODE_GUIDE.md)** - Development mode documentation +- **[docs/architecture.md](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/docs/architecture.md)** - System architecture +- **[docs/analyzer_guide.md](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/docs/analyzer_guide.md)** - Analyzer implementation guide +- **[docs/usage_guide.md](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/docs/usage_guide.md)** - Comprehensive usage guide +- **[docs/testing_guide.md](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/docs/testing_guide.md)** - Testing documentation +- **[docs/a2a-threats-taxonomy.md](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/docs/a2a-threats-taxonomy.md)** - A2A threat taxonomy reference +- **[docs/scanner_placement_guide.md](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/docs/scanner_placement_guide.md)** - Scanner placement strategies --- @@ -815,7 +815,7 @@ For enterprise-grade A2A security solutions and support: ## License -Distributed under the Apache 2.0 License. See [LICENSE](./LICENSE) for more information. +Distributed under the Apache 2.0 License. See [LICENSE](https://github.com/cisco-ai-defense/a2a-scanner/blob/main/LICENSE) for more information. Copyright 2025 Cisco Systems, Inc. and its affiliates @@ -825,7 +825,6 @@ Copyright 2025 Cisco Systems, Inc. and its affiliates - **[A2A Protocol](https://github.com/a2aproject/A2A)** - Official A2A specification - **[A2A Samples](https://github.com/a2aproject/a2a-samples)** - Example agent implementations -- **[Cisco AI Defense A2A Scanner](https://github.com/cisco-ai-defense/a2a-scanner)** - Agent-to-Agent (A2A) Protocol Scanner ---