ziran

Category: Tools & Productivity | Uploader: taoq-ai | Downloads: 0 | Version: v1.0（Latest）

ZIRAN is an open-source security testing framework for AI agents. It tests agents with tools, memory, and multi-step reasoning — not just LLMs. It runs multi-phase trust exploitation campaigns, analyzes dangerous tool chain combinations, and tracks attack paths via knowledge graphs.

Changelog: Source: GitHub https://github.com/taoq-ai/ziran

Directory Structure

Current level: Root

📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 bug_report.md 614 B
  - 📄 feature_request.md 389 B
  - 📄 skill_cve.md 938 B
- 📁 workflows/
  - 📄 action-test.yml 2.4 KB
  - 📄 ci.yml 2.4 KB
  - 📄 docs.yml 483 B
  - 📄 lint.yml 568 B
  - 📄 release.yml 7.2 KB
  - 📄 test.yml 1.3 KB
- 📄 PULL_REQUEST_TEMPLATE.md 592 B
📁 docs/
- 📁 assets/
  - 📄 demo.gif 1.2 MB
  - 📄 report.png 632.8 KB
- 📁 community/
  - 📄 contributing.md 1.6 KB
  - 📄 roadmap.md 5.1 KB
  - 📄 skill-cves.md 2.1 KB
- 📁 concepts/
  - 📄 a2a-protocol.md 3.2 KB
  - 📄 adaptive-campaigns.md 4.0 KB
  - 📄 architecture.md 6.2 KB
  - 📄 attack-vectors.md 4.7 KB
  - 📄 detection-pipeline.md 4.1 KB
  - 📄 knowledge-graph.md 1.7 KB
  - 📄 multi-agent.md 4.5 KB
  - 📄 owasp-mapping.md 4.8 KB
  - 📄 pentesting-agent.md 5.4 KB
  - 📄 remote-scanning.md 4.1 KB
  - 📄 romance-scan.md 4.4 KB
  - 📄 streaming.md 3.7 KB
  - 📄 tool-chains.md 2.6 KB
- 📁 guides/
  - 📄 adapters.md 2.3 KB
  - 📄 cicd-integration.md 5.8 KB
  - 📄 custom-attacks.md 1.1 KB
  - 📄 interpreting-results.md 2.0 KB
  - 📄 remote-agents.md 5.0 KB
  - 📄 scanning-agents.md 3.7 KB
  - 📄 static-analysis.md 4.7 KB
- 📁 reference/
  - 📄 api.md 7.4 KB
  - 📄 attack-library.md 3.4 KB
  - 📄 cli.md 6.2 KB
- 📄 getting-started.md 5.4 KB
- 📄 index.md 3.7 KB
📁 examples/
- 📁 01-static-analysis/
  - 📄 main.py 4.3 KB
  - 📄 README.md 977 B
  - 📄 run.sh 218 B
  - 📄 sample_agent.py 4.4 KB
- 📁 02-attack-library/
  - 📄 custom_vector.yaml 762 B
  - 📄 main.py 5.0 KB
  - 📄 README.md 879 B
  - 📄 run.sh 193 B
- 📁 03-dynamic-vectors/
  - 📄 main.py 4.0 KB
  - 📄 README.md 823 B
  - 📄 run.sh 214 B
- 📁 04-skill-cve/
  - 📄 main.py 5.0 KB
  - 📄 README.md 780 B
  - 📄 run.sh 212 B
- 📁 05-poc-generation/
  - 📄 fixtures.py 1.8 KB
  - 📄 main.py 3.2 KB
  - 📄 README.md 928 B
  - 📄 run.sh 209 B
- 📁 06-policy-engine/
  - 📄 fixtures.py 3.1 KB
  - 📄 main.py 3.4 KB
  - 📄 README.md 1017 B
  - 📄 run.sh 209 B
  - 📄 strict_policy.yaml 679 B
- 📁 07-cicd-quality-gate/
  - 📄 fixtures.py 2.7 KB
  - 📄 gate_config.yaml 227 B
  - 📄 main.py 5.1 KB
  - 📄 README.md 1.7 KB
  - 📄 run.sh 221 B
  - 📄 ziran-scan.yml 3.2 KB
