git:20260823.cd1010e to git:20261031.ec06412

# add-ave-record

The main workflow for this repo. Adds one new AVE record end to end.

## Steps

### 1. Grill the vulnerability class first

Run grill-with-docs. Answer:

- What does a vulnerable component DO? (behavioral_fingerprint)

- What attack_class is this? (new or existing?)

- What is the worst-case impact? (drives AIVSS)

- Which engines can detect it? (evidence_basis_engines)

- Can a static scan see it, or does it need runtime? (detection_stage)

- Does it chain with other AVEs? (derivable_into)

### 2. Assign the next ave_id

Format AVE-YYYY-NNNNN. Never reuse a number. Check records/ for the highest.

### 3. Write the record JSON

records/AVE-YYYY-NNNNN.json. Must validate against the schema.

Include the evidence fields:

- evidence_kind_default

- detection_stage

- detection_layer

- confidence_baseline

- evidence_basis_engines

- derivable_into

**The `researcher` field, a common, real mistake, not a hypothetical

one**: defaulting to the AVE maintainer's own name because it's the

name most readily at hand while drafting. Check first: does this

record trace to a real external CVE, paper, vendor disclosure, or

existing tool implementation? If yes, and it almost always is yes,

that source's own name or organization belongs in `researcher`, not

the person writing the AVE record. This exact mistake shipped on two

published records before being caught by an external maintainer being

credited incorrectly himself. See docs/specs/researcher-process.md's

Accountability and sourcing section for the full rule.

**The four governance/framework fields — `owasp_mcp`, `owasp_asi`,

`mitre_atlas`, `nist_ai_rmf` — always include the key, never let one go

missing.** These are the fields a CISO reads first; a security team

maps an AVE record onto their own reporting frameworks through these.

An absent key silently reads as "nobody checked this framework." An

empty array reads as "checked, no real fit was found." Only the second

one is an honest, defensible state.

- `owasp_mcp`: **required** once `status` is `active`/`deprecated`

(schema-enforced, `minItems: 1`) — needs at least one real mapping,

verified against the OWASP MCP Top 10's own primary-source category

text, not inferred from how a similar-sounding record in the corpus

happened to tag itself.

- `owasp_asi`, `mitre_atlas`, `nist_ai_rmf`: not yet schema-required

