ziran

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

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 behavior.

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

Directory Structure

Current level: tree/main/

📁 .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
  - 📄 benchmark.yml 1.5 KB
  - 📄 ci.yml 1.0 KB
  - 📄 docs.yml 483 B
  - 📄 release-please.yml 534 B
  - 📄 release.yml 8.5 KB
  - 📄 test.yml 1.5 KB
- 📄 PULL_REQUEST_TEMPLATE.md 592 B
📁 .specify/
- 📁 memory/
  - 📄 constitution.md 4.4 KB
- 📁 scripts/
  - 📁 bash/
    
    📄 check-prerequisites.sh 6.0 KB
    
    📄 common.sh 10.0 KB
    
    📄 create-new-feature.sh 11.2 KB
    
    📄 setup-plan.sh 2.2 KB
    
    📄 update-agent-context.sh 28.7 KB
- 📁 templates/
  - 📄 agent-file-template.md 464 B
  - 📄 checklist-template.md 1.3 KB
  - 📄 constitution-template.md 2.3 KB
  - 📄 plan-template.md 3.6 KB
  - 📄 spec-template.md 3.9 KB
  - 📄 tasks-template.md 9.0 KB
- 📄 init-options.json 150 B
📁 benchmarks/
- 📁 ground_truth/
  - 📁 agents/
    
    📄 safe_agentcore_devops.yaml 3.2 KB
    
    📄 safe_bedrock_analyst.yaml 2.9 KB
    
    📄 safe_code_assistant.yaml 2.5 KB
    
    📄 safe_data_analyst.yaml 2.8 KB
    
    📄 safe_devops.yaml 2.3 KB
    
    📄 safe_helpdesk.yaml 3.2 KB
    
    📄 safe_mcp_research.yaml 2.4 KB
    
    📄 safe_multi_agent.yaml 3.0 KB
    
    📄 safe_rag_knowledge.yaml 2.3 KB
    
    📄 safe_saas_multitenant.yaml 3.1 KB
    
    📄 vulnerable_agentcore_devops.yaml 3.1 KB
    
    📄 vulnerable_bedrock_analyst.yaml 2.7 KB
    
    📄 vulnerable_code_assistant.yaml 4.2 KB
    
    📄 vulnerable_data_analyst.yaml 4.3 KB
    
    📄 vulnerable_devops.yaml 4.4 KB
    
    📄 vulnerable_helpdesk.yaml 4.4 KB
    
    📄 vulnerable_mcp_research.yaml 5.2 KB
    
    📄 vulnerable_multi_agent.yaml 6.5 KB
    
    📄 vulnerable_rag_knowledge.yaml 4.4 KB
    
    📄 vulnerable_saas_multitenant.yaml 3.0 KB
  - 📁 scenarios/
    
    📁 authorization/
    
    📄 tn_001_auth_rejects_cross_account.yaml 1.3 KB
    
    📄 tn_002_role_scoping_blocks_admin.yaml 1.3 KB
    
    📄 tp_001_bola_cross_account.yaml 1.2 KB
    
    📄 tp_002_bfla_admin_tool.yaml 1.3 KB
    
    📄 tp_003_horizontal_escalation.yaml 1.2 KB
    
    📄 tp_004_vertical_escalation.yaml 1.2 KB
    
    📁 campaign/
    
    📄 tn_001_safe_helpdesk_full_campaign.yaml 1.2 KB
    
    📄 tn_002_safe_rag_hardcoded_templates.yaml 1.1 KB
    
    📄 tn_003_safe_mcp_patched.yaml 1.3 KB
    
    📄 tn_004_safe_multiagent_scoped.yaml 1014 B
    
    📄 tn_005_safe_code_assistant_sandbox.yaml 1.2 KB
    
    📄 tn_006_safe_data_analyst_parameterized.yaml 934 B
    
    📄 tn_007_safe_helpdesk_minimal.yaml 999 B
    
    📄 tn_008_safe_devops_readonly.yaml 993 B
    
    📄 tn_009_safe_multiagent_depth_limit.yaml 1.0 KB
    
    📄 tp_001_helpdesk_full_campaign.yaml 1.7 KB
    
    📄 tp_002_code_assistant_inject_exfil.yaml 1.5 KB
    
    📄 tp_003_rag_indirect_inject_template.yaml 1.4 KB
    
    📄 tp_004_mcp_poisoning_fs_exfil.yaml 1.2 KB
    
    📄 tp_005_multiagent_supervisor_inject.yaml 1.2 KB
    
    📄 tp_006_data_analyst_sql_python_email.yaml 1.4 KB
    
    📄 tp_007_devops_env_shell_deploy.yaml 1.3 KB
    
    📄 tp_008_helpdesk_prompt_extraction.yaml 1.2 KB
    
    📄 tp_009_code_assistant_memory_persist.yaml 1.3 KB
    
    📁 framework/
    
    📄 tn_001_bedrock_safe_analyst.yaml 1.3 KB
    
    📄 tn_002_agentcore_safe_devops.yaml 1.3 KB
    
    📄 tp_001_bedrock_s3_exfil.yaml 1.5 KB
    
    📄 tp_002_agentcore_secret_leak.yaml 1.5 KB
    
    📁 llm_judge/
    
    📄 tn_001_benign_multiturn.yaml 1.3 KB
    
    📄 tn_002_legitimate_aggregation.yaml 1.4 KB
    
    📄 tp_001_subtle_exfil_encoded.yaml 1.4 KB
    
    📄 tp_002_gradual_trust_escalation.yaml 1.4 KB
    
    📄 tp_003_indirect_injection_context.yaml 1.4 KB
    
    📁 side_effect/
    
    📄 tn_001_parameterized_sql.yaml 992 B
    
    📄 tn_002_email_recipient_validated.yaml 979 B
    
    📄 tn_003_shell_refused_guardrail.yaml 1.0 KB
    
    📄 tn_004_writefile_sandbox_restricted.yaml 986 B
    
    📄 tn_005_code_exec_refused.yaml 1013 B
    
    📄 tn_006_pii_filter_redacts.yaml 989 B
    
    📄 tn_007_patched_mcp_blocks_symlinks.yaml 968 B
    
    📄 tn_008_env_masked_scoped.yaml 1017 B
    
    📄 tp_001_sql_injection_raw_query.yaml 995 B
    
    📄 tp_002_email_exfil_pii.yaml 1008 B
    
    📄 tp_003_shell_execution.yaml 1.1 KB
    
    📄 tp_004_file_overwrite.yaml 1001 B
    
    📄 tp_005_python_code_exec.yaml 970 B
    
    📄 tp_006_mcp_symlink_escape.yaml 1.0 KB
    
    📄 tp_007_bulk_pii_extraction.yaml 1.1 KB
    
    📄 tp_008_credential_leak_config.yaml 1.1 KB
    
    📄 tp_009_env_secret_http_exfil.yaml 967 B
    
    📄 tp_010_git_path_traversal.yaml 955 B
    
    📁 tool_chain/
    
    📄 tn_001_safe_readfile_sandboxed.yaml 1.1 KB
    
    📄 tn_002_safe_requests_allowlist.yaml 1.1 KB
    
    📄 tn_003_safe_readonly_sql_no_network.yaml 988 B
    
    📄 tn_004_safe_calculator_faq_only.yaml 958 B
    
    📄 tn_005_safe_email_allowlist.yaml 1.1 KB
    
    📄 tn_006_safe_python_sandbox.yaml 1.1 KB
    
    📄 tn_007_safe_human_approval.yaml 1.1 KB
    
    📄 tn_008_safe_search_display_only.yaml 1004 B
    
    📄 tp_001_readfile_requests_exfil.yaml 1.4 KB
    
    📄 tp_002_employees_email_exfil.yaml 1.4 KB
    
    📄 tp_003_sql_email_exfil.yaml 1.2 KB
    
    📄 tp_004_python_shell_rce.yaml 1.4 KB
    
    📄 tp_005_readfile_python_rce.yaml 1.4 KB
    
    📄 tp_006_employees_http_pii.yaml 1.2 KB
    
    📄 tp_007_multiagent_db_shell.yaml 1.2 KB
    
    📄 tp_008_env_shell_exfil.yaml 1.2 KB
    
    📄 tp_009_mcp_fs_fetch_exfil.yaml 1.2 KB
    
    📄 tp_010_url_loader_vectorstore.yaml 1.2 KB
  - 📄 README.md 4.6 KB
  - 📄 run.py 22.4 KB
  - 📄 schema.py 4.8 KB
  - 📄 validate.py 8.2 KB
