Skip to content
coms4995-ai4secPublic

About

No description, website, or topics provided.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

AuditZoo

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.

Installation

Prerequisites

  • Python 3.10+
  • Conda (Miniconda or Anaconda)

Quick Install

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

The 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

Usage

Basic Example

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())

Creating Custom Analysis Agents

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.

Key Concepts

  • 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), error
    • Request/Response are 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

Development

Note: If you want to contribute to or extend AuditZoo, please refer to DEVELOPMENT.md for detailed architecture documentation and development guidelines.

Project Status

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.

License

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.

Citation

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

About

No description, website, or topics provided.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages