AuditZoo is a CPG-centered, agent-based program analysis framework built on Joern and AutoGen-Core. It provides a unified infrastructure for building and composing program analyses using lightweight agents that communicate through a flexible protocol.
- Python 3.10+
- Conda (Miniconda or Anaconda)
# Clone the repository
git clone https://github.com/Biscope-AI/auditzoo.git
cd auditzoo
# Run the installation script (installs AuditZoo + Joern in a conda environment)
bash install.sh
# Activate the environment
conda activate auditzooThe installation script will:
- Create a conda environment with Python 3.10 and Java 17
- Install AuditZoo and its dependencies
- Download and install Joern
- Configure environment variables
import asyncio
from auditzoo import AnalysisRuntime, UKRegistry, auto_detect_backend, Request, CodeUnit
from auditzoo.core.protocol.utils import to_schema
async def main():
# Auto-detect backend configuration
config = auto_detect_backend("./my_project")
# Initialize runtime (connects to backend, loads IR)
async with AnalysisRuntime(config) as runtime:
# Send IR queries
response = await runtime.send_message(
Request(
type="ir.get_all_units_by_kind",
payload={"kind": UKRegistry.Function()},
response_schema=to_schema(list[CodeUnit]),
),
runtime.ir_agent_id
)
functions = response.unwrap()
print(f"Found {len(functions)} functions")
asyncio.run(main())from autogen_core import MessageContext, AgentId
from auditzoo import BaseAnalysisAgent, Request, Response
class MyAnalysisAgent(BaseAnalysisAgent):
def __init__(self):
super().__init__("My custom analysis agent")
async def _handle_request(self, message: Request, ctx: MessageContext) -> Response:
if message.type != "task.my_analysis":
return Response.fail("Unknown task type")
functions = await self.get_functions(ctx)
results = [f.name for f in functions]
return Response.ok(data={"results": results})
# Register and use
async with AnalysisRuntime(config) as runtime:
await runtime.register_agent(MyAnalysisAgent, "my_analyzer", lambda: MyAnalysisAgent())
runtime.start()
response = await runtime.send_message(
Request(type="task.my_analysis", payload={}),
AgentId("my_analyzer", "default")
)See examples/find_callers.py for complete examples.
- Runtime: Manages backend, IR, and agent lifecycle
- Agents: Lightweight workers for analysis tasks
- Protocol: Request/Response messaging
Request: type (e.g., "ir.", "task."), payload (dict)Response: success, data (any type), errorRequest/Responseare sealed; do not subclass
- IR Model: Code representation via Code Property Graphs
CodeUnit: Code at any granularity (file, function, statement, etc.)CodeUnitRelation: Relationships (calls, contains, etc.)Facts: Analysis results attached to units/relations
Note: If you want to contribute to or extend AuditZoo, please refer to DEVELOPMENT.md for detailed architecture documentation and development guidelines.
AuditZoo is at a very early stage of development. We welcome contributions and feedback!
Feel free to open pull requests, but please note:
- IMPORTANT: Any PR should NOT mix changes in
core/and changes in other places. Keep core infrastructure changes separate from analysis implementations.
AuditZoo is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
This means:
- ✅ You can freely use, modify, and distribute this software
- ✅ Perfect for academic research and open-source projects
⚠️ If you run a modified version as a network service (e.g., SaaS, web application), you must make your source code available to users⚠️ Any modifications or derivative works must also be licensed under AGPL-3.0
For commercial licensing options or if AGPL doesn't fit your use case, please contact us.
If you use AuditZoo in your research, please cite:
@software{auditzoo,
author = {Zhang, Zhuo},
title = {AuditZoo: CPG-centered Agent-based Program Analysis Framework},
year = {2025},
url = {https://github.com/Biscope-AI/auditzoo}
}