(that's a tracked v1.2.0 change, see the roadmap issue), but always

write the key. Verify each against its own primary source (live

`ATLAS.yaml` for MITRE ATLAS, the actual NIST AI 100-1 text for NIST

AI RMF, the framework's own published category list for OWASP ASI)

before adding a value. Genuinely checked and found nothing that

fits? Set it to `[]` and say so in `aivss.notes` — don't just leave

the key out because the array would otherwise be empty. This exact

mistake (a silently-missing `owasp_asi` key, not an empty one)

shipped on AVE-2026-00078/00079/00080 and was caught reviewing that

same PR — see docs/specs/researcher-process.md's Common Mistakes

section.

**"Its own primary source" means fetch and read the actual document

— a repo's raw files, the framework's own published PDF — never a

search result, a summarized page, or a third-party blog's retelling

of it, and never corpus precedent no matter how many existing

records agree with each other.** `ASI01`-`ASI10`, the numbering this

corpus and the schema's own `owasp_asi` regex both use, is correct —

it's OWASP's own "Top 10 for Agentic Applications 2026" document's

category IDs. A separate OWASP document, "Agentic AI – Threats and

Mitigations," uses a different, `T1`-`T17` numbering; issue #179

fetched only that second document, found no `ASI0` matches in it,

and initially (wrongly) concluded the corpus's numbering was

fabricated — corrected in that issue's own thread once the first

document was found. Same underlying discipline either way: fetch and

read the actual primary source before trusting corpus precedent, and

when a framework's publisher maintains more than one document, check

that the one fetched is actually the one whose ID format is being

verified.

**Before assigning `owasp_asi`, also check the real category

definition, not just the label that sounds closest.** A full-corpus

audit (#196) found 48 of 70 tagged records wrong, mostly `ASI08`

applied to single-instance failures with no real cross-agent

propagation, and `ASI07` applied to single-agent tool misuse with no

actual inter-agent messaging involved. See

docs/specs/researcher-process.md's own note on this for the full

pattern.

### 4. Write conformance fixtures (TDD — fixtures first)

tests/fixtures/AVE-YYYY-NNNNN_positive.md — a conforming implementation MUST flag this

tests/fixtures/AVE-YYYY-NNNNN_negative.md — a conforming implementation MUST NOT flag this

The negative fixture is the false-positive guard. Make it realistic —

a benign file that looks similar to the malicious one.

### 5. Open a coordinated detection-rule PR

Detection rule implementations (pattern, YARA, semgrep, or anything else)

are implementation artifacts, not standard artifacts — they live in

whichever tool implements against this standard, not in this repo. Open a

PR in that tool's own repo (e.g. bawbel/scanner) referencing the ave_id and

the fixtures above; see CONTRIBUTING.md Step 4.

### 6. Validate

```bash

python scripts/validate_records.py

pytest tests/ -x -q

```

If validate_records.py fails on AIVSS arithmetic, fix the record's own

aarf/cvss_base/thm/mitigation_factor values or the stated aivss_score,

don't just adjust one to match the other without checking which one is

actually wrong; a computed mismatch usually means the record was drafted

against a different set of factors than what got written down.

### 7. Publish

A record passing validation is not yet a published one. Update:

- **dist/ave-records-latest.json**: add or replace this record's entry,

keeping the array sorted by ave_id.

- **CHANGELOG.md**: one line under Unreleased/Added: the ave_id, title,

severity, and aivss_score.

- **README.md, three separate things, don't assume any of them share a

format**:

1. **Prose record count.** Find it first:

```bash

grep -n "[0-9]\+ records\|[0-9]\+ behavioral class" README.md

```

Update to the real count from `ls records/AVE-*.json | wc -l`, not by

incrementing the old number, more than one record can land in a

single batch.

2. **A record-count badge**, if one exists. Badges are usually

shields.io-style, with the count embedded as a URL path segment, not

free prose, so the prose grep above won't reliably catch it. Find it

separately:

```bash

grep -n "shields.io\|badge.*record\|records.*badge" README.md

```

If found, the count sits inside the badge URL itself (something like

`.../badge/records-59-blue`), update that specific segment to the

real count, don't touch the rest of the badge's color, label text, or

link target.

3. **A list or table enumerating individual records**, if one exists.

This is not a number to update, it needs a new row appended for

whatever record just landed, matching the exact column structure and

formatting of the existing rows exactly, so it doesn't stand out as

the one inconsistently-formatted entry. Find it first:

```bash

grep -n "AVE-2026-" README.md

```

If this is a comprehensive, actively-maintained list, append the new

record's row after whatever the file's own existing ordering

convention is (chronological, by ID, by severity, confirm which

before assuming). If it's a curated set of examples rather than a

complete enumeration (a handful of illustrative records, not all of

them), don't add to it automatically, that's an editorial decision

about which records are worth featuring, not a mechanical update; ask

before changing this one.

For all three: if the grep for any of them finds nothing, that specific

piece doesn't exist in README.md, skip it, don't invent one. If any grep

finds something whose format doesn't match what's described above, stop

and ask rather than force an edit that might not fit.

Do not bump schema_version or create a new versioned dist snapshot

(dist/ave-records-vX.Y.Z.json) as part of this step. That's a separate,

deliberate decision tied to an actual schema change, not something that

happens automatically because one record got added.

## Severity / AIVSS consistency

CRITICAL → aivss_score >= 9.0

HIGH → 7.0 to 8.9

MEDIUM → 4.0 to 6.9

LOW → < 4.0

If severity and aivss_score disagree, the record fails validation.

A mechanism that reads as severe in plain English can still land MEDIUM,

correctly, if it's narrow and single-vector, AARF's ten factors reward

breadth of amplification, not just raw impact. cvss_base alone carries

the severity of the underlying impact. Don't inflate AARF factors to

force a record into a more severe-sounding band; if the honestly computed

score feels low relative to the mechanism's intuitive severity, say so in

the record's own aivss.notes field rather than adjusting the inputs to

hit a target. See references/aivss-scoring.md for the full formula and

worked examples of this exact situation.

## confidence_baseline guide

High-signal AVE (hardcoded AWS key, explicit external fetch): 0.85-0.95

Medium-signal (suspicious instruction phrasing): 0.55-0.75

Low-signal (vague, needs corroboration): 0.40-0.55

The scanner adjusts from this baseline via the FP pipeline.

## Reference files

- references/aivss-scoring.md: the AARF formula, how aars is computed

from the ten factors, and worked examples spanning MEDIUM through HIGH,

including the specific trap of inflating factors to chase a severity

band.

- references/schema-fields.md: the provenance_vector.entry_class enum

(confirmed live against the corpus) and escalation values, distinct

from grill-with-docs Q7's detection_layer, a coarser, separate field;

don't conflate the two when writing provenance_vector.