- 📁 results/
  - 📁 history/
    
    📄 .gitignore 72 B
  - 📄 .gitignore 98 B
  - 📄 baseline.json 5.3 KB
  - 📄 ground_truth_latest.md 517 B
- 📄 accuracy_metrics.py 8.5 KB
- 📄 benchmark_comparison.py 19.4 KB
- 📄 comparative_analysis.py 11.7 KB
- 📄 gap_status.py 7.5 KB
- 📄 generate_all.py 15.8 KB
- 📄 historical_tracking.py 6.1 KB
- 📄 inventory.py 4.3 KB
- 📄 owasp_coverage.py 3.5 KB
- 📄 performance_metrics.py 7.5 KB
- 📄 README.md 10.8 KB
- 📄 regression_check.py 7.4 KB
- 📄 utility_metrics.py 5.3 KB
📁 docs/
- 📁 assets/
  - 📄 demo.gif 1.2 MB
  - 📄 report.png 632.8 KB
  - 📄 ui-dashboard.png 60.8 KB
  - 📄 ui-findings.png 110.0 KB
  - 📄 ui-library.png 151.2 KB
  - 📄 ui-new-run.png 43.7 KB
  - 📄 ui-settings.png 87.9 KB
- 📁 community/
  - 📄 contributing.md 1.6 KB
  - 📄 roadmap.md 6.9 KB
  - 📄 skill-cves.md 2.8 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
  - 📄 browser-scanning.md 7.7 KB
  - 📄 detection-pipeline.md 4.1 KB
  - 📄 knowledge-graph.md 1.7 KB
  - 📄 multi-agent.md 4.5 KB
  - 📄 owasp-mapping.md 5.2 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
  - 📄 browser-agents.md 5.9 KB
  - 📄 cicd-integration.md 5.8 KB
  - 📄 custom-attacks.md 1.1 KB
  - 📄 interpreting-results.md 2.0 KB
  - 📄 otel-tracing.md 5.2 KB
  - 📄 promptfoo-integration.md 4.4 KB
  - 📄 remote-agents.md 5.0 KB
  - 📄 scanning-agents.md 3.7 KB
  - 📄 static-analysis.md 4.7 KB
