ziran 0.1.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
Knowledge graph tracking	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.
• Romance Scan — Multi-phase campaigns that build trust before testing boundaries, like a real attacker.
• Knowledge Graph — Every discovered capability, relationship, and attack path is tracked in a live graph.
• Framework Agnostic — LangChain, CrewAI, MCP, 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[all]          # everything

---

Quick Start

CLI

# scan a LangChain agent
ziran scan --framework langchain --agent-path my_agent.py

# 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 14 runnable demos — from static analysis to multi-agent supervisor scans.

---

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

Romance Scan Phases

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.

---

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:

# GitHub Actions
- uses: taoq-ai/ziran@v1
  with:
    agent-path: my_agent.py
    framework: langchain
    fail-on: high            # fail the build on high+ findings

Or with the Python API — see 07-cicd-quality-gate.

---

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