Documentation updates

harimohanr · Jan 19, 2024 · a1978cd · a1978cd
1 parent a045cbc
commit a1978cd
Show file tree

Hide file tree

Showing 7 changed files with 343 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -1,23 +1,28 @@
-# BeS-schema
-"BeS open source projects of interest(OSSPoI), open source vulnerabilities of interest( OSSVoI ), BeS open source models of Interest (OSMoI) , BeS Environments , BeS Playbooks , Open source Assessment Report (OSAR) and BeS Exploit & Attack Simuation (EAS) Interchange formats for BeSLabs & BeSLighthouse."
-
-# Open Source Software Projects of Interest (OSSPoI)
-
-# Open Source Software Vulnerabilities of Interest ( OSSVoI )
-
-# Open Source Models of Interest (OSMoI) 
-
-# Open Source Assessment Report (OSAR)
-
-# Exploit & Attack Simuation (EAS)
-
-# BeS Environment Info & Status
-
-# BeS Playbook Info & Status
-
-# Bes Lab Info & Status
-
-# BeS Lab Attestation History & Record
+# BeS-Schema
+This repository defines the data exchage schema for various assets and its features in Be-Secure. 
+
+Key Be-Secure assets are ..
+- Open source projects of interest(OSSPoI)
+- Open source vulnerabilities of interest( OSSVoI)
+- Open source models of Interest (OSMoI)
+
+Key features of assets are ..
+- BeS Environments
+- BeS Playbooks
+- Open source Assessment Report (OSAR)
+- BeS Exploit & Attack Simuation (EAS)
+- BeSLabs
+
+# Schema Definitions
+- Open Source Software Projects of Interest (OSSPoI)
+- Open Source Software Vulnerabilities of Interest (OSSVoI)
+- Open Source Models of Interest (OSMoI) 
+- Open Source Assessment Report (OSAR)
+- Exploit & Attack Simuation (EAS)
+- BeS Environment Info & Status
+- BeS Playbook Info & Status
+- BeS Lab Info & Status
+- BeS Lab Attestation History & Record
 
 
 

diff --git a/.gitignore → docs/.gitignore b/.gitignore → docs/.gitignore
diff --git a/docs/assessment-report-schema.md b/docs/assessment-report-schema.md
@@ -37,36 +37,39 @@ The exact details of each field are elaborated in the next section. All strings
 contain UTF-8 text.
 
 A JSON Schema for validation is also available
