cmd/lava: document report output format

cmd/lava/internal/help/helpdoc.go

@@ -200,22 +200,23 @@ example.
 	      },
 	      "severity": "medium",
 	      "shown": false,
-	      "excluded": false,
-	      "rule": {
-	        "target": "",
-	        "resource": "",
-	        "fingerprint": "",
-	        "summary": "",
-	        "expiration": "0001-01-01T00:00:00Z",
-	        "description": ""
+	      "excluded": true,
+	      "exclusion_rule": {
+	        "resource": "path/testdata/(goodpath|vulnpath)/Dockerfile",
+	        "description": "Ignore test targets."
 	      }
-	    }
+	    },
+	    ...
 	  ],
 	  "summary": {
 	    "count": {
-	      "medium": 1
+	      "critical": 1,
+	      "high": 6,
+	      "medium": 2,
+	      "low": 8,
+	      "info": 4
 	    },
-	    "excluded": 0
+	    "excluded": 1
 	  },
 	  "status": [
 	    {
@@ -261,8 +262,8 @@ it was included in the report generated by Lava.
   - shown: whether the vulnerability is shown in the report.
   - excluded: whether the vulnerability is excluded from the generated
     report because of an exclusion rule.
-  - rule: in the case of an excluded finding, which is the matching
-    exclusion rule.
+  - exclusion_rule: in the case of an excluded finding, this is the
+    matching exclusion rule.
 
 # check_data
 
@@ -572,3 +573,101 @@ A Lava metrics file contains the following data:
     severity.
 	`,
 }
+
+// HelpReport documents the report file format.
+var HelpReport = &base.Command{
+	UsageLine: "report",
+	Short:     "report file format",
+	Long: `
+After a security scan has finished, Lava generates a report that
+includes the detected findings, a summary of the issues and an
+overview of the exit status of the executed checks. Lava supports
+multiple output formats: human-readable and JSON.
+
+For more details on how to configure the output format, use "lava help
+lava.yaml" and "lava help run".
+
+# JSON
+
+The JSON output format is a JSON document as shown in the following
+example.
+
+	{
+	  "vulnerabilities": [
+	    {
+	      "id": "58cf04ac-8a5c-48c8-b999-8f83f1d6f185",
+	      "summary": "Vulnerability title",
+	      "score": 6.9,
+	      "affected_resource": "golang.org/x/net:0.19.0",
+	      "affected_resource_string": "",
+	      "fingerprint": "51b4b93663ed7c4d97ad5d9f1f29df109a2b7d272963d0b25d1ae9d387a44d29",
+	      "cwe_id": 937,
+	      "description": "Vulnerability description.",
+	      "details": "Details generated when running the checktype against the target.",
+	      "impact_details": "Details about the impact of the vulnerability.",
+	      "labels": [
+	        "label1",
+	        "label2"
+	      ],
+	      "recommendations": [
+	        "Recommendation to fix the issue."
+	      ],
+	      "references": [
+	        "https://example.org"
+	      ],
+	      "resources": [
+	        {
+	          "Name": "Resource name",
+	          "Header": [
+	            "header1",
+	            "header2"
+	          ],
+	          "Rows": [
+	            {
+	              "header1": "value2",
+	              "header2": "value1"
+	            }
+	          ]
+	        }
+	      ],
+	      "attachments": [
+	        {
+	          "name": "Attachment name",
+	          "content_type": "image/png",
+	          "data": "YmFzZTY0LWVuY29kZWQgZGF0YQ=="
+	        }
+	      ],
+	      "vulnerabilities": null,
+	      "check_data": {
+	        "check_id": "d9a8d860-0fa9-4caa-ae0b-139b81acc94c",
+	        "checktype_name": "vulcansec/vulcan-example",
+	        "checktype_version": "edge",
+	        "status": "FINISHED",
+	        "target": ".",
+	        "options": "{\"option1\":\"value1\"}",
+	        "tag": "",
+	        "start_time": "2024-07-25T18:26:03Z",
+	        "end_time": "2024-07-25T18:26:07Z"
+	      },
+	      "severity": "medium"
+	    }
+	  ],
+	  "summary": {
+	    "count": {
+	      "medium": 1
+	    },
+	    "excluded": 0
+	  },
+	  "status": [
+	    {
+	      "checktype": "vulcansec/vulcan-example",
+	      "target": ".",
+	      "status": "FINISHED"
+	    }
+	  ]
+	}
+
+This output format is a subset of the full report file format. For
+more details about the included data, use "lava help fullreport".
+	`,
+}

cmd/lava/main.go

@@ -34,6 +34,7 @@ func init() {
 		help.HelpFullReport,
 		help.HelpLavaYAML,
 		help.HelpMetrics,
+		help.HelpReport,
 	}
 }