RFC: SARIF Envelope Schema (ATR rule-id + target.digest)

[aliksir]

RFC: SARIF Envelope Schema (ATR rule-id + target.digest)

Context

Derived from anthropics/skills#492. This RFC proposes a standardized SARIF envelope schema for the claude-code-skill-security-check scanner output, incorporating agreements reached with @eeee2345.

The goal is to enable consistent, interoperable security scan results across multiple scanners while maintaining compatibility with SARIF 2.1.0 tooling.

---

Envelope Schema Overview

The proposed envelope wraps standard SARIF 2.1.0 output with three additions: a namespaced ATR rule-id for cross-scanner deduplication, a target.digest field (SHA-256) for precise artifact identification, and SARIF-native taxonomy binding via result.taxa[] and run.taxonomies[]. Invocation metadata (executionSuccessful, timing fields, toolExecutionNotifications[]) is included to support audit trails and failure diagnosis.

---

Agreed Specifications

1. ATR Rule-ID Namespace

ID assignment follows a PR-to-ATR first policy:

• Primary: IDs are assigned via the PR-to-ATR process. Stable, scanner-comparable IDs are only available after ATR assignment.
• Emergency / pre-assignment escape hatch: Use DRAFT-<scanner>-<slug> as a temporary ID (e.g., DRAFT-bandit-sql-injection).
  • A tracking issue URL must be embedded in the rule metadata when using a DRAFT ID.
  • DRAFT IDs must not be used for cross-scanner comparison until an ATR ID is assigned.

"rules": [
  {
    "id": "ATR-SEC-0042",
    "shortDescription": { "text": "SQL Injection via string concatenation" },
    "properties": {
      "draft-id": "DRAFT-bandit-sql-injection",
      "tracking-issue": "https://github.com/aliksir/claude-code-skill-security-check/issues/NNN"
    }
  }
]

2. target.digest

The target artifact is identified by SHA-256 digest using the standard artifactLocation + hashes pattern:

"artifacts": [
  {
    "location": { "uri": "src/app.py" },
    "hashes": {
      "sha-256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  }
]

• Format: lowercase hex, 64 characters.
• Required for all file-level results to enable deduplication across scan runs.

3. SARIF-Native Taxonomy Binding

Decision: Use SARIF 2.1.0 standard result.taxa[] and run.taxonomies[] instead of a custom taxonomy_uri property.

• In v1, taxonomy binding is MAY / optional — do not block adoption on taxonomy completeness.
• Lock-in of taxonomy URIs deferred until multi-taxonomy consumers emerge in practice.
• Versioning policy: Promoting taxonomy binding from MAY to MUST constitutes a breaking change and requires a semver major bump to the envelope schema.

"run": {
  "taxonomies": [
    {
      "name": "CWE",
      "version": "4.12",
      "organization": "MITRE",
      "shortDescription": { "text": "Common Weakness Enumeration" },
      "taxa": [
        { "id": "CWE-89", "name": "SQL Injection" }
      ]
    }
  ],
  "results": [
    {
      "ruleId": "ATR-SEC-0042",
      "taxa": [
        {
          "toolComponent": { "name": "CWE" },
          "id": "CWE-89"
        }
      ]
    }
  ]
}

4. Invocation Metadata

All invocations must include:

Field	Type	Required	Notes
executionSuccessful	boolean	MUST	false if scanner exited non-zero or threw
startTimeUtc	string (ISO 8601)	SHOULD	UTC, e.g. "2026-06-25T03:00:00.000Z"
endTimeUtc	string (ISO 8601)	SHOULD	UTC
toolExecutionNotifications[]	array	MUST if failed	One entry per error; level: "error" for failures. Include properties.standardError (stderr excerpt) for debuggability

"invocations": [
  {
    "executionSuccessful": false,
    "startTimeUtc": "2026-06-25T03:00:00.000Z",
    "endTimeUtc": "2026-06-25T03:00:05.123Z",
    "toolExecutionNotifications": [
      {
        "message": { "text": "Scanner exited with code 2: config file not found" },
        "level": "error",
        "properties": {
          "standardError": "Error: ENOENT: config.yml not found"
        }
      }
    ]
  }
]

---

Envelope JSON Schema Draft

Top-level structure (simplified; not a complete definition):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/aliksir/claude-code-skill-security-check/schemas/sarif-envelope-v1.json",
  "title": "SARIF Envelope v1",
  "description": "ATR-compatible SARIF 2.1.0 envelope for claude-code-skill-security-check",
  "type": "object",
  "required": ["version", "runs"],
  "properties": {
    "version": {
      "type": "string",
      "enum": ["2.1.0"]
    },
    "runs": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["tool", "invocations", "artifacts", "results"],
        "properties": {
          "tool": {
            "type": "object",
            "required": ["driver"],
            "properties": {
              "driver": {
                "type": "object",
                "required": ["name", "version", "rules"],
                "properties": {
                  "name": { "type": "string" },
                  "version": { "type": "string" },
                  "rules": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["id"],
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^(ATR-[A-Z]+-[0-9]+|DRAFT-[a-z]+-[a-z0-9-]+)$"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "invocations": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": ["executionSuccessful"],
              "properties": {
                "executionSuccessful": { "type": "boolean" },
                "startTimeUtc": { "type": "string", "format": "date-time" },
                "endTimeUtc": { "type": "string", "format": "date-time" },
                "toolExecutionNotifications": { "type": "array" }
              }
            }
          },
          "artifacts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "location": { "type": "object" },
                "hashes": {
                  "type": "object",
                  "properties": {
                    "sha-256": {
                      "type": "string",
                      "pattern": "^[0-9a-f]{64}$"
                    }
                  }
                }
              }
            }
          },
          "taxonomies": { "type": "array" },
          "results": { "type": "array" }
        }
      }
    }
  }
}