- 📁 08-custom-adapter/
  - 📄 main.py 7.4 KB
  - 📄 README.md 892 B
  - 📄 run.sh 207 B
- 📁 09-langchain-scan/
  - 📄 main.py 3.7 KB
  - 📄 README.md 1.1 KB
  - 📄 run.sh 369 B
- 📁 10-vulnerable-agent/
  - 📁 data/
    
    📄 employees.json 568 B
    
    📄 system_configs.json 464 B
  - 📄 main.py 6.1 KB
  - 📄 README.md 1.7 KB
  - 📄 run.sh 377 B
  - 📄 system_prompt.txt 1.1 KB
- 📁 11-rag-financial-advisor/
  - 📁 data/
    
    📄 financial_docs.json 1.4 KB
  - 📄 main.py 5.2 KB
  - 📄 README.md 1.4 KB
  - 📄 run.sh 391 B
- 📁 12-router-rag/
  - 📁 data/
    
    📄 customer_records.json 679 B
    
    📄 market_data.json 335 B
    
    📄 product_docs.json 935 B
  - 📄 main.py 6.6 KB
  - 📄 README.md 1.6 KB
  - 📄 run.sh 369 B
- 📁 13-supervisor-multi-agent/
  - 📁 data/
    
    📄 finance_records.json 339 B
    
    📄 hr_records.json 323 B
  - 📄 main.py 7.9 KB
  - 📄 README.md 1.5 KB
  - 📄 run.sh 383 B
- 📁 14-crewai-scan/
  - 📄 main.py 2.8 KB
  - 📄 README.md 1.0 KB
  - 📄 run.sh 339 B
- 📁 15-remote-agent-scan/
  - 📄 main.py 2.7 KB
  - 📄 README.md 3.9 KB
  - 📄 run.sh 1.7 KB
  - 📄 target-a2a.yaml 1.1 KB
  - 📄 target-agentcore.yaml 997 B
  - 📄 target-local.yaml 592 B
  - 📄 target-mcp.yaml 423 B
  - 📄 target-ollama.yaml 417 B
  - 📄 target-openai-custom.yaml 706 B
  - 📄 target-openai.yaml 521 B
  - 📄 target-rest.yaml 749 B
  - 📄 vulnerable_server.py 9.9 KB
- 📁 16-llm-judge/
  - 📄 main.py 7.4 KB
  - 📄 README.md 2.3 KB
  - 📄 run.sh 363 B
- 📁 17-bedrock-agent-scan/
  - 📄 bedrock-agent.yaml 561 B
  - 📄 main.py 4.2 KB
  - 📄 README.md 1.9 KB
  - 📄 run.sh 718 B
- 📁 18-agentcore-scan/
  - 📄 main.py 7.7 KB
  - 📄 README.md 1.8 KB
  - 📄 run.sh 503 B
- 📁 19-pentesting-agent/
  - 📁 pentest_reports/
    
    📄 pentest_dd99e6947a0d4ff3.html 17.4 KB
    
    📄 pentest_dd99e6947a0d4ff3.json 1.2 MB
    
    📄 pentest_dd99e6947a0d4ff3.md 10.9 KB
  - 📄 interactive.py 4.4 KB
  - 📄 main.py 3.5 KB
  - 📄 pentest_vulnerable_agent.py 8.8 KB
  - 📄 README.md 2.2 KB
  - 📄 run.sh 125 B
- 📁 _common/
  - 📄 __init__.py 41 B
  - 📄 progress.py 5.1 KB
- 📄 .env.example 429 B
- 📄 pyproject.toml 1.1 KB
- 📄 README.md 3.4 KB
📁 scripts/
- 📄 record_readme_assets.sh 5.1 KB
- 📄 setup-branch-protection.sh 4.0 KB
📁 tests/
- 📁 fixtures/
  - 📄 sample_campaign_result.json 3.0 KB
- 📁 integration/
  - 📄 __init__.py 25 B
  - 📄 test_bedrock_adapter.py 3.8 KB
  - 📄 test_campaign.py 6.3 KB
  - 📄 test_crewai_adapter.py 2.5 KB
  - 📄 test_http_adapter.py 3.5 KB
  - 📄 test_langchain_adapter.py 3.8 KB
  - 📄 test_pentest_campaign.py 4.6 KB
