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 operations tasks—including incident response, threat hunting, detection engineering, alert triage, and investigation—powered by a Progressive Disclosure Skills Architecture.

Documentation

The full documentation for this project, including detailed runbooks and agent information, is available at:
https://dandye.github.io/adk_runbooks

Overview

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.

Key Features

• Multi-Agent Architecture: A root Manager agent coordinates specialized sub-agents with domain expertise and shared toolsets.
• Dual-Tier Progressive Disclosure Framework:
  • 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().
  • 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.
• 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).
• Enterprise Security MCP Tooling: Unified integration across Chronicle SIEM, Chronicle SOAR, VirusTotal / Google Threat Intelligence (GTI), and SecOps Detection Engineering.
• 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.

Dual Progressive Disclosure Architecture

Operational procedures and external MCP tools are loaded strictly on-demand to prevent prompt bloat and context degradation:

┌────────────────────────────────────────────────────────────────────────────┐
│ DUAL PROGRESSIVE DISCLOSURE ARCHITECTURE                                   │
│                                                                            │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ TIER 1: Procedural Skills Progressive Disclosure (`SkillRegistry`)     │ │
│ │  - Lean catalog of available skills injected into agent prompt.        │ │
│ │  - Full procedural runbook loaded on demand via `load_skill()`.        │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ TIER 2: Progressive MCP Tool Discovery (`MCPToolRegistry`)             │ │
│ │  - Replaces 30+ static tool schemas with 3 lightweight meta-tools:     │ │
│ │      1. search_mcp_tools(query, server) -> Search available tools      │ │
│ │      2. get_mcp_tool_schema(tool_name)  -> Retrieve JSON schema        │ │
│ │      3. execute_mcp_tool(tool_name, args) -> Dynamic tool execution    │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────┘

Skill Taxonomy Categories

Security Agents & Model Distribution

Project Structure

adk_runbooks/
├── multi-agent/              # Multi-agent system implementation
│   ├── manager/              # Manager agent and sub-agents
│   │   ├── sub_agents/       # Specialized security sub-agents
│   │   └── tools/            # MCP tool configurations & skill loading tools
│   └── reports/              # Generated markdown operational reports
├── dac-agent/                # Standalone Detection-as-Code agent
├── skills/                   # Standardized security skills repository (SKILL.md)
│   ├── atomic/               # Atomic IOC lookups and enrichment skills
│   ├── common/               # Reusable SOAR and reporting procedures
│   ├── detection/            # Detection engineering and rule tuning
│   ├── hunting/              # Threat hunting playbooks
│   ├── investigation/        # Case investigation and timeline analysis
│   ├── irps/                 # Incident Response Plans (IRPs)
│   ├── reporting/            # Standardized report writing guidelines
│   ├── triage/               # Alert and vulnerability triage procedures
│   └── registry.py           # Central SkillRegistry and parser engine
├── rules-bank/               # Agent personas and behavioral definitions
│   └── personas/             # System prompts and role definitions
├── evals/                    # Evaluation and benchmark framework
│   ├── datasets/             # Workflow benchmark datasets (core, all 36, expanded)
│   ├── rubrics/              # 4-rubric evaluation implementations
│   ├── runner.py             # CLI benchmark evaluation runner
│   └── registry.py           # Workflow definitions and graph executor
└── tests/                    # Unit and integration test suites

Quick Start

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

Testing & Benchmarking

Running Test Suites

# Run all unit and integration tests
./venv/bin/pytest tests/ evals/tests/ -v

Running Workflow Evaluations

The evaluation harness tests multi-agent and graph workflows against 4 procedural compliance rubrics (Triage/IRP, Threat Hunting, Detection Engineering, Reporting):

# Run core benchmark workflows (10 test cases)
./venv/bin/python -m evals.runner --dataset core_workflows

# Run all 36 operational workflows
./venv/bin/python -m evals.runner --dataset all_36_workflows

# Run expanded cases and alerts dataset (25 test cases)
./venv/bin/python -m evals.runner --dataset expanded_cases_alerts

Contributing

Contributions are welcome! Please see our contributing guidelines for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built on Google's Agent Development Kit (ADK)
• Leverages Model Context Protocol (MCP) for security tool integration
• Security procedures based on industry best practices and frameworks