---

Open Questions

• Multi-file results: When a result spans multiple files (e.g., taint flow), which artifact carries the digest? Resolved (2026-06-25): Each artifact carries its own artifacts[].hashes["sha-256"]; set of per-file digests = flow identity in v1. No flow-level composite digest. Per SARIF 3.24.11 + 3.36-3.38. Composite flow identity deferred to v1.x.
• DRAFT ID lifecycle: What is the maximum allowed duration for a DRAFT ID before ATR assignment is required? Resolved (2026-06-25): Scanner-side mechanics only: (a) tracking-issue URL required before first emit, (b) historical SARIF frozen at scan-time ruleId + previous-draft-id for 2 minor versions, (c) id-alias-map.json sidecar with tombstone entries, (d) stale/retired thresholds set by ATR not envelope, (e) CI gate behavior is scanner-author choice. Extension fields in reportingDescriptor.properties: draft-id, tracking-issue, previous-draft-id, draft-status.
• Digest scope (Resolved 2026-06-28): Should target.digest be required for all result levels, or only error / warning? (Currently: required for file-level results)
• Taxonomy version pinning: When a taxonomy version (e.g., CWE 4.12) is updated, should existing results be re-tagged or frozen at scan-time version?
• Schema versioning: Should $id include a semver suffix (e.g., sarif-envelope-v1.0.0.json) or keep v1 as a floating pointer?

---

Next Steps

• Publish JSON Schema to schemas/sarif-envelope-v1.json in this repo (include reportingDescriptor.properties extension fields: draft-id, tracking-issue, previous-draft-id, draft-status)
• Update scanner output to include invocations[].executionSuccessful + timing fields
• Add result.taxa[] support (optional in v1; document the opt-in path)
• Define DRAFT ID lifecycle policy (tracking issue + expiry) Resolved: scanner-side mechanics defined (see Open Questions)
• Define id-alias-map.json sidecar schema (tombstone = null for rejected IDs)
• Add schema validation step to CI (e.g., ajv validate)
• Add CI gate: fail build if any DRAFT-* rule-id appears in results[] (scanner-author choice; strict default)
• Update README with envelope schema reference
• Review PDA SARIF emitter draft PR (expected ~2 weeks from 2026-06-25)