- 📁 unit/
  - 📄 __init__.py 18 B
  - 📄 test_a2a_models.py 10.6 KB
  - 📄 test_adapter_smoke.py 6.7 KB
  - 📄 test_adaptive.py 18.9 KB
  - 📄 test_agentcore_adapter.py 7.3 KB
  - 📄 test_attack_library.py 5.4 KB
  - 📄 test_bedrock_adapter.py 8.9 KB
  - 📄 test_chain_analyzer.py 12.7 KB
  - 📄 test_cicd.py 13.8 KB
  - 📄 test_cli_helpers.py 18.9 KB
  - 📄 test_cli_main.py 18.3 KB
  - 📄 test_cli_smoke.py 2.1 KB
  - 📄 test_deduplication.py 14.8 KB
  - 📄 test_detectors.py 14.5 KB
  - 📄 test_dynamic_vectors.py 19.8 KB
  - 📄 test_entities.py 12.7 KB
  - 📄 test_html_report.py 19.3 KB
  - 📄 test_http_adapter.py 46.2 KB
  - 📄 test_knowledge_graph.py 7.0 KB
  - 📄 test_langchain_crewai_adapters.py 8.9 KB
  - 📄 test_litellm_client.py 13.0 KB
  - 📄 test_llm_adaptive.py 9.7 KB
  - 📄 test_llm_client.py 14.7 KB
  - 📄 test_llm_judge.py 8.8 KB
  - 📄 test_logger.py 2.7 KB
  - 📄 test_multi_agent.py 27.0 KB
  - 📄 test_owasp_mapping.py 7.4 KB
  - 📄 test_pentest_agent.py 28.1 KB
  - 📄 test_pentest_cli.py 3.8 KB
  - 📄 test_pentest_entities.py 14.3 KB
  - 📄 test_pentest_orchestrator.py 18.3 KB
  - 📄 test_pentest_progress.py 15.5 KB
  - 📄 test_pentest_tools.py 19.0 KB
  - 📄 test_poc_generator.py 10.7 KB
  - 📄 test_policy_engine.py 15.1 KB
  - 📄 test_protocol_handlers.py 23.0 KB
  - 📄 test_reports.py 6.6 KB
  - 📄 test_scanner.py 13.3 KB
  - 📄 test_side_effect_detector.py 10.5 KB
  - 📄 test_skill_cve.py 10.6 KB
  - 📄 test_sse_handler.py 12.9 KB
  - 📄 test_static_analysis.py 16.7 KB
  - 📄 test_storage.py 2.2 KB
  - 📄 test_streaming.py 6.5 KB
  - 📄 test_target_config.py 15.1 KB
  - 📄 test_tool_classifier.py 5.1 KB
  - 📄 test_visualizations.py 5.7 KB
  - 📄 test_ws_handler.py 11.9 KB