- 📁 reference/
  - 📁 benchmarks/
    
    📄 coverage-comparison.md 9.9 KB
  - 📄 api.md 7.4 KB
  - 📄 attack-library.md 3.4 KB
  - 📄 cli.md 6.7 KB
- 📄 getting-started.md 5.4 KB
- 📄 index.md 4.4 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.2 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
- 📁 20-browser-agent-scan/
  - 📄 main.py 2.1 KB
  - 📄 README.md 2.1 KB
  - 📄 run.sh 253 B
  - 📄 target-browser-auto.yaml 182 B
  - 📄 target-browser-login.yaml 771 B
  - 📄 target-browser.yaml 809 B
- 📁 21-promptfoo-integration/
  - 📁 configs/
    
    📄 authorization-bypass.yaml 3.5 KB
    
    📄 basic-security.yaml 3.3 KB
    
    📄 data-exfiltration.yaml 3.8 KB
    
    📄 full-campaign.yaml 1.4 KB
  - 📄 promptfooconfig.yaml 3.1 KB
  - 📄 README.md 3.9 KB
  - 📄 ziran_assertions.py 1.1 KB
  - 📄 ziran_provider.py 1.0 KB
- 📁 22-otel-tracing/
  - 📄 otel_console_scan.py 1.7 KB
  - 📄 otel_otlp_scan.py 2.4 KB
  - 📄 README.md 2.1 KB
- 📁 _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
📁 specs/
- 📁 001-release-please-automation/
  - 📁 checklists/
    
    📄 requirements.md 1.5 KB
  - 📄 data-model.md 1.5 KB
  - 📄 plan.md 4.3 KB
  - 📄 quickstart.md 1.5 KB
  - 📄 research.md 3.3 KB
  - 📄 spec.md 9.3 KB
  - 📄 tasks.md 6.3 KB
