quarry

module

v0.1.3 Latest Latest Go to latest Published: Jul 31, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/0xjustus/quarry

Links

Open Source Insights

README ¶

quarry

Quarry finds and verifies vulnerabilities in native targets. An agent proposes candidate inputs, and a deterministic oracle confirms a bug by re-executing the target and requiring a real crash or hang. A sanitizer report only counts when the process actually aborts, so fabricated reports are rejected.

Install

Requires Go 1.26 or newer.

make build   # builds bin/quarry (pure Go, no cgo)
make test

Usage

Verify a candidate proof-of-vulnerability. Offline, no model or key needed:

bin/quarry verify --bin ./target --pov ./candidate.bin

Add --json for machine output (exit code 0 for a real bug, 3 for unconfirmed), or pipe it to quarry report --sarif to emit a SARIF bug candidate.

Run the discovery agent (needs model access):

export QUARRY_API_KEY=...
bin/quarry copilot --target quarry.yaml --model <name> --verbose

Query the commons, a content-addressed store of verified crash abstracts:

bin/quarry commons-verify ./quarry-commons
bin/quarry query --tree ./quarry-commons --keys bk:...

Documentation

QUICKSTART.md for a full walk-through
ARCHITECTURE.md for the design and current status
docs/ for the oracle, the agent loop, and OSS-CRS triage

License

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
quarry command Command quarry is the client CLI: it points a coding agent at a target and judges the result with the deterministic oracle, running one complete cycle of the Loop.	Command quarry is the client CLI: it points a coding agent at a target and judges the result with the deterministic oracle, running one complete cycle of the Loop.
quarry-vetd command Command quarry-vetd is the off-Cloudflare vetting worker.	Command quarry-vetd is the off-Cloudflare vetting worker.
internal
agent Package agent embodies the Loop as a compact ReAct cycle over the fixed M1 tool belt (edit / read_file / ls / exec / run_pov), talking to a model through the pluggable model seam and choosing that model through the Router seam.	Package agent embodies the Loop as a compact ReAct cycle over the fixed M1 tool belt (edit / read_file / ls / exec / run_pov), talking to a model through the pluggable model seam and choosing that model through the Router seam.
artifact Package artifact defines quarry's atomic unit as a minimal, content-addressed core with a thin envelope — the versioned contract between the Client (System A) and the Infrastructure (System B).	Package artifact defines quarry's atomic unit as a minimal, content-addressed core with a thin envelope — the versioned contract between the Client (System A) and the Infrastructure (System B).
chain Package chain models exploitation as content-addressed capability transitions and the chains built from them.	Package chain models exploitation as content-addressed capability transitions and the chains built from them.
channels Package channels defines the four code seams between the Client (System A) and the Infrastructure (System B), plus the emit gate that every outbound pattern must pass.	Package channels defines the four code seams between the Client (System A) and the Infrastructure (System B), plus the emit gate that every outbound pattern must pass.
config Package config resolves client configuration from flags/env with sane defaults, and manages the persistent client signing key used to attest emitted pattern artifacts.	Package config resolves client configuration from flags/env with sane defaults, and manages the persistent client signing key used to attest emitted pattern artifacts.
gitcommons Package gitcommons materializes the public abstract tier of the knowledge commons as a git-native tree (ADR-0001, quarry-commons): content-addressed artifact abstracts, a prefix-sharded behavioral-key index, and a Bloom-filter root digest for cheap "novel or prior-art?" existence checks before any fetch.	Package gitcommons materializes the public abstract tier of the knowledge commons as a git-native tree (ADR-0001, quarry-commons): content-addressed artifact abstracts, a prefix-sharded behavioral-key index, and a Bloom-filter root digest for cheap "novel or prior-art?" existence checks before any fetch.
hydrate Package hydrate seeds the Knowledge Commons from ARVO / OSS-Fuzz vulnerability entries — the first System-B deliverable.	Package hydrate seeds the Knowledge Commons from ARVO / OSS-Fuzz vulnerability entries — the first System-B deliverable.
loop Package loop is quarry's supervisor: one complete cycle of the expanded scientific method, end-to-end, on a real target.	Package loop is quarry's supervisor: one complete cycle of the expanded scientific method, end-to-end, on a real target.
mcp Package mcp is a minimal Model Context Protocol client (stdio transport, JSON-RPC 2.0).	Package mcp is a minimal Model Context Protocol client (stdio transport, JSON-RPC 2.0).
model Package model is the pluggable model seam.	Package model is the pluggable model seam.
oracle Package oracle is the deterministic verifier at the center of quarry.	Package oracle is the deterministic verifier at the center of quarry.
router Package router is the model-selection seam.	Package router is the model-selection seam.
runner Package runner executes the authoritative target and produces the oracle.RunResult.	Package runner executes the authoritative target and produces the oracle.RunResult.
store Package store is quarry's grounding substrate: one embedded SQLite database (knowledge base + hypothesis frontier + provenance + trajectory event log) plus a content-addressed blob directory.	Package store is quarry's grounding substrate: one embedded SQLite database (knowledge base + hypothesis frontier + provenance + trajectory event log) plus a content-addressed blob directory.
target Package target ingests a target descriptor and prepares it for the Loop: it resolves how the target is built and run, keeping the target's build environment separate from the agent's toolkit.	Package target ingests a target descriptor and prepares it for the Loop: it resolves how the target is built and run, keeping the target's build environment separate from the agent's toolkit.
toolcat Package toolcat is the tool catalog + MCP broker.	Package toolcat is the tool catalog + MCP broker.
verify Package verify is the oracle-as-referee: it wires the runner (which produces RunResults on the authoritative target) to the pure oracle evaluator, and records every judgment as an experiment in the Datastore.	Package verify is the oracle-as-referee: it wires the runner (which produces RunResults on the authoritative target) to the pure oracle evaluator, and records every judgment as an experiment in the Datastore.