Skip to content
Back to search

adk_runbooks

A comprehensive multi-agent cybersecurity operations system built on Google's Agent Development Kit (ADK). This project provides specialized AI agents that collaborate to handle complex security…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dandye--adk-runbooks/badge.svg)](/listings/dandye--adk-runbooks)

HTML

<a href="/listings/dandye--adk-runbooks"><img src="/api/listings/dandye--adk-runbooks/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.10+ - Google API key (for Gemini models) - Virtual environment tool (`venv`)

Basic Setup

# Clone the repository with submodules
git clone --recurse-submodules https://github.com/dandye/adk_runbooks.git
cd adk_runbooks

# If already cloned without submodules:
git submodule update --init --recursive

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r multi-agent/requirements.txt

# Configure environment
cp multi-agent/manager/.env.example multi-agent/manager/.env
# Edit multi-agent/manager/.env and add your GOOGLE_API_KEY

Running the Multi-Agent System

# Run CLI interface
cd multi-agent
adk run manager

# Run Web UI
adk web

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 210 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ADK Runbooks
  2. A comprehensive multi-agent cybersecurity operations system built on Google's Agent Development Kit (ADK). This project provides specialized AI agents that collaborate to handle complex security operations tasks—including incident response, threat hunting, detection engineering, alert triage, and investigation—powered by a **Progressive Disclosure Skills Architecture**.
  3. ## Documentation
  4. The full documentation for this project, including detailed runbooks and agent information, is available at:
  5. [https://dandye.github.io/adk_runbooks](https://dandye.github.io/adk_runbooks)
  6. ## Overview
  7. ADK Runbooks implements a manager-orchestrated multi-agent system where specialized security agents work together to execute security operations. Instead of inlining entire runbook corpora into system prompts, the system employs **Progressive Disclosure**: agents receive concise skill catalogs in their context and dynamically load full procedural playbooks, execution guidelines, and rubrics on-demand using specialized skill tools.
  8. ### Key Features
  9. - **Multi-Agent Architecture**: A root Manager agent coordinates specialized sub-agents with domain expertise and shared toolsets.
  10. - **Dual-Tier Progressive Disclosure Framework**:
  11. - **Tier 1 (Skills)**: 62+ battle-tested security skills organized into standard taxonomy packages (`SKILL.md`) indexed by `SkillRegistry`. Agents dynamically fetch step-by-step instructions via `load_skill()`.
  12. - **Tier 2 (MCP Discovery)**: Client-side progressive tool discovery (`MCPToolRegistry`) replaces 30+ upfront static JSON parameter schemas with dynamic meta-tools (`search_mcp_tools`, `get_mcp_tool_schema`, `execute_mcp_tool`), achieving **60.5% token reduction beyond skills alone and 94.0% reduction vs monolithic prompts**.
  13. - **Detection-as-Code (DAC) & Google SecOps 1P MCP Integration**: Dedicated `dac-agent` and Detection Engineer sub-agent integrated with Google Cloud SecOps 1P Agentic Detection Engineering MCP Server (70+ tools for TDO extraction, synthetic UDM events, coverage evaluation, and YARA-L rule generation).
  14. - **Enterprise Security MCP Tooling**: Unified integration across Chronicle SIEM, Chronicle SOAR, VirusTotal / Google Threat Intelligence (GTI), and SecOps Detection Engineering.
  15. - **Rigorous Evaluation & Benchmarking**: 4-rubric graph workflow evaluation framework covering 36+ end-to-end security operations workflows with automated scoring, latency measurement, token usage tracking, and Markdown/JSON report generation.
  16. ---
  17. ## Dual Progressive Disclosure Architecture
  18. Operational procedures and external MCP tools are loaded strictly on-demand to prevent prompt bloat and context degradation:
  19. ```
  20. ┌────────────────────────────────────────────────────────────────────────────┐
  21. │ DUAL PROGRESSIVE DISCLOSURE ARCHITECTURE │
  22. │ │
  23. │ ┌────────────────────────────────────────────────────────────────────────┐ │
  24. │ │ TIER 1: Procedural Skills Progressive Disclosure (`SkillRegistry`) │ │
  25. │ │ - Lean catalog of available skills injected into agent prompt. │ │
  26. │ │ - Full procedural runbook loaded on demand via `load_skill()`. │ │
  27. │ └────────────────────────────────────────────────────────────────────────┘ │
  28. │ │
  29. │ ┌────────────────────────────────────────────────────────────────────────┐ │
  30. │ │ TIER 2: Progressive MCP Tool Discovery (`MCPToolRegistry`) │ │
  31. │ │ - Replaces 30+ static tool schemas with 3 lightweight meta-tools: │ │
  32. │ │ 1. search_mcp_tools(query, server) -> Search available tools │ │
  33. │ │ 2. get_mcp_tool_schema(tool_name) -> Retrieve JSON schema │ │
  34. │ │ 3. execute_mcp_tool(tool_name, args) -> Dynamic tool execution │ │
  35. │ └────────────────────────────────────────────────────────────────────────┘ │
  36. └────────────────────────────────────────────────────────────────────────────┘
  37. ```
  38. ### Skill Taxonomy Categories
  39. | Category | Description | Examples |
  40. |---|---|---|
  41. | **`skills/triage/`** | Alert triage and initial investigation | `triage-alerts`, `suspicious-login-triage`, `malware-triage`, `cloud-vulnerability-triage` |
  42. | **`skills/irps/`** | Incident Response Plans for specific incident classes | `malware-incident-response`, `phishing-response`, `ransomware-response`, `compromised-user-account-response` |
  43. | **`skills/investigation/`** | Case investigation, grouping, timelines, and IOC analysis | `deep-dive-ioc-analysis`, `prioritize-and-investigate-case`, `case-event-timeline-analysis`, `ioc-containment` |
  44. | **`skills/hunting/`** | Proactive threat hunting playbooks | `advanced-threat-hunting`, `apt-threat-hunt`, `ioc-threat-hunt`, `lateral-movement-hunt-psexec-wmi` |
  45. | **`skills/detection/`** | Detection-as-Code workflows, coverage evaluation, and rule validation | `detection-engineering-coverage-evaluation`, `detection-rule-validation-tuning`, `detection-as-code-workflows` |
  46. | **`skills/reporting/`** | Standardized reporting guidelines and templates | `report-writing-guidelines`, `create-investigation-report`, `alert-report`, `case-report`, `detection-report` |
  47. | **`skills/atomic/`** | Atomic IOC lookups and enrichment steps | `lookup-ip-chronicle`, `lookup-domain-gti`, `search-chronicle-udm-hash`, `lookup-user-chronicle` |
  48. | **`skills/common/`** | Reusable operational procedures | `document-in-soar`, `close-soar-artifact`, `find-relevant-soar-case`, `enrich-ioc`, `generate-report-file` |
  49. ---
  50. ## Security Agents & Model Distribution
  51. | Agent | Module | Default Model | Role & Core Responsibilities |
  52. |---|---|:---:|---|
  53. | **Manager Agent** | `multi-agent/manager/agent.py` | `gemini-3.7-flash` | Root orchestrator; triages requests, delegates to specialists, tracks IRP lifecycle. |
  54. | **SOC Analyst Tier 1** | `multi-agent/manager/sub_agents/soc_analyst_tier1/` | `gemini-2.5-flash-lite` | High-speed initial alert triage, basic IOC enrichment, duplicate case handling. |
  55. | **SOC Analyst Tier 2** | `multi-agent/manager/sub_agents/soc_analyst_tier2/` | `gemini-2.5-flash-lite` | Case investigation, event timeline analysis, GTI campaign correlation. |
  56. | **SOC Analyst Tier 3** | `multi-agent/manager/sub_agents/soc_analyst_tier3/` | `gemini-3.7-flash` | Advanced forensics, complex incident escalation, detection rule tuning. |
  57. | **Threat Hunter** | `multi-agent/manager/sub_agents/threat_hunter/` | `gemini-3.7-flash` | Proactive hypothesis-driven hunting, APT campaigns, TTP credential access & lateral movement hunts. |
  58. | **CTI Researcher** | `multi-agent/manager/sub_agents/cti_researcher/` | `gemini-3.7-flash` | Cyber threat intelligence research, GTI collections, actor profiling, malware communication analysis. |
  59. | **Incident Responder** | `multi-agent/manager/sub_agents/incident_responder/` | `gemini-3.7-flash` | Containment, eradication, recovery, endpoint isolation, and full IRP execution. |
  60. | **Detection Engineer** | `multi-agent/manager/sub_agents/detection_engineer/` | `gemini-3.7-flash` | Rule authoring, YARA-L 2.0 validation, Detection-as-Code workflows, false positive tuning. |
  61. | **LLM Judge** | `multi-agent/manager/sub_agents/llm_judge/` | `gemini-3.7-flash` | Procedural compliance assessment and rubric-based report evaluation. |
  62. | **DAC Agent** | `dac-agent/agent.py` | `gemini-3.7-flash` | Standalone Detection-as-Code agent with Google SecOps 1P Agentic Detection Engineering MCP Server integration. |
  63. ---
  64. ## Project Structure
  65. ```
  66. adk_runbooks/
  67. ├── multi-agent/ # Multi-agent system implementation
  68. │ ├── manager/ # Manager agent and sub-agents
  69. │ │ ├── sub_agents/ # Specialized security sub-agents
  70. │ │ └── tools/ # MCP tool configurations & skill loading tools
  71. │ └── reports/ # Generated markdown operational reports
  72. ├── dac-agent/ # Standalone Detection-as-Code agent
  73. ├── skills/ # Standardized security skills repository (SKILL.md)
  74. │ ├── atomic/ # Atomic IOC lookups and enrichment skills
  75. │ ├── common/ # Reusable SOAR and reporting procedures
  76. │ ├── detection/ # Detection engineering and rule tuning
  77. │ ├── hunting/ # Threat hunting playbooks
  78. │ ├── investigation/ # Case investigation and timeline analysis
  79. │ ├── irps/ # Incident Response Plans (IRPs)
  80. │ ├── reporting/ # Standardized report writing guidelines
  81. │ ├── triage/ # Alert and vulnerability triage procedures
  82. │ └── registry.py # Central SkillRegistry and parser engine
  83. ├── rules-bank/ # Agent personas and behavioral definitions
  84. │ └── personas/ # System prompts and role definitions
  85. ├── evals/ # Evaluation and benchmark framework
  86. │ ├── datasets/ # Workflow benchmark datasets (core, all 36, expanded)
  87. │ ├── rubrics/ # 4-rubric evaluation implementations
  88. │ ├── runner.py # CLI benchmark evaluation runner
  89. │ └── registry.py # Workflow definitions and graph executor
  90. └── tests/ # Unit and integration test suites
  91. ```
  92. ---
  93. ## Quick Start
  94. ### Screencast Walkthrough
  95. **Standard (`venv` + `pip` + `adk`) Workflow:**
  96. ![ADK Runbooks Quick Start & Multi-Agent System Screencast](docs/images/adk_runbooks_screencast.gif)
  97. <details>
  98. <summary><strong>Modernized <code>just</code> + <code>uv</code> Workflow Screencast (<code>just setup</code>, <code>just config-auto-discover</code>, <code>just run-manager</code>, <code>just adk-web</code>)</strong></summary>
  99. <br>
  100. ![ADK Runbooks just + uv Screencast](docs/images/adk_runbooks_just_screencast.gif)
  101. </details>
  102. ### Prerequisites
  103. - Python 3.10+
  104. - Google API key (for Gemini models)
  105. - Virtual environment tool (`venv`)
  106. ### Basic Setup
  107. ```bash
  108. # Clone the repository with submodules
  109. git clone --recurse-submodules https://github.com/dandye/adk_runbooks.git
  110. cd adk_runbooks
  111. # If already cloned without submodules:
  112. git submodule update --init --recursive
  113. # Create and activate virtual environment
  114. python3 -m venv venv
  115. source venv/bin/activate # On Windows: venv\Scripts\activate
  116. # Install dependencies
  117. pip install -r multi-agent/requirements.txt
  118. # Configure environment
  119. cp multi-agent/manager/.env.example multi-agent/manager/.env
  120. # Edit multi-agent/manager/.env and add your GOOGLE_API_KEY
  121. ```
  122. ### Running the Multi-Agent System
  123. ```bash
  124. # Run CLI interface
  125. cd multi-agent
  126. adk run manager
  127. # Run Web UI
  128. adk web
  129. ```
  130. ---
  131. ## Testing & Benchmarking
  132. ### Running Test Suites
  133. ```bash
  134. # Run all unit and integration tests
  135. ./venv/bin/pytest tests/ evals/tests/ -v
  136. ```
  137. ### Running Workflow Evaluations
  138. The evaluation harness tests multi-agent and graph workflows against 4 procedural compliance rubrics (Triage/IRP, Threat Hunting, Detection Engineering, Reporting):
  139. ```bash
  140. # Run core benchmark workflows (10 test cases)
  141. ./venv/bin/python -m evals.runner --dataset core_workflows
  142. # Run all 36 operational workflows
  143. ./venv/bin/python -m evals.runner --dataset all_36_workflows
  144. # Run expanded cases and alerts dataset (25 test cases)
  145. ./venv/bin/python -m evals.runner --dataset expanded_cases_alerts
  146. ```
  147. ---
  148. ## Contributing
  149. Contributions are welcome! Please see our contributing guidelines for more information.
  150. ## License
  151. This project is licensed under the MIT License - see the LICENSE file for details.
  152. ## Acknowledgments
  153. - Built on [Google's Agent Development Kit (ADK)](https://github.com/google/adk)
  154. - Leverages [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for security tool integration
  155. - Security procedures based on industry best practices and frameworks

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.