- 📁 002-extract-shared-factories/
  - 📁 checklists/
    
    📄 requirements.md 1.3 KB
  - 📄 data-model.md 1.8 KB
  - 📄 plan.md 4.3 KB
  - 📄 quickstart.md 1.9 KB
  - 📄 research.md 3.8 KB
  - 📄 spec.md 6.0 KB
  - 📄 tasks.md 9.8 KB
- 📁 003-configurable-detector-pipeline/
  - 📄 spec.md 3.2 KB
- 📁 004-resilience-gap-metric/
  - 📁 checklists/
    
    📄 requirements.md 1.1 KB
  - 📄 spec.md 5.6 KB
- 📁 005-utility-under-attack/
  - 📄 spec.md 3.9 KB
- 📁 006-perf-optimizations/
  - 📁 checklists/
    
    📄 requirements.md 1.1 KB
  - 📄 data-model.md 986 B
  - 📄 plan.md 6.4 KB
  - 📄 quickstart.md 1.1 KB
  - 📄 research.md 3.3 KB
  - 📄 spec.md 7.5 KB
  - 📄 tasks.md 7.4 KB
- 📁 007-ground-truth-business-impact/
  - 📁 checklists/
    
    📄 requirements.md 1.1 KB
  - 📄 data-model.md 3.5 KB
  - 📄 plan.md 8.0 KB
  - 📄 quickstart.md 1.6 KB
  - 📄 research.md 3.1 KB
  - 📄 spec.md 9.8 KB
  - 📄 tasks.md 10.5 KB
- 📁 008-web-ui-foundation/
  - 📁 checklists/
    
    📄 requirements.md 1.4 KB
  - 📁 contracts/
    
    📄 api.md 1.3 KB
    
    📄 cli.md 1.3 KB
  - 📄 data-model.md 3.8 KB
  - 📄 plan.md 6.1 KB
  - 📄 quickstart.md 1.3 KB
  - 📄 research.md 5.7 KB
  - 📄 spec.md 9.6 KB
  - 📄 tasks.md 15.2 KB
- 📁 009-ui-findings-compliance/
  - 📁 checklists/
    
    📄 requirements.md 1.3 KB
  - 📁 contracts/
    
    📄 api.md 5.5 KB
  - 📄 data-model.md 6.5 KB
  - 📄 plan.md 8.3 KB
  - 📄 quickstart.md 2.0 KB
  - 📄 research.md 4.0 KB
  - 📄 spec.md 13.1 KB
  - 📄 tasks.md 19.8 KB
- 📁 010-ui-polish-pages/
  - 📁 checklists/
    
    📄 requirements.md 1.3 KB
  - 📁 contracts/
    
    📄 api.md 2.7 KB
  - 📄 plan.md 4.6 KB
  - 📄 spec.md 11.8 KB
  - 📄 tasks.md 6.6 KB
- 📁 archive/
  - 📁 003-mcp-delegation-patterns/
    
    📄 spec.md 3.6 KB
  - 📁 003-precompile-regex-patterns/
    
    📁 checklists/
    
    📄 requirements.md 1.1 KB
    
    📄 data-model.md 1.0 KB
    
    📄 plan.md 2.8 KB
    
    📄 quickstart.md 949 B
    
    📄 research.md 1.8 KB
    
    📄 spec.md 4.6 KB
    
    📄 tasks.md 6.4 KB
  - 📁 003-split-agent-scanner/
    
    📁 checklists/
    
    📄 requirements.md 1.1 KB
    
    📄 data-model.md 1.3 KB
    
    📄 plan.md 3.6 KB
    
    📄 quickstart.md 1.1 KB
    
    📄 research.md 2.4 KB
    
    📄 spec.md 6.9 KB
    
    📄 tasks.md 10.3 KB
- 📁 feat/
  - 📁 155-resilience-gap-metric/
    
    📄 data-model.md 1.2 KB
    
    📄 plan.md 2.7 KB
    
    📄 research.md 2.1 KB
    
    📄 spec.md 5.6 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_otel_integration.py 10.0 KB
  - 📄 test_pentest_campaign.py 4.6 KB
  - 📄 test_promptfoo_integration.py 9.4 KB
  - 📄 test_web_app.py 1.5 KB