- 📄 __init__.py 28 B
- 📄 conftest.py 7.2 KB
📁 ziran/
- 📁 application/
  - 📁 agent_scanner/
    
    📄 __init__.py 60 B
    
    📄 scanner.py 35.9 KB
  - 📁 attacks/
    
    📁 vectors/
    
    📄 a2a_attacks.yaml 13.4 KB
    
    📄 chain_of_thought_manipulation.yaml 21.3 KB
    
    📄 data_exfiltration.yaml 18.6 KB
    
    📄 indirect_injection.yaml 21.0 KB
    
    📄 memory_poisoning.yaml 19.6 KB
    
    📄 multi_agent.yaml 12.9 KB
    
    📄 privilege_escalation.yaml 17.8 KB
    
    📄 prompt_injection.yaml 21.3 KB
    
    📄 system_prompt_extraction.yaml 17.4 KB
    
    📄 tool_manipulation.yaml 17.3 KB
    
    📄 __init__.py 56 B
    
    📄 library.py 11.1 KB
  - 📁 cicd/
    
    📄 __init__.py 0 B
    
    📄 gate.py 6.3 KB
    
    📄 github_actions.py 4.8 KB
    
    📄 sarif.py 5.0 KB
  - 📁 detectors/
    
    📄 __init__.py 61 B
    
    📄 indicator.py 7.3 KB
    
    📄 llm_judge.py 6.3 KB
    
    📄 pipeline.py 9.1 KB
    
    📄 refusal.py 8.9 KB
    
    📄 side_effect.py 8.3 KB
  - 📁 dynamic_vectors/
    
    📄 __init__.py 0 B
    
    📄 config.py 8.3 KB
    
    📄 default_config.yaml 8.8 KB
    
    📄 generator.py 12.4 KB
  - 📁 knowledge_graph/
    
    📄 __init__.py 56 B
    
    📄 chain_analyzer.py 22.0 KB
    
    📄 graph.py 17.6 KB
  - 📁 multi_agent/
    
    📄 __init__.py 249 B
    
    📄 discoverer.py 14.3 KB
    
    📄 scanner.py 11.6 KB
  - 📁 pentesting/
    
    📁 tools/
    
    📄 __init__.py 44 B
    
    📄 explain.py 4.5 KB
    
    📄 external.py 4.2 KB
    
    📄 graph.py 4.5 KB
    
    📄 scan.py 4.8 KB
    
    📄 vectors.py 2.4 KB
    
    📄 __init__.py 70 B
    
    📄 agent.py 25.2 KB
    
    📄 deduplication.py 10.0 KB
    
    📄 orchestrator.py 23.1 KB
    
    📄 progress.py 7.7 KB
    
    📄 prompts.py 5.4 KB
  - 📁 poc/
    
    📄 __init__.py 0 B
    
    📄 config.py 6.1 KB
    
    📄 default_config.yaml 1.8 KB
    
    📄 generator.py 14.8 KB
  - 📁 policy/
    
    📄 __init__.py 0 B
    
    📄 default_policy.yaml 3.2 KB
    
    📄 engine.py 12.3 KB
  - 📁 skill_cve/
    
    📄 __init__.py 13.7 KB
    
    📄 database.py 179 B
  - 📁 static_analysis/
    
    📄 __init__.py 0 B
    
    📄 analyzer.py 9.1 KB
    
    📄 config.py 8.0 KB
    
    📄 default_config.yaml 6.8 KB
  - 📁 strategies/
    
    📄 __init__.py 219 B
    
    📄 adaptive.py 9.8 KB
    
    📄 fixed.py 2.2 KB
    
    📄 llm_adaptive.py 9.6 KB
    
    📄 protocol.py 4.9 KB
  - 📄 __init__.py 55 B
- 📁 domain/
  - 📁 entities/
    
    📄 __init__.py 42 B
    
    📄 a2a.py 8.8 KB
    
    📄 attack.py 6.7 KB
    
    📄 capability.py 4.1 KB
    
    📄 ci.py 3.5 KB
    
    📄 detection.py 2.0 KB
    
    📄 multi_agent.py 7.1 KB
    
    📄 pentest.py 6.7 KB
    
    📄 phase.py 5.3 KB
    
    📄 policy.py 3.4 KB
    
    📄 streaming.py 1.9 KB
    
    📄 target.py 9.4 KB
  - 📁 interfaces/
    
    📄 __init__.py 65 B
    
    📄 adapter.py 5.2 KB
    
    📄 detector.py 1.6 KB
  - 📄 __init__.py 72 B
  - 📄 tool_classifier.py 8.0 KB
- 📁 infrastructure/
  - 📁 adapters/
    
    📁 protocols/
    
    📄 __init__.py 3.8 KB
    
    📄 a2a_handler.py 14.6 KB
    
    📄 mcp_handler.py 8.2 KB
    
    📄 openai_handler.py 10.5 KB
    
    📄 rest_handler.py 3.8 KB
    
    📄 sse_handler.py 12.6 KB
    
    📄 ws_handler.py 11.0 KB
    
    📄 __init__.py 32 B
    
    📄 agentcore_adapter.py 7.4 KB
    
    📄 bedrock_adapter.py 8.7 KB
    
    📄 crewai_adapter.py 5.6 KB
    
    📄 http_adapter.py 17.2 KB
    
    📄 langchain_adapter.py 8.6 KB
  - 📁 llm/
    
    📄 __init__.py 846 B
    
    📄 base.py 4.9 KB
    
    📄 factory.py 3.6 KB
    
    📄 litellm_client.py 7.2 KB
  - 📁 logging/
    
    📄 __init__.py 44 B
    
    📄 logger.py 2.3 KB
  - 📁 storage/
    
    📄 __init__.py 33 B
    
    📄 graph_storage.py 4.4 KB
  - 📄 __init__.py 61 B