---

CC: @eeee2345 @ppcvote

[ppcvote]

Envelope reads cleanly — the four agreed specs (PR-to-ATR-first with DRAFT escape hatch, SARIF-native result.taxa[], executionSuccessful + toolExecutionNotifications[], target.digest via artifacts[].hashes) are reproduced accurately and the versioning-as-semver discipline on taxonomy binding is the right call. Two answers below on the open questions you flagged.

Q1 — digest scope for multi-file results

Recommend (A): each artifact touched by the finding carries its own artifacts[].hashes["sha-256"]; the set of per-file digests IS the flow identity in v1. No flow-level composite digest as MUST.

Rationale: §3.24.11 places hashes on the artifact, not the result or codeFlow — the spec offers no flow-level hash slot. Per spec: "An artifact object MAY contain a property named hashes whose value is an array of one or more unique hash objects." §3.36–3.38 model multi-file flows by having each threadFlowLocation reference its own artifactLocation (typically via index into run.artifacts[]), so "set of per-file artifacts + ordered locations" IS the spec-native identity model. SHA-256 of file bytes is content-addressed, so two scanners hitting the same files produce the same digest set regardless of analysis engine — dedup property is preserved.

If a future scanner emits codeFlows[] and wants composite-flow identity, that's a v1.x discussion driven by that scanner's concrete need — punt until then rather than reserving extension surface ahead of demand.

For scanners emitting flat results (PDA, ultraprobe today), Answer (A) is the N=1 case; for scanners emitting codeFlows[] already (Semgrep, CodeQL), the per-artifact-hashes model is already spec-native.

Q2 — DRAFT ID lifecycle (scanner-side only)

Scoping this to mechanics a scanner can implement unilaterally, leaving ATR-side timing/labels to ATR:

• (a) Creation precondition: tracking-issue URL REQUIRED before first emit of a DRAFT-<scanner>-<slug> id (scanner refuses to register the rule otherwise). Your RFC already mandates the URL in rule metadata; this just pins when — before first emit, not eventually.
• (b) Historical immutability: historical SARIF stays frozen at scan-time ruleId — mutating would break the audit-artifact integrity that target.digest is meant to guarantee. On promotion, new scans emit canonical ATR id and SHOULD include properties.previous-draft-id for two minor versions.
• (c) Reconciliation: consumers reconcile via scanner-published sidecar id-alias-map.json (same pattern as OSV/CVE/GHSA), with tombstone entries (null) for rejected ids so consumers can distinguish "tried and rejected" from "never existed."
• (d) Lifecycle thresholds (stale, retired) should be set by ATR, not the envelope. The envelope just defines the SHAPE of the alias map and the metadata slots (draft-id, tracking-issue, previous-draft-id, optional draft-status), all living in the reportingDescriptor.properties extension bag.
• (e) CI gate behavior is scanner-author choice; envelope only requires that tracking-issue and draft-status slots exist so a gate CAN be built. Your original fail-on-any-DRAFT works for strict shops; looser shops can WARN. No envelope mandate either way.

This kills any coupling to ATR's review cadence or label vocabulary — every clause is implementable by a single scanner against reportingDescriptor.properties and a sidecar JSON file.

On the PDA side I'll open a tracking issue for SARIF emitter work this week and target a draft PR for your review within ~2 weeks. codeFlow modeling stays out of the first emitter PR — separate tracking issue once that's up.

[aliksir]

Response to Q1 & Q2

Reviewed both answers (3-perspective mini-review: spec alignment, implementation impact, audit trail).

Q1 — Per-artifact hashes: Accepted

