ziran 0.6.1

AI Agent Security Testing Framework — multi-phase scan campaigns with knowledge graph tracking

ZIRAN 🧘

AI Agent Security Testing

Find vulnerabilities in AI agents — not just LLMs, but agents with tools, memory, and multi-step reasoning.

Install · Quick Start · Examples · Docs

---

Why ZIRAN?

Most security tools test the LLM (prompt injection, jailbreaks) or the web app (XSS, SQLi). ZIRAN tests the AI agent — the system that wields tools, retains memory, and chains reasoning. That's a fundamentally different attack surface.

Capability	ZIRAN	Garak	Promptfoo	PyRIT	Shannon
Agent-aware (tools + memory)	Yes	—	Partial	—	—
Tool chain analysis	Yes	—	—	—	—
Multi-phase campaigns	Yes	—	—	Partial	Yes
Multi-agent coordination	Yes	—	—	—	—
Adaptive campaigns	Yes	—	—	—	—
Autonomous pentesting agent	Yes	—	—	—	—
Streaming (SSE/WebSocket)	Yes	—	—	—	—
Knowledge graph tracking	Yes	—	—	—	—
Remote agent scanning (HTTPS)	Yes	REST only	HTTP provider	Partial	—
Multi-protocol (REST/OpenAI/MCP/A2A)	Yes	—	—	—	—
A2A protocol support	Yes	—	—	—	—
Protocol auto-detection	Yes	—	—	—	—
CI/CD quality gate	Yes	—	Yes	—	Pro
Open source	Apache-2.0	Apache-2.0	MIT	MIT	AGPL-3.0

Key differentiators:

• Tool Chain Analysis — Detects dangerous tool combinations (read_file → http_request = data exfiltration). No other tool does this.
• Multi-Phase Trust Exploitation — Progressive campaigns that build trust before testing boundaries, like a real attacker.
• Multi-Agent Coordination — Discover topologies (supervisor, router, peer-to-peer) and test cross-agent trust boundaries and delegation patterns.
• Adaptive Campaigns — Three execution strategies — fixed, rule-based adaptive, and LLM-driven — that adjust attack plans in real-time based on knowledge graph state.
• Streaming Support — Real-time attack monitoring via SSE and WebSocket protocols for long-running agent responses.
• Knowledge Graph — Every discovered capability, relationship, and attack path is tracked in a live graph.
• Remote Agent Scanning — Test any published agent over HTTPS with YAML-driven target configuration. Supports REST, OpenAI-compatible, MCP, and A2A protocols with automatic detection.
• A2A Protocol Support — First security tool to test Agent-to-Agent agents, including Agent Card discovery, task lifecycle attacks, and multi-turn manipulation.
• Autonomous Pentesting Agent — An LLM-driven agent that plans, executes, and adapts attack campaigns autonomously, with finding deduplication and interactive red-team mode.
• Framework Agnostic — LangChain, CrewAI, MCP, remote HTTPS agents, or write your own adapter.

---

Install

pip install ziran

# with framework adapters
pip install ziran[langchain]    # LangChain support
pip install ziran[crewai]       # CrewAI support
pip install ziran[a2a]          # A2A protocol support
pip install ziran[streaming]    # SSE/WebSocket streaming
pip install ziran[pentest]      # autonomous pentesting agent
pip install ziran[all]          # everything

---

Quick Start

CLI

# scan a LangChain agent (in-process)
ziran scan --framework langchain --agent-path my_agent.py

# scan a remote agent over HTTPS
ziran scan --target target.yaml

# adaptive campaign with LLM-driven strategy
ziran scan --target target.yaml --strategy llm-adaptive

# stream responses in real-time
ziran scan --target target.yaml --streaming

# scan a multi-agent system
ziran multi-agent-scan --target target.yaml

# discover capabilities of a remote agent
ziran discover --target target.yaml

# autonomous pentesting agent
ziran pentest --target target.yaml

# interactive red-team mode
ziran pentest --target target.yaml --interactive

# view the interactive HTML report
open reports/campaign_*_report.html

Python API