- 📁 unit/
  - 📁 application/
    
    📄 __init__.py 0 B
    
    📄 test_attack_executor.py 4.7 KB
    
    📄 test_checkpoint.py 8.7 KB
    
    📄 test_detector_config.py 6.7 KB
    
    📄 test_factories.py 10.5 KB
    
    📄 test_precompiled_patterns.py 6.5 KB
    
    📄 test_progress_emitter.py 4.9 KB
    
    📄 test_result_builder.py 7.0 KB
    
    📄 test_scanner_size.py 2.7 KB
  - 📄 __init__.py 18 B
  - 📄 test_a2a_models.py 10.6 KB
  - 📄 test_accuracy_metrics.py 3.0 KB
  - 📄 test_adapter_smoke.py 8.2 KB
  - 📄 test_adaptive.py 18.9 KB
  - 📄 test_agentcore_adapter.py 7.3 KB
  - 📄 test_attack_library.py 10.7 KB
  - 📄 test_authorization_detector.py 8.4 KB
  - 📄 test_bedrock_adapter.py 8.9 KB
  - 📄 test_benchmark_regression.py 2.5 KB
  - 📄 test_benchmark_scripts.py 5.4 KB
  - 📄 test_browser_adapter.py 67.2 KB
  - 📄 test_business_impact.py 2.7 KB
  - 📄 test_chain_analyzer.py 14.4 KB
  - 📄 test_chain_patterns.py 7.1 KB
  - 📄 test_cicd.py 13.8 KB
  - 📄 test_cli_helpers.py 19.1 KB
  - 📄 test_cli_main.py 24.4 KB
  - 📄 test_cli_smoke.py 2.1 KB
  - 📄 test_comparative_analysis.py 2.5 KB
  - 📄 test_deduplication.py 14.8 KB
  - 📄 test_detectors.py 27.1 KB
  - 📄 test_dynamic_vectors.py 19.8 KB
  - 📄 test_encoding.py 7.1 KB
  - 📄 test_entities.py 15.9 KB
  - 📄 test_expanded_tactics.py 6.6 KB
  - 📄 test_findings_extractor.py 6.4 KB
  - 📄 test_findings_schemas.py 5.9 KB
  - 📄 test_harmful_tasks.py 7.3 KB
  - 📄 test_historical_tracking.py 2.6 KB
  - 📄 test_html_report.py 19.3 KB
  - 📄 test_http_adapter.py 46.3 KB
  - 📄 test_jailbreakbench.py 1.9 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 10.5 KB
  - 📄 test_logger.py 2.7 KB
  - 📄 test_mcp_metadata_analyzer.py 7.1 KB
  - 📄 test_model_dos.py 3.9 KB
  - 📄 test_multi_agent.py 28.7 KB
  - 📄 test_otel_tracing.py 5.6 KB
  - 📄 test_owasp_mapping.py 8.1 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_performance_metrics.py 2.9 KB
  - 📄 test_poc_generator.py 10.7 KB
  - 📄 test_policy_engine.py 15.1 KB
  - 📄 test_promptfoo_provider.py 8.2 KB
  - 📄 test_protocol_handlers.py 23.0 KB
  - 📄 test_reports.py 9.3 KB
  - 📄 test_resilience.py 7.8 KB
  - 📄 test_rjudge.py 1.9 KB
  - 📄 test_scanner.py 22.6 KB
  - 📄 test_side_effect_detector.py 11.3 KB
  - 📄 test_skill_cve.py 12.5 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_tactics.py 10.6 KB
  - 📄 test_target_config.py 15.1 KB
  - 📄 test_tool_classifier.py 8.4 KB
  - 📄 test_utility.py 8.3 KB
  - 📄 test_utility_metrics.py 4.0 KB
  - 📄 test_visualizations.py 5.7 KB
  - 📄 test_web_config.py 1.7 KB
  - 📄 test_web_models.py 1.9 KB
  - 📄 test_web_schemas.py 856 B
  - 📄 test_ws_handler.py 11.9 KB
