<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:media="http://search.yahoo.com/mrss/"><channel><title>Vexctl | FirewallSync</title><link>https://firewallsync.com/tags/vexctl/</link><description>Practical cybersecurity writing for engineering teams that ship fast.</description><language>en-us</language><image><url>https://firewallsync.com/icon-512.png</url><title>FirewallSync</title><link>https://firewallsync.com/</link></image><lastBuildDate>Fri, 20 Nov 2026 04:30:00 +0000</lastBuildDate><atom:link href="https://firewallsync.com/tags/vexctl/index.xml" rel="self" type="application/rss+xml"/><item><title>OpenVEX Statement Fields: What Trivy and go-vex Ignore</title><link>https://firewallsync.com/posts/openvex-statement-fields-status-notes-action-statement-version-trivy/</link><guid>https://firewallsync.com/posts/openvex-statement-fields-status-notes-action-statement-version-trivy/</guid><pubDate>Fri, 20 Nov 2026 04:30:00 +0000</pubDate><dc:creator>John Marshall</dc:creator><category>AppSec &amp; APIs</category><description>OpenVEX v0.2.0 defines 13 statement fields, but Trivy v0.76.2 acts on two of them: status and justification, from the matching statement with the newest timestamp. Here is what happens to status_notes, action_statement, last_updated, version and supplier, read from the go-vex v0.2.9 and Trivy source.</description><enclosure url="https://firewallsync.com/posts/openvex-statement-fields-status-notes-action-statement-version-trivy/cover_hu9992264959083435414.jpg" type="image/jpeg" length="0"/><media:content url="https://firewallsync.com/posts/openvex-statement-fields-status-notes-action-statement-version-trivy/cover_hu9992264959083435414.jpg" medium="image" type="image/jpeg" width="1200" height="630"/><content:encoded><![CDATA[<p><img src="https://firewallsync.com/posts/openvex-statement-fields-status-notes-action-statement-version-trivy/cover_hu9992264959083435414.jpg" alt="Black-framed reading glasses resting on a printed document, the text blurred beneath the lenses" width="1200" height="630"></p><p><strong>Short answer:</strong> OpenVEX v0.2.0 gives a statement 13 fields, from <code>status</code> and <code>justification</code> to <code>status_notes</code>, <code>action_statement</code>, <code>last_updated</code> and a statement-level <code>version</code>. Trivy v0.76.2, through the go-vex v0.2.9 library, acts on two of them once a statement matches: <strong><code>status</code></strong> and <strong><code>justification</code></strong>. It picks the winning statement by <strong><code>timestamp</code></strong> alone. Everything else is either decoded and ignored, or, for statement <code>version</code> and <code>supplier</code>, not decoded at all and lost when a go-vex tool rewrites the file.</p>
<p>That matters if you write VEX for your own images and expect a scanner to honour it. A field you set to change the outcome may have no effect, and a field you rely on as an audit trail may vanish on the next <code>vexctl add</code>.</p>
<p>This article reads the <a href="https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md">OpenVEX v0.2.0 specification</a>, its <a href="https://github.com/openvex/spec/blob/main/openvex_json_schema.json">JSON schema</a>, <a href="https://github.com/openvex/go-vex/tree/v0.2.9">go-vex v0.2.9</a> (the newest tag on November 20, 2026, and the version pinned in Trivy&rsquo;s go.mod) and <a href="https://github.com/aquasecurity/trivy/tree/v0.76.2">Trivy v0.76.2</a>. For what the statuses mean, start with <a href="/posts/vex-explained-what-a-not-affected-statement-means-and-how-to-read-one/">VEX explained</a>; for how products and purls match, see <a href="/posts/openvex-products-subcomponents-purl-matching-trivy/">OpenVEX products and subcomponents</a>.</p>
<h2 id="field-by-field-spec-schema-go-vex-trivy">Field by field: spec, schema, go-vex, Trivy</h2>
<table>
  <thead>
      <tr>
          <th>Statement field</th>
          <th>Spec v0.2.0</th>
          <th>JSON schema</th>
          <th>go-vex v0.2.9</th>
          <th>Trivy v0.76.2</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><code>vulnerability</code></td>
          <td>required</td>
          <td>required</td>
          <td>decoded</td>
          <td>matched against the finding ID</td>
      </tr>
      <tr>
          <td><code>products</code> / <code>subcomponents</code></td>
          <td>required for a complete statement, can be inherited</td>
          <td>optional</td>
          <td>decoded</td>
          <td>matched against the scanned purls</td>
      </tr>
      <tr>
          <td><code>status</code></td>
          <td>required</td>
          <td>required</td>
          <td>decoded, validated by <code>Validate()</code></td>
          <td><strong>acts on it</strong>: suppresses <code>not_affected</code> and <code>fixed</code></td>
      </tr>
      <tr>
          <td><code>justification</code></td>
          <td><code>not_affected</code> needs it or <code>impact_statement</code></td>
          <td>same rule (<code>anyOf</code>)</td>
          <td>decoded</td>
          <td><strong>copied</strong> into the modified finding&rsquo;s <code>Statement</code></td>
      </tr>
      <tr>
          <td><code>timestamp</code></td>
          <td>optional, inherits from the document</td>
          <td>optional</td>
          <td>decoded, <strong>used to sort</strong></td>
          <td>the newest matching statement wins</td>
      </tr>
      <tr>
          <td><code>last_updated</code></td>
          <td>optional</td>
          <td>optional</td>
          <td>decoded, not compared</td>
          <td>ignored</td>
      </tr>
      <tr>
          <td><code>status_notes</code></td>
          <td>MAY</td>
          <td>optional</td>
          <td>decoded</td>
          <td>ignored</td>
      </tr>
      <tr>
          <td><code>impact_statement</code></td>
          <td>alternative to <code>justification</code></td>
          <td>alternative</td>
          <td>decoded</td>
          <td>ignored</td>
      </tr>
      <tr>
          <td><code>action_statement</code></td>
          <td>MUST for <code>affected</code></td>
          <td>required for <code>affected</code></td>
          <td>decoded; <code>Validate()</code> enforces it</td>
          <td>ignored, not validated</td>
      </tr>
      <tr>
          <td><code>action_statement_timestamp</code></td>
          <td>optional</td>
          <td>optional</td>
          <td>decoded</td>
          <td>ignored</td>
      </tr>
      <tr>
          <td><code>version</code> (statement)</td>
          <td>optional, &ldquo;Defaults to zero&rdquo;</td>
          <td>integer, <code>minimum: 1</code></td>
          <td><strong>no struct field: dropped</strong></td>
          <td>not seen</td>
      </tr>
      <tr>
          <td><code>supplier</code> (statement)</td>
          <td>optional</td>
          <td>(not listed)</td>
          <td><strong>no struct field: dropped</strong></td>
          <td>not seen</td>
      </tr>
  </tbody>
</table>
<p>&ldquo;Ignored&rdquo; means the field takes no part in whether Trivy suppresses a finding or in what it records about the suppression. The data is still in your file; it is just not consumed.</p>
<h2 id="how-trivy-decides">How Trivy decides</h2>
<p>Trivy&rsquo;s OpenVEX handler is short. In <a href="https://github.com/aquasecurity/trivy/blob/v0.76.2/pkg/vex/openvex.go"><code>pkg/vex/openvex.go</code></a>, <code>NotAffected</code> asks go-vex for the matching statements, then:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-go" data-lang="go"><span style="display:flex;"><span><span style="color:#75715e">// Take the latest statement for a given vulnerability and product
</span></span></span><span style="display:flex;"><span><span style="color:#75715e">// as a sequence of statements can be overridden by the newer one.
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span><span style="color:#a6e22e">stmt</span> <span style="color:#f92672">:=</span> <span style="color:#a6e22e">stmts</span>[len(<span style="color:#a6e22e">stmts</span>)<span style="color:#f92672">-</span><span style="color:#ae81ff">1</span>]
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">if</span> <span style="color:#a6e22e">stmt</span>.<span style="color:#a6e22e">Status</span> <span style="color:#f92672">==</span> <span style="color:#a6e22e">openvex</span>.<span style="color:#a6e22e">StatusNotAffected</span> <span style="color:#f92672">||</span> <span style="color:#a6e22e">stmt</span>.<span style="color:#a6e22e">Status</span> <span style="color:#f92672">==</span> <span style="color:#a6e22e">openvex</span>.<span style="color:#a6e22e">StatusFixed</span> {
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">modifiedFindings</span> <span style="color:#f92672">:=</span> <span style="color:#a6e22e">types</span>.<span style="color:#a6e22e">NewModifiedFinding</span>(<span style="color:#a6e22e">vuln</span>, <span style="color:#a6e22e">findingStatus</span>(<span style="color:#a6e22e">stmt</span>.<span style="color:#a6e22e">Status</span>), string(<span style="color:#a6e22e">stmt</span>.<span style="color:#a6e22e">Justification</span>), <span style="color:#a6e22e">v</span>.<span style="color:#a6e22e">source</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> <span style="color:#a6e22e">modifiedFindings</span>, <span style="color:#66d9ef">true</span>
</span></span><span style="display:flex;"><span>}
</span></span></code></pre></div><p>Two consequences follow directly from that code:</p>
<ol>
<li><strong>Only <code>status</code> changes the result.</strong> <code>affected</code> and <code>under_investigation</code> leave the finding in place, whatever <code>action_statement</code> or <code>status_notes</code> say.</li>
<li><strong>Only <code>justification</code> is carried into the output.</strong> The third argument to <code>NewModifiedFinding</code> becomes the <code>Statement</code> field of the finding listed under <code>ExperimentalModifiedFindings</code> in Trivy&rsquo;s JSON report. A <code>not_affected</code> statement that explains itself only with <code>impact_statement</code> is valid, yet Trivy records an empty <code>Statement</code> for it. If an auditor reads Trivy&rsquo;s report rather than your VEX file, the reasoning is gone.</li>
</ol>
<h2 id="which-statement-wins-timestamp-not-last_updated-or-version">Which statement wins: timestamp, not last_updated or version</h2>
<p>The list Trivy indexes into is sorted by go-vex&rsquo;s <code>SortStatements</code> in <a href="https://github.com/openvex/go-vex/blob/v0.2.9/pkg/vex/statement.go"><code>pkg/vex/statement.go</code></a>. For statements about the same vulnerability it compares <code>Timestamp</code>, and a statement with no timestamp of its own uses the document&rsquo;s:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-go" data-lang="go"><span style="display:flex;"><span><span style="color:#a6e22e">iTime</span> <span style="color:#f92672">:=</span> <span style="color:#a6e22e">stmts</span>[<span style="color:#a6e22e">i</span>].<span style="color:#a6e22e">Timestamp</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">if</span> <span style="color:#a6e22e">iTime</span> <span style="color:#f92672">==</span> <span style="color:#66d9ef">nil</span> <span style="color:#f92672">||</span> <span style="color:#a6e22e">iTime</span>.<span style="color:#a6e22e">IsZero</span>() {
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">iTime</span> = <span style="color:#f92672">&amp;</span><span style="color:#a6e22e">documentTimestamp</span>
</span></span><span style="display:flex;"><span>}
</span></span><span style="display:flex;"><span><span style="color:#75715e">// ...
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span><span style="color:#66d9ef">return</span> <span style="color:#a6e22e">iTime</span>.<span style="color:#a6e22e">Before</span>(<span style="color:#f92672">*</span><span style="color:#a6e22e">jTime</span>)
</span></span></code></pre></div><p><code>last_updated</code> is never compared, and statement <code>version</code> does not exist in the struct. The sort is stable, so two statements with equal timestamps stay in file order and the later one wins.</p>
<p>This follows the spec, which defines <code>timestamp</code> as &ldquo;the time at which the information expressed in the Statement was known to be true&rdquo; and says a statement &ldquo;is useless without a timestamp as it cannot be related to others talking about the same subject.&rdquo; The trap is editing a statement in place. If you change an old <code>not_affected</code> statement&rsquo;s text and bump its <code>last_updated</code> and <code>version</code>, it keeps its old <code>timestamp</code> and still loses to any newer statement for the same product and CVE.</p>
<p>The spec&rsquo;s own update example shows the safe pattern: keep the old statement unchanged with its original timestamp, and add a new statement that carries the new status and a newer timestamp (its own, or the bumped document timestamp it inherits). <code>vexctl add</code> does this for you, as covered in our <a href="/posts/vexctl-create-add-merge-attest-openvex-documents/">vexctl guide</a>.</p>
<h2 id="statement-version-and-supplier-are-dropped-on-rewrite">Statement version and supplier are dropped on rewrite</h2>
<p>The spec lists <code>version</code> on the statement as an &ldquo;Optional integer representing the statement&rsquo;s version number. Defaults to zero, required when incremented&rdquo;, and <code>supplier</code> as the &ldquo;Supplier of the product or subcomponent.&rdquo; The go-vex v0.2.9 <code>Statement</code> struct has fields for <code>@id</code>, <code>vulnerability</code>, <code>timestamp</code>, <code>last_updated</code>, <code>products</code>, <code>status</code>, <code>status_notes</code>, <code>justification</code>, <code>impact_statement</code>, <code>action_statement</code> and <code>action_statement_timestamp</code>, and nothing else. Go&rsquo;s <code>encoding/json</code> discards keys it has no field for.</p>
<p>We checked the effect with a stdlib-only Go 1.24.7 program whose <code>Statement</code> struct copies go-vex v0.2.9&rsquo;s field set and JSON tags (with <code>products</code> and <code>vulnerability</code> held as raw JSON). Input:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-json" data-lang="json"><span style="display:flex;"><span>{<span style="color:#f92672">&#34;version&#34;</span>:<span style="color:#ae81ff">2</span>,<span style="color:#f92672">&#34;supplier&#34;</span>:<span style="color:#e6db74">&#34;Example Corp&#34;</span>,<span style="color:#f92672">&#34;vulnerability&#34;</span>:{<span style="color:#f92672">&#34;name&#34;</span>:<span style="color:#e6db74">&#34;CVE-2024-32002&#34;</span>},
</span></span><span style="display:flex;"><span> <span style="color:#f92672">&#34;timestamp&#34;</span>:<span style="color:#e6db74">&#34;2026-11-01T10:00:00Z&#34;</span>,<span style="color:#f92672">&#34;last_updated&#34;</span>:<span style="color:#e6db74">&#34;2026-11-20T08:00:00Z&#34;</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">&#34;products&#34;</span>:[{<span style="color:#f92672">&#34;@id&#34;</span>:<span style="color:#e6db74">&#34;pkg:oci/app@sha256:abc&#34;</span>}],<span style="color:#f92672">&#34;status&#34;</span>:<span style="color:#e6db74">&#34;affected&#34;</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">&#34;status_notes&#34;</span>:<span style="color:#e6db74">&#34;Reachable from the upload handler&#34;</span>,<span style="color:#f92672">&#34;action_statement&#34;</span>:<span style="color:#e6db74">&#34;Upgrade git to 2.45.1&#34;</span>,
</span></span><span style="display:flex;"><span> <span style="color:#f92672">&#34;action_statement_timestamp&#34;</span>:<span style="color:#e6db74">&#34;2026-11-20T08:00:00Z&#34;</span>}
</span></span></code></pre></div><p>Output after <code>json.Unmarshal</code> and <code>json.Marshal</code>:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-json" data-lang="json"><span style="display:flex;"><span>{<span style="color:#f92672">&#34;vulnerability&#34;</span>:{<span style="color:#f92672">&#34;name&#34;</span>:<span style="color:#e6db74">&#34;CVE-2024-32002&#34;</span>},<span style="color:#f92672">&#34;timestamp&#34;</span>:<span style="color:#e6db74">&#34;2026-11-01T10:00:00Z&#34;</span>,<span style="color:#f92672">&#34;last_updated&#34;</span>:<span style="color:#e6db74">&#34;2026-11-20T08:00:00Z&#34;</span>,<span style="color:#f92672">&#34;products&#34;</span>:[{<span style="color:#f92672">&#34;@id&#34;</span>:<span style="color:#e6db74">&#34;pkg:oci/app@sha256:abc&#34;</span>}],<span style="color:#f92672">&#34;status&#34;</span>:<span style="color:#e6db74">&#34;affected&#34;</span>,<span style="color:#f92672">&#34;status_notes&#34;</span>:<span style="color:#e6db74">&#34;Reachable from the upload handler&#34;</span>,<span style="color:#f92672">&#34;action_statement&#34;</span>:<span style="color:#e6db74">&#34;Upgrade git to 2.45.1&#34;</span>,<span style="color:#f92672">&#34;action_statement_timestamp&#34;</span>:<span style="color:#e6db74">&#34;2026-11-20T08:00:00Z&#34;</span>}
</span></span></code></pre></div><p><code>version</code> and <code>supplier</code> are gone. Any tool that loads a document through go-vex and writes it back, including <code>vexctl add</code> and <code>vexctl merge</code>, will do the same. If your process uses statement <code>version</code> as a change counter, keep that history somewhere go-vex does not touch, such as the document <code>version</code> (which go-vex does keep) or your Git history.</p>
<p>The spec and schema also disagree slightly here: the spec says statement <code>version</code> defaults to zero, while the schema sets <code>minimum: 1</code>. A statement with an explicit <code>&quot;version&quot;: 0</code> fails schema validation.</p>
<p>The openvex/go-vex main branch has an unreleased validator (commit 42a83ee, November 19, 2026) whose field table carries the same warning for both fields: &ldquo;go-vex does not decode it; it is dropped when the document is rewritten.&rdquo; The vexctl main branch already wires it into a <code>vexctl validate</code> command; the latest vexctl release, v0.4.4, does not include it.</p>
<h2 id="action_statement-required-by-the-spec-not-checked-by-trivy">action_statement: required by the spec, not checked by Trivy</h2>
<p>The spec says an <code>affected</code> statement &ldquo;MUST include a statement that SHOULD describe actions to remediate or mitigate the vulnerability,&rdquo; and the JSON schema makes <code>action_statement</code> required when <code>status</code> is <code>affected</code>. go-vex enforces this in <code>Statement.Validate()</code>:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-go" data-lang="go"><span style="display:flex;"><span><span style="color:#75715e">// action statement is now required
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span><span style="color:#66d9ef">if</span> <span style="color:#a6e22e">v</span> <span style="color:#f92672">:=</span> <span style="color:#a6e22e">stmt</span>.<span style="color:#a6e22e">ActionStatement</span>; <span style="color:#a6e22e">v</span> <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;&#34;</span> {
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> <span style="color:#a6e22e">fmt</span>.<span style="color:#a6e22e">Errorf</span>(<span style="color:#e6db74">&#34;action statement must be set when using status %q&#34;</span>, <span style="color:#a6e22e">s</span>)
</span></span><span style="display:flex;"><span>}
</span></span></code></pre></div><p>Trivy never calls it. Its <code>decodeOpenVEX</code> in <a href="https://github.com/aquasecurity/trivy/blob/v0.76.2/pkg/vex/document.go"><code>pkg/vex/document.go</code></a> runs <code>json.NewDecoder(r).Decode(&amp;openVEX)</code> and only checks that <code>@context</code> is not empty. go-vex&rsquo;s own <code>Parse</code> also just unmarshals. A non-conforming <code>affected</code> statement loads without complaint, and since Trivy does not suppress <code>affected</code> findings, the scan output looks identical either way.</p>
<p>On the producer side, vexctl (v0.4.4 and main) sets the <code>--action-statement</code> flag&rsquo;s default to the go-vex constant <code>NoActionStatementMsg</code>, which is the string <code>&quot;No action statement provided&quot;</code>. An <code>affected</code> statement created without <code>-a</code> therefore passes validation with a placeholder that tells a reader nothing. Search your VEX files for that string before publishing them.</p>
<h2 id="a-pre-publish-check-you-can-run">A pre-publish check you can run</h2>
<p>The script below flags the cases above. It is plain Python 3 with no dependencies; we ran it with Python 3 against the sample document that follows. It checks fields, not purl matching, so pair it with schema validation.</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e">#!/usr/bin/env python3</span>
</span></span><span style="display:flex;"><span><span style="color:#e6db74">&#34;&#34;&#34;Flag OpenVEX v0.2.0 statement fields that Trivy v0.76.2 / go-vex v0.2.9 will not act on.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> json<span style="color:#f92672">,</span> sys
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> datetime <span style="color:#f92672">import</span> datetime
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">ts</span>(v):
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> datetime<span style="color:#f92672">.</span>fromisoformat(v<span style="color:#f92672">.</span>replace(<span style="color:#e6db74">&#34;Z&#34;</span>, <span style="color:#e6db74">&#34;+00:00&#34;</span>)) <span style="color:#66d9ef">if</span> v <span style="color:#66d9ef">else</span> <span style="color:#66d9ef">None</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>doc <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>load(open(sys<span style="color:#f92672">.</span>argv[<span style="color:#ae81ff">1</span>]))
</span></span><span style="display:flex;"><span>doc_ts <span style="color:#f92672">=</span> doc<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;timestamp&#34;</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">for</span> i, s <span style="color:#f92672">in</span> enumerate(doc<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;statements&#34;</span>, [])):
</span></span><span style="display:flex;"><span>    where <span style="color:#f92672">=</span> <span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;statements[</span><span style="color:#e6db74">{</span>i<span style="color:#e6db74">}</span><span style="color:#e6db74">] </span><span style="color:#e6db74">{</span>s<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#39;vulnerability&#39;</span>, {})<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#39;name&#39;</span>)<span style="color:#e6db74">}</span><span style="color:#e6db74"> </span><span style="color:#e6db74">{</span>s<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#39;status&#39;</span>)<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>
</span></span><span style="display:flex;"><span>    st <span style="color:#f92672">=</span> s<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;status&#34;</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> <span style="color:#e6db74">&#34;version&#34;</span> <span style="color:#f92672">in</span> s:
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;</span><span style="color:#e6db74">{</span>where<span style="color:#e6db74">}</span><span style="color:#e6db74">: statement &#39;version&#39; is dropped when go-vex tools rewrite the file&#34;</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> <span style="color:#e6db74">&#34;supplier&#34;</span> <span style="color:#f92672">in</span> s:
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;</span><span style="color:#e6db74">{</span>where<span style="color:#e6db74">}</span><span style="color:#e6db74">: statement &#39;supplier&#39; is dropped when go-vex tools rewrite the file&#34;</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> st <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;affected&#34;</span> <span style="color:#f92672">and</span> <span style="color:#f92672">not</span> s<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;action_statement&#34;</span>):
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;</span><span style="color:#e6db74">{</span>where<span style="color:#e6db74">}</span><span style="color:#e6db74">: affected without action_statement (spec MUST; Trivy loads it anyway)&#34;</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> st <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;affected&#34;</span> <span style="color:#f92672">and</span> s<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;action_statement&#34;</span>) <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;No action statement provided&#34;</span>:
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;</span><span style="color:#e6db74">{</span>where<span style="color:#e6db74">}</span><span style="color:#e6db74">: action_statement is the vexctl placeholder&#34;</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> st <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;not_affected&#34;</span> <span style="color:#f92672">and</span> <span style="color:#f92672">not</span> s<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;justification&#34;</span>):
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;</span><span style="color:#e6db74">{</span>where<span style="color:#e6db74">}</span><span style="color:#e6db74">: not_affected with impact_statement only; Trivy reports an empty Statement&#34;</span>)
</span></span><span style="display:flex;"><span>    eff <span style="color:#f92672">=</span> ts(s<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;timestamp&#34;</span>) <span style="color:#f92672">or</span> doc_ts)
</span></span><span style="display:flex;"><span>    lu <span style="color:#f92672">=</span> ts(s<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;last_updated&#34;</span>))
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> lu <span style="color:#f92672">and</span> eff <span style="color:#f92672">and</span> lu <span style="color:#f92672">&gt;</span> eff:
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;</span><span style="color:#e6db74">{</span>where<span style="color:#e6db74">}</span><span style="color:#e6db74">: last_updated </span><span style="color:#e6db74">{</span>s[<span style="color:#e6db74">&#39;last_updated&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> is newer than the timestamp used for ordering (</span><span style="color:#e6db74">{</span>eff<span style="color:#f92672">.</span>isoformat()<span style="color:#e6db74">}</span><span style="color:#e6db74">)&#34;</span>)
</span></span></code></pre></div><p>Sample document (illustrative names and digest). The author edited the second statement on November 19, bumping <code>last_updated</code> and <code>version</code>, and expects <code>not_affected</code> to win:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-json" data-lang="json"><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;@context&#34;</span>: <span style="color:#e6db74">&#34;https://openvex.dev/ns/v0.2.0&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;@id&#34;</span>: <span style="color:#e6db74">&#34;https://example.com/vex/app-2026-11-20&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;author&#34;</span>: <span style="color:#e6db74">&#34;Example Corp Product Security&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;timestamp&#34;</span>: <span style="color:#e6db74">&#34;2026-11-20T08:00:00Z&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;version&#34;</span>: <span style="color:#ae81ff">3</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;statements&#34;</span>: [
</span></span><span style="display:flex;"><span>    {
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;vulnerability&#34;</span>: {<span style="color:#f92672">&#34;name&#34;</span>: <span style="color:#e6db74">&#34;CVE-2024-32002&#34;</span>},
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;products&#34;</span>: [{<span style="color:#f92672">&#34;@id&#34;</span>: <span style="color:#e6db74">&#34;pkg:oci/app@sha256:abc&#34;</span>}],
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;status&#34;</span>: <span style="color:#e6db74">&#34;affected&#34;</span>,
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;timestamp&#34;</span>: <span style="color:#e6db74">&#34;2026-11-01T10:00:00Z&#34;</span>,
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;action_statement&#34;</span>: <span style="color:#e6db74">&#34;No action statement provided&#34;</span>
</span></span><span style="display:flex;"><span>    },
</span></span><span style="display:flex;"><span>    {
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;version&#34;</span>: <span style="color:#ae81ff">2</span>,
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;vulnerability&#34;</span>: {<span style="color:#f92672">&#34;name&#34;</span>: <span style="color:#e6db74">&#34;CVE-2024-32002&#34;</span>},
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;products&#34;</span>: [{<span style="color:#f92672">&#34;@id&#34;</span>: <span style="color:#e6db74">&#34;pkg:oci/app@sha256:abc&#34;</span>}],
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;status&#34;</span>: <span style="color:#e6db74">&#34;not_affected&#34;</span>,
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;timestamp&#34;</span>: <span style="color:#e6db74">&#34;2026-10-15T10:00:00Z&#34;</span>,
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;last_updated&#34;</span>: <span style="color:#e6db74">&#34;2026-11-19T12:00:00Z&#34;</span>,
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;impact_statement&#34;</span>: <span style="color:#e6db74">&#34;The vulnerable clone path is never called&#34;</span>
</span></span><span style="display:flex;"><span>    }
</span></span><span style="display:flex;"><span>  ]
</span></span><span style="display:flex;"><span>}
</span></span></code></pre></div><p>Output:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>statements[0] CVE-2024-32002 affected: action_statement is the vexctl placeholder
</span></span><span style="display:flex;"><span>statements[1] CVE-2024-32002 not_affected: statement &#39;version&#39; is dropped when go-vex tools rewrite the file
</span></span><span style="display:flex;"><span>statements[1] CVE-2024-32002 not_affected: not_affected with impact_statement only; Trivy reports an empty Statement
</span></span><span style="display:flex;"><span>statements[1] CVE-2024-32002 not_affected: last_updated 2026-11-19T12:00:00Z is newer than the timestamp used for ordering (2026-10-15T10:00:00+00:00)
</span></span></code></pre></div><p>By go-vex&rsquo;s sort, the <code>affected</code> statement (timestamp November 1) is newer than the <code>not_affected</code> one (October 15), so Trivy keeps reporting the CVE. The fix is a new <code>not_affected</code> statement with a current timestamp and a <code>justification</code> label, not an edit to the old one.</p>
<h2 id="what-to-do">What to do</h2>
<ul>
<li><strong>Supersede, do not edit.</strong> Add a new statement with a newer <code>timestamp</code> for every status change. Treat <code>last_updated</code> as a note for humans.</li>
<li><strong>Always set <code>justification</code> on <code>not_affected</code>.</strong> Use <code>impact_statement</code> as extra detail, not as the only explanation, if a scanner report is what auditors see.</li>
<li><strong>Write real action statements.</strong> Reject <code>&quot;No action statement provided&quot;</code> in CI. Trivy will not use the text, but customers and your own triage queue will.</li>
<li><strong>Keep statement <code>version</code> and <code>supplier</code> out of go-vex round trips,</strong> or accept that they will be lost. Put supplier data on the product or subcomponent purl instead.</li>
<li><strong>Validate against the schema in CI.</strong> Neither Trivy nor go-vex&rsquo;s <code>Parse</code> will reject a non-conforming file for you. The <code>openvex_json_schema.json</code> file catches the missing <code>action_statement</code> and a statement <code>version</code> of 0.</li>
</ul>
<p>VEX is one input to the patch decision, alongside KEV, EPSS and SSVC. Our <a href="/posts/vulnerability-prioritization-workflow-cve-record-to-patch-ticket/">vulnerability prioritization workflow</a> shows where a <code>not_affected</code> statement should close a ticket, and where it should not.</p>
<h2 id="limits-of-this-article">Limits of this article</h2>
<p>This describes Trivy v0.76.2 and go-vex v0.2.9 as of November 20, 2026, read from source; we did not run Trivy itself. Other consumers (Grype, Docker Scout, vendor platforms) may read <code>status_notes</code> or <code>action_statement</code>, or sort on different fields. The go-vex validator and <code>vexctl validate</code> mentioned above are unreleased and may change before a tagged release. The Go round-trip test used a copy of go-vex&rsquo;s struct definition, not the library itself.</p>
<h2 id="sources-and-verification">Sources and verification</h2>
<table>
  <thead>
      <tr>
          <th>Important claim</th>
          <th>Source</th>
          <th>Status</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>Statement field list, MUST/MAY wording, timestamp inheritance, update example</td>
          <td><a href="https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md">OpenVEX spec v0.2.0</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td><code>action_statement</code> required for <code>affected</code>; statement <code>version</code> minimum 1</td>
          <td><a href="https://github.com/openvex/spec/blob/main/openvex_json_schema.json">openvex_json_schema.json</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>Statement struct fields; <code>SortStatements</code> compares timestamps only; <code>Validate()</code> rules</td>
          <td><a href="https://github.com/openvex/go-vex/blob/v0.2.9/pkg/vex/statement.go">go-vex v0.2.9 statement.go</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>Trivy takes the last matching statement, suppresses only <code>not_affected</code>/<code>fixed</code>, passes <code>justification</code> as Statement</td>
          <td><a href="https://github.com/aquasecurity/trivy/blob/v0.76.2/pkg/vex/openvex.go">Trivy v0.76.2 openvex.go</a>, <a href="https://github.com/aquasecurity/trivy/blob/v0.76.2/pkg/types/finding.go">finding.go</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>Trivy decodes OpenVEX without validation; pins go-vex v0.2.9</td>
          <td><a href="https://github.com/aquasecurity/trivy/blob/v0.76.2/pkg/vex/document.go">Trivy v0.76.2 document.go</a>, <a href="https://github.com/aquasecurity/trivy/blob/v0.76.2/go.mod">go.mod</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>vexctl&rsquo;s default action statement placeholder</td>
          <td><a href="https://github.com/openvex/vexctl/blob/v0.4.4/internal/cmd/options.go">vexctl options.go</a>, <a href="https://github.com/openvex/go-vex/blob/v0.2.9/pkg/vex/vex.go">go-vex vex.go</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>Unreleased validator warns that statement <code>version</code> and <code>supplier</code> are dropped</td>
          <td><a href="https://github.com/openvex/go-vex/blob/main/pkg/validate/schema.go">go-vex main pkg/validate/schema.go</a></td>
          <td>Qualified (unreleased)</td>
      </tr>
      <tr>
          <td><code>version</code> and <code>supplier</code> dropped on a JSON round trip</td>
          <td>Our Go 1.24.7 test with a copy of the go-vex struct</td>
          <td>Verified (reproduction, not the library)</td>
      </tr>
  </tbody>
</table>
]]></content:encoded></item><item><title>vexctl: Create, Add, Merge and Attest OpenVEX Documents</title><link>https://firewallsync.com/posts/vexctl-create-add-merge-attest-openvex-documents/</link><guid>https://firewallsync.com/posts/vexctl-create-add-merge-attest-openvex-documents/</guid><pubDate>Thu, 12 Nov 2026 04:40:00 +0000</pubDate><dc:creator>Craig Leslie</dc:creator><category>AppSec &amp; APIs</category><description>A source-checked guide to vexctl v0.4.4: the create, add, merge and attest commands, the validation rules they enforce, why merge keeps every statement instead of resolving them, and the defaults that quietly produce weak VEX documents.</description><enclosure url="https://firewallsync.com/posts/vexctl-create-add-merge-attest-openvex-documents/cover_hu12264946083305802858.jpg" type="image/jpeg" length="0"/><media:content url="https://firewallsync.com/posts/vexctl-create-add-merge-attest-openvex-documents/cover_hu12264946083305802858.jpg" medium="image" type="image/jpeg" width="1200" height="630"/><content:encoded><![CDATA[<p><img src="https://firewallsync.com/posts/vexctl-create-add-merge-attest-openvex-documents/cover_hu12264946083305802858.jpg" alt="Tall stacks of paper documents and green and brown file folders with yellow-edged pages on an office desk under ceiling lights" width="1200" height="630"></p><p><code>vexctl</code> is the OpenVEX project&rsquo;s own tool for writing VEX (Vulnerability Exploitability eXchange) documents: <code>create</code> starts a document, <code>add</code> appends a statement and bumps the version, <code>merge</code> combines documents into one timeline, and <code>attest</code> wraps a document in an in-toto attestation you can sign and attach to an image. The commands are short. The defaults behind them are where weak VEX comes from: an anonymous author, a placeholder action statement, and a merge that resolves nothing.</p>
<p>This guide reads the <a href="https://github.com/openvex/vexctl/tree/v0.4.4">vexctl v0.4.4 source</a> (the newest tag on November 12, 2026, committed June 16, 2026) and the <a href="https://github.com/openvex/go-vex/tree/v0.2.8">go-vex v0.2.8</a> library it builds on. It fills the gap left by our <a href="/posts/trivy-vex-oci-openvex-attestations-cosign-attest/">Trivy <code>--vex oci</code> guide</a>: Trivy consumes VEX but does not write it. If you need the basics of what a statement asserts, start with <a href="/posts/vex-explained-what-a-not-affected-statement-means-and-how-to-read-one/">what a not_affected statement means</a>.</p>
<h2 id="install-and-version-check">Install and version check</h2>
<p>The <a href="https://github.com/openvex/vexctl/blob/v0.4.4/README.md">README</a> gives two install routes:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>go install github.com/openvex/vexctl@latest   <span style="color:#75715e"># or pin: @v0.4.4</span>
</span></span><span style="display:flex;"><span>brew install vexctl
</span></span></code></pre></div><p>v0.4.4&rsquo;s <code>go.mod</code> requires Go 1.26.4, <code>github.com/openvex/go-vex v0.2.8</code> and <code>github.com/sigstore/cosign/v2 v2.6.3</code>. Pin the version in CI: the behaviour below is read from that tag, and a few help texts in it are out of step with the code (covered under merge).</p>
<h2 id="vexctl-create-one-statement-new-document">vexctl create: one statement, new document</h2>
<p><code>create</code> takes positional arguments or flags (<code>create [flags] [product_id [vuln_id [status]]]</code>):</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>vexctl create <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  --author<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;Example Corp PSIRT &lt;psirt@example.com&gt;&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  --product<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;pkg:oci/api-gateway@sha256:&lt;digest&gt;?repository_url=registry.example.com/team&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  --vuln<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;CVE-2026-12345&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  --status<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;not_affected&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  --justification<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;vulnerable_code_not_in_execute_path&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  --impact-statement<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;The parser that contains the flaw is never loaded by this image.&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  --file<span style="color:#f92672">=</span>api-gateway.vex.json
</span></span></code></pre></div><p><em>Illustrative: the command and flag names are taken from the v0.4.4 source; we did not run the binary for this article.</em></p>
<p>The flags that shape the statement, from <code>internal/cmd/options.go</code>:</p>
<table>
  <thead>
      <tr>
          <th>Flag</th>
          <th>Short</th>
          <th>Default</th>
          <th>Notes</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><code>--product</code></td>
          <td><code>-p</code></td>
          <td>none</td>
          <td>Repeatable. At least one is required. A purl or other IRI.</td>
      </tr>
      <tr>
          <td><code>--vuln</code></td>
          <td><code>-v</code></td>
          <td>none</td>
          <td>Required.</td>
      </tr>
      <tr>
          <td><code>--status</code></td>
          <td><code>-s</code></td>
          <td>none</td>
          <td><code>not_affected</code>, <code>affected</code>, <code>fixed</code> or <code>under_investigation</code>.</td>
      </tr>
      <tr>
          <td><code>--justification</code></td>
          <td><code>-j</code></td>
          <td>none</td>
          <td>Only allowed with <code>not_affected</code>. <code>vexctl list</code> prints the valid labels.</td>
      </tr>
      <tr>
          <td><code>--impact-statement</code></td>
          <td></td>
          <td>none</td>
          <td>Only allowed with <code>not_affected</code>.</td>
      </tr>
      <tr>
          <td><code>--action-statement</code></td>
          <td><code>-a</code></td>
          <td><code>No action statement provided</code></td>
          <td>Only kept when status is <code>affected</code>.</td>
      </tr>
      <tr>
          <td><code>--status-note</code></td>
          <td></td>
          <td>none</td>
          <td>How the status was determined.</td>
      </tr>
      <tr>
          <td><code>--aliases</code></td>
          <td></td>
          <td>none</td>
          <td>Other IDs (GHSA, GO-&hellip;). Duplicates, or an alias equal to <code>--vuln</code>, are rejected.</td>
      </tr>
      <tr>
          <td><code>--subcomponents</code></td>
          <td></td>
          <td>none</td>
          <td>Rejected when more than one <code>--product</code> is given.</td>
      </tr>
      <tr>
          <td><code>--author</code></td>
          <td></td>
          <td><code>Unknown Author</code></td>
          <td>Document author.</td>
      </tr>
      <tr>
          <td><code>--author-role</code></td>
          <td></td>
          <td>empty</td>
          <td>Optional.</td>
      </tr>
      <tr>
          <td><code>--id</code></td>
          <td></td>
          <td>generated</td>
          <td>Generated from the document&rsquo;s canonical hash when omitted.</td>
      </tr>
      <tr>
          <td><code>--file</code></td>
          <td></td>
          <td>stdout</td>
          <td>Output path.</td>
      </tr>
  </tbody>
</table>
<p>Two validation layers apply. vexctl&rsquo;s own checks (above) run first; then go-vex&rsquo;s statement validator enforces the <a href="https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md">OpenVEX spec</a> rules: a <code>not_affected</code> statement needs a <code>justification</code> or an <code>impact_statement</code>, and an <code>affected</code> statement needs an <code>action_statement</code>. The spec words them as MUSTs: &ldquo;For statements conveying a <code>not_affected</code> status, a VEX statement MUST include either a status justification or an impact_statement&rdquo;, and &ldquo;For a statement with &lsquo;affected&rsquo; status, a VEX statement MUST include a statement that SHOULD describe actions to remediate or mitigate the vulnerability.&rdquo;</p>
<h3 id="two-defaults-to-override-every-time">Two defaults to override every time</h3>
<p><strong>The author.</strong> go-vex sets <code>DefaultAuthor = &quot;Unknown Author&quot;</code>, and vexctl&rsquo;s validator only rejects a <em>blank</em> author, so the placeholder passes. The spec says <code>author</code> &ldquo;MUST be an individual or organization&rdquo;. A consumer that weighs VEX by issuer cannot trust an anonymous statement, so pass <code>--author</code> on <code>create</code>, <code>add</code> and <code>merge</code>.</p>
<p><strong>The action statement.</strong> The <code>-a</code> flag defaults to <code>No action statement provided</code>. For an <code>affected</code> statement that default fills the required field, so the validator is satisfied and the document carries no remediation advice. Write the real action (upgrade target, configuration change, compensating control) every time.</p>
<h3 id="reproducible-timestamps">Reproducible timestamps</h3>
<p><code>create</code> and <code>add</code> honour <code>SOURCE_DATE_EPOCH</code>; the help text says it may be &ldquo;formatted in UNIX time or RFC3339&rdquo;. Set it in release pipelines so a rebuilt document gets the same timestamp and, with the default ID, the same <code>@id</code>. go-vex serializes statement timestamps in UTC.</p>
<h2 id="vexctl-add-append-and-bump-the-version">vexctl add: append and bump the version</h2>
<p>The spec says a document&rsquo;s <code>version</code> &ldquo;must be incremented when any content within the VEX document changes&rdquo;. <code>add</code> does that for you:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>vexctl add --in-place api-gateway.vex.json <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  <span style="color:#e6db74">&#34;pkg:oci/api-gateway@sha256:&lt;digest&gt;?repository_url=registry.example.com/team&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  CVE-2026-23456 under_investigation
</span></span></code></pre></div><p><em>Illustrative.</em> Per <code>internal/cmd/add.go</code>, <code>add</code>:</p>
<ul>
<li>reads the document from the first positional argument or <code>-d/--document</code>, and writes to stdout unless you pass <code>-i/--in-place</code> or <code>--file</code>;</li>
<li>copies the document&rsquo;s <code>last_updated</code> (or <code>timestamp</code>) into any statement that has no timestamp of its own, so those statements keep their inherited date once the document changes;</li>
<li>refuses the new statement if any existing statement&rsquo;s <code>timestamp</code> or <code>last_updated</code> is later than the new time (&ldquo;date cannot be older than other statements&rdquo;);</li>
<li>appends the statement, sets the document&rsquo;s <code>last_updated</code> and increments <code>version</code>.</li>
</ul>
<p>The time check matters with <code>SOURCE_DATE_EPOCH</code>: an epoch older than the newest statement makes <code>add</code> fail rather than write an out-of-order history.</p>
<h2 id="vexctl-merge-a-timeline-not-a-verdict">vexctl merge: a timeline, not a verdict</h2>
<p><code>merge</code> exists for the case the README describes, &ldquo;when more than one stakeholder is issuing VEX metadata about a piece of software&rdquo;:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>vexctl merge --author<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;Example Corp PSIRT&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  --product<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;pkg:apk/wolfi/bash@1.0.0&#34;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span><span style="color:#ae81ff"></span>  examples/openvex/document1.vex.json examples/openvex/document2.vex.json &gt; merged.vex.json
</span></span></code></pre></div><p>What it does, from <code>Merge()</code> in <code>pkg/ctl/implementation.go</code>:</p>
<ol>
<li><strong>Filters, optionally.</strong> With <code>--product</code> and/or <code>--vuln</code>, only matching statements are kept. Product matching is go-vex&rsquo;s, which compares purls rather than plain strings.</li>
<li><strong>Fills timestamps.</strong> A statement without a timestamp takes its source document&rsquo;s timestamp. If both are missing, merge fails: &ldquo;unable to cascade timestamp from doc to timeless statement&rdquo;.</li>
<li><strong>Keeps everything.</strong> Every matching statement is copied. There is no deduplication and no conflict resolution.</li>
<li><strong>Sorts.</strong> Statements are sorted by vulnerability name (string order), then by timestamp, oldest first.</li>
<li><strong>Names the result deterministically.</strong> Without <code>--id</code>, the new <code>@id</code> is <code>merged-vex-</code> plus the SHA-256 of the input documents&rsquo; <code>@id</code> values, sorted and joined with <code>:</code>. A document with no <code>@id</code> contributes <code>VEX-DOC-&lt;position&gt;</code>.</li>
<li><strong>Starts a fresh document.</strong> Version 1, a new timestamp, and <code>Unknown Author</code> unless you pass <code>--author</code>.</li>
</ol>
<p>Who wins? Not merge. go-vex&rsquo;s <code>EffectiveStatement()</code> returns the <em>last</em> matching statement after the same sort, so the newest statement for a product and vulnerability is the current status. That is how the README explains a merged history of <code>under_investigation</code> followed by <code>fixed</code>: tools &ldquo;replay&rdquo; the statements in order.</p>
<p>We ported steps 1 to 5 to Python (product matching simplified to exact strings) and ran the port on the two example documents in the vexctl repository:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>$ python3 -I merge_port.py document2.vex.json document1.vex.json
</span></span><span style="display:flex;"><span>merged-vex-6b33f63783819578804350ba1cde277ddd8f90aa2bbcb706d19a61d211a8443f
</span></span><span style="display:flex;"><span>2023-12-05T05:04:34.77929922Z CVE-1234-5678 under_investigation
</span></span><span style="display:flex;"><span>2023-12-05T05:06:38.099731287Z CVE-1234-5678 fixed
</span></span><span style="display:flex;"><span>effective: fixed
</span></span></code></pre></div><p>Passing the files in the other order produced the same <code>@id</code>, because the IDs are sorted before hashing. That is a property of the port matching the source; treat it as a reading aid, not a test of the vexctl binary.</p>
<h3 id="merge-pitfalls">Merge pitfalls</h3>
<ul>
<li><strong>Clock skew decides conflicts.</strong> Two issuers stating different statuses for the same product rely on their timestamps alone. A supplier&rsquo;s <code>not_affected</code> with a later clock beats your own <code>affected</code>. Merge per issuer, or review conflicts before publishing.</li>
<li><strong>Output is stdout only.</strong> <code>merge</code> registers no <code>--file</code> flag in v0.4.4; redirect the output.</li>
<li><strong>The flag is <code>--vuln</code>.</strong> The command&rsquo;s own help example shows <code>--vulnerability=CVE-2022-3294</code>, but the flag registered in v0.4.4 is <code>--vuln</code> (constant <code>vulnLongFlag = &quot;vuln&quot;</code>). Use <code>--vuln</code>.</li>
<li><strong>Merged documents grow.</strong> History is kept, so a long-lived merged file accumulates every status change. That is by design; prune by publishing a new document rather than editing statements in place.</li>
</ul>
<h2 id="vexctl-attest-wrap-sign-attach">vexctl attest: wrap, sign, attach</h2>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>vexctl attest api-gateway.vex.json                      <span style="color:#75715e"># unsigned in-toto statement to stdout</span>
</span></span><span style="display:flex;"><span>vexctl attest --sign api-gateway.vex.json               <span style="color:#75715e"># sign with the sigstore flow</span>
</span></span><span style="display:flex;"><span>vexctl attest --attach api-gateway.vex.json             <span style="color:#75715e"># sign and attach to each image subject</span>
</span></span><span style="display:flex;"><span>vexctl attest --attach api-gateway.vex.json registry.example.com/team/api-gateway@sha256:&lt;digest&gt;
</span></span></code></pre></div><p><em>Illustrative.</em> From <code>internal/cmd/attest.go</code> and <code>pkg/ctl/ctl.go</code>:</p>
<ul>
<li>The predicate is the OpenVEX document; go-vex sets the predicate type to <code>https://openvex.dev/ns/v0.2.0</code>.</li>
<li>Without positional image arguments, subjects come from the document&rsquo;s products. <code>pkg:oci</code> purls become image references (the help text&rsquo;s example: <code>pkg:oci/kube-apiserver?repository_url=registry.k8s.io&amp;tag=v1.26.0</code> becomes <code>registry.k8s.io/kube-apiserver:v1.26.0</code>), and references without a digest &ldquo;will trigger a network lookup to read the image digest from the registry&rdquo;.</li>
<li>Products that are neither oci purls nor image references are kept only if they carry <code>sha256</code> or <code>sha512</code> hashes. Otherwise they are skipped with a warning, or rejected with an error if you named them explicitly.</li>
<li><code>--attach</code> (<code>-a</code>) &ldquo;always implies &ndash;sign as sigstore does not support attaching unsigned attestations&rdquo;. <code>--refs</code> (<code>-r</code>) names the images to attach to when automatic attachment fails.</li>
</ul>
<p>If your scanner reads the attestation from the registry, check the predicate type it accepts. Our <a href="/posts/trivy-vex-oci-openvex-attestations-cosign-attest/">Trivy <code>--vex oci</code> guide</a> covers how Trivy matches OpenVEX predicate types and why you should verify the signature yourself before trusting what it finds.</p>
<h2 id="where-vexctl-fits-in-a-patch-decision-flow">Where vexctl fits in a patch-decision flow</h2>
<p>VEX is the last filter before a finding becomes work: a <code>not_affected</code> statement with a sound justification closes a scanner finding that KEV, EPSS or CVSS would otherwise push up the queue. Our <a href="/posts/vulnerability-prioritization-workflow-cve-record-to-patch-ticket/">vulnerability prioritization workflow</a> shows where that step sits between the CVE record and the ticket. Product IDs are where most VEX fails in practice, so check the matching rules in our <a href="/posts/openvex-products-subcomponents-purl-matching-trivy/">OpenVEX products and subcomponents guide</a> before you publish, and see the <a href="/posts/cyclonedx-vex-analysis-state-justification-openvex-csaf-mapping/">CycloneDX VEX mapping</a> if your consumers expect CycloneDX.</p>
<p>Two more commands exist and are out of scope here: <code>vexctl filter</code> applies VEX to SARIF results (the README says &ldquo;We support results files in SARIF for now&rdquo;), and <code>vexctl generate</code> builds documents from &ldquo;golden&rdquo; template files (default directory <code>.openvex/templates</code>).</p>
<h2 id="limits-of-this-article">Limits of this article</h2>
<ul>
<li>We read the v0.4.4 source and README; we did not run the vexctl binary. Commands are marked illustrative. The merge output comes from a Python port of the merge and sort logic, not from vexctl.</li>
<li>Behaviour may change after v0.4.4. Re-check flags with <code>vexctl &lt;command&gt; --help</code> against the version you install.</li>
<li>vexctl writes OpenVEX only. CSAF and CycloneDX VEX producers follow their own formats.</li>
</ul>
<h2 id="sources-and-verification">Sources and verification</h2>
<table>
  <thead>
      <tr>
          <th>Important claim</th>
          <th>Source</th>
          <th>Status</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>v0.4.4 is the newest tag; dependency versions</td>
          <td><a href="https://github.com/openvex/vexctl/blob/v0.4.4/go.mod">vexctl v0.4.4 go.mod</a>, git tags</td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>Flags, defaults and validation rules</td>
          <td><a href="https://github.com/openvex/vexctl/blob/v0.4.4/internal/cmd/options.go">internal/cmd/options.go</a>, <a href="https://github.com/openvex/go-vex/blob/v0.2.8/pkg/vex/vex.go">go-vex vex.go</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>add version bump and time checks</td>
          <td><a href="https://github.com/openvex/vexctl/blob/v0.4.4/internal/cmd/add.go">internal/cmd/add.go</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>Merge filters, keeps, sorts and hashes IDs</td>
          <td><a href="https://github.com/openvex/vexctl/blob/v0.4.4/pkg/ctl/implementation.go">pkg/ctl/implementation.go</a>, <a href="https://github.com/openvex/go-vex/blob/v0.2.8/pkg/vex/statement.go">go-vex statement.go</a></td>
          <td>Verified (source); example run via Python port</td>
      </tr>
      <tr>
          <td>Latest statement is the effective one</td>
          <td><a href="https://github.com/openvex/go-vex/blob/v0.2.8/pkg/vex/vex.go">go-vex vex.go EffectiveStatement</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>Attest predicate type and subject rules</td>
          <td><a href="https://github.com/openvex/vexctl/blob/v0.4.4/internal/cmd/attest.go">internal/cmd/attest.go</a>, <a href="https://github.com/openvex/vexctl/blob/v0.4.4/pkg/ctl/ctl.go">pkg/ctl/ctl.go</a>, <a href="https://github.com/openvex/go-vex/tree/v0.2.8/pkg/attestation">go-vex attestation</a></td>
          <td>Verified</td>
      </tr>
      <tr>
          <td>Spec MUSTs for author, version, justification, action statement</td>
          <td><a href="https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md">OpenVEX specification</a></td>
          <td>Verified</td>
      </tr>
  </tbody>
</table>
]]></content:encoded></item></channel></rss>