import asyncio
from ziran.application.agent_scanner.scanner import AgentScanner
from ziran.application.attacks.library import AttackLibrary
from ziran.infrastructure.adapters.langchain_adapter import LangChainAdapter

adapter = LangChainAdapter(agent=your_agent)
scanner = AgentScanner(adapter=adapter, attack_library=AttackLibrary())

result = asyncio.run(scanner.run_campaign())
print(f"Vulnerabilities found: {result.total_vulnerabilities}")
print(f"Dangerous tool chains: {len(result.dangerous_tool_chains)}")

See examples/ for 19 runnable demos — from static analysis to autonomous pentesting.

---

Remote Agent Scanning

ZIRAN can test any published agent over HTTPS — no source code or in-process access required. Define your target in a YAML file and ZIRAN handles the rest:

# target.yaml
name: my-agent
url: https://agent.example.com
protocol: auto  # auto | rest | openai | mcp | a2a

auth:
  type: bearer
  token_env: AGENT_API_KEY

tls:
  verify: true

Supported protocols:

Protocol	Use Case	Auto-detected via
REST	Generic HTTP endpoints	Fallback default
OpenAI-compatible	Chat completions API (/v1/chat/completions)	Path probing
MCP	Model Context Protocol agents (JSON-RPC 2.0)	JSON-RPC response
A2A	Google Agent-to-Agent protocol	/.well-known/agent.json

# auto-detect protocol and scan
ziran scan --target target.yaml

# force a specific protocol
ziran scan --target target.yaml --protocol openai

# A2A agent with Agent Card discovery
ziran scan --target a2a_target.yaml --protocol a2a

See examples/15-remote-agent-scan/ for ready-to-use target configurations.

---

What ZIRAN Finds

Prompt-level — injection, system prompt extraction, memory poisoning, chain-of-thought manipulation.

Tool-level — tool manipulation, privilege escalation, data exfiltration chains.

Tool chains (unique to ZIRAN) — automatic graph analysis of dangerous tool compositions:

┌──────────┬─────────────────────┬─────────────────────────────┬──────────────────────────────────────┐
│ Risk     │ Type                │ Tools                       │ Description                          │
├──────────┼─────────────────────┼─────────────────────────────┼──────────────────────────────────────┤
│ critical │ data_exfiltration   │ read_file → http_request    │ File contents sent to external server│
│ critical │ sql_to_rce          │ sql_query → execute_code    │ SQL results executed as code         │
│ high     │ pii_leakage         │ get_user_info → external_api│ User PII sent to third-party API     │
└──────────┴─────────────────────┴─────────────────────────────┴──────────────────────────────────────┘

---

How It Works

flowchart LR
    subgraph agent["🤖 Your Agent"]
        direction TB
        T["🔧 Tools"]
        M["🧠 Memory"]
        P["🔑 Permissions"]
    end

    agent -->|"adapter layer"| D

    subgraph ziran["⛩️ ZIRAN Pipeline"]
        direction TB
        D["1 · DISCOVER\nProbe tools, permissions,\ndata access"]
        MAP["2 · MAP\nBuild knowledge graph\n(NetworkX MultiDiGraph)"]
        A["3 · ANALYZE\nWalk graph for dangerous\nchains (30+ patterns)"]
        ATK["4 · ATTACK\nMulti-phase exploits\ninformed by the graph"]
        R["5 · REPORT\nScored findings with\nremediation guidance"]
        D --> MAP --> A --> ATK --> R
    end

    R --> HTML["📊 HTML\nInteractive graph"]
    R --> MD["📝 Markdown\nCI/CD tables"]
    R --> JSON["📦 JSON\nMachine-parseable"]

    style agent fill:#1a1a2e,stroke:#e94560,color:#fff,stroke-width:2px
    style ziran fill:#0f3460,stroke:#e94560,color:#fff,stroke-width:2px
    style D fill:#16213e,stroke:#0ea5e9,color:#fff
    style MAP fill:#16213e,stroke:#0ea5e9,color:#fff
    style A fill:#16213e,stroke:#0ea5e9,color:#fff
    style ATK fill:#16213e,stroke:#e94560,color:#fff
    style R fill:#16213e,stroke:#10b981,color:#fff
    style HTML fill:#1e293b,stroke:#10b981,color:#fff
    style MD fill:#1e293b,stroke:#10b981,color:#fff
    style JSON fill:#1e293b,stroke:#10b981,color:#fff
    style T fill:#2d2d44,stroke:#e94560,color:#fff
    style M fill:#2d2d44,stroke:#e94560,color:#fff
    style P fill:#2d2d44,stroke:#e94560,color:#fff

