# Project Quarry

> Python framework and DSL for detecting threats and behavior patterns in AI agent conversations using compiled rules.

Project Quarry is a Python framework from the cisco-ai-defense organization for detecting threats and behavior patterns in agent conversations. Rules are written in a DSL over messages, tool calls, tool results, and event order, and can optionally call a configured model adapter. The project is in alpha, and its DSL syntax may change before v1.0.0.

## What It Is

Quarry is a detection DSL and engine for AI agents. Rules live in `.rule` files, each containing one named rule with optional metadata, strings, variables, and parameters blocks plus a required condition. When rules are loaded, Quarry parses, validates, links, and compiles each one to a symbolic finite-state automaton, and rules that cannot compile fail at load time. A scan runs the compiled program over an OpenAI-shaped conversation supplied as JSON with a messages array.

## How Detection Works

Rules can use text, RE2 regular expressions, structured-field, and tool use checks. Multi-turn flow rules support captures, counts, and typed policy parameters. When local checks are not enough, a rule can use a configured model for scoring, classification, completion, token counting, and spans. Results include witness evidence, explain output, and typed collections for supported rules. Explicit input, compile, time, and model-call limits can be set.

## Using It

Quarry supports Python 3.11 through 3.13 and is installed from source with uv. It exposes sync and async Python APIs, including QuarryGuard, DSLScanner, and compile_policy, and a CLI with human, JSON, and CSV output. The CLI exits 0 for a clean scan, 1 for a match, and 2 for an invalid or incomplete scan. The repository also documents an agent plugin for Codex, Claude Code, and MCP hosts, and ships synthetic examples that run without model credentials.

## Features
- Detection DSL compiled to symbolic finite-state automata
- Text, RE2 regex, structured-field, and tool use checks
- Multi-turn flow rules, captures, counts, and typed policy parameters
- Optional model scoring, classification, completion, token counting, and spans
- Witness evidence and explain output
- Sync and async Python APIs
- Human, JSON, and CSV CLI output
- Explicit input, compile, time, and model-call limits
- Agent plugin for Codex, Claude Code, and MCP hosts

## Integrations
Codex, Claude Code, MCP

## Platforms
WINDOWS, MACOS, LINUX, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
0.1.0

## Links
- Website: https://github.com/cisco-ai-defense/project-quarry
- Documentation: https://github.com/cisco-ai-defense/project-quarry/blob/main/docs/getting-started.md
- Repository: https://github.com/cisco-ai-defense/project-quarry
- EveryDev.ai: https://www.everydev.ai/tools/project-quarry