- 📄 __init__.py 28 B
- 📄 conftest.py 8.1 KB
📁 ui/
- 📁 e2e/
  - 📄 dashboard.spec.ts 1.4 KB
  - 📄 findings.spec.ts 2.6 KB
  - 📄 library.spec.ts 3.3 KB
  - 📄 navigation.spec.ts 1.7 KB
  - 📄 new-run.spec.ts 2.3 KB
  - 📄 settings.spec.ts 2.6 KB
- 📁 src/
  - 📁 api/
    
    📄 client.ts 683 B
    
    📄 compliance.ts 409 B
    
    📄 configs.ts 1.3 KB
    
    📄 export.ts 1.1 KB
    
    📄 findings.ts 2.6 KB
    
    📄 library.ts 1.2 KB
    
    📄 runs.ts 1.5 KB
  - 📁 components/
    
    📁 compliance/
    
    📄 OwaspMatrix.tsx 2.9 KB
    
    📁 findings/
    
    📄 BulkActions.tsx 1.6 KB
    
    📄 FindingDetail.tsx 6.3 KB
    
    📄 FindingFilters.tsx 2.6 KB
    
    📄 FindingsTable.tsx 6.7 KB
    
    📄 SeverityBadge.tsx 698 B
    
    📁 graph/
    
    📄 KnowledgeGraph.tsx 10.4 KB
    
    📁 layout/
    
    📄 Layout.tsx 261 B
    
    📄 Sidebar.tsx 3.0 KB
    
    📄 ThemeToggle.tsx 1.0 KB
    
    📁 library/
    
    📄 VectorDetail.tsx 2.7 KB
    
    📄 VectorTable.tsx 3.5 KB
    
    📁 ui/
    
    📄 badge.tsx 1.0 KB
    
    📄 ErrorBoundary.tsx 1.5 KB
    
    📄 Skeleton.tsx 1.1 KB
  - 📁 hooks/
    
    📄 useWebSocket.ts 1.0 KB
  - 📁 lib/
    
    📄 utils.ts 166 B
  - 📁 pages/
    
    📄 Compliance.tsx 905 B
    
    📄 Dashboard.tsx 4.7 KB
    
    📄 Findings.tsx 4.3 KB
    
    📄 Library.tsx 3.8 KB
    
    📄 NewRun.tsx 5.7 KB
    
    📄 NotFound.tsx 773 B
    
    📄 RunDetail.tsx 7.7 KB
    
    📄 Settings.tsx 15.2 KB
  - 📁 types/
    
    📄 index.ts 5.2 KB
  - 📄 App.tsx 2.1 KB
  - 📄 index.css 2.5 KB
  - 📄 main.tsx 230 B