Multi-Phase Trust Exploitation

Phase	Goal
Reconnaissance	Discover capabilities and data sources
Trust Building	Establish rapport with the agent
Capability Mapping	Map tools, permissions, data access
Vulnerability Discovery	Identify attack paths
Exploitation Setup	Position without triggering defences
Execution	Execute the exploit chain
Persistence	Maintain access across sessions (opt-in)
Exfiltration	Extract sensitive data (opt-in)

Each phase builds on the knowledge graph from previous phases.

Campaign Strategies

Strategy	Description
fixed	Sequential phases in order (default)
adaptive	Rule-based adaptation — skips, repeats, or re-orders phases based on knowledge graph state
llm-adaptive	LLM-driven strategy — uses an LLM to analyze findings and plan the next phase dynamically

ziran scan --target target.yaml --strategy adaptive
ziran scan --target target.yaml --strategy llm-adaptive

Autonomous Pentesting Agent

An LLM-powered agent that autonomously plans, executes, and adapts penetration testing campaigns:

# fully autonomous mode
ziran pentest --target target.yaml --max-iterations 5

# interactive red-team mode — collaborate with the agent
ziran pentest --target target.yaml --interactive

The pentesting agent:

• Plans attack strategies using LLM reasoning and knowledge graph state
• Executes multi-step exploit chains with real-time adaptation
• Deduplicates findings using LLM embeddings to cluster related vulnerabilities
• Reports with detailed HTML reports including OWASP LLM Top 10 mapping

See examples/19-pentesting-agent/ for a complete walkthrough.

Multi-Agent Scanning

Test coordinated multi-agent systems — supervisors, routers, peer-to-peer networks:

ziran multi-agent-scan --target target.yaml

ZIRAN discovers the agent topology, scans each agent individually, then runs cross-agent attacks targeting trust boundaries and delegation patterns.

Streaming

Monitor attack responses in real-time via SSE or WebSocket:

ziran scan --target target.yaml --streaming

---

Reports

Three output formats, generated automatically:

• HTML — Interactive knowledge graph with attack path highlighting
• Markdown — CI/CD-friendly summary tables
• JSON — Machine-parseable for programmatic consumption

---

CI/CD Integration

Use ZIRAN as a quality gate in your pipeline:

Live scan (runs the full attack suite against your agent)

# .github/workflows/security.yml
- uses: taoq-ai/ziran@v0
  with:
    command: scan
    framework: langchain        # langchain | crewai | bedrock
    agent-path: my_agent.py     # OR use target: target.yaml for remote agents
    coverage: standard           # essential | standard | comprehensive
    gate-config: gate_config.yaml
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}   # or ANTHROPIC_API_KEY, etc.

Offline CI gate (evaluate a previous scan result)

- uses: taoq-ai/ziran@v0
  with:
    command: ci
    result-file: scan_results/campaign_report.json
    gate-config: gate_config.yaml

Outputs: status (passed/failed), trust-score, total-findings, critical-findings, sarif-file.

See the full example workflow or use the Python API.

---

Development

git clone https://github.com/taoq-ai/ziran.git && cd ziran
uv sync --group dev

uv run ruff check .            # lint
uv run mypy ziran/             # type-check
uv run pytest --cov=ziran      # test

---

Contributing

See CONTRIBUTING.md. Ways to help:

• Report bugs
• Request features
• Submit Skill CVEs for tool vulnerabilities
• Add attack vectors (YAML) or adapters

---

License

Apache License 2.0 — See NOTICE for third-party attributions.

Built by TaoQ AI