- 📁 interfaces/
  - 📁 cli/
    
    📁 visualizations/
    
    📄 __init__.py 12.7 KB
    
    📄 graph_viz.py 154 B
    
    📄 __init__.py 55 B
    
    📄 html_report.py 37.1 KB
    
    📄 main.py 69.7 KB
    
    📄 reports.py 11.0 KB
  - 📄 __init__.py 49 B
- 📄 __init__.py 868 B
- 📄 py.typed 9 B
📄 .env.example 442 B
📄 .gitignore 656 B
📄 action.yml 8.1 KB
📄 CONTRIBUTING.md 3.0 KB
📄 LICENSE 10.5 KB
📄 mkdocs.yml 2.6 KB
📄 NOTICE 770 B
📄 pyproject.toml 3.8 KB
📄 README.md 14.3 KB
📄 SKILL.md 6.5 KB

SKILL.md

# ZIRAN — AI Agent Security Testing Framework

## What is this project?

ZIRAN is an open-source security testing framework for AI agents. It tests agents with tools, memory, and multi-step reasoning — not just LLMs. It runs multi-phase trust exploitation campaigns, analyzes dangerous tool chain combinations, and tracks attack paths via knowledge graphs.

Built by [TaoQ AI](https://www.taoq.ai). Licensed under Apache-2.0.

## Tech stack

- **Language:** Python 3.11+ (tested on 3.11, 3.12, 3.13)
- **Package manager:** [uv](https://docs.astral.sh/uv/)
- **Build system:** hatchling + hatch-vcs (version from git tags)
- **Linter/formatter:** Ruff
- **Type checker:** MyPy (strict mode, with pydantic plugin)
- **Test framework:** pytest + pytest-asyncio + pytest-cov
- **Core libraries:** Pydantic, NetworkX, Click, Rich, httpx, PyYAML

## Architecture

Clean Architecture with Domain-Driven Design:

```
ziran/
├── domain/           # Pure entities (Pydantic models) and interfaces — no infrastructure/framework dependencies
│   ├── entities/     # Data models: attack, phase, capability, target, detection, etc.
│   └── interfaces/   # Abstract base classes: BaseAgentAdapter, detector protocols
├── application/      # Business logic — orchestrators, strategies, detectors
│   ├── agent_scanner/ # Core campaign orchestrator (AgentScanner)
│   ├── attacks/       # Attack library + YAML vector files
│   ├── strategies/    # Campaign execution: fixed, adaptive, llm-adaptive
│   ├── knowledge_graph/ # NetworkX MultiDiGraph + chain analyzer (30+ patterns)
│   ├── detectors/     # Vulnerability detection pipeline
│   ├── pentesting/    # Autonomous pentesting agent (LangGraph-based)
│   ├── cicd/          # CI/CD gate, SARIF output, GitHub Actions integration
│   ├── multi_agent/   # Multi-agent system scanning
│   ├── dynamic_vectors/ # Runtime attack generation
│   ├── poc/           # Proof-of-concept exploit generation
│   ├── policy/        # Policy engine
│   ├── skill_cve/     # CVE knowledge base
│   └── static_analysis/ # Source code analysis
├── infrastructure/   # Technical implementations — adapters, LLM clients, storage
│   ├── adapters/      # Framework adapters: langchain, crewai, bedrock, agentcore, http
│   │   └── protocols/ # Protocol handlers: rest, openai, mcp, a2a, sse, ws
│   ├── llm/           # LiteLLM-based multi-provider LLM client
│   ├── logging/       # Structured logging
│   └── storage/       # JSON-based graph persistence
└── interfaces/       # User-facing layer
    └── cli/           # Click-based CLI (main.py), reports, visualizations
```

## Key commands

```bash
# Setup
uv sync --group dev                  # Install all dev dependencies

# Quality checks
uv run ruff check .                  # Lint
uv run ruff format .                 # Format
uv run ruff format --check .         # Format check (CI)
uv run mypy ziran/                   # Type check (strict)

# Testing
uv run pytest                        # All tests
uv run pytest -m "not integration"   # Unit tests only
uv run pytest -m integration         # Integration tests only
uv run pytest --cov=ziran            # With coverage
uv run pytest -k "test_name"         # Specific test

# Build
uv build                             # Build wheel + sdist
```

## CLI entry point

`ziran = ziran.interfaces.cli.main:cli` — Click command group.

Main commands: `scan`, `discover`, `library`, `report`, `poc`, `policy`, `audit`, `ci`, `multi-agent-scan`, `pentest`.

## Conventions

- **Type hints everywhere** — MyPy strict mode is enforced
- **Pydantic models** for all domain entities
- **Google-style docstrings** for public APIs
- **Composition over inheritance** — adapters implement `BaseAgentAdapter` ABC
- **Ruff rules:** E, W, F, I, N, UP, B, SIM, TCH, RUF (E501 ignored)
- **Line length:** 100 characters
- **Commit style:** `type: short description` — types: feat, fix, docs, test, refactor, chore
- **Coverage gate:** 80% minimum (pyproject.toml), 89% in CI
- **Attack vectors:** YAML files in `ziran/application/attacks/vectors/`
- **Tests mirror source:** `tests/unit/` and `tests/integration/`

## Optional dependency groups

The project has optional extras for framework integrations:

- `langchain` — LangChain agent support
- `crewai` — CrewAI framework support
- `a2a` — Agent-to-Agent protocol
- `bedrock` — AWS Bedrock agents
- `agentcore` — Bedrock AgentCore
- `llm` — LiteLLM multi-provider routing
- `pentest` — Autonomous pentesting agent (includes llm + langgraph + numpy)
- `all` — Everything

Install extras: `pip install ziran[all]` or `uv sync --extra all`

## Key domain concepts

- **Campaign:** A multi-phase security scan (8 phases: reconnaissance through exfiltration)
- **Attack vector:** A YAML-defined prompt template with success/failure indicators and OWASP mapping
- **Knowledge graph:** NetworkX MultiDiGraph tracking tools, data sources, permissions, vulnerabilities, and exploit chains
- **Chain analysis:** Detects dangerous tool compositions (e.g., `read_file` + `http_request` = data exfiltration)
- **Adapter:** Framework-specific integration layer implementing `BaseAgentAdapter`
- **Strategy:** Campaign execution plan (fixed, adaptive, or llm-adaptive)
- **Detection pipeline:** Multi-detector system (indicator-based, LLM judge, refusal detector)

## CI/CD

GitHub Actions workflows in `.github/workflows/`:

- `ci.yml` — Primary pipeline: lint + typecheck + test (Python 3.11/3.12/3.13) + integration tests
- `test.yml` — Unit & integration tests with Codecov upload
- `lint.yml` — Ruff + MyPy checks
- `release.yml` — Build + publish to PyPI on version tags (`v*.*.*`)
- `action-test.yml` — Self-testing for the GitHub Action (`action.yml`)

## Environment variables

LLM configuration (for adaptive campaigns, pentesting agent, LLM judge):

- `ZIRAN_LLM_PROVIDER` — LLM provider name (default: `litellm`)
- `ZIRAN_LLM_MODEL` — Model name (default: `gpt-4o`)
- `ZIRAN_LLM_API_KEY_ENV` — Name of the env var holding the API key (e.g., `OPENAI_API_KEY`)
- `ZIRAN_LLM_BASE_URL` — Override base URL for the LLM provider
- `ZIRAN_LLM_TEMPERATURE` — Sampling temperature (default: `0.0`)
- `ZIRAN_LLM_MAX_TOKENS` — Max response tokens (default: `4096`)

API keys (set whichever your chosen provider requires):

- `OPENAI_API_KEY` — For OpenAI models
- `ANTHROPIC_API_KEY` — For Anthropic models

See `.env.example` for reference.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

ziran

Directory Structure

SKILL.md

Report

Notice