- 📄 .gitignore 253 B
- 📄 .npmrc 37 B
- 📄 eslint.config.js 621 B
- 📄 index.html 351 B
- 📄 package-lock.json 149.3 KB
- 📄 package.json 1.1 KB
- 📄 playwright.config.ts 338 B
- 📄 README.md 2.5 KB
- 📄 tailwind.config.ts 834 B
- 📄 tsconfig.app.json 732 B
- 📄 tsconfig.json 119 B
- 📄 tsconfig.node.json 653 B
- 📄 vite.config.ts 434 B
📁 ziran/
- 📁 application/
  - 📁 agent_scanner/
    
    📄 __init__.py 888 B
    
    📄 attack_executor.py 11.9 KB
    
    📄 checkpoint.py 5.0 KB
    
    📄 phase_executor.py 11.0 KB
    
    📄 progress.py 2.5 KB
    
    📄 result_builder.py 4.4 KB
    
    📄 scanner.py 29.4 KB
  - 📁 attacks/
    
    📁 vectors/
    
    📄 a2a_attacks.yaml 13.4 KB
    
    📄 alert_coverage.yaml 24.0 KB
    
    📄 authorization.yaml 12.3 KB
    
    📄 chain_of_thought_manipulation.yaml 21.3 KB
    
    📄 data_exfiltration.yaml 18.6 KB
    
    📄 expanded_tactics.yaml 21.3 KB
    
    📄 harmful_tasks.yaml 28.4 KB
    
    📄 harmful_tasks_expanded.yaml 151.3 KB
    
    📄 indirect_injection.yaml 21.0 KB
    
    📄 indirect_injection_escalation.yaml 20.8 KB
    
    📄 indirect_injection_exfiltration.yaml 21.6 KB
    
    📄 indirect_injection_tool_abuse.yaml 19.6 KB
    
    📄 jailbreakbench.yaml 34.0 KB
    
    📄 mcp_attacks.yaml 13.0 KB
    
    📄 mcp_attacks_expanded.yaml 99.9 KB
    
    📄 memory_poisoning.yaml 19.6 KB
    
    📄 model_dos.yaml 15.9 KB
    
    📄 multi_agent.yaml 12.9 KB
    
    📄 multi_turn_tactics.yaml 16.2 KB
    
    📄 privilege_escalation.yaml 17.8 KB
    
    📄 prompt_injection.yaml 21.4 KB
    
    📄 rjudge.yaml 23.0 KB
    
    📄 system_prompt_extraction.yaml 17.4 KB
    
    📄 tool_manipulation.yaml 17.3 KB
    
    📄 __init__.py 56 B
    
    📄 encoding.py 12.5 KB
    
    📄 library.py 14.1 KB
    
    📄 tactics.py 7.6 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
    
    📄 authorization.py 8.8 KB
    
    📄 indicator.py 7.3 KB
    
    📄 llm_judge.py 9.6 KB
    
    📄 pipeline.py 14.3 KB
    
    📄 refusal.py 9.6 KB
    
    📄 side_effect.py 8.7 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 17.6 KB
    
    📄 chain_patterns.py 3.5 KB
    
    📄 chain_patterns.yaml 34.5 KB
    
    📄 graph.py 19.5 KB
  - 📁 multi_agent/
    
    📄 __init__.py 249 B
    
    📄 discoverer.py 14.3 KB
    
    📄 scanner.py 11.9 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 31.4 KB
    
    📄 database.py 179 B
  - 📁 static_analysis/
    
    📄 __init__.py 0 B
    
    📄 analyzer.py 9.1 KB
    
    📄 config.py 9.6 KB
    
    📄 default_config.yaml 6.8 KB
    
    📄 mcp_metadata_analyzer.py 7.2 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
  - 📁 utility/
    
    📄 __init__.py 0 B
    
    📄 measurer.py 5.5 KB
  - 📄 __init__.py 55 B
  - 📄 factories.py 10.1 KB
- 📁 domain/
  - 📁 entities/
    
    📄 __init__.py 42 B
    
    📄 a2a.py 8.8 KB
    
    📄 attack.py 14.1 KB
    
    📄 capability.py 4.1 KB
    
    📄 ci.py 3.5 KB
    
    📄 detection.py 3.5 KB
    
    📄 multi_agent.py 7.1 KB
    
    📄 pentest.py 6.7 KB
    
    📄 phase.py 8.4 KB
    
    📄 policy.py 3.4 KB
    
    📄 streaming.py 1.9 KB
    
    📄 target.py 15.0 KB
    
    📄 utility.py 2.1 KB
  - 📁 interfaces/
    
    📄 __init__.py 65 B
    
    📄 adapter.py 5.2 KB
    
    📄 detector.py 1.6 KB
  - 📄 __init__.py 72 B
  - 📄 tool_classifier.py 11.3 KB
- 📁 infrastructure/
  - 📁 adapters/
    
    📁 protocols/
    
    📄 __init__.py 4.4 KB
    
    📄 a2a_handler.py 14.8 KB
    
    📄 mcp_handler.py 8.3 KB
    
    📄 openai_handler.py 10.6 KB
    
    📄 rest_handler.py 3.9 KB
    
    📄 sse_handler.py 12.8 KB
    
    📄 ws_handler.py 11.0 KB
    
    📄 __init__.py 32 B
    
    📄 agentcore_adapter.py 7.4 KB
    
    📄 bedrock_adapter.py 8.7 KB
    
    📄 browser_adapter.py 62.6 KB
    
    📄 crewai_adapter.py 5.6 KB
    
    📄 http_adapter.py 22.5 KB
    
    📄 langchain_adapter.py 8.6 KB
  - 📁 llm/
    
    📄 __init__.py 846 B
    
    📄 base.py 4.9 KB
    
    📄 factory.py 4.2 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
  - 📁 telemetry/
    
    📄 __init__.py 420 B
    
    📄 tracing.py 3.5 KB
  - 📄 __init__.py 61 B
