From 6adc26ee8d3b36ba2df122b3d72bc17703544db6 Mon Sep 17 00:00:00 2001 From: chaksaray Date: Sun, 19 Jul 2026 21:59:47 +0700 Subject: [PATCH 1/2] feat: add implementer-guide.html Transcribes docs/specs/ave-implementer-guide.md from aveproject/ave (post em-dash and stale-endpoint fixes in PR #65) using the site's existing page template (topbar/pagehead/footer from schema.html). Not yet linked from nav or footer on any page; that's a separate change. --- implementer-guide.html | 294 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 implementer-guide.html diff --git a/implementer-guide.html b/implementer-guide.html new file mode 100644 index 0000000..e9deb29 --- /dev/null +++ b/implementer-guide.html @@ -0,0 +1,294 @@ + + + + +Implementer Guide — AVE Behavioral Classification Standard + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + + AVE + Agentic Vulnerability Enumeration + + + + + +
+
+
+
+ Implementer Guide +

Adding AVE IDs to your scanner

+

AVE assigns stable behavioral classification IDs to agentic AI component +flaws. Adding an ave_id field to your scanner's finding output +lets security teams deduplicate findings across tools, link to full +behavioral fingerprints and IOCs, and report against a shared vocabulary. +This guide covers three consumption patterns depending on your environment.

+
+
+
+ +

Which pattern to use

+
+ + + + +
Your environmentRecommended pattern
Cloud CI/CD, always-on internetPattern 1: Runtime API
Mixed or uncertainPattern 2: Bundled offline
Air-gapped or regulated (banking, defense, healthcare)Pattern 2: Bundled offline or Pattern 3: ID-only
Enterprise SIEM resolves references downstreamPattern 3: ID-only
+ +

Pattern 1: Runtime API lookup

+

Scanner emits ave_id in its finding output and optionally + calls the AVE reference API at scan time to enrich with the full record.

+

API endpoint: GET https://api.aveproject.org/records/{ave_id}

+

Returns: full record JSON including behavioral_fingerprint, + indicators_of_compromise, remediation, + owasp_mcp, mitre_atlas, aivss.

+ +
import httpx + +def enrich_finding(ave_id: str) -> dict: + resp = httpx.get(f"https://api.aveproject.org/records/{ave_id}", timeout=5) + resp.raise_for_status() + return resp.json() + +finding = { + "rule_id": "your-rule-id", + "ave_id": "AVE-2026-00002", + "severity": "HIGH", + # optional: enrich at scan time + "ave_record": enrich_finding("AVE-2026-00002"), +}
+ +

When to use: developer machines, cloud CI/CD + pipelines, SaaS tools with outbound internet.
+ When not to use: air-gapped environments, regulated + environments where outbound calls to third-party APIs are blocked.

+ +

Pattern 2: Bundled offline record set

+

Download the full AVE record set at build/install time. Bundle it + with your scanner. At scan time, look up records locally.

+

Offline artifact, always current, no release tag required:
+ https://raw.githubusercontent.com/aveproject/ave/main/dist/ave-records-latest.json

+

Regenerated automatically on every records/ change on + develop; see scripts/build-records.js. A + companion manifest at dist/ave-records-latest.manifest.json + carries schema_version, record_count, and + generated_at for a cheap sanity check before parsing the + full array. A versioned, frozen snapshot is also committed at each + schema transition (dist/ave-records-v1.1.0.json, later + dist/ave-records-v1.2.0.json, and so on) for anyone who + deliberately wants to pin to one point in time rather than track + current; a GitHub + Release attaches the matching frozen file as a second distribution + point when one is cut, not the only one.

+

Format: JSON array of all active records (59 as of schema v1.1.0).

+ +
import json +from pathlib import Path + +# Load at startup +AVE_RECORDS = { + r["ave_id"]: r + for r in json.loads(Path("ave-records-latest.json").read_text()) +} + +def lookup_ave(ave_id: str) -> dict | None: + return AVE_RECORDS.get(ave_id)
+ +

Sync strategy: track ave-records-latest.json + if you always want current data, or pin to a specific + ave-records-v<version>.json snapshot if you want + stability, that file is frozen once written and never changes underneath + you. Either way, do not auto-update at runtime; re-fetch on your own + release cadence.

+

When to use: air-gapped environments, regulated + environments, tools that cannot make outbound calls, offline-first + scanners.

+ +

Pattern 3: ID-only emission

+

Scanner emits ave_id in its finding output. No enrichment + at scan time. The consuming system (SIEM, dashboard, ticket system, SARIF + viewer) resolves the ID when connectivity is available.

+

This is the most air-gap-friendly pattern because the scanner itself + makes zero network calls related to AVE.

+

Example SARIF output (the correct way to carry + ave_id in SARIF):

+ +
{ + "runs": [{ + "results": [{ + "ruleId": "your-rule-id", + "properties": { + "ave_id": "AVE-2026-00002", + "ave_url": "https://aveproject.org/registry.html#AVE-2026-00002", + "ave_api": "https://api.aveproject.org/records/AVE-2026-00002" + } + }] + }] +}
+ +

Full SARIF convention: docs/specs/ave-in-sarif.md

+

When to use: any environment. Especially useful when + the scanner runs in a restricted environment but findings are reviewed + in a connected dashboard.

+ +

The mapping step

+

To emit AVE IDs, you need a mapping from your internal rule IDs to AVE + IDs. Two options:

+

Option A: build your own mapping table. Use the + crosswalk files in this repo as reference:

+
    +
  • crosswalks/skillspector-to-ave.json: maps NVIDIA + SkillSpector categories to AVE IDs.
    • +
  • crosswalks/clawscan-to-ave.json: maps ClawScan rule + IDs to AVE IDs.
    • +
+

These show the mapping format and rationale. Build an equivalent for + your own rule IDs.

+

Option B: request a crosswalk. Open an issue in this + repo with your scanner's detection categories. The maintainer will help + map them to AVE IDs and publish the crosswalk.

+ +

Minimum viable integration

+

The smallest possible integration is adding one field:

+ +
finding = { + "rule_id": "prompt-injection/tool-description", + "severity": "HIGH", + "ave_id": "AVE-2026-00002", # add this +}
+ +

That is it. The ID is stable and permanent. No other changes required. + Your users get cross-tool deduplication and links to the full behavioral + record.

+ +

Contact

+

Open an issue at github.com/aveproject/ave + or email aveproject.org@gmail.com.

+

Maintaining a scanner? Submit a crosswalk PR, we will help with the + mapping.

+ +
+ + + + From c9789c5e62be6af9aa25498d9b8d44e569f7a7bd Mon Sep 17 00:00:00 2001 From: chaksaray Date: Sun, 19 Jul 2026 22:39:10 +0700 Subject: [PATCH 2/2] feat: wire implementer guide into nav/footer, add copy buttons and homepage card - Adds a "Guide" top-nav link and "Implementer Guide" footer link to all six existing pages plus a self-referential active link on the new page itself. Verified at both desktop and mobile widths: the nav does not wrap or crowd with six items, and the mobile hamburger menu opens cleanly with all six entries plus GitHub. - Fixes stale github.com/bawbel/ave nav/footer/body links (registry, crosswalks, architecture, scoring) to github.com/aveproject/ave, found while touching those same nav blocks. github.com/bawbel/scanner links (the separate reference-scanner repo) are untouched. - Adds a copy-to-clipboard button to each code block on implementer-guide.html, reusing the site's existing dark codeblock styling. Verified live: click copies the exact code text and the button swaps to a checkmark. - Adds a sixth "Implementer guide" card to the homepage route grid, matching the existing card style and completing a 3x2 layout. --- architecture.html | 8 +++++--- crosswalks.html | 6 ++++-- implementer-guide.html | 44 ++++++++++++++++++++++++++++++++++-------- index.html | 7 +++++++ registry.html | 6 ++++-- schema.html | 2 ++ scoring.html | 6 ++++-- styles.css | 7 +++++++ 8 files changed, 69 insertions(+), 17 deletions(-) diff --git a/architecture.html b/architecture.html index 78fc85a..4c15dbc 100644 --- a/architecture.html +++ b/architecture.html @@ -102,7 +102,8 @@ Architecture Scoring Schema - GitHub + Guide + GitHub @@ -371,7 +372,7 @@

Output: how AVE travels

Build your own implementation -

The schema, records, rules, and fixtures are all open under Apache 2.0. Honor the declares-vs-assigns contract and the SARIF convention, and your tool’s findings will interoperate with every other AVE implementation. See the schema reference and the repository.

+

The schema, records, rules, and fixtures are all open under Apache 2.0. Honor the declares-vs-assigns contract and the SARIF convention, and your tool’s findings will interoperate with every other AVE implementation. See the schema reference and the repository.

@@ -391,7 +392,8 @@

Output: how AVE travels

Architecture Scoring Schema v1.0.0 - GitHub repo + Implementer Guide + GitHub repo
Implementations diff --git a/crosswalks.html b/crosswalks.html index 0ebc90e..37e4a65 100644 --- a/crosswalks.html +++ b/crosswalks.html @@ -102,7 +102,8 @@ Architecture Scoring Schema - GitHub + Guide + GitHub
@@ -151,7 +152,8 @@

AVE → OWASP · MITRE ATLAS

Architecture Scoring Schema v1.0.0 - GitHub repo + Implementer Guide + GitHub repo
Implementations diff --git a/implementer-guide.html b/implementer-guide.html index e9deb29..8b142e2 100644 --- a/implementer-guide.html +++ b/implementer-guide.html @@ -100,6 +100,7 @@ Architecture Scoring Schema + Guide GitHub
@@ -133,7 +134,10 @@

Pattern 1: Runtime API lookup

indicators_of_compromise, remediation, owasp_mcp, mitre_atlas, aivss.

-
import httpx +
import httpx def enrich_finding(ave_id: str) -> dict: resp = httpx.get(f"https://api.aveproject.org/records/{ave_id}", timeout=5) @@ -146,7 +150,7 @@

Pattern 1: Runtime API lookup

"severity": "HIGH", # optional: enrich at scan time "ave_record": enrich_finding("AVE-2026-00002"), -}
+}

When to use: developer machines, cloud CI/CD pipelines, SaaS tools with outbound internet.
@@ -172,7 +176,10 @@

Pattern 2: Bundled offline record set

point when one is cut, not the only one.

Format: JSON array of all active records (59 as of schema v1.1.0).

-
import json +
import json from pathlib import Path # Load at startup @@ -182,7 +189,7 @@

Pattern 2: Bundled offline record set

} def lookup_ave(ave_id: str) -> dict | None: - return AVE_RECORDS.get(ave_id)
+ return AVE_RECORDS.get(ave_id)

Sync strategy: track ave-records-latest.json if you always want current data, or pin to a specific @@ -203,7 +210,10 @@

Pattern 3: ID-only emission

Example SARIF output (the correct way to carry ave_id in SARIF):

-
{ +
{ "runs": [{ "results": [{ "ruleId": "your-rule-id", @@ -214,7 +224,7 @@

Pattern 3: ID-only emission

} }] }] -}
+}

