Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
124 lines (97 loc) · 4.04 KB

CONTRIBUTING.md

File metadata and controls

124 lines (97 loc) · 4.04 KB
Raw

Contributing to ADRF

Thanks for considering a contribution. This repo covers two distinct categories of change:

  1. New or updated agent rules in examples/baseline.yaml or a new per-agent file in examples/.
  2. Spec changes to SPEC.md or schemas/v0.json.

These have different review bars; the sections below walk through each.

1. New or updated agent rules

A rule lands when an operator can plausibly recognise the agent from public information without privileged access. The bar is reproducibility: another reviewer should be able to spin the agent up and observe the same wire shape.

PR template

Copy and fill in:

## Agent

- Name and vendor:
- Public surface (download URL, docs link):
- Why this agent is worth identifying (size of footprint, ops
  reason, security relevance):

## Wire shape evidence

For each signal you propose to match on, cite the source. If the
source is a vendor doc, link to it. If you observed the wire
shape directly, name the version and the date.

- User-Agent pattern:
  - Observed value:
  - Version / date observed:
  - Source:
- Header tells (if any):
  - Header name:
  - Why this header is stable (vendor doc / SDK source):
  - Source:
- JA4 prefix (if any):
  - Observed JA4:
  - Capture method:

## Rule

Paste the proposed YAML rule. Include the inline comment that
documents the wire-shape rationale.

## Tradeoffs

- False-positive risk (what else could match this pattern):
- False-negative risk (how the agent might change to dodge):
- Why this is the right `score` and `provenance` tier:

Vetting checklist (reviewer)

  • The cited sources are public and resolve.
  • At least two signals OR a high-specificity UA prefix (e.g. ^claude-cli/, not (?i)claude).
  • The wire-shape comment in the YAML explains the rationale; a future reviewer can audit without leaving the file.
  • The score matches the confidence of the match. High-confidence (90+) is reserved for matches a reviewer could not plausibly fake without source-modifying the SDK.
  • The provenance tier is unsigned-named, not signed. signed is reserved for traffic with a verified signature delivered by a separate verifier; named ADRF rules do not produce it.
  • The rule does not narrow on the agent's version unless the version is part of the stability claim.
  • The PR includes a CHANGELOG.md entry under the unreleased heading.

2. Spec changes

Changes to SPEC.md or schemas/v0.json are governed by GOVERNANCE.md. The summary:

  • Additive changes (new optional fields, new provenance values added to the enum without removing existing values) ride within the current schema version. The CHANGELOG records the addition.
  • Backward-incompatible changes (removed fields, changed semantics, type changes on existing fields) require a new schema version. The new version ships as a separate JSON Schema file in schemas/; both schemas live in the repo until the older version is retired.
  • Removing a schema version requires at least one minor release of advance notice in the CHANGELOG.

A spec-change PR includes:

  • A SPEC.md diff with the rationale in the PR body.
  • A schemas/vN.json diff that mirrors the SPEC.md change word-for-word at the field level.
  • A CHANGELOG.md entry under the unreleased heading.
  • If the change affects the reference matcher in sbproxy, an issue or PR linked against that repo.

What does NOT belong here

  • Agent allow/deny lists. ADRF identifies the agent; policy (what to do with the identification) is downstream and consumer-specific.
  • Vendor-private telemetry. Rules must rely on public wire shape, not on contracts the vendor only documents to paying customers.
  • Trade-secret-protected fingerprints. If a signal is only observable under NDA, it cannot live in this repo.

Code of Conduct

By participating in this project, you agree to abide by the Contributor Covenant: https://www.contributor-covenant.org/. Report concerns to legal@soapbucket.com.