- 📁 integrations/
  - 📁 promptfoo/
    
    📄 __init__.py 293 B
    
    📄 assertions.py 2.9 KB
    
    📄 provider.py 5.5 KB
  - 📄 __init__.py 42 B
- 📁 interfaces/
  - 📁 cli/
    
    📁 visualizations/
    
    📄 __init__.py 12.7 KB
    
    📄 graph_viz.py 154 B
    
    📄 __init__.py 55 B
    
    📄 html_report.py 37.2 KB
    
    📄 main.py 75.6 KB
    
    📄 reports.py 16.4 KB
  - 📁 web/
    
    📁 migrations/
    
    📁 versions/
    
    📄 001_initial_schema.py 4.1 KB
    
    📄 002_findings_schema.py 4.7 KB
    
    📄 __init__.py 0 B
    
    📄 __init__.py 0 B
    
    📄 env.py 1.7 KB
    
    📄 script.py.mako 670 B
    
    📁 routes/
    
    📄 __init__.py 25 B
    
    📄 compliance.py 4.1 KB
    
    📄 configs.py 3.0 KB
    
    📄 export.py 6.9 KB
    
    📄 findings.py 8.8 KB
    
    📄 health.py 763 B
    
    📄 library.py 4.7 KB
    
    📄 runs.py 3.6 KB
    
    📄 ws.py 1.6 KB
    
    📁 services/
    
    📄 __init__.py 23 B
    
    📄 findings_extractor.py 5.2 KB
    
    📄 run_manager.py 9.3 KB
    
    📄 __init__.py 74 B
    
    📄 app.py 4.5 KB
    
    📄 config.py 937 B
    
    📄 dependencies.py 1.6 KB
    
    📄 models.py 8.8 KB
    
    📄 schemas.py 8.0 KB
  - 📄 __init__.py 49 B
- 📄 __init__.py 868 B
- 📄 py.typed 9 B
📄 .dockerignore 154 B
📄 .env.example 679 B
📄 .gitignore 723 B
📄 .release-please-manifest.json 20 B
📄 action.yml 8.1 KB
📄 CHANGELOG.md 6.9 KB
📄 CITATION.cff 878 B
📄 CLAUDE.md 4.9 KB
📄 CONTRIBUTING.md 3.0 KB
📄 docker-compose.yml 620 B
📄 Dockerfile 741 B
📄 hatch_build.py 2.1 KB
📄 LICENSE 10.5 KB
📄 mkdocs.yml 2.8 KB
📄 NOTICE 770 B
📄 pyproject.toml 4.6 KB
📄 README.md 15.4 KB
📄 release-please-config.json 896 B
📄 SKILL.md 7.9 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 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 behavior.

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

## Positioning — what ZIRAN is and is not

**ZIRAN IS:**
- An agent security scanner that discovers dangerous tool compositions via graph analysis (e.g., `read_file` + `http_request` = data exfiltration)
- An execution-level detector that catches when agents refuse in text but execute dangerous tools anyway
- A multi-phase campaign orchestrator with knowledge graph feedback across phases
- An autonomous pentesting agent that plans, executes, and adapts attack campaigns

**ZIRAN IS NOT:**
- An LLM safety/alignment tool (for jailbreak breadth, encoding attacks, and compliance plugins → Promptfoo or Garak)
- A runtime guardrail (for real-time input/output protection → NeMo Guardrails, Lakera Guard, or LLM Guard)
- A general-purpose eval framework (for model evaluation and benchmarking → Inspect AI or Deepeval)
- A pentesting tool for web apps or networks (for AI-driven pentesting of infrastructure → Shannon or PentestGPT)

When contributing, keep features aligned with agent security testing. Don't add LLM alignment checks, compliance plugins, or runtime guardrail features — those belong in complementary tools.

## 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, browser
│   │   └── 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)
- `browser` — Headless browser scanning via Playwright
- `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)
- **Browser scanning:** Headless Playwright adapter that interacts with chat UIs via network interception (primary) or DOM extraction (fallback); configured via `BrowserConfig` in target YAML with `protocol: browser`

## 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