Update README to openvex org and latest features

Signed-off-by: Adolfo García Veytia (Puerco) <[email protected]>

README.md

@@ -1,36 +1,131 @@
 # vexctl: A tool to make VEX work
 
-`vexctl` is a tool to apply and attest VEX (Vulnerability Exploitability eXchange)
-data. Its purpose is to "turn off" alerts of vulnerabilities known not to affect
-a product.
+`vexctl` is a tool to create, apply and attest VEX (Vulnerability Exploitability
+eXchange) data. Its purpose is to help with the creation and management of
+VEX documents that allow "turning off" security scanner alerts of vulnerabilities
+known  not to affect a product.
 
 VEX can be though as a "negative security advisory". Using VEX, software authors
 can communicate to their users that a vulnerable component has no security
 implications for their product.
 
 ## Operational Model
 
-To achieve its mission, `vexctl` has two main modes of operation. One
-helps the user create VEX statements, the second applies the VEX data
-to scanner results.
+To achieve its mission, `vexctl` has three main modes of operation:
+
+1. Create VEX documents
+2. Wrapping VEX documents in signed attestations
+2. Applying the VEX data to scanner results
 
 ### 1. Create VEX Statements
 
+#### Creating New VEX Documents
+
 VEX data can be created to a file on disk or it can be captured in a
 signed attestation which can be attached to a container image.
 
+The easiest way to create a VEX document is using the `vexctl create` command:
+
+```
+vex ctl create --product="pkg:apk/wolfi/[email protected]?arch=x86_64" \
+               --vuln="CVE-2023-12345" \
+               --status="not_affected" \
+               --justification="inline_mitigations_already_exist"
+```
+
+
+The previous invocations creates a vex document with a single statment asserting
+that the WolfiOS package `git-2.38.1-r0` is not affected by CVE-2023-12345 because
+it has already been mitigated in the distribution.
+
+This is the resulting document:
+
+```json
+{
+  "@context": "https://openvex.dev/ns",
+  "@id": "https://openvex.dev/docs/public/vex-cfaef18d38537412a0307ec266bed56aa88fa58b7c1f2c6b8c9ef997028ba4bd",
+  "author": "Unknown Author",
+  "role": "Document Creator",
+  "timestamp": "2023-01-10T20:24:50.498233798-06:00",
+  "version": "1",
+  "statements": [
+    {
+      "vulnerability": "CVE-2023-12345",
+      "products": [
+        "pkg:apk/wolfi/[email protected]?arch=x86_64"
+      ],
+      "status": "not_affected",
+      "justification": "component_not_present"
+    }
+  ]
+}
+
+```
+
+vexctl can create VEX documents from three different sources:
+
+1. From the command line, as shown
+2. From a _golden file_ of predefined rules
+3. From merging other vex documents into a new one
+
 The data is generated from a known rule set (the Golden Data) which is
 reused and reapplied to new releases of the same project.
 
-#### Generation Examples
+#### Merging Existing Documents
+
+When more than one stake holder is issuing VEX metadata about a piece of software,
+vexctl can merge the documents to get the most up-to-date impact assessment of
+a vulnerability. The following example can be run using the test documents found
+in this repository:
+
+```
+vexctl merge --product=pkg:apk/wolfi/[email protected] \
+             pkg/ctl/testdata/document1.vex.json \
+             pkg/ctl/testdata/document2.vex.json
+```
+The resulting document combines the VEX statements that express data about
+`[email protected]` into a single document that tells the whole story of how CVE-1234-5678
+was `under_investigation` and then `fixed` four hours later:
+
+```json
+{
+  "@context": "https://openvex.dev/ns",
+  "@id": "https://openvex.dev/docs/public/merged-vex-67124ea942ef30e1f42f3f2bf405fbbc4f5a56e6e87684fc5cd957212fa3e025",
+  "author": "Unknown Author",
+  "role": "Document Creator",
+  "timestamp": "2023-01-10T20:36:55.524170935-06:00",
+  "version": "1",
+  "statements": [
+    {
+      "vulnerability": "CVE-1234-5678",
+      "timestamp": "2022-12-22T16:36:43-05:00",
+      "products": [
+        "pkg:apk/wolfi/[email protected]"
+      ],
+      "status": "under_investigation"
+    },
+    {
+      "vulnerability": "CVE-1234-5678",
+      "timestamp": "2022-12-22T20:56:05-05:00",
+      "products": [
+        "pkg:apk/wolfi/[email protected]"
+      ],
+      "status": "affected"
+    }
+  ]
+}
+
+```
+
+#### 2. Attesting Examples
 
 ```
 # Attest and attach vex statements in mydata.vex.json to a container image:
 vexctl attest --attach --sign mydata.vex.json cgr.dev/image@sha256:e4cf37d568d195b4..
 
 ```
 
-### 2. VEXing a Results Set
+### 3. VEXing a Results Set
 
 Using statements in a VEX document or from an attestation, `vexctl` will filter
 security scanner results to remove _vexed out_ entries.
@@ -91,14 +186,14 @@ will be filtered out.
 
 ## Build vexctl
 
-To build `vexctl` clone this repository and run simply run make.
+To build `vexctl`, clone this repository and run simply run make.
 
 ```console
-git clone [email protected]:chainguard-dev/vex.git
+git clone [email protected]:openvex/vexctl
 cd vex
 make
 
-./vexctl version
+/vexctl version
  _   _  _____ __   __ _____  _____  _
 | | | ||  ___|\ \ / //  __ \|_   _|| |
 | | | || |__   \ V / | /  \/  | |  | |
@@ -107,11 +202,11 @@ make
  \___/ \____/ \/   \/ \____/  \_/  \_____/
 vexctl: A tool for working with VEX data
 
-GitVersion:    devel
-GitCommit:     unknown
-GitTreeState:  unknown
-BuildDate:     unknown
-GoVersion:     go1.19
+GitVersion:    v0.1.0-6-gf32c652-dirty
+GitCommit:     f32c65225aa93f03c6bd84af5dec9294c9b8ed3a
+GitTreeState:  dirty
+BuildDate:     2023-01-11T02:11:56Z
+GoVersion:     go1.19.4
 Compiler:      gc
 Platform:      linux/amd64
 ```