-[here](https://github.com/Be-Secure/bes-schema/blob/main/validation/assessment-report-schema.json).
+[here](https://github.com/Be-Secure/bes-schema/blob/main/validation/assessment-report-schema-validator.json).
 
 ```json
 {
     "schema_version": string,
     "asset": {
         "type": string,
         "name": string,
-        "url": string
+        "url": string,
+        "environment": string
     },
     "assessments": [
         {
             "tool": {
                 "name": string,
                 "type": string,
                 "version": string,
-                "playbook": string
+                "playbook": string,
+                "detailedReport": string
             },
             "execution": {
                 "type": string,
                 "id": string,
                 "status": string,
                 "timestamp": timestamp,
-                "url": string
+                "timeTaken": string
             },
-            "result": [
+            "results": [
                 {
-                    "type": string,
+                    "feature": string,
+                    "aspect": string,
                     "attribute": string,
-                    "value": string
+                    "value": number
                 }
             ]
         }
@@ -99,7 +102,7 @@ versions of the schema only add new fields, without changing the meaning of old
 fields, so that a client that knows how to read version 1.2.0 can process data
 identifying as schema version 1.3.0 by ignoring any unexpected fields.
 
-## open source asset attributes
+## asset field
 
 ```json
 "asset": {
@@ -109,47 +112,154 @@ identifying as schema version 1.3.0 by ignoring any unexpected fields.
 }
 ```
 
-Description goes here
+Details about the open source asset that was assessed.
 
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>type</code></td>
+      <td>
+        Project / Model
+      </td>
+    </tr>
+    <tr>
+      <td><code>name</code></td>
+      <td>
+        Name of the project or model that was assessed
+      </td>
+    </tr>
+        <tr>
+      <td><code>url</code></td>
+      <td>
+        Project source code URL or the ML model card URL
+      </td>
+    </tr>
+  </tbody>
+</table>
 
-## assessment tool attributes
+## assessments.tool field
 
 ```json
 "tool": {
     "name": string,
     "type": string,
     "version": string,
-    "playbook": string
+    "playbook": string,
+    "detailedReport": string
 }
 ```
 
-Description goes here
+Details about the tool used for assessment. "assessments" is an array and it should contain all the assessments done on a particular asset. For instance, a typical open source assessment in Be-Secure comprises of SAST, Fuzzing, SCA, OpenSSF Criticality Score & ScoreCard and License compliance checks. All the assessments metadata should be contained in this array.
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>name</code></td>
+      <td>
+        Name of the tool used for this assessment. For SAST type assessment CodeQL is an example tool name 
+      </td>
+    </tr>
+    <tr>
+      <td><code>type</code></td>
+      <td>
+        SAST / Fuzzing / License Compliance / Criticality Score / SBOM
+      </td>
+    </tr>
+    <tr>
+      <td><code>version</code></td>
+      <td>
+        Tool version
+      </td>
+    </tr>
+    <tr>
+      <td><code>playbook</code></td>
+      <td>
+        Assessment tool playbook name
+      </td>
+    </tr>
+  </tbody>
+</table>
 
-## Assessment playbook execution attributes
+## assessments.execution field
 
 ```json
 "execution": {
     "type": string,
     "id": string,
     "status": string,
     "timestamp": timestamp,
-    "url": string
+    "timeTaken": string
 }
 ```
 
-Description goes here
+Assessment tool execution metadata. 
+
+<table>
+  <thead>
+    <tr>
+      <th>Field</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>type</code></td>
+      <td>
+        Is this assessment tool execution done by an Organization / Individual
+      </td>
+    </tr>
+    <tr>
+      <td><code>id</code></td>
+      <td>
+        Organization Id or the Individual's id (It could be a GitHub id of the individual). An example for organization is Be-Secure
+      </td>
+    </tr>
+    <tr>
+      <td><code>status</code></td>
+      <td>
+        Success / Failure
+      </td>
+    </tr>
+    <tr>
+      <td><code>timestamp</code></td>
+      <td>
+        Date and time of assessment tool execution
+      </td>
+    </tr>
+    <tr>
+      <td><code>timeTaken</code></td>
+      <td>
+        Total time taken in seconds to complete the assessment tool execution
+      </td>
+    </tr>
+  </tbody>
+</table>
 
-## Assessment playbook execution attributes
+## assessments.results array
 
 ```json
-"result": [
+"results": [
     {
-        "type": string,
+        "feature": string,
+        "aspect": string,
         "attribute": string,
-        "value": string
+        "value": number
     }
 ]
 ```
+Summary of assessment tool execution results. Individual tool execution results should be translated to this format to accomodate the summary of result. 
 
 <table>
   <thead>
@@ -160,18 +270,54 @@ Description goes here
   </thead>
   <tbody>
     <tr>
-      <td><code>A</code></td>
+      <td><code>feature</code></td>
       <td>
-        Description goes here
+        Vulnerability / Code Smell / Criticality Score / ScoreCard / License Compliance / Dependency
       </td>
     </tr>
     <tr>
-      <td><code>A</code></td>
+      <td><code>aspect</code></td>
       <td>
-        Description goes here
+        Severity / Count / Score
+      </td>
+    </tr>
+    <tr>
+      <td><code>attribute</code></td>
+      <td>
+        Depends on the tool feature and the aspect. For instance, in SAST the aspect may be "Severity"and the attribute will be "Critical"
+      </td>
+    </tr>
+    <tr>
+      <td><code>value</code></td>
+      <td>
+        The summary count or value
       </td>
     </tr>
   </tbody>
 </table>
 
-Description goes here
+For instance, a SAST tool execution result may give 10 vulnerability information and 50 code smells of various severity along with the file name and the exact line numbers. For this schema, the result summary should be abstracted as below.
+
+```json
+"results": [
+    {
+        "feature": "Vulnerability",
+        "aspect": "Severity",
+        "attribute": "Critical",
+        "value": 6
+    },
+    {
+        "feature": "Vulnerability",
+        "aspect": "Severity",
+        "attribute": "Medium",
+        "value": 4
+    },
+    {
+        "feature": "Code Smell",
+        "aspect": "Severity",
+        "attribute": "Low",
+        "value": 50
+    }
+]
+```
+
diff --git a/docs/index.md b/docs/index.md
@@ -3,4 +3,33 @@ layout: home
 nav_order: 1
 ---
 
-# BeSecure Schema
+### Be-Secure Schema Definitions
+
+An easy-to-use data format that maps precisely to various data exchange needs between cybersecurity analysts and security labs. These schema definitions address many of the shortcomings of dealing with vulnerabilities in open source software and ML models in Be-Secure ecosystem.
+
+These unified format means that vulnerability databases, open source users, and security researchers can easily share tooling and consume vulnerabilities across all of open source. This means a more complete view of vulnerabilities in open source for everyone, as well as faster detection and remediation times resulting from easier automation.
+
+Key Be-Secure assets these schema definitions cater to are as below.
+- Open source projects of interest(OSSPoI)
+- Open source vulnerabilities of interest( OSSVoI)
+- Open source models of Interest (OSMoI)
+
+Key tooling Be-Secure offers..
+- BeS Environments
+- BeS Playbooks
+- BeS Assessments
+- BeS Exploit & Attack Simuation (EAS)
+- BeSLabs
+
+# Schema Definitions
+- Open Source Software Projects of Interest (OSSPoI)
+- Open Source Software Vulnerabilities of Interest (OSSVoI)
+- Open Source Models of Interest (OSMoI) 
+- Open Source Assessment Report (OSAR)
+- Exploit & Attack Simuation (EAS)
+- BeS Environment Info & Status
+- BeS Playbook Info & Status
+- BeS Lab Info & Status
+- BeS Lab Attestation History & Record
+
+
diff --git a/docs/moi-schema.md b/docs/moi-schema.md
@@ -1,6 +1,6 @@
 ---
 layout: page
-title: Vulnerabilities Of Interest
+title: Models Of Interest
 permalink: /models-of-interest/
 nav_order: 4
 ---

diff --git a/validation/README.md b/validation/README.md
@@ -0,0 +1,10 @@
+# JSON Validator
+
+This directory contains the JSON schemas to validate various BeS entries.
+
+## Usage
+
+```
+$ pip install check-jsonschema
+$ check-jsonschema --schemafile assessment-report-schema-validator.json assessment_report_to_test.json
+```