Network Working Group J. Carroll Internet-Draft The Clearing Room Intended status: Informational 9 April 2026 Expires: 11 October 2026 Triageable Evidence Format (TEF) draft-tcr-tef-00 Abstract This document defines the Triageable Evidence Format (TEF), a YAML- based format for structured vulnerability evidence submission. TEF provides a standard way for security researchers to describe software defects so that triage systems, whether human or automated, can classify them without ambiguity. TEF combines YAML data structure with a Given/When/Then evidence model. Each submission carries structured metadata, one or more evidence scenarios with preconditions, triggers, and observed outcomes, location data identifying where the defect exists, and reproduction artefacts proving its presence. TEF is an intake format. It does not replace vulnerability publication formats (CVE, CSAF, OSV) or scan output formats (SARIF). It fills the gap between discovery and classification. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 11 October 2026. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. Carroll Expires 11 October 2026 [Page 1] Internet-Draft TEF April 2026 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 2. Format Overview . . . . . . . . . . . . . . . . . . . . . . . 3 3. Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Defect Block (REQUIRED) . . . . . . . . . . . . . . . . . 3 3.2. Evidence Block (REQUIRED) . . . . . . . . . . . . . . . . 4 4. Target Types . . . . . . . . . . . . . . . . . . . . . . . . 4 5. Presence Patterns . . . . . . . . . . . . . . . . . . . . . . 5 6. Location Block . . . . . . . . . . . . . . . . . . . . . . . 5 7. Reproduction Block . . . . . . . . . . . . . . . . . . . . . 6 8. Defect Classes . . . . . . . . . . . . . . . . . . . . . . . 6 9. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 6 10. Relationship to Other Formats . . . . . . . . . . . . . . . . 7 11. Security Considerations . . . . . . . . . . . . . . . . . . . 7 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 13.1. Normative References . . . . . . . . . . . . . . . . . . 7 13.2. Informative References . . . . . . . . . . . . . . . . . 8 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction Vulnerability disclosure relies on structured formats at the publication stage (CVE records, CSAF advisories, OSV entries) and at the scanning stage (SARIF). There is no equivalent standard for the intake stage: what a researcher submits when reporting a software defect to a coordination body, vendor, or disclosure platform. Most intake systems accept free text. This creates ambiguity, inconsistency, and friction. A researcher describes their finding in prose. A triager interprets the prose, potentially misunderstanding preconditions, confusing the trigger with the outcome, or missing evidence entirely. At scale, this process does not work. TEF addresses this gap by defining a structured, machine-parseable, human-readable format for vulnerability evidence. Carroll Expires 11 October 2026 [Page 2] Internet-Draft TEF April 2026 1.1. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. Format Overview A TEF document is a YAML file containing two required top-level keys: "defect" and "evidence". The "defect" key contains structured metadata about the affected product, vendor, target type, weakness classification, affected versions, and defect manifestation pattern. The "evidence" key contains one or more scenarios, each describing a distinct piece of evidence using a Given/When/Then structure, an optional location block, and an optional reproduction block. 3. Schema 3.1. Defect Block (REQUIRED) The "defect" block MUST contain the following fields: * "product" (string, REQUIRED): The name of the affected product. * "vendor" (string, REQUIRED): The vendor domain or identifier. * "type" (string, REQUIRED): The target type. See Section 4. * "cwe" (integer, REQUIRED): The CWE identifier for the weakness class. * "versions" (array of strings, REQUIRED): The affected version range. * "presence" (string, REQUIRED): The defect manifestation pattern. See Section 5. The "defect" block MAY contain: * "os" (string): The operating system or platform. * "description" (string): Freeform context. Carroll Expires 11 October 2026 [Page 3] Internet-Draft TEF April 2026 * "cvss" (string): CVSS vector or score. * "references" (array of strings): URLs, CVE IDs, advisory links. * "reproduction_rate" (string): For probabilistic or timing- dependent defects (e.g., "15/100"). * "environment" (string): Specific environment if relevant. 3.2. Evidence Block (REQUIRED) The "evidence" block MUST contain one or more scenario entries. Each scenario MUST contain: * "title" (string, REQUIRED): A short name for the scenario. * "given" (array of strings, REQUIRED): Preconditions that must be true before the trigger. * "when" (array of strings, REQUIRED): The action or input that reveals or triggers the defect. * "then" (array of strings, REQUIRED): The observed outcome that proves the defect exists. Each scenario MAY contain: * "location": A block identifying where the defect exists. See Section 6. * "reproduction": A block carrying proof artefacts. See Section 7. 4. Target Types The "type" field in the "defect" block MUST be one of the following values: "web", "api", "mobile_android", "mobile_ios", "mobile", "desktop", "server", "os", "embedded", "network", "cloud", "ot", "ai_ml", "supply_chain". Producers SHOULD use "mobile_android" or "mobile_ios" rather than "mobile" when the defect is platform-specific. The "desktop" type refers to the application, not the operating system. The "server" type covers software running as a service. Web applications running on server software are "web". Carroll Expires 11 October 2026 [Page 4] Internet-Draft TEF April 2026 5. Presence Patterns The "presence" field MUST be one of: "static_artefact", "static_config", "behavioural_deterministic", "behavioural_stateful", "behavioural_timing", "probabilistic", "environmental", "design_flaw", "supply_chain". "static_artefact": The defect exists in the artefact itself and can be confirmed without execution. "static_config": Observable in configuration, headers, DNS, or policy without exploitation. "behavioural_deterministic": Requires execution but same input always produces same result. "behavioural_stateful": Requires specific application state or multi- step interaction. "behavioural_timing": Depends on timing or concurrency. Submissions SHOULD include "reproduction_rate". "probabilistic": Same input may produce different outcomes because the system is non-deterministic. Distinct from timing-dependent. Submissions SHOULD include "reproduction_rate". "environmental": Only manifests in specific environments. Submissions SHOULD include comparison. "design_flaw": The design itself is insecure. No single code fix resolves it. "supply_chain": Inherited from a third-party component or dependency. 6. Location Block The "location" block identifies where the defect exists. It MAY appear on any evidence scenario. * "type" (string, REQUIRED): One of "endpoint", "file", "function", "binary_offset", "register", "port", "config", "path". * "value" (string, REQUIRED): The specific location. * "context" (string, OPTIONAL): Broader context. Carroll Expires 11 October 2026 [Page 5] Internet-Draft TEF April 2026 7. Reproduction Block The "reproduction" block carries raw proof artefacts. All fields are OPTIONAL. * "commands" (array of strings): Exact commands executed. * "code" (string): Vulnerable code snippet or exploit script. * "request" (string): Raw protocol request. * "response" (string): Raw protocol response. * "logs" (string): Relevant log entries. * "output" (string): Tool output, crash dumps, extraction results. * "files" (array of objects): References to attached evidence files, each with "name" (string), "hash" (string, SHA-256), and "type" (string). 8. Defect Classes TEF recognises 19 defect classes across two categories. The defect class is not required but is RECOMMENDED. Producers MAY use the "bugClass" field. Code defects: injection, auth, crypto, data_exposure, access_control, deserialization, file_handling, ssrf, memory, logic, supply_chain, ai_ml. Configuration defects: config_tls, config_headers, config_secrets, config_permissions, config_logging, config_dns, config_default. The "ai_ml" class covers defects in AI and machine learning systems including prompt injection, training data poisoning, model extraction, adversarial inputs, excessive agent permissions, RAG corpus manipulation, and model supply chain compromise. 9. Conformance A TEF producer MUST include all REQUIRED fields. A TEF consumer MUST accept documents with unknown fields and MUST NOT reject them. Carroll Expires 11 October 2026 [Page 6] Internet-Draft TEF April 2026 A TEF document is valid if: (1) it is valid YAML, (2) the "defect" block contains all REQUIRED fields, (3) the "evidence" block contains at least one scenario, (4) each scenario contains "title", "given", "when", and "then", (5) the "type" value is from Section 4, (6) the "presence" value is from Section 5. 10. Relationship to Other Formats TEF is an intake format. It captures what a researcher observed, structured for triage. After triage, findings are published as CVE records, CSAF [CSAF] advisories, or correlated with SARIF [SARIF] output. The Common Weakness Enumeration [CWE] provides the defect taxonomy. TEF does not duplicate these formats. It precedes them in the vulnerability lifecycle. 11. Security Considerations TEF documents may contain offensive security content: exploit code, injection payloads, shell commands, memory corruption details, and proof-of-concept material. Systems processing TEF documents MUST treat all user-supplied content as untrusted input. TEF documents SHOULD NOT contain plaintext credentials or unredacted sensitive data belonging to third parties. Producers SHOULD redact sensitive values while preserving enough information for verification. The "reproduction" block may reference attached files by SHA-256 hash. Consumers MUST NOT execute attached files without explicit user authorisation. 12. IANA Considerations This document has no IANA actions. A media type registration for "application/tef+yaml" may be requested in a future version. 13. References 13.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . Carroll Expires 11 October 2026 [Page 7] Internet-Draft TEF April 2026 13.2. Informative References [CWE] MITRE, "Common Weakness Enumeration", . [SARIF] OASIS, "Static Analysis Results Interchange Format (SARIF) Version 2.1.0", 2020, . [CSAF] OASIS, "Common Security Advisory Framework (CSAF) Version 2.0", 2022, . Acknowledgments The TEF format was developed through implementation experience at The Clearing Room, an independent vulnerability disclosure clearing house. Feedback from the security research community, particularly on presence pattern classification and AI/ML defect coverage, shaped the current specification. Examples Complete TEF examples covering all target types and presence patterns are maintained at the TEF template library: https://theclearingroom.io/templates Author's Address John Carroll The Clearing Room Email: jc@thecontractor.io Carroll Expires 11 October 2026 [Page 8]