Agree with option (A). The rationale is spec-grounded (§3.24.11 hashes on artifact, §3.36–3.38 threadFlowLocation → artifactLocation) and practically zero-cost for our scanners (flat results = N=1 case). Composite flow identity deferred to v1.x per concrete need — correct application of YAGNI.

Q2 — DRAFT ID lifecycle: All five clauses accepted

Clause	Status
(a) tracking-issue before first emit	Accepted — strengthens existing mandate
(b) historical SARIF frozen + previous-draft-id for 2 minor versions	Accepted — preserves audit-artifact integrity
(c) id-alias-map.json sidecar with tombstone entries	Accepted — OSV/CVE/GHSA pattern, clean reconciliation
(d) stale/retired thresholds set by ATR, envelope defines shape only	Accepted — clean responsibility separation
(e) CI gate behavior is scanner-author choice	Accepted — our strict default (fail-on-DRAFT) unchanged, flexibility preserved

The scanner-side scoping eliminates coupling to ATR's review cadence — every clause is implementable unilaterally. This is a well-designed boundary.

Schema updates needed

Based on Q1+Q2 agreements, the following fields should be added to the envelope schema:

In reportingDescriptor.properties (extension bag):

• draft-id (string, optional)
• tracking-issue (string/uri, REQUIRED when draft-id present)
• previous-draft-id (string, optional — SHOULD be present for 2 minor versions after promotion)
• draft-status (string, optional — enables CI gate construction)

Sidecar file:

• id-alias-map.json — scanner-published, tombstone = null for rejected IDs

PDA timeline acknowledged

Tracking issue for SARIF emitter this week, draft PR in ~2 weeks. codeFlows[] modeling as separate tracking issue. We'll be ready for review.

Open Questions resolution

Marking Q1 (multi-file digest scope) and Q2 (DRAFT ID lifecycle) as resolved. Remaining open questions (digest level requirement, taxonomy version pinning, schema versioning $id format) can be addressed incrementally.

[aliksir]

Proposals for remaining Open Questions

OQ1 — Digest scope

Proposal: Required for all file-level results regardless of severity.

The dedup value of per-artifact hashes (Q1 agreement) does not depend on severity level. A warning-level finding needs the same cross-scan identity as an error-level one. note-level results (informational, non-vulnerability) MAY omit digest.

OQ2 — Taxonomy version pinning

Proposal: Frozen at scan-time version.

Consistent with Q2(b) historical immutability. Re-tagging a CWE 4.12 finding to CWE 4.13 after the fact would break audit-artifact integrity. Consumers can determine taxonomy currency from run.taxonomies[].version. If a taxonomy is updated, new scans emit results tagged with the new version — historical results remain untouched.

OQ3 — Schema versioning ($id format)

Proposal: Semver suffix (sarif-envelope-v1.0.0.json).

The semver discipline is already agreed for taxonomy binding (MAY→MUST = major bump). Applying the same convention to the schema $id makes version tracking explicit. A floating v1 pointer obscures whether a breaking change has occurred.

---

Also published: schemas/id-alias-map.schema.json — JSON Schema for the sidecar alias map file (Q2(c) agreement). Keys are DRAFT-* IDs, values are ATR-* IDs or null (tombstone).

[aliksir]

Correction to OQ1 proposal (internal review feedback):

Withdraw the note-level exclusion. Revised proposal: digest required for ALL file-level results regardless of severity level, including note.

Reason: SARIF note severity can include code quality findings that benefit from cross-scan dedup. An exclusion based on severity creates an arbitrary boundary — the dedup value of per-artifact hashes applies uniformly.

OQ2 (frozen at scan-time) and OQ3 (semver suffix) proposals stand unchanged.

[eeee2345]

@aliksir Agreed — withdrawing the note-level carve-out is the right call. The dedup identity is SHA-256 of file bytes, which is content-addressed and has nothing to do with severity, so gating on note would just add a boundary the digest itself doesn't care about. A code-quality finding at note benefits from cross-scan dedup the same as an error. Uniform-for-all-file-level is cleaner to spec and to implement.

No friction on the ATR side. Rule-ids are stable and the engine emits matches independent of severity level, so there's no severity-gated path here that a uniform digest rule would collide with. result.ruleId -> ATR id stays a clean 1:1 at every level.

One edge case worth pinning down while the boundary is being made uniform: the proposal says "all file-level results." SARIF results don't always have a file-level location — some carry a directory/logical location, and some have an empty result.locations (project- or run-level findings). Those have no artifacts[].hashes slot to hang a digest on. Probably fine to leave them out of scope, but it's worth one sentence saying so explicitly, otherwise "all file-level" quietly reintroduces the same kind of arbitrary boundary one level up. Not a blocker for OQ1 — just cheaper to settle now than to discover later when a scanner emits a project-level result.

OQ2 (frozen taxonomy version) and OQ3 (semver $id) both read fine to me as written.

[aliksir]

Good catch — that edge case sharpens the boundary.

OQ1 resolved: digest required for all file-level results, regardless of severity.

Adding to §2 (target.digest):

Results that do not reference a file-level artifactLocation (e.g., directory-level, logical-location-only, or run-level findings with empty result.locations[]) are not subject to the digest requirement.

Boundary: "has a file artifact = has a hash." No severity gate, no location-type gate beyond artifact existence.

OQ2 — leaning toward frozen-at-scan-time (consistent with Q2(b) historical immutability). OQ3 — semver suffix, pending one more consumer to validate the need. Will formalize both in a follow-up revision.

Will update the RFC body.

[aliksir]

PDA SARIF Emitter Draft — RFC alignment check

Reviewed the draft PR description against this RFC. Alignment looks solid:

RFC section	Implementation	Status
§1 ATR Rule-ID namespace	DRAFT-pda-<slug> + tracking-issue in reportingDescriptor.properties	Aligned
§2 target.digest	artifacts[].hashes["sha-256"] (64-char lowercase hex)	Aligned
§3 Taxonomy binding (MAY in v1)	Explicitly out of scope — correct for v1 MAY	Aligned
§4 Invocation metadata	executionSuccessful + toolExecutionNotifications[] (stderr excerpt)	Aligned

Additional good decisions:

• Backward compat: legacy --json / default output stays byte-identical (external GH Action consumers unaffected)
• Credential safety: findings are located (charOffset/charLength) but never reproduced in snippet.text
• Schema conformance: validated against vendored OASIS SARIF 2.1.0 errata01 via ajv-draft-04
• columnKind: utf16CodeUnits: unambiguous region offsets on non-BMP input

Happy to do a full code review once the PR is marked ready. No blockers from the RFC side.

---

Housekeeping: updating OQ3 checkbox — resolved per 2026-06-28 discussion (all file-level results regardless of severity).

[ppcvote]

Thanks for the careful RFC-alignment pass, @aliksir — good to have §1–§4 confirmed.

Status update: PR #3 (ppcvote/prompt-defense-audit#3) is now marked ready for review. It's out of draft with CI green (Test on Node 20 and Node 22 both pass), so it's all set whenever you have bandwidth for the full code review you offered — no rush on timing from my end.

On §3 (taxonomy binding, MAY in v1): staying out of scope for now, as you flagged. It's tracked in ppcvote/prompt-defense-audit#1 as a deferred item, with the plan to add result.taxa[] / run.taxonomies[] when the envelope promotes taxonomy binding MAY→MUST (which reads as a semver-major per the RFC), rather than partially wiring it in early.

On the semver $id suffix question: PDA emits SARIF-native $schema today and doesn't wrap in your envelope yet, so I can't speak to the suffix decision directly. If a second consumer is still useful there, PDA is glad to be one once/if it adopts the envelope wrapper — a standing offer, not a claim to resolve it.

Thanks again for keeping the RFC side unblocked.