ADRF: Agent Detection Rule Format

ADRF is an open YAML format for identifying AI agents and coding assistants from the wire shape of their HTTP requests. The format is designed for proxies, gateways, and detection engines that need to attach a stable agent_id to a request based on fingerprints (TLS, headers, payload) that the agent emits in practice.

This repository hosts the spec, the JSON Schema for the rule-pack file, the canonical worked examples, and the governance for adding new rules.

Status

• v0.1.0 — the format below corresponds to ADRF schema version 0. The reference parser lives in the sbproxy project, crate sbproxy-agent-detect.

Why a spec

Every gateway that wants to classify agentic traffic ends up inventing the same matchers: User-Agent regex, header presence, JA4 prefix. Without a shared format, every operator hand-rolls a fork, every consumer reinvents the loader, and the rules go stale in isolation. ADRF is the boring common shape so the rules themselves can be the contribution.

The format is intentionally small. v0 covers the matchers in production use today (UA + headers + JA4 prefix). Later versions extend the schema additively (see ROADMAP.md) so a v0 pack remains parseable as the spec evolves.

Quick start

A rule pack is a YAML file with a version line and a list of agents:

version: 0
agents:
  - id: claude-code-cli
    match:
      user_agent_pattern: '^claude-cli/'
      header_present:
        - x-stainless-arch
    provenance: unsigned-named
    score: 95
    confidence: 0.95

Validate it with any JSON Schema validator against schemas/v0.json:

# Using ajv (npm install -g ajv-cli)
ajv validate -s schemas/v0.json -d examples/baseline.yaml --strict=false

# Using check-jsonschema (pipx install check-jsonschema)
check-jsonschema --schemafile schemas/v0.json examples/baseline.yaml

For the runtime that consumes these packs (the reference matcher), see the sbproxy-agent-detect crate.

What this repo contains

• SPEC.md — the format specification.
• schemas/v0.json — JSON Schema for v0.
• examples/ — worked rule packs. baseline.yaml is the canonical reference pack; per-agent files are copy-paste starting points for new packs.
• GOVERNANCE.md — how the spec evolves, versioning, deprecation policy.
• CONTRIBUTING.md — how to propose a new agent rule or a spec change.
• ROADMAP.md — planned extensions (header-order hash, JA4T / JA4X TLS predicates, behavioural cadence, payload signals, Signature-Agent verification).
• CHANGELOG.md — release notes per version.

License

BSD-3-Clause. The reference matcher in sbproxy is under its own license (BSL 1.1); the spec and JSON Schema here are permissively licensed so any project can consume them without fee.

Related work

• FoxIO JA4+ — TLS / TCP / HTTP fingerprinting building blocks the JA4-prefix predicate consumes.
• Falco and the Sysdig Prempti rule set — alternative shape for runtime detection; ADRF is the request- scoped HTTP-layer complement.
• Web Bot Auth (draft-meunier-web-bot-auth) — Signature-Agent provides the signed provenance tier ADRF references; rules can downgrade or skip when a verified signature is already present.