Full SARIF convention: docs/specs/ave-in-sarif.md

When to use: any environment. Especially useful when @@ -241,11 +251,14 @@

The mapping step

Minimum viable integration

The smallest possible integration is adding one field:

-
finding = { +
finding = { "rule_id": "prompt-injection/tool-description", "severity": "HIGH", "ave_id": "AVE-2026-00002", # add this -}
+}

That is it. The ID is stable and permanent. No other changes required. Your users get cross-tool deduplication and links to the full behavioral @@ -274,6 +287,7 @@

Contact

Architecture Scoring Schema v1.1.0 + Implementer Guide GitHub repo
@@ -290,5 +304,19 @@

Contact

+ + diff --git a/index.html b/index.html index 65a2ae7..0834be7 100644 --- a/index.html +++ b/index.html @@ -102,6 +102,7 @@ Architecture Scoring Schema + Guide GitHub @@ -154,6 +155,11 @@

The behavioral classification standard for agentic AI

Every field, its type, whether it is required, and what it means, plus the evidence declarations and an example record.

Open the schema → + + Integrate

Implementer guide

+

Add ave_id to your scanner's finding output: three consumption patterns for runtime API lookup, bundled offline records, or ID-only emission.

+ Start integrating → + @@ -183,6 +189,7 @@

Contribute a new agentic flaw standard

Architecture Scoring Schema v1.0.0 + Implementer Guide GitHub repo
diff --git a/registry.html b/registry.html index 61d5eb4..33c05fc 100644 --- a/registry.html +++ b/registry.html @@ -102,7 +102,8 @@ Architecture Scoring Schema - GitHub + Guide + GitHub
@@ -177,7 +178,8 @@

All records

Architecture Scoring Schema v1.0.0 - GitHub repo + Implementer Guide + GitHub repo
Implementations diff --git a/schema.html b/schema.html index c51b6a2..86f1330 100644 --- a/schema.html +++ b/schema.html @@ -100,6 +100,7 @@ Architecture Scoring Schema + Guide GitHub
@@ -225,6 +226,7 @@

Example record

Architecture Scoring Schema v1.1.0 + Implementer Guide GitHub repo
diff --git a/scoring.html b/scoring.html index 764957f..b906225 100644 --- a/scoring.html +++ b/scoring.html @@ -102,7 +102,8 @@ Architecture Scoring Schema - GitHub + Guide + GitHub
@@ -261,7 +262,8 @@

Where this lives in a record

Architecture Scoring Schema v1.0.0 - GitHub repo + Implementer Guide + GitHub repo
Implementations diff --git a/styles.css b/styles.css index 5c9d616..91e1be9 100644 --- a/styles.css +++ b/styles.css @@ -296,6 +296,13 @@ table.ref tbody tr:hover { background: #f7f9f7; } .codeblock { font-family: var(--mono); font-size: 13px; background: var(--deep); color: #d7ece1; border-radius: 12px; padding: 18px 20px; overflow-x: auto; line-height: 1.6; margin: 18px 0; white-space: pre; } .codeblock .c { color: #9ec3b2; } .codeblock .g { color: var(--gold); } +.codeblock-wrap { position: relative; } +.codeblock-wrap .copy-btn { position: absolute; top: 10px; right: 10px; display: flex; align-items: center; justify-content: center; width: 30px; height: 30px; color: #9ec3b2; background: rgba(255,255,255,0.06); border: 1px solid rgba(255,255,255,0.14); border-radius: 7px; cursor: pointer; padding: 0; } +.codeblock-wrap .copy-btn:hover { background: rgba(255,255,255,0.14); color: #d7ece1; } +.codeblock-wrap .copy-btn .i-check { display: none; } +.codeblock-wrap .copy-btn.done { color: var(--gold); border-color: var(--gold); background: rgba(212,160,23,0.14); } +.codeblock-wrap .copy-btn.done .i-copy { display: none; } +.codeblock-wrap .copy-btn.done .i-check { display: block; } /* ============ responsive improvements ============ */