{"id":44473651,"url":"https://github.com/taoq-ai/ziran","last_synced_at":"2026-05-22T19:01:29.633Z","repository":{"id":337892155,"uuid":"1153625283","full_name":"taoq-ai/ziran","owner":"taoq-ai","description":"自然 ZIRAN is an open-source security testing framework for AI agents. It discovers dangerous tool chain compositions via knowledge graph analysis, detects execution-level side effects (not just text output), and runs multi-phase trust exploitation campaigns that model real attacker behaviour.","archived":false,"fork":false,"pushed_at":"2026-03-30T15:05:41.000Z","size":7047,"stargazers_count":5,"open_issues_count":16,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T16:34:47.082Z","etag":null,"topics":["a2a-protocol","agent-security","ai-security","crewai","cybersecurity","langchain","llm-security","mcp","owasp","penetration-testing","pentesting","python","red-teaming","vulnerability-scanners"],"latest_commit_sha":null,"homepage":"https://taoq-ai.github.io/ziran/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taoq-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T14:13:08.000Z","updated_at":"2026-03-30T15:07:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"911119a5-4d49-4a0a-9818-7d99d8262caa","html_url":"https://github.com/taoq-ai/ziran","commit_stats":null,"previous_names":["taoq-ai/ziran"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/taoq-ai/ziran","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoq-ai%2Fziran","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoq-ai%2Fziran/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoq-ai%2Fziran/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoq-ai%2Fziran/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taoq-ai","download_url":"https://codeload.github.com/taoq-ai/ziran/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoq-ai%2Fziran/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a-protocol","agent-security","ai-security","crewai","cybersecurity","langchain","llm-security","mcp","owasp","penetration-testing","pentesting","python","red-teaming","vulnerability-scanners"],"created_at":"2026-02-12T22:00:45.761Z","updated_at":"2026-05-22T19:01:29.622Z","avatar_url":"https://github.com/taoq-ai.png","language":"Python","funding_links":[],"categories":["Tools"],"sub_categories":["Services"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/hero-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/hero-light.svg\"\u003e\n    \u003cimg src=\"docs/assets/hero-light.svg\" alt=\"ZIRAN: your AI agent — with tools, memory, and permissions — flows through the ZIRAN pipeline (discover, map, analyze, attack, report) and out into a ranked list of findings. The top finding 'read_file → http_request' is highlighted as a critical data-exfiltration tool chain. Keywords: AI agent security, agent red team, tool chain analysis, knowledge graph, MCP, A2A, LangChain, CrewAI, prompt injection, side-effect detection, multi-phase campaigns.\" width=\"100%\" draggable=\"false\"/\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eFind vulnerabilities in your \u003cem\u003eAI agents.\u003c/em\u003e\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStar us\u0026nbsp;❤️\u0026nbsp;→\u003c/strong\u003e\u0026nbsp;\u003ca href=\"https://github.com/taoq-ai/ziran\" title=\"Star ZIRAN on GitHub — open-source agent security testing framework\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/star-btn-dark.svg\"\u003e\u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/star-btn-light.svg\"\u003e\u003cimg src=\"docs/assets/star-btn-light.svg\" alt=\"Star ZIRAN on GitHub — open-source AI agent security scanner with tool chain discovery, side-effect detection, and adaptive multi-phase campaigns\" height=\"36\" align=\"absmiddle\"/\u003e\u003c/picture\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://taoq-ai.github.io/ziran/\"\u003e\u003cb\u003e📚 Docs\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"examples/\"\u003e\u003cb\u003e🧪 Examples\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://pypi.org/project/ziran/\"\u003e\u003cb\u003e📦 PyPI\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://github.com/taoq-ai/ziran/issues\"\u003e\u003cb\u003e🐛 Issues\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  ZIRAN finds vulnerabilities in AI agents — not just LLMs, but agents with tools, memory, and multi-step reasoning. It models your agent as a graph of capabilities and tests what happens when they combine — surfacing dangerous tool chains, execution-level side effects, and multi-phase exploits that single-prompt scanners miss.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eGraph-based\u003c/b\u003e · tool-chain discovery \u0026nbsp;·\u0026nbsp; \u003cb\u003eExecution-aware\u003c/b\u003e · side-effect detection \u0026nbsp;·\u0026nbsp; \u003cb\u003eAdaptive\u003c/b\u003e · 8-phase campaigns\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![CI](https://github.com/taoq-ai/ziran/actions/workflows/ci.yml/badge.svg)](https://github.com/taoq-ai/ziran/actions/workflows/ci.yml)\n[![Tests](https://github.com/taoq-ai/ziran/actions/workflows/test.yml/badge.svg)](https://github.com/taoq-ai/ziran/actions/workflows/test.yml)\n[![PyPI](https://img.shields.io/pypi/v/ziran.svg)](https://pypi.org/project/ziran/)\n[![Downloads](https://img.shields.io/pypi/dm/ziran.svg)](https://pypistats.org/packages/ziran)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)\n[![Stars](https://img.shields.io/github/stars/taoq-ai/ziran?style=flat\u0026label=stars\u0026color=fbbf24)](https://github.com/taoq-ai/ziran)\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#install\"\u003e\u003cb\u003eInstall\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#quick-start\"\u003e\u003cb\u003eQuick Start\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#web-ui\"\u003e\u003cb\u003eWeb UI\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"examples/\"\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://taoq-ai.github.io/ziran/\"\u003e\u003cb\u003eDocs\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/ui-dashboard.png\" alt=\"ZIRAN Dashboard — web UI showing campaign results, attack library, and knowledge graph\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n---\n\n## Benchmarks\n\n\u003e **639** attack vectors · **11** categories · **100%** OWASP LLM Top 10 · **72/86** MITRE ATLAS techniques · **20** benchmarks analyzed\n\n| Benchmark | Coverage |\n|-----------|----------|\n| OWASP LLM Top 10 | **10/10** categories (strong or comprehensive) |\n| MITRE ATLAS (Oct 2025) | 72/86 techniques, 14/14 agent-specific |\n| AgentHarm (ICLR 2025) | 100% harm categories |\n| JailbreakBench (NeurIPS 2024) | 100% categories, 175 vectors |\n| Agent Security Bench | 100% vectors (639/400) |\n| HarmBench (ICML 2024) | 55.6% tactics, 175 jailbreak vectors |\n| R-Judge | 100% risk types |\n| ALERT | 100% micro categories (32/32) |\n| TensorTrust / WildJailbreak / ToolEmu / CyberSecEval | Representative pattern families |\n| LLMail-Inject / RAG Poisoning | Retrieval-ranked vectors across 4 document framings |\n\nFull results: [benchmarks/](benchmarks/) · [docs](https://taoq-ai.github.io/ziran/reference/benchmarks/coverage-comparison/)\n\n---\n\n## Why ZIRAN?\n\nMost security tools test prompts and tools in isolation. But agent vulnerabilities emerge from how tools interact -- an agent with `read_file` and `http_request` has a data exfiltration path, even though neither tool is dangerous alone. Testing each tool individually misses this entirely.\n\nZIRAN models your agent as a graph of capabilities and tests what happens when they combine.\n\n| Capability | ZIRAN | [Promptfoo](https://github.com/promptfoo/promptfoo) | [Invariant](https://invariantlabs.ai/) (Snyk) | [Garak](https://github.com/NVIDIA/garak) | [PyRIT](https://github.com/Azure/PyRIT) | [Inspect AI](https://github.com/UKGovernmentBEIS/inspect_ai) |\n|---|:---:|:---:|:---:|:---:|:---:|:---:|\n| Tool chain discovery (graph-based) | Yes | -- | Policy-based | -- | -- | -- |\n| Side-effect detection (execution-level) | Yes | -- | Trace-based | -- | -- | Sandbox |\n| Multi-phase campaigns w/ graph feedback | Yes | Turn-level | Flow analysis | -- | Composable | Multi-turn |\n| Autonomous pentesting agent | Yes | -- | -- | -- | -- | -- |\n| Multi-agent coordination | Yes | -- | -- | -- | -- | -- |\n| Knowledge graph tracking | Yes | -- | Policy lang. | -- | -- | -- |\n| Agent-aware (tools + memory) | Yes | Partial | Yes | -- | -- | Partial |\n| A2A protocol support | Yes | -- | -- | -- | -- | -- |\n| MCP protocol support | Yes | Partial | Yes | -- | -- | -- |\n| Encoding/obfuscation attacks | Yes (8) | Yes (12+) | -- | -- | -- | -- |\n| Industry compliance plugins | -- | Yes (46) | -- | -- | -- | -- |\n| Streaming (SSE/WebSocket) | Yes | -- | -- | -- | -- | -- |\n| CI/CD quality gate | Yes | Yes | -- | -- | -- | -- |\n| Open source | Apache-2.0 | MIT | Partial | Apache-2.0 | MIT | MIT |\n\n**What these capabilities catch:**\n\n### Tool-chain discovery — graph beats list\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/toolchain-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/toolchain-light.svg\"\u003e\n    \u003cimg src=\"docs/assets/toolchain-light.svg\" alt=\"Side-by-side comparison: a list-based scanner sees four individually-safe tools (read_file, http_request, sql_query, exec_code) and reports no findings, while ZIRAN walks the capability graph and surfaces dangerous transitive compositions — read_file→http_request as critical data exfiltration, sql_query→exec_code as high-severity SQL-to-RCE.\" width=\"100%\"/\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\nIndividual tools pass security review in isolation, but their compositions create vulnerabilities. Graph-based analysis finds transitive attack paths — `read_file → http_request` for data exfiltration, `sql_query → exec_code` for SQL-to-RCE — that list-based testing misses entirely.\n\n### Side-effect detection — chat is not the truth\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/sideeffect-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/sideeffect-light.svg\"\u003e\n    \u003cimg src=\"docs/assets/sideeffect-light.svg\" alt=\"Two stacked layers: on the surface, the agent replies 'I can't do that — request refused' to 'Delete user 42' and a chat-only scanner marks it safe; on the execution layer below, ZIRAN intercepts the actual tool call delete_user(id=42) firing silently and flags it as critical.\" width=\"100%\"/\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\nAgents can refuse a request in their text response while still executing the dangerous tool call underneath. ZIRAN intercepts at the execution layer and flags these silent failures — chat-only scanners mark them as safe.\n\n### Adaptive 8-phase campaigns — the graph drives the next move\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/adaptive-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/adaptive-light.svg\"\u003e\n    \u003cimg src=\"docs/assets/adaptive-light.svg\" alt=\"A live knowledge graph grows phase by phase: Reconnaissance discovers 3 capabilities, Capability Map adds 3 tools, Vulnerability Discovery surfaces a critical read_file→http_request chain, Exploit Setup attaches an attack node. Trust Building is skipped (no auth surface) and Persistence is skipped (ephemeral target) because the graph state makes them irrelevant. The right panel narrates how each new graph state picks the next phase.\" width=\"100%\"/\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\nA live knowledge graph grows as the scan progresses, and the graph picks the next phase — not a fixed sequence. A critical chain found mid-campaign immediately routes to Exploit Setup, while phases like Trust Building or Persistence are skipped when graph state shows they would not yield results. Three strategies control this: `fixed` (sequential, reproducible for CI), `adaptive` (rule-based reordering), and `llm-adaptive` (LLM examines the graph after each phase to plan).\n\n### And…\n\n- **Multi-Agent Coordination** -- In multi-agent systems, an agent may trust messages from peers without validation. Testing cross-agent trust boundaries reveals lateral movement paths.\n- **A2A + MCP Protocols** -- Tests [Agent-to-Agent](https://google.github.io/A2A/) and [MCP](https://modelcontextprotocol.io/) agents through their native protocols, exercising the actual attack surface rather than a simplified proxy.\n- **Framework Agnostic** -- LangChain, CrewAI, Bedrock, MCP, browser UIs, remote HTTPS agents, or [custom adapters](examples/08-custom-adapter/).\n\n### What ZIRAN Is / What ZIRAN Is Not\n\n**ZIRAN is** an agent security scanner that discovers dangerous tool compositions via graph analysis, detects execution-level side effects, and runs multi-phase campaigns that model real attacker behavior.\n\n**ZIRAN is not:**\n\n- An LLM safety/alignment tool -- for prompt injection breadth, jailbreak templates, and compliance testing, use [Promptfoo](https://github.com/promptfoo/promptfoo) or [Garak](https://github.com/NVIDIA/garak)\n- A runtime guardrail -- for real-time input/output protection, use [NeMo Guardrails](https://github.com/NVIDIA/NeMo-Guardrails), [Lakera Guard](https://www.lakera.ai/), or [LLM Guard](https://github.com/protectai/llm-guard)\n- A general-purpose eval framework -- for model evaluation and benchmarking, use [Inspect AI](https://github.com/UKGovernmentBEIS/inspect_ai) or [Deepeval](https://github.com/confident-ai/deepeval)\n\n### Works With\n\nZIRAN is complementary to other tools in the AI security ecosystem:\n\n**Pre-deploy testing:**\n\n- **[Promptfoo](https://github.com/promptfoo/promptfoo)** for attack breadth (encoding strategies, jailbreak templates, compliance plugins) + **ZIRAN** for agent depth (tool chains, side-effects, campaigns)\n- **[Garak](https://github.com/NVIDIA/garak)** for LLM-layer vulnerability scanning + **ZIRAN** for agent-layer tool chain analysis\n\n**Runtime governance:**\n\n- **[NeMo Guardrails](https://github.com/NVIDIA/NeMo-Guardrails)** / **[Lakera](https://www.lakera.ai/)** for runtime input/output protection + **ZIRAN** for pre-deployment testing\n- **[Invariant (Snyk)](https://invariantlabs.ai/)** for runtime policy enforcement + **ZIRAN** for pre-deploy tool chain analysis\n\n**Observability:**\n\n- **[Langfuse](https://langfuse.com/)** for production trace analytics + **ZIRAN** `analyze-traces` for security evaluation of production behavior\n- **[LangSmith](https://smith.langchain.com/)** for debugging and eval + **ZIRAN** for security-focused campaign testing\n\nSee the [Agent Security Landscape](https://taoq-ai.github.io/ziran/concepts/agent-security-landscape/) for a full mapping of tools across pre-deploy, runtime, and observability layers.\n\n---\n\n## Install\n\n```bash\npip install ziran\n\n# with framework adapters\npip install ziran[langchain]    # LangChain support\npip install ziran[crewai]       # CrewAI support\npip install ziran[a2a]          # A2A protocol support\npip install ziran[streaming]    # SSE/WebSocket streaming\npip install ziran[pentest]      # autonomous pentesting agent\npip install ziran[otel]         # OpenTelemetry tracing\npip install ziran[ui]            # web dashboard\npip install ziran[all]          # everything\n```\n\n---\n\n## Web UI\n\nZIRAN includes a built-in web dashboard for visual security analysis. Install the UI extra and start:\n\n```bash\npip install ziran[ui]\nziran ui\n# Dashboard: http://127.0.0.1:8484\n```\n\nOr with Docker:\n\n```bash\ndocker compose up\n# Dashboard: http://localhost:8484\n```\n\n### Attack Library -- 639 vectors across 11 categories\n\n![Attack Library](docs/assets/ui-library.png)\n\n### Scan Configuration\n\n![New Run](docs/assets/ui-new-run.png)\n\n---\n\n## Quick Start\n\n### CLI\n\n```bash\n# scan a LangChain agent (in-process)\nziran scan --framework langchain --agent-path my_agent.py\n\n# scan a remote agent over HTTPS\nziran scan --target target.yaml\n\n# adaptive campaign with LLM-driven strategy\nziran scan --target target.yaml --strategy llm-adaptive\n\n# stream responses in real-time\nziran scan --target target.yaml --streaming\n\n# scan with encoding bypass variants (Base64 + ROT13)\nziran scan --target target.yaml --encoding base64 --encoding rot13\n\n# scan with OpenTelemetry tracing\nziran scan --target target.yaml --otel\n\n# scan a multi-agent system\nziran multi-agent-scan --target target.yaml\n\n# discover capabilities of a remote agent\nziran discover --target target.yaml\n\n# autonomous pentesting agent\nziran pentest --target target.yaml\n\n# interactive red-team mode\nziran pentest --target target.yaml --interactive\n\n# view the interactive HTML report\nopen reports/campaign_*_report.html\n```\n\n### Python API\n\n```python\nimport asyncio\nfrom ziran.application.agent_scanner.scanner import AgentScanner\nfrom ziran.application.attacks.library import AttackLibrary\nfrom ziran.infrastructure.adapters.langchain_adapter import LangChainAdapter\n\nadapter = LangChainAdapter(agent=your_agent)\nscanner = AgentScanner(adapter=adapter, attack_library=AttackLibrary())\n\nresult = asyncio.run(scanner.run_campaign())\nprint(f\"Vulnerabilities found: {result.total_vulnerabilities}\")\nprint(f\"Dangerous tool chains: {len(result.dangerous_tool_chains)}\")\n```\n\nSee [examples/](examples/) for 22 runnable demos -- from static analysis to autonomous pentesting.\n\n---\n\n## Remote Agent Scanning\n\nZIRAN can test any published agent over HTTPS -- no source code or in-process access required. Define your target in a YAML file:\n\n```yaml\n# target.yaml\nname: my-agent\nurl: https://agent.example.com\nprotocol: auto  # auto | rest | openai | mcp | a2a\n\nauth:\n  type: bearer\n  token_env: AGENT_API_KEY\n\ntls:\n  verify: true\n```\n\n**Supported protocols:**\n\n| Protocol | Use Case | Auto-detected via |\n|---|---|---|\n| **REST** | Generic HTTP endpoints | Fallback default |\n| **OpenAI-compatible** | Chat completions API (`/v1/chat/completions`) | Path probing |\n| **MCP** | Model Context Protocol agents (JSON-RPC 2.0) | JSON-RPC response |\n| **A2A** | Google Agent-to-Agent protocol | `/.well-known/agent.json` |\n\n```bash\n# auto-detect protocol and scan\nziran scan --target target.yaml\n\n# force a specific protocol\nziran scan --target target.yaml --protocol openai\n\n# A2A agent with Agent Card discovery\nziran scan --target a2a_target.yaml --protocol a2a\n```\n\nSee [examples/15-remote-agent-scan/](examples/15-remote-agent-scan/) for ready-to-use target configurations.\n\n---\n\n## What ZIRAN Finds\n\n**Prompt-level** -- injection, system prompt extraction, memory poisoning, chain-of-thought manipulation.\n\n**Tool-level** -- tool manipulation, privilege escalation, data exfiltration chains.\n\n**Tool chains** -- automatic graph analysis of dangerous tool compositions:\n\n```\n+----------+---------------------+-----------------------------+--------------------------------------+\n| Risk     | Type                | Tools                       | Description                          |\n+----------+---------------------+-----------------------------+--------------------------------------+\n| critical | data_exfiltration   | read_file -\u003e http_request   | File contents sent to external server|\n| critical | sql_to_rce          | sql_query -\u003e execute_code   | SQL results executed as code         |\n| high     | pii_leakage         | get_user_info -\u003e external_api| User PII sent to third-party API    |\n+----------+---------------------+-----------------------------+--------------------------------------+\n```\n\n---\n\n## How It Works\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/pipeline-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/pipeline-light.svg\"\u003e\n    \u003cimg src=\"docs/assets/pipeline-light.svg\" alt=\"ZIRAN pipeline diagram: your agent (with tools, memory, and permissions) connects through an adapter layer into the ZIRAN pipeline — DISCOVER probes capabilities, MAP builds a NetworkX MultiDiGraph, ANALYZE walks the graph for dangerous chains across 30+ patterns, ATTACK runs multi-phase exploits informed by the graph, and REPORT emits scored findings. Outputs land in three formats: HTML interactive graph, Markdown CI/CD tables, and JSON for programmatic consumption.\" width=\"100%\"/\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\nFive sequential stages: **DISCOVER** probes tools, permissions, and data access; **MAP** builds a NetworkX MultiDiGraph of capabilities; **ANALYZE** walks the graph against 30+ dangerous-chain patterns; **ATTACK** runs multi-phase exploits informed by the graph; **REPORT** emits scored findings with remediation guidance.\n\n### Campaign phases\n\nThe ATTACK stage runs an 8-phase campaign — reconnaissance, trust building, capability mapping, vulnerability discovery, exploitation setup, execution, persistence, exfiltration. Phases are **not linear**: the live knowledge graph drives execution order, so a discovery during exploitation may trigger a return to reconnaissance, and revealed tools cause capability mapping to re-run with updated context. (See [Adaptive 8-phase campaigns](#adaptive-8-phase-campaigns--the-graph-drives-the-next-move) above for an animated walk-through, including how Trust Building and Persistence are skipped when graph state makes them irrelevant.)\n\nThree strategies control this:\n\n- **`fixed`** -- Sequential execution through all 8 phases (reproducible, good for CI)\n- **`adaptive`** -- Rule-based reordering: skips phases that won't yield results given current graph state, revisits phases when new capabilities are discovered\n- **`llm-adaptive`** -- LLM-driven planning: an LLM examines the knowledge graph after each phase and decides what to do next\n\nSee [adaptive campaigns docs](https://taoq-ai.github.io/ziran/concepts/adaptive-campaigns/).\n\n---\n\n## Reports\n\nThree output formats, generated automatically:\n\n- **HTML** -- Interactive knowledge graph with attack path highlighting\n- **Markdown** -- CI/CD-friendly summary tables\n- **JSON** -- Machine-parseable for programmatic consumption\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/report-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/assets/report-light.svg\"\u003e\n    \u003cimg src=\"docs/assets/report-light.svg\" alt=\"Mock-up of a ZIRAN HTML campaign report — header with target metadata, severity counters (3 critical, 7 high, 12 medium, 28 low), a findings table listing the top tool-chain vulnerabilities (data exfiltration, SQL-to-RCE, PII leakage, prompt injection, multi-agent trust boundary), and a live knowledge graph with the critical attack paths highlighted.\" width=\"100%\"/\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n---\n\n## CI/CD Integration\n\nUse ZIRAN as a quality gate in your pipeline. Templates are available for five CI systems:\n\n| CI System | Template | SARIF Integration |\n|-----------|----------|-------------------|\n| **GitHub Actions** | [`ziran-scan.yml`](examples/07-cicd-quality-gate/ziran-scan.yml) | GitHub Security tab |\n| **GitLab CI** | [`gitlab-ci.yml`](examples/07-cicd-quality-gate/gitlab-ci.yml) | GitLab Security Dashboard |\n| **Jenkins** | [`Jenkinsfile`](examples/07-cicd-quality-gate/Jenkinsfile) | Warnings Next Generation Plugin |\n| **CircleCI** | [`circleci-config.yml`](examples/07-cicd-quality-gate/circleci-config.yml) | Build artifacts |\n| **Azure Pipelines** | [`azure-pipelines.yml`](examples/07-cicd-quality-gate/azure-pipelines.yml) | PublishBuildArtifacts |\n\n### GitHub Actions (official action)\n\n```yaml\n# .github/workflows/security.yml\n- uses: taoq-ai/ziran@v0\n  with:\n    command: ci\n    result-file: scan_results.json\n    severity-threshold: medium\n    sarif-output: results.sarif\n```\n\n### GitLab CI\n\n```yaml\nziran-security-scan:\n  stage: test\n  image: python:3.12-slim\n  before_script:\n    - pip install ziran\n  script:\n    - ziran ci --result-file scan_results.json --severity-threshold medium --output sarif --sarif-file gl-sast-report.json\n  artifacts:\n    reports:\n      sast: gl-sast-report.json\n```\n\n**Outputs:** `status` (passed/failed), `trust-score`, `total-findings`, `critical-findings`, `sarif-file`.\n\nSee [CI integrations docs](https://taoq-ai.github.io/ziran/guides/ci-integrations/) for Jenkins, CircleCI, and Azure Pipelines examples, or browse the [template directory](examples/07-cicd-quality-gate/).\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/taoq-ai/ziran.git \u0026\u0026 cd ziran\nuv sync --group dev\n\nuv run ruff check .            # lint\nuv run mypy ziran/             # type-check\nuv run pytest --cov=ziran      # test\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Ways to help:\n\n- [Report bugs](https://github.com/taoq-ai/ziran/issues/new?template=bug_report.md)\n- [Request features](https://github.com/taoq-ai/ziran/issues/new?template=feature_request.md)\n- [Submit Skill CVEs](https://github.com/taoq-ai/ziran/issues/new?template=skill_cve.md) for tool vulnerabilities\n- Add [attack vectors](ziran/application/attacks/vectors/) (YAML) or [adapters](ziran/infrastructure/adapters/)\n\n---\n\n## Citation\n\nIf you use ZIRAN in academic work, please cite:\n\n```bibtex\n@software{ziran2026,\n  title     = {ZIRAN: AI Agent Security Testing},\n  author    = {{TaoQ AI} and Lage Perdigao, Leone},\n  year      = {2026},\n  url       = {https://github.com/taoq-ai/ziran},\n  license   = {Apache-2.0},\n  version   = {0.25.0}\n}\n```\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE) -- See [NOTICE](NOTICE) for third-party attributions.\n\n\u003cp align=\"center\"\u003e\n  Built by \u003ca href=\"https://www.taoq.ai\"\u003eTaoQ AI\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaoq-ai%2Fziran","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaoq-ai%2Fziran","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaoq-ai%2Fziran/lists"}