{"id":14155427,"url":"https://github.com/openvex/vexctl","last_synced_at":"2025-08-06T01:31:27.674Z","repository":{"id":65338757,"uuid":"587100966","full_name":"openvex/vexctl","owner":"openvex","description":"A  tool to create, transform and attest VEX metadata","archived":false,"fork":false,"pushed_at":"2024-10-22T02:56:03.000Z","size":1402,"stargazers_count":115,"open_issues_count":10,"forks_count":21,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-10-23T04:19:16.427Z","etag":null,"topics":["go","golang","supply-chain","vex"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openvex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-10T00:38:14.000Z","updated_at":"2024-10-22T02:56:05.000Z","dependencies_parsed_at":"2023-02-12T09:45:53.591Z","dependency_job_id":"b0cad70d-4d43-4c35-a2ee-72a700715a0e","html_url":"https://github.com/openvex/vexctl","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openvex%2Fvexctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openvex%2Fvexctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openvex%2Fvexctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openvex%2Fvexctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openvex","download_url":"https://codeload.github.com/openvex/vexctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228821405,"owners_count":17977166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","supply-chain","vex"],"created_at":"2024-08-17T08:03:07.567Z","updated_at":"2024-12-09T02:31:22.925Z","avatar_url":"https://github.com/openvex.png","language":"Go","funding_links":[],"categories":["golang","Go"],"sub_categories":[],"readme":"# vexctl: A tool to make VEX work\n\n[![Build Status](https://github.com/openvex/vexctl/actions/workflows/ci-build-test.yaml/badge.svg?branch=main)](https://github.com/openvex/vexctl/actions/workflows/ci-build-test.yaml?query=branch%3Amain)\n[![Go Report Card](https://goreportcard.com/badge/github.com/openvex/vexctl)](https://goreportcard.com/report/github.com/openvex/vexctl)\n\n`vexctl` is a tool to create, apply, and attest VEX (Vulnerability Exploitability\neXchange) data. Its purpose is to help with the creation and management of\nVEX documents that allow \"turning off\" security scanner alerts of vulnerabilities\nknown not to affect a product.\n\nVEX can be thought of as a \"negative security advisory\". Using VEX, software authors\ncan communicate to their users that an otherwise vulnerable component has no security\nimplications for their product.\n\n## Installing\n\nIf you have Go 1.16 or later installed, you can run the following to install `vexctl`:\n```console\ngo install github.com/openvex/vexctl@latest\n```\n\nIf you use Homebrew, you can install the latest tagged version of `vexctl` using:\n```console\nbrew install vexctl\n```\n\n## Operational Model\n\nTo achieve its mission, `vexctl` has three main modes of operation:\n\n1. Creating VEX documents\n2. Wrapping VEX documents in signed attestations\n3. Applying the VEX data to scanner results\n\n### 1. Creating VEX Documents\n\n#### Creating New VEX Documents\n\nVEX data can be created to a file on disk, or it can be captured in a\nsigned attestation that can be attached to a container image.\n\nThe easiest way to create a VEX document is using the `vexctl create` command:\n\n```\nvexctl create --product=\"pkg:apk/wolfi/git@2.38.1-r0?arch=x86_64\" \\\n               --vuln=\"CVE-2014-123456\" \\\n               --status=\"not_affected\" \\\n               --justification=\"inline_mitigations_already_exist\"\n```\n\n\nThe previous invocations creates a VEX document with a single statement asserting\nthat the WolfiOS package `git-2.38.1-r0` is not affected by `CVE-2014-123456` because\nit has already been mitigated in the distribution.\n\nThis is the resulting document:\n\n```json\n{\n  \"@context\": \"https://openvex.dev/ns/v0.2.0\",\n  \"@id\": \"https://openvex.dev/docs/public/vex-adc52fe6c8d2ba0feee7f4343f9b40c90e8cdb077817f880a6650502aece82bc\",\n  \"author\": \"Unknown Author\",\n  \"timestamp\": \"2023-10-07T23:32:07.620932-08:00\",\n  \"version\": 1,\n  \"statements\": [\n    {\n      \"vulnerability\": {\n        \"name\": \"CVE-2014-123456\"\n      },\n      \"timestamp\": \"2023-10-07T23:32:07.620932-08:00\",\n      \"products\": [\n        {\n          \"@id\": \"pkg:apk/wolfi/git@2.38.1-r0?arch=x86_64\"\n        }\n      ],\n      \"status\": \"not_affected\",\n      \"justification\": \"inline_mitigations_already_exist\"\n    }\n  ]\n}\n```\n\nvexctl can create VEX documents from three different sources:\n\n1. From the command line, as shown\n2. From a _golden file_ of predefined rules\n3. From merging other VEX documents into a new one\n\nThe data is generated from a known rule set (the Golden Data) which is\nreused and reapplied to new releases of the same project.\n\n#### Merging Existing Documents\n\nWhen more than one stakeholder is issuing VEX metadata about a piece of software,\nvexctl can merge the documents to get the most up-to-date impact assessment of\na vulnerability. The following example can be run using the test documents found\nin this repository:\n\n```\nvexctl merge --product=pkg:apk/wolfi/bash@1.0.0 \\\n             examples/openvex/document1.vex.json \\\n             examples/openvex/document2.vex.json\n```\nThe resulting document combines the VEX statements that express data about\n`bash@1.0.0` into a single document that tells the whole story of how `CVE-2014-123456`\nwas `under_investigation` and then `fixed` four hours later:\n\n```json\n{\n  \"@context\": \"https://openvex.dev/ns/v0.2.0\",\n  \"@id\": \"merged-vex-077a7a26ee6f351b86fba3206d39e1872cb726f955ce18535b2e890cc20a8bf6\",\n  \"author\": \"Unknown Author\",\n  \"timestamp\": \"2023-10-07T23:33:45.966496-08:00\",\n  \"version\": 1,\n  \"statements\": [\n    {\n      \"vulnerability\": {\n        \"name\": \"CVE-1234-5678\"\n      },\n      \"timestamp\": \"2022-12-22T16:36:43-05:00\",\n      \"products\": [\n        {\n          \"@id\": \"pkg:apk/wolfi/bash@1.0.0\"\n        }\n      ],\n      \"status\": \"under_investigation\"\n    },\n    {\n      \"vulnerability\": {\n        \"name\": \"CVE-1234-5678\"\n      },\n      \"timestamp\": \"2022-12-22T20:56:05-05:00\",\n      \"products\": [\n        {\n          \"@id\": \"pkg:apk/wolfi/bash@1.0.0\"\n        }\n      ],\n      \"status\": \"fixed\"\n    }\n  ]\n}\n```\n\n### 2. Attesting Examples\n\n```shell\n# Attest and attach VEX statements in mydata.vex.json to a container image:\nvexctl attest --attach --sign mydata.vex.json cgr.dev/image@sha256:e4cf37d568d195b4..\n```\n\n### 3. VEXing a Results Set\n\nUsing statements in a VEX document or from an attestation, `vexctl` will filter\nsecurity scanner results to remove _VEX'ed out_ entries.\n\n#### Filtering Examples\n\n```shell\n# From a VEX file:\nvexctl filter scan_results.sarif.json vex_data.csaf\n\n# From a stored VEX attestation:\nvexctl filter scan_results.sarif.json cgr.dev/image@sha256:e4cf37d568d195b4b5af4c36a...\n```\n\nThe output from both examples will be the same: the SARIF result data, but\nwithout the vulnerabilities that were stated as not exploitable:\n\n```json\n{\n  \"version\": \"2.1.0\",\n  \"$schema\": \"https://json.schemastore.org/sarif-2.1.0-rtm.5.json\",\n  \"runs\": [\n    {\n      \"tool\": {\n        \"driver\": {\n          \"fullName\": \"Trivy Vulnerability Scanner\",\n          \"informationUri\": \"https://github.com/aquasecurity/trivy\",\n          \"name\": \"Trivy\",\n          \"rules\": [\n\n```\n\nWe support results files in SARIF for now. We plan to add support for the\nproprietary formats of the most popular scanners.\n\n### Multiple VEX Files\n\nAssessing impact is process that takes time. VEX is designed to\ncommunicate with users as time progresses. An example timeline may look like\nthis:\n\n1. A project becomes aware of `CVE-2014-123456`, associated with one of its components.\n2. Developers issue a VEX data file with a status of `under_investigation` to\ninform their users they are aware of the CVE but are checking what impact it has.\n3. After investigation, the developers determine the CVE has no impact\nin their project because the vulnerable function in the component is never executed.\n4. They issue a second VEX document with a status of `not_affected` and using\nthe `vulnerable_code_not_in_execute_path` justification.\n\n`vexctl` will read all the documents in chronological order and \"replay\" the\nknown impacts statuses the order they were found, effectively computing the\n`not_affected` status.\n\nIf a SARIF report is VEX'ed with `vexctl` any entries alerting of `CVE-2014-123456`\nwill be filtered out.\n\n## Build vexctl\n\nTo build `vexctl`, clone this repository and run `make`.\n\n```console\n$ git clone https://github.com/openvex/vexctl.git\n$ cd vex\n$ make\n$ ./vexctl version\n _   _  _____ __   __ _____  _____  _\n| | | ||  ___|\\ \\ / //  __ \\|_   _|| |\n| | | || |__   \\ V / | /  \\/  | |  | |\n| | | ||  __|  /   \\ | |      | |  | |\n\\ \\_/ /| |___ / /^\\ \\| \\__/\\  | |  | |____\n \\___/ \\____/ \\/   \\/ \\____/  \\_/  \\_____/\nvexctl: A tool for working with VEX data\n\nGitVersion:    v0.1.0-21-g769ba3f-dirty\nGitCommit:     769ba3f0c638003b6c5e3c41ae88f4cdc63555ab\nGitTreeState:  dirty\nBuildDate:     2023-01-18T00:19:24Z\nGoVersion:     go1.19.4\nCompiler:      gc\nPlatform:      darwin/arm64\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenvex%2Fvexctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenvex%2Fvexctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenvex%2Fvexctl/lists"}