How do you translate vexctl CLI documentation without changing vulnerability identifiers, OpenVEX status meanings, package URLs or signed security assertions? This guide explains vexctl localization for technical translators, security analysts and software maintainers working across languages. It covers how to write readable command instructions while preserving every executable token and distinguishing a vulnerability finding from a justified statement about whether a particular product is affected.
Vulnerability Exploitability eXchange, or VEX, is not another scanner. It communicates an assessment about a named vulnerability in a named product. The open-source vexctl command-line tool can create and merge OpenVEX documents, attach signed statements to container images and filter supported SARIF scanner results. A translator must make those operations understandable without suggesting that a status label itself proves safety, that a package identifier is free text, or that an attestation automatically supplies trustworthy evidence.
Start with an accurate mental model: a scanner identifies a possible issue; a security investigation determines its practical impact; an OpenVEX statement records the outcome; and the consuming system decides how to use it. This tutorial provides non-production examples, realistic incident scenarios, terminology decisions, Unicode and right-to-left checks, a detailed editorial review method and questions that help writers preserve human understanding and machine meaning together.
At a glance: how to localize VEX safely
- Identify the product and exact version before interpreting a vulnerability status.
- Keep command names, option flags, CVE IDs, package URLs, JSON keys, status enums and digests unchanged.
- Translate explanatory prose, not machine tokens or shell syntax.
- Read create, merge, attest and filter as distinct actions with different responsibilities.
- Preserve the evidence behind every not_affected or fixed conclusion.
- Test UTF-8, right-to-left rendering, copy-paste behavior and parser compatibility.
- Retain raw scanner evidence when a VEX statement filters a report.
Understanding vexctl, OpenVEX and technical translation
1. What vexctl actually does
vexctl is a command-line utility from the OpenVEX project. It produces, combines, signs and applies structured VEX metadata. Those actions are connected, but they are not equivalent. Creating a document records the author’s assessment; attaching it makes the statement available with an artifact; filtering a report consumes already-issued metadata. A localized heading must identify the action, not replace all of them with the vague verb ‘scan’.
A reader seeking a scanner expects detection and coverage guarantees. Here the central problem is attribution and assessment, not discovery. Explain that vulnerability scanners can flag a library version even when the affected code path is unreachable in one deployed product. The assessment must still be supported by evidence; the fact that vexctl can encode a reason does not establish that the reason is true.
In review, ask someone to put four verbs—discover, investigate, attest and filter—in chronological order. If the translation makes the utility appear to perform the investigation automatically, revise it. Keep the executable spelling vexctl unchanged, including lower-case letters.
2. VEX versus CVE versus SBOM
A CVE identifier names a publicly tracked vulnerability. A software bill of materials inventories components. A VEX statement evaluates the relationship between a vulnerability and a particular product. These objects answer different questions and should not be collapsed into a single target-language word for ‘security report’. A vulnerable package in an inventory is not automatically proof of exploitation.
Take an SBOM that lists an embedded image library. The scanner flags a CVE against an affected version. The manufacturer investigates whether its application invokes the vulnerable parser. A VEX statement may say the product is not affected under a specific justification. Translating that into ‘the library has no vulnerability’ would falsely universalize a product-scoped finding.
Ask a reviewer to identify the subject of every statement: which product, which vulnerability and what conclusion? In captions and tables, keep the relation explicit. A CVE value is an identifier rather than translatable prose; retain its punctuation, prefix and digits exactly.
3. A product identifier is an address, not a label
OpenVEX statements can refer to products through package URLs or other identifiers. A package URL has syntax, including a package type, namespace, name, version and optional qualifiers. These fields must survive translation byte for byte unless the software owner is intentionally creating a new target with an approved identifier.
For example, pkg:apk/wolfi/git@2.38.1-r0?arch=x86_64 is not an English sentence. Translating wolfi, replacing an underscore with a space or normalizing the dash inside the version could point the statement at a different or invalid product. Give the human explanation beside the value, never inside it.
Reviewers should compare each identifier against the original using machine equality and a visual inspection for lookalike Unicode. Particularly check slashes, colons, question marks, at signs, ampersands and percent-encoded values. Do not let a translation memory segment these values into ordinary words.
4. Preserve vulnerability identifiers literally
A value such as CVE-2026-12345 is a precise key. It is not a number to reformat according to local digit grouping conventions, nor a headline to paraphrase. The prefix CVE, separator hyphens and sequence belong to the identity of the vulnerability. A correct local-language sentence may explain what CVE means, but never rewrites the identifier.
A help article might say ‘select the applicable CVE’. The phrase around the token can be translated freely. However, a right-to-left page that uses local numerals in an embedded code sample can create an apparently similar string that fails in a script or search index. Keep all actual keys in a left-to-right code container.
In a practical review, copy and paste each printed identifier into a plain-text diff and compare it with the source. Do not rely solely on screen appearance. If a document invents placeholder CVE values, label them as examples and never suggest they are verified live advisories.
5. The four principal status outcomes
The widely used OpenVEX statuses distinguish affected, not_affected, fixed and under_investigation. They communicate materially different judgments. An affected statement means the product is known to be impacted; not_affected says the identified vulnerability does not affect that product; fixed means an affected condition has been remediated; under_investigation says the assessment remains unresolved.
Do not translate not_affected into ‘no risk anywhere’, fixed into ‘the scanner deleted the finding’, or under_investigation into ‘safe to deploy’. Keep the machine enum values untouched in JSON and command flags while explaining them in the local language. In end-user prose, ‘investigation ongoing’ is more faithful than a phrase implying a confirmed defect.
One useful test is to show four incident snapshots to a bilingual reviewer and ask which deployments they would allow. If the translation produces the same operational decision for all four statuses, the distinctions have been lost. Record the intended meaning separately from the exact machine spelling.
6. Justification is not a free-form excuse
A not_affected statement often needs a structured justification. A justification identifies the technical basis, for example that the affected code is absent, not reachable or mitigated. Its precise enum spelling depends on the supported format and version, so authors should verify the installed tool’s help and documentation instead of inventing a near-synonym.
When a case explains ‘vulnerable code not in execute path’, the phrase must be interpreted carefully. It is not a claim that the source package was never installed. It means that, for the assessed product configuration, the vulnerable functionality is not executed. A change in feature flags or runtime integration could invalidate the assessment.
In localization QA, separate two columns: exact enum and human explanation. Translate only the explanatory column. Ask engineers to confirm the supporting evidence and scope; translators cannot supply technical proof by improving the wording. Where an investigation is unfinished, say so instead of completing the story.
7. Using vexctl create safely
The documented create command constructs an OpenVEX statement from explicit properties such as product, vulnerability, status and justification. A tutorial can introduce the shape with vexctl create –help, then display a clearly fictional example. Creating the file is not a live scan and does not validate the truth of an assessor’s claim.
An example command can use a demonstration package URL and a fictitious vulnerability identifier, with a note that the resulting VEX represents a hypothetical assessment only. Do not insert real customer product names, private registry addresses or internal vulnerability ticket numbers into a public lesson. For a classroom, show how altering the product identifier changes the scope.
Command reviewers need to distinguish shell quoting from natural-language quotation marks. Smart quotes, translated option names and inserted line breaks can make a carefully written example fail. Keep flags such as –product, –vuln and –status exactly as the tool expects; use the surrounding narrative for localization.
8. Understanding the OpenVEX JSON shape
A VEX document contains document metadata and statements. Each statement connects a vulnerability, one or more products and a status; supporting details may include justification, impact language and timing. In a rendered guide, explain the hierarchy before enumerating every field so readers know why a statement is nested rather than flat.
The JSON key @context identifies a vocabulary, while @id identifies the document or object. Translate neither key. Similarly, statements, vulnerability, products, status and timestamp are machine field names, not editable display labels inside the payload. A local-language walkthrough can annotate these keys outside the code block or in a separate table.
The strongest test is to parse the localized code sample as JSON, then compare key names and non-translatable values to the original. Visual formatting can change outside the object; changing a property name to a translated equivalent cannot. Treat escaping, UTF-8 encoding and quotation marks as data-quality requirements.
9. Status updates over time
VEX is particularly useful because product impact assessments evolve. A team may first acknowledge a possible vulnerability under investigation, later discover the product is affected and finally issue an updated statement after remediation. The correct story is a timeline with evidence, not a single permanent label pulled out of context.
The vexctl merge workflow can combine several documents for a selected product so readers see a more current assessment. The repository documentation illustrates how an early status can be superseded by a later one. A translation must not silently reverse dates, drop timezone offsets or call the latest document universally authoritative without checking its issuer and scope.
When editing a chronology, keep each status tied to its documented timestamp and product. Create a timeline in plain language, then verify it against the JSON. If two issuers disagree, represent that disagreement instead of inventing a resolution. Provenance matters as much as recency.
10. Merging documents is not averaging opinions
A merge operation is a structured combination of VEX statements. It is not a consensus algorithm deciding which security specialist is correct. The examples in the project documentation show how a changing status can be represented, yet trust still depends on who issued each statement and whether it applies to the artifact in question.
Suppose two teams publish assessments for adjacent versions of an application. Combining documents without preserving the exact product versions could make a fixed claim appear to cover a version that has not received the patch. The translation should explain how to select the product explicitly and inspect the resulting statements.
Use a side-by-side case: version 2.0 is affected, version 2.1 is fixed. Ask readers which identifier each sentence names. If a translated summary says only ‘the application is fixed’ without version or release context, it is too broad for a reliable security decision.
11. Read the difference between an image and a digest
A container image may be named by a mutable tag or by an immutable content digest. An example using image:latest does not guarantee the same bytes over time, whereas a digest such as sha256:… identifies particular content. Attaching a VEX assertion to the wrong target can create a serious interpretive error.
A public tutorial should teach readers to ask whether a statement concerns an image release, an embedded package, or a particular digest. The relationship is not always obvious from the displayed repository name. The language around a sample must make the scope visible, especially when support teams copy examples into incident notes.
Check colons, slashes, algorithm prefixes and hex characters in image references. Never translate registry hostnames or alter digest bytes. Use fabricated but syntactically illustrative examples with clearly shortened values, and explain that shortened values are not executable references.
12. Attestations mean signed claims, not guaranteed truth
vexctl can wrap statements as signed attestations and attach them to supported container registries. Signing gives consumers mechanisms to check origin and integrity under appropriate verification policies. It does not, by itself, independently establish that the vulnerability assessment was correct, complete or still current.
Imagine a supplier signing a statement that a product is not affected. The consumer may verify the signature and still need to evaluate whether the supplier examined the correct version and vulnerable function. A localized introduction should not say ‘cryptographically proven safe’. A more precise account is that the statement was signed by an identity whose trust must be assessed.
Have security reviewers mark separately the signer, referenced product, vulnerability, status, supporting evidence and verification outcome. If any element is missing, the publication should not imply end-to-end assurance. The words certified, verified and trusted are not interchangeable.
13. DSSE and Sigstore bundles
The project documents signing and output formats such as Sigstore bundles and DSSE envelopes. DSSE is a structured wrapper for signed statements; a bundle can carry material required for verification. These are packaging and evidence concepts, not translated prose containers in which every string becomes a local-language string.
A tutorial may describe –format dsse as a version-sensitive option, then link to the maintained project instructions for the exact installed release. Avoid mixing a command’s input VEX document with its output attestation in the same sentence. They have different verification paths, storage behavior and intended consumers.
Keep DSSE, Sigstore, JSON and OCI as technical identifiers in command examples. Translate their definitions on first use. A bilingual reviewer should be able to answer which file contains the original assessment and which file contains signed evidence about that assessment.
14. OCI referrers versus legacy attachment
Signed VEX attestations can be associated with container images through OCI referrer mechanisms, while the documentation also describes legacy attachment layouts for compatibility with older systems. A localized explanation should tell readers that the same statement can be distributed through different storage conventions without claiming they are universally interchangeable.
An example referring to an image digest and the –attach-method legacy flag must explain why a compatibility mode exists. If the system fetching attestations does not support the expected attachment convention, the assertion may be present in a registry but invisible to that client. This is a retrieval problem, not necessarily proof that the producer failed to publish.
For release documentation, state the expected registry capability, tool version and consumption method. Do not translate –attach-method, DSSE or att into new option syntax. In a multilingual runbook, give operational owners one clearly labeled lookup path per environment.
15. The place of SARIF scanner results
The documented vexctl filter mode can consume supported SARIF scanner results and apply VEX information to suppress findings covered by appropriate statements. SARIF is a standardized static-analysis result format, and the project’s documentation identifies SARIF as the current supported input in its examples. Other scanner-native JSON formats should not be promised without verification.
An analyst might scan an image with Trivy, export SARIF and apply a VEX document. If a finding disappears from the filtered report, the raw scanner evidence still exists and should remain available for audit. Translate the workflow as evidence refinement, not destruction of a vulnerability record.
Review the precise input order in the chosen tool release and test with safe sample files. Keep filenames, extensions and command tokens exact. Explain whether the output is meant for a human dashboard, automated gate or audit archive; readers should know what is hidden and where the original report is retained.
16. Filtering does not repair software
Suppressing a scanner finding is not the same as patching a vulnerable package. A VEX statement may establish that an issue is not applicable in a specific product, but it does not modify code, update dependencies or change runtime behavior. Localization should preserve this distinction even when interface copy uses compact labels like resolved or addressed.
Consider a dashboard with a hundred findings reduced to twenty after VEX filtering. The reduction might reflect well-documented non-applicability, or it could reflect poor statements and bad matching. The team must know which and why. Writing ‘eighty vulnerabilities fixed’ from that number would mislead readers and distort a risk report.
Use two counts in educational examples: raw findings and actionable findings after assessment. Also retain the number of evidence-backed exclusions. The reviewer should confirm that the original alerts remain retrievable and that exception statements expire or are re-evaluated when conditions change.
17. Avoid the myth of universal no-impact
The status not_affected is product-specific and evidence-specific. Even if a dependency carries a CVE, one application may not reach its vulnerable code while a second application does. A statement about the first product does not automatically transfer to the second simply because they share a library name.
A marketing translation that says ‘this CVE can be ignored’ is dangerously broad. Better wording says ‘the named product and version were assessed as not affected, based on the stated justification’. This small change keeps the reader focused on a bounded technical conclusion rather than a sweeping assurance.
During review, circle every generic phrase such as safe, harmless, resolved and no threat. Ask which precise product configuration, release, runtime and time window support it. If the answer cannot be found, qualify the wording or return it for technical clarification.
18. Evidence that makes a justification credible
A useful VEX publication can point to reachability analysis, build configuration, code review, runtime controls or version-scoped tests. The appropriate evidence depends on the vulnerability. The format helps distribute conclusions, but the investigation must live outside the enum. A translator should not substitute confident language for missing engineering work.
For an unused parsing function, evidence could include a code search, call-graph review and focused integration test. For a library embedded in a disabled feature, the product team must know whether customers can enable that feature. These scenarios demand different wording because the grounds for non-applicability differ.
Ask reviewers to separate observations, assumptions and conclusions. Observations come from tests or inspected code; assumptions describe deployment constraints; the conclusion is the VEX status. The translated paragraph should not quietly promote an assumption into a universal fact.
19. The importance of producer identity
An OpenVEX file contains author and document metadata. In a distributed ecosystem, producer identity matters because customers may receive multiple assessments about the same component. The maintainer of a library, the vendor of an appliance and an independent auditor may have different scopes and evidence.
Translating an author field’s descriptive label can help a reader, but changing the identifier inside a serialized document can break validation or alter the recorded source. Never invent a company endorsement. If the public example lists ‘Unknown Author’, explain that real release processes should identify a responsible issuer.
A quality check should verify the signer or document issuer independently of claims inside the file. Where the author is unknown, do not call the statement an official vendor advisory. Maintain the chain between assessment owner, approval record and published file.
20. Time zones, timestamps and incident chronology
OpenVEX metadata may record timestamps with offsets. These dates help consumers understand when an assessment was issued or revised, but a timestamp alone cannot prove that the data is current. Translations can show a reader-friendly local time alongside the source value without changing the actual machine timestamp.
For example, an assessment issued just after midnight in one time zone may still be dated the previous calendar day elsewhere. Converting it carelessly could reverse the apparent order of investigation, patch and release. Keep ISO-style timestamps inside examples and add explanatory local-date notes outside them.
Ask someone to reconstruct the timeline from the raw data after localization. If the story changes, correct the prose. This is particularly important when a product was temporarily affected and later fixed; a consumer must not mistake an old statement for the latest approved position.
21. Translating technical severity with restraint
A VEX status is not a severity score. Security advisories may separately discuss CVSS, exploitability, exposure and business impact. Replacing affected with critical, or not_affected with low severity, conflates different dimensions and can lead to inappropriate remediation priorities.
A vulnerability rated highly severe in its general context may still be not_affected for one product because vulnerable functionality is not present. Conversely, an affected issue may have constrained exposure in a controlled environment. Readers need to see that general severity and product impact are connected but not identical.
In tables, give severity its own column if the source provides it. Do not invent scores from VEX statuses. Translate explanatory labels consistently and preserve any normative scoring values exactly as issued by their owners.
22. Multilingual UI labels and JSON keys
The safest division is between human-facing UI strings and machine-facing tokens. Translate headings, hints, cautionary prose and explanatory table captions. Preserve JSON field names, command options, status enums, package URLs, digest strings and shell operators. This separation holds for languages written left to right and right to left.
A localized documentation page may show a translated heading ‘Under investigation’ above a literal JSON excerpt containing under_investigation. Both are correct in different roles. An inexperienced reviewer may demand that the JSON match the translated heading; that would be a functional regression.
Use distinct typography for display text and code. Maintain code directionality and monospace rendering. Where a paragraph switches scripts around a CVE ID, ensure bidirectional control characters have not been copied into the actual token.
23. Unicode normalization and lookalike characters
International technical documentation must handle accented names, East Asian scripts, combining marks and bidirectional text. A code token can look correct while containing a fullwidth colon, a nonbreaking hyphen or a visually similar Cyrillic letter. These are not cosmetic differences when the token is parsed by software.
A translated sample that changes –status to an em dash followed by a word will fail. Similarly, a CVE identifier with a non-ASCII dash may not match the advisory database. Some JSON string values legitimately contain Unicode, but the surrounding syntax remains fixed.
Review files with UTF-8-aware tools and compare protected tokens bytewise. Test copy-paste from the published page, not only the editor. Explain normalization only where relevant; never bulk-normalize production identifiers without checking their identity rules.
24. Right-to-left and mixed-script documentation
Arabic and Hebrew editions introduce layout challenges because technical tokens are predominantly left-to-right. Slashes, parentheses and quote marks can appear reordered to readers if the page does not isolate code appropriately. The underlying data must remain unchanged even when its visual arrangement is adjusted.
Place command examples in left-to-right code blocks and isolate inline identifiers from surrounding translated text. In a screenshot, ensure the command remains copyable and that an example product URL has not been broken by line wrapping. Translate surrounding direction words such as source and destination carefully.
A bilingual reviewer should copy each example into a terminal or plain-text file to check actual character order. Test both narrow mobile screens and desktop rendering. Avoid adding hidden directional marks inside values that will be executed or used as equality keys.
25. Scanner interoperability and format boundaries
A VEX workflow might involve Trivy, Grype or another scanner, but the exact integration depends on output formats and installed versions. Translators should not imply every scanner has a built-in vexctl option. Instead explain the data handoff: scanner output, documented interchange format, VEX file or attestation and a filtering consumer.
If a user has proprietary scanner JSON instead of SARIF, the described filter command may not accept it directly. A helpful guide shows where to check exporter support and advises preserving the original scanner result before transformation. Avoid promising invisible converters or automatic mapping of every security field.
When writing cross-tool documentation, label which tool produces each file. Differentiate a scanner’s ‘–vex’ capability from the independent vexctl filter operation where relevant. This prevents localized instructions from silently shifting an option to the wrong executable.
26. Example: a false-positive triage review
Picture a development team that receives an alert about a library embedded in a read-only service. A security analyst identifies the vulnerable function and traces whether the product can execute it. The investigation discovers that the function is absent from the compiled build. The team records the product digest and supporting build evidence.
The correct explanatory statement names the assessment scope and says the vulnerability was considered not applicable because the relevant code was not present. It does not claim the upstream library is safe in all settings. If the build later changes, the assessment must be revisited and potentially replaced.
In translation, keep the evidence description specific enough that a downstream consumer knows what was checked. Preserve source names and commit references as identifiers. A reviewer should be able to distinguish this from a case where vulnerable code exists but a mitigating control blocks it.
27. Example: an investigation still open
A new advisory arrives while the team is preparing a release. Initial scanning shows the affected dependency version, but the product owner cannot yet establish whether the vulnerable behavior is reachable. Publishing not_affected would be premature; the honest current status is under_investigation.
A multilingual customer note should state that analysis remains in progress, what interim controls exist and when the next update will be issued if known. Do not fill an information gap with reassurance. The VEX statement can convey uncertainty, while a separate support note can explain customer-facing precautions.
When reviewing this scenario, check whether the translation accidentally uses a completed-tense verb. In some languages, a short label can imply that the investigation has already finished. Prefer explicit time framing so the product team and customer reach the same operational conclusion.
28. Example: patch issued for a release
A team confirms a vulnerability in application release 4.2 and builds release 4.2.1 with a corrected dependency. A VEX record for the first release may remain affected while the updated release can be marked fixed based on the remediation evidence. This is a product-version distinction, not a historical contradiction.
In customer documentation, avoid a statement such as ‘all versions are now fixed’ unless the vendor actually supports it. Keep release identifiers visible in tables, downloadable files and headings. A translation may explain what fixed means, but cannot claim users received the patch automatically.
Ask reviewers whether a reader on the earlier release would know they still need to update. If the answer is no, the communication is not safe enough. The goal is not a reassuring tone; it is a clear decision about which software version to deploy.
29. Example: an attestation is present but identity is wrong
Imagine that a registry returns a signed VEX attestation, but the signer is an unfamiliar testing identity rather than the approved supplier. The signature may be technically valid. That does not make the assertion acceptable under the consumer’s trust policy, because identity and authorization still matter.
An accurate translation distinguishes verification of signature integrity from verification of expected signer identity and approval. The instruction to ‘verify the attestation’ must name the relevant policy or explain where that policy is configured. Otherwise readers can treat any signed statement as sufficient.
For quality assurance, create one classroom case with the expected signer and another with an unrecognized signer. The outcome should differ, even though both signatures may be mathematically sound. Do not translate verification to a broad word that implies independent validation of the underlying risk assessment.
30. Example: a finding disappears after filtering
A security dashboard displays a vulnerability before a VEX filter is applied. After filtering, the alert no longer appears in an actionable view. An analyst should be able to retrieve the original result, the VEX file, the matching identifiers and the justification. That is the audit trail supporting the changed display.
The localized user interface should say something like ‘filtered by applicable VEX assessment’ rather than ‘vulnerability removed from software’. Explain why: the operation changes the presentation of findings, not the contents of the image. A misleading label might cause operations staff to stop patching a genuinely affected system.
A review exercise can ask readers to trace the finding from raw SARIF to the VEX statement and final report. If they cannot identify the product and CVE that justified the exclusion, the documentation has not provided enough information for a repeatable decision.
31. Release handoff between teams
Localization is often one step in a chain involving the developer, security analyst, documentation owner and customer support team. The developer knows the code; the analyst approves the assessment; the writer explains the result; the support team fields questions. Confusing these responsibilities can create false authority.
A translator should be empowered to query unclear status wording, but should not independently choose a VEX justification. Require the technical owner to approve product references, vulnerability identifiers and claims of applicability. Editorial approval does not replace security approval or a signed release process.
For handoff, maintain a compact evidence bundle: original document, localized guide, immutable identifier list, reviewed examples, test results and owner sign-off. This is particularly useful when an urgent advisory must be communicated simultaneously in several languages.
32. Designing an effective learning sequence
Start new readers with the object relationships rather than a long command reference. First show the vulnerability, then the product, then the status and its evidence. Only after this should a lesson introduce create, merge, attest and filter commands. The sequence gives readers a reason to care about each tool operation.
A useful classroom exercise begins with four cards: component, CVE, product and conclusion. Ask students to arrange a valid VEX assertion. Then introduce the corresponding fields in a JSON sample. This gradual approach makes the syntax a representation of a meaningful judgment rather than arbitrary punctuation.
Once readers can explain the model, move on to actual command help and safe local sample files. Do not hand them production registry addresses or private artifacts. Finish with a copy-paste test, an identity check and a question about what the VEX statement does not prove.
Frequently asked questions
Is vexctl itself a vulnerability scanner?
No. It manages VEX information, including creating, merging, attesting and filtering with supported report formats. The vulnerability finding and investigation come from other tools and people. Presenting vexctl as a scanner obscures who generated evidence and who made the impact judgment. Readers should understand the distinction before treating any VEX status as actionable.
Can I translate not_affected inside JSON?
No. In machine-readable examples, retain not_affected exactly. You may translate its meaning in an adjacent label or prose paragraph. The same rule applies to under_investigation, affected and fixed. Treat these strings as protocol values: even a translation that sounds correct to a human can be invalid input for the software.
Does a VEX attestation prove that a product is safe?
No. A signed attestation supplies evidence about who made a structured assertion and whether it was altered, subject to appropriate identity verification. A competent security investigation is still needed to support the assertion. Product scope, date, version and external conditions all remain important. Distinguish integrity of a message from truth of its contents.
What should translators do with CVE IDs and package URLs?
Keep them exact. Do not localize digits, separators, package names, version qualifiers or registry addresses. Give explanatory translations outside the literal tokens. For right-to-left pages, isolate the tokens visually without inserting hidden direction markers into copyable examples. Confirm them using plain-text comparison rather than visual proofreading alone.
What if the VEX file says fixed but a scanner still reports the CVE?
First check that both systems refer to the same product, version and vulnerability. A scanner may assess the package independently of the product’s remediation state, and available metadata may be out of sync. Do not assume either output is wrong without investigation. Keep raw scan results and the exact VEX evidence for review.
Can I run vexctl filter on any security JSON file?
Do not assume that. The project’s published examples focus on SARIF result files, and capabilities can change by release. Read the installed version’s help and confirm the required input format. A translator should label example file types explicitly and avoid extending documented compatibility to tools or formats that have not been verified.
How should a translated guide handle dates?
Preserve timestamps inside machine-readable files. A human-facing edition may show a converted local time, but label the time zone and avoid changing the chronology. Vulnerability status can change across documents, so the date belongs to the meaning of the claim. A date translation that reverses the sequence can make a stale assertion appear current.
What is the safest first exercise?
Use fictional identifiers and local sample files, read vexctl –help, inspect a simple OpenVEX statement and identify product, vulnerability, status and justification. Then explain what additional evidence would be required before publishing a genuine not_affected statement. This teaches semantics without encouraging students to issue unsupported security claims.
A practical final review checklist
Before publication, verify the approved product scope, CVE identifiers, status values, justification, issuer, dates, reference digests, any signing identity requirements, and whether your examples are safe and version-appropriate. Compare every non-translatable token against source, parse the JSON, check command help against the installed release, and read the complete localized explanation aloud to a colleague who was not involved in drafting it. Keep a record of the review, especially when vulnerability statements may change rapidly.
A trustworthy translated security article gives readers clear boundaries: what is known, what remains under investigation, what the tool does, and what evidence an organization must still provide. Excellent localization makes consequential distinctions easier to understand; it does not make the software or its claims magically safer.
Further reading
OpenVEX vexctl project documentation: https://github.com/openvex/vexctl . OpenVEX specification and concepts: https://openvex.dev . For complementary topics, study SBOM generation, vulnerability scanning and signed OCI attestations separately. Command flags and integration behavior can change; verify examples against the version in your environment.