CLAUDE.md — aveproject/ave

Read this file completely before touching anything. Single source of truth for how work happens in this repo.

Project

aveproject/ave — the behavioral classification standard for agentic AI components. An independent standard that bawbel-scanner implements. NOT a feature of the scanner.

• Records: see dist/ave-records-latest.json (the count changes; do not hardcode it here)
• Schema: schema/ave-record.schema.json, the alias for the newest version; each record is validated against the versioned file it declares, schema/ave-record-X.Y.Z.schema.json
• Scoring: OWASP AIVSS v0.8
• Registry: aveproject.org
• Public API: api.aveproject.org
• Scanner: github.com/bawbel/scanner (reference implementation)

This repo contains DEFINITIONS, not detections. An AVE record defines a behavioral class. A scanner Finding is one detection that references an AVE record by ave_id.

The critical distinction — read this twice

AVE Record (this repo)              Finding (scanner repo)
──────────────────────              ──────────────────────
static behavioral class definition  runtime detection instance
authored once by a human            produced by every scan
one per behavioral class            one per detection
NO confidence field                 HAS confidence field
NO evidence_stage field             HAS evidence_stage field
declares confidence_baseline        assigns actual confidence
declares evidence_kind_default      assigns actual evidence_kind
declares detection_stage            reaches an actual evidence_stage

confidence is PER-DETECTION. It never lives in an AVE record. The record declares the BASELINE; the scanner assigns the ACTUAL value.

Record schema

Every record validates against the versioned schema file named by its own schema_version (schema/ave-record-X.Y.Z.schema.json); scripts/validate_records.py looks it up.

15 required fields (for every status except draft): ave_id · schema_version · status · published title · description · attack_class · severity · behavioral_fingerprint aivss · owasp_mcp indicators_of_compromise · remediation references · researcher

Draft submit-required core (status: "draft" only needs these 8): ave_id · schema_version · status · title · description · attack_class · behavioral_fingerprint · references

Statuses: active, deprecated, merged (needs merged_into, an active record), rejected (needs rejection_reason, linking the public decision) and draft. Consumers treat any status other than active as not active.

Optional framework fields (add when applicable, omit rather than force): owasp_asi · mitre_atlas · nist_ai_rmf

Optional runtime/mitigation classification fields (vendor-neutral only — no enforcement-tool config ever belongs here): provenance_vector · trifecta_profile · mitigation · example_patterns

Optional scanner evidence declarations (declare defaults the scanner uses): evidence_kind_default · detection_stage · detection_layer confidence_baseline · evidence_basis_engines · derivable_into

Optional evidence and rationale fields: evidence_vantage · evidence_method · verification_basis (derived by scripts/write_verification_basis.py, never authored) · security_boundary · missing_control · vulnerability_rationale

Optional provenance and history fields: framework_sources · revisions (append-only, see hard rule 11) · merged_into · rejection_reason

Optional ecosystem fields: component_type · affected_platforms · affected_registries behavioral_vector · mutation_count · detection_methodology kill_switch_active · aivss_score · cvss_base_vector researcher_url · last_updated

Full reference: aveproject.org/schema.html

Adding a record

Use the add-ave-record skill. Every record requires:

1. A JSON record in records/ validating against the schema
2. A positive fixture in tests/fixtures/ that a conforming implementation must flag
3. A negative fixture in tests/fixtures/ that a conforming implementation must not flag

Detection rule implementations (pattern, YARA, semgrep, or anything else) are implementation artifacts, not standard artifacts. They live in whichever tool implements against this standard — open a coordinated PR in that tool's own repo (see CONTRIBUTING.md Step 4).

Open an issue first to confirm the id. A new ave_id is only for a genuinely distinct behavioral class — variants go as sub-case notes in the parent record, not as new ids.

Function comments — What/Why/How

Every function in validation scripts gets a What/Why/How comment.

# What: validates one AVE record against the JSON schema
# Why:  a malformed record breaks every downstream scanner that loads it
# How:  jsonschema.validate against the schema file the record's schema_version names
def validate_record(record: dict) -> tuple[bool, list[str]]:
    ...

TDD loop

1. Write the failing test (record validation, fixture)
2. Run -> MUST FAIL
3. Add the record / fixture
4. Run -> MUST PASS
5. Run full suite -> green before commit

Local commands

npm install ajv ajv-formats           # schema validation deps
node scripts/build-records.js         # build dist/ave-records-latest.json
python3 scripts/build_taxonomy.py     # build dist/ave-taxonomy-latest.json from it (--check: fail if stale)

# Python validation
pip install -e ".[dev]"
pytest tests/ -x -q                   # validate records + fixtures; includes the frozen-file check
python scripts/validate_records.py    # schema-check every record
python scripts/check_fixtures.py      # every record has +/- fixtures
python scripts/write_verification_basis.py   # derive verification_basis from the evidence axes
python scripts/check_terms_sync.py    # docs/terms.md matches the schema (generate_terms.py rewrites it)
python scripts/check_confidence_signal.py --ratchet-since origin/develop   # high confidence states evidence_vantage
python scripts/check_revisions_ratchet.py --ratchet-since origin/develop   # revisions append-only, gated changes have entries

Hard rules

1. Every record validates against the schema file its schema_version names.
2. confidence NEVER appears in an AVE record — it is per-detection.
3. Behavioral fingerprints over signatures — describe what it DOES.
4. Every record has a positive + negative conformance fixture. Detection rule implementations live in the implementing tool's own repo, not here.
5. ave_id is immutable once published. Never renumber. Deprecate, never delete.
6. severity and aivss.aivss_score must agree (CRITICAL implies >= 9.0).
7. All names from LANGUAGE.md.
8. owasp_mcp is required. owasp_asi, mitre_atlas, nist_ai_rmf are optional — add when they apply, omit rather than force a poor fit.
9. references must have at least one citable primary source.
10. Never commit records/INDEX.md — it is removed. The README is the index.
11. A change to a record's severity, status or derived verification_basis carries a revisions entry in the same PR; entries are append-only (CONTRIBUTING.md, "Recording a change"; checked by scripts/check_revisions_ratchet.py).

Scaling and governance rules

• Before proposing a new record, check docs/specs/scaling-and-governance.md Section 1. A record needs a genuinely distinct behavioral mechanism, not a category wrapper around existing coverage. If it looks like "framework X's category, applied to agentic AI," it's not a record, flag this rather than draft it.
• Never delete or reuse a published ave_id, ever, no exceptions. If a record turns out wrong or redundant, that's a status change (deprecated/merged/rejected), not a deletion. See Section 3.
• Frozen versioned schema and dist files (ave-record-X.Y.Z.schema.json, ave-records-vX.Y.Z.json) are never edited retroactively, including typo fixes. A correction ships in the next version. schema/frozen-artifacts.json lists them by SHA-256 and tests/test_frozen_artifacts.py fails when one changes; a new version adds its files there and never edits an entry.

Agent skills

Product context

Read CONTEXT.md. AVE is a standalone standard implemented by more than one tool; no implementer, Bawbel's own tools included, owns it.

The records grow with research, not with quotas. Growth is bounded by distinct behavioral classes, not by any external target or event. A new ave_id requires a distinct behavioral class and a citable primary source. No padding.