OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

csaf message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [csaf] Pull request just sent... "lang" changes

Hi Eric,

Am 06.11.18 um 22:27 schrieb Eric Johnson:

Hi CSAF TC,

I've just submitted a pull request to complete my long-overdue changes
to add "lang", and "source_lang" to the CSAF documents, as per
resolution of the TC.
https://github.com/oasis-tcs/csaf/pull/5
approved from my side and submitted a comment to the notes (existed before the changes). 


In addition to whether or not anyone has comments / thoughts about that
pull request, I have another question.

I've been trying to find a tool that will take the JSON schema document,
and generate an easier-to-consume form - either Markdown or HTML seem to
be obvious options. Markdown is, in some ways easier, because the HTML
approaches will pay lots of attention to styling, interaction, etc.,
whereas I am just looking for something that will materialize an easier
to read descriptions of the contents of the schema.

I've found two tools that claim to do jsonschema --> markdown, but they
appear to be failing on specific constructs used in the schema, yielding
unresolved references. I can probably go and debug the conversion, but
figured I'd start by asking my question.

Does someone know of good tools to convert jsonschema to either HTML or
Markdown form?
well json schema in its way of evolving might not be a good substrate for open source tools (sometimes progress seems to stall, sometimes everyone is in a rush ...) but there are tools claiming to support draft-07, but some expect a $id element, other interesting ones liek doca have problems with cyclic structures. 

To me https://github.com/adobe/jsonschema2md worled as in the name
doing your minimal and direct requested transformation json 2 markdown.
It does so by noting loads of unresolved refs but maybe you take a look at the markdown file, as it seems to be readably structured and might 
represent what you are looking for.


Sample of markdown documentation run attached.
PS: I would love to push the CSAF json schema towards SwaggerHub (OASIS is performing a trial currently ...) and I thought I had already kindly nagged for a prototype with CSAF on the list ... 

All the best,
Stefan


Eric.




--
Stefan Hagen
read://shagen.de
talk: eventually

# Vulnerability Report Schema

```
```

Representation of vulnerability information as a JSON document.

| Abstract | Extensible | Status | Identifiable | Custom Properties | Additional Properties | Defined In |
|----------|------------|--------|--------------|-------------------|-----------------------|------------|
| Can be instantiated | Yes | Experimental | No | Forbidden | Permitted | [csaf_json.schema.json](csaf_json.schema.json) |

# Vulnerability Report Properties

| Property | Type | Required | Defined by |
|----------|------|----------|------------|
| [document](#document) | `object` | **Required** | Vulnerability Report (this schema) |
| [product_tree](#product_tree) | complex | Optional | Vulnerability Report (this schema) |
| [vulnerabilities](#vulnerabilities) | reference | Optional | Vulnerability Report (this schema) |
| `*` | any | Additional | this schema *allows* additional properties |

## document


`document`

* is **required**
* type: `object`
* defined in this schema

### document Type


`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `distribution`|  | Optional |
| `notes`|  | Optional |
| `publisher`| object | **Required** |
| `references`|  | Optional |
| `title`|  | **Required** |
| `tracking`| object | **Required** |
| `type`|  | **Required** |



#### distribution

undefined

`distribution`

* is optional
* type: reference

##### distribution Type


* []() â?? `#/definitions/str_option_t`







#### notes

undefined

`notes`

* is optional
* type: reference

##### notes Type


* []() â?? `#/definitions/notes_t`







#### publisher

undefined

`publisher`

* is **required**
* type: `object`

##### publisher Type

Unknown type `object`.

```json
{
  "type": "object",
  "properties": {
    "contact_details": {
      "type": "string"
    },
    "issuing_authority": {
      "type": "string"
    },
    "vendor_id": {
      "type": "string"
    }
  },
  "simpletype": "`object`"
}
```







#### references

undefined

`references`

* is optional
* type: reference

##### references Type


* []() â?? `#/definitions/references_t`







#### title

undefined

`title`

* is **required**
* type: reference

##### title Type


* []() â?? `#/definitions/str_option_t`







#### tracking

undefined

`tracking`

* is **required**
* type: `object`

##### tracking Type

Unknown type `object`.

```json
{
  "type": "object",
  "properties": {
    "current_release_date": {
      "$ref": "#/definitions/date_t"
    },
    "generator": {
      "type": "object",
      "properties": {
        "engine": {
          "type": "string"
        },
        "date": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "identification": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "aliases": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/non_empty_string_t"
          }
        }
      }
    },
    "initial_release_date": {
      "$ref": "#/definitions/date_t"
    },
    "revision_history": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/revision_t"
      }
    },
    "status": {
      "$ref": "#/definitions/status_t"
    },
    "version": {
      "$ref": "#/definitions/version_type_t"
    }
  },
  "simpletype": "`object`"
}
```







#### type

undefined

`type`

* is **required**
* type: reference

##### type Type


* []() â?? `#/definitions/non_empty_string_t`










## product_tree


`product_tree`

* is optional
* type: complex
* defined in this schema

### product_tree Type

Unknown type ``.

```json
{
  "$comment": "Currently only supports branch_t and full_product_name_t children of product_tree",
  "properties": {
    "branch": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/branch_branches_t"
      }
    },
    "full_product_name": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/full_product_name_t"
      }
    }
  },
  "simpletype": "complex"
}
```





## vulnerabilities


`vulnerabilities`

* is optional
* type: reference
* defined in this schema

### vulnerabilities Type


Array type: reference

All items must be of the type:
* []() â?? `#/definitions/vulnerability_t`








# Vulnerability Report Definitions

| Property | Type | Group |
|----------|------|-------|
| [acknowledgments](#acknowledgments) | `object[]` | `#/definitions/vulnerability_t` |
| [branch](#branch) | reference | `#/definitions/branch_branches_t` |
| [cpe](#cpe) | reference | `#/definitions/full_product_name_t` |
| [cve](#cve) | `string` | `#/definitions/vulnerability_t` |
| [cvss_score_sets](#cvss_score_sets) | `object` | `#/definitions/vulnerability_t` |
| [cwe](#cwe) | `object` | `#/definitions/vulnerability_t` |
| [date](#date) | reference | `#/definitions/revision_t` |
| [description](#description) | `string` | `#/definitions/revision_t` |
| [discovery_date](#discovery_date) | reference | `#/definitions/vulnerability_t` |
| [full_product_name](#full_product_name) | reference | `#/definitions/branch_product_t` |
| [id](#id) | `object` | `#/definitions/vulnerability_t` |
| [involvements](#involvements) | `object[]` | `#/definitions/vulnerability_t` |
| [lang](#lang) | `string` | `#/definitions/str_with_lang_t` |
| [name](#name) | `string` | `#/definitions/branch_product_t` |
| [notes](#notes) | reference | `#/definitions/vulnerability_t` |
| [number](#number) | reference | `#/definitions/revision_t` |
| [ordinal](#ordinal) | `integer` | `#/definitions/vulnerability_t` |
| [product_id](#product_id) | reference | `#/definitions/full_product_name_t` |
| [product_status](#product_status) | `object` | `#/definitions/vulnerability_t` |
| [references](#references) | reference | `#/definitions/vulnerability_t` |
| [release_date](#release_date) | reference | `#/definitions/vulnerability_t` |
| [remediations](#remediations) | `object[]` | `#/definitions/vulnerability_t` |
| [text](#text) | reference | `#/definitions/str_with_lang_t` |
| [threats](#threats) | `object[]` | `#/definitions/vulnerability_t` |
| [title](#title) | reference | `#/definitions/vulnerability_t` |
| [type](#type) | reference | `#/definitions/note_t` |
| [url](#url) | `string` | `#/definitions/reference_t` |

## acknowledgments


`acknowledgments`

* is optional
* type: `object[]`
* defined in this schema

### acknowledgments Type


Array type: `object[]`

All items must be of the type:
`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `description`|  | Optional |
| `name`| array | Optional |
| `organization`| array | Optional |
| `urls`| array | Optional |



#### description

undefined

`description`

* is optional
* type: reference

##### description Type


* []() â?? `#/definitions/non_empty_string_t`







#### name

undefined

`name`

* is optional
* type: reference


##### name Type


Array type: reference

All items must be of the type:
* []() â?? `#/definitions/non_empty_string_t`










#### organization

undefined

`organization`

* is optional
* type: reference


##### organization Type


Array type: reference

All items must be of the type:
* []() â?? `#/definitions/non_empty_string_t`










#### urls

undefined

`urls`

* is optional
* type: `string[]`


##### urls Type


Array type: `string[]`

All items must be of the type:
`string`

* format: `uri` â?? Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986))
















## branch


`branch`

* is optional
* type: reference
* defined in this schema

### branch Type


Array type: reference

All items must be of the type:
* []() â?? `#/definitions/branch_branches_t`








## cpe


`cpe`

* is optional
* type: reference
* defined in this schema

### cpe Type


* []() â?? `#/definitions/non_empty_string_t`





## cve


`cve`

* is optional
* type: `string`
* defined in this schema

### cve Type


`string`



All instances must conform to this regular expression 
(test examples [here](https://regexr.com/?expression=%5ECVE-%5B0-9%5D%7B4%7D-%5B0-9%5D%7B4%2C%7D%24)):
```regex
^CVE-[0-9]{4}-[0-9]{4,}$
```






## cvss_score_sets


`cvss_score_sets`

* is optional
* type: `object`
* defined in this schema

### cvss_score_sets Type


`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `score_set_v3`| array | Optional |



#### score_set_v3

undefined

`score_set_v3`

* is optional
* type: `object[]`


##### score_set_v3 Type


Array type: `object[]`

All items must be of the type:
`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `base_score_v3`|  | **Required** |
| `environmental_score_v3`|  | Optional |
| `product_id`|  | Optional |
| `temporal_score_v3`|  | Optional |
| `vector_v3`|  | Optional |



#### base_score_v3

undefined

`base_score_v3`

* is **required**
* type: reference

##### base_score_v3 Type


* []() â?? `#/definitions/cvss_v3_score_t`







#### environmental_score_v3

undefined

`environmental_score_v3`

* is optional
* type: reference

##### environmental_score_v3 Type


* []() â?? `#/definitions/cvss_v3_score_t`







#### product_id

undefined

`product_id`

* is optional
* type: reference

##### product_id Type


* []() â?? `#/definitions/products_t`







#### temporal_score_v3

undefined

`temporal_score_v3`

* is optional
* type: reference

##### temporal_score_v3 Type


* []() â?? `#/definitions/cvss_v3_score_t`







#### vector_v3

undefined

`vector_v3`

* is optional
* type: reference

##### vector_v3 Type


* []() â?? `#/definitions/cvss_v3_vector_t`

















## cwe


`cwe`

* is optional
* type: `object`
* defined in this schema

### cwe Type


`object` with following properties:


| Property | Type | Required |
|----------|------|----------|






## date


`date`

* is optional
* type: reference
* defined in this schema

### date Type


* []() â?? `#/definitions/date_t`





## description


`description`

* is optional
* type: `string`
* defined in this schema

### description Type


`string`







## discovery_date


`discovery_date`

* is optional
* type: reference
* defined in this schema

### discovery_date Type


* []() â?? `#/definitions/date_t`





## full_product_name


`full_product_name`

* is optional
* type: reference
* defined in this schema

### full_product_name Type


* []() â?? `#/definitions/full_product_name_t`





## id


`id`

* is optional
* type: `object`
* defined in this schema

### id Type


`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `system_name`|  | **Required** |
| `text`|  | **Required** |



#### system_name

undefined

`system_name`

* is **required**
* type: reference

##### system_name Type


* []() â?? `#/definitions/non_empty_string_t`







#### text

undefined

`text`

* is **required**
* type: reference

##### text Type


* []() â?? `#/definitions/non_empty_string_t`










## involvements


`involvements`

* is optional
* type: `object[]`
* defined in this schema

### involvements Type


Array type: `object[]`

All items must be of the type:
`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `description`|  | Optional |
| `party`|  | **Required** |
| `status`|  | **Required** |



#### description

undefined

`description`

* is optional
* type: reference

##### description Type


* []() â?? `#/definitions/non_empty_string_t`







#### party

undefined

`party`

* is **required**
* type: `enum`

The value of this property **must** be equal to one of the [known values below](#involvements-known-values).

##### party Known Values
| Value | Description |
|-------|-------------|
| `coordinator` |  |
| `discoverer` |  |
| `other` |  |
| `user` |  |
| `vendor` |  |






#### status

undefined

`status`

* is **required**
* type: `enum`

The value of this property **must** be equal to one of the [known values below](#involvements-known-values).

##### status Known Values
| Value | Description |
|-------|-------------|
| `completed` |  |
| `contact accepted` |  |
| `disputed` |  |
| `in progress` |  |
| `not contacted` |  |
| `open` |  |












## lang


`lang`

* is optional
* type: `string`
* defined in this schema

### lang Type


`string`







## name


`name`

* is optional
* type: `string`
* defined in this schema

### name Type


`string`







## notes


`notes`

* is optional
* type: reference
* defined in this schema

### notes Type


* []() â?? `#/definitions/notes_t`





## number


`number`

* is optional
* type: reference
* defined in this schema

### number Type


* []() â?? `#/definitions/version_type_t`





## ordinal


`ordinal`

* is optional
* type: `integer`
* defined in this schema

### ordinal Type


`integer`

* minimum value: `1`






## product_id


`product_id`

* is optional
* type: reference
* defined in this schema

### product_id Type


* []() â?? `#/definitions/non_empty_string_t`





## product_status


`product_status`

* is optional
* type: `object`
* defined in this schema

### product_status Type


`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `first_affected`|  | Optional |
| `first_fixed`|  | Optional |
| `fixed`|  | Optional |
| `known_affected`|  | Optional |
| `known_not_affected`|  | Optional |
| `last_affected`|  | Optional |
| `recommended`|  | Optional |



#### first_affected

undefined

`first_affected`

* is optional
* type: reference

##### first_affected Type


* []() â?? `#/definitions/products_t`







#### first_fixed

undefined

`first_fixed`

* is optional
* type: reference

##### first_fixed Type


* []() â?? `#/definitions/products_t`







#### fixed

undefined

`fixed`

* is optional
* type: reference

##### fixed Type


* []() â?? `#/definitions/products_t`







#### known_affected

undefined

`known_affected`

* is optional
* type: reference

##### known_affected Type


* []() â?? `#/definitions/products_t`







#### known_not_affected

undefined

`known_not_affected`

* is optional
* type: reference

##### known_not_affected Type


* []() â?? `#/definitions/products_t`







#### last_affected

undefined

`last_affected`

* is optional
* type: reference

##### last_affected Type


* []() â?? `#/definitions/products_t`







#### recommended

undefined

`recommended`

* is optional
* type: reference

##### recommended Type


* []() â?? `#/definitions/products_t`










## references


`references`

* is optional
* type: reference
* defined in this schema

### references Type


* []() â?? `#/definitions/references_t`





## release_date


`release_date`

* is optional
* type: reference
* defined in this schema

### release_date Type


* []() â?? `#/definitions/date_t`





## remediations


`remediations`

* is optional
* type: `object[]`
* at least `1` items in the array
* defined in this schema

### remediations Type


Array type: `object[]`

All items must be of the type:
`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `description`|  | **Required** |
| `entitlements`| array | Optional |
| `product_ids`|  | Optional |
| `url`| string | Optional |



#### description

undefined

`description`

* is **required**
* type: reference

##### description Type


* []() â?? `#/definitions/str_option_t`







#### entitlements

undefined

`entitlements`

* is optional
* type: reference


##### entitlements Type


Array type: reference

All items must be of the type:
* []() â?? `#/definitions/non_empty_string_t`










#### product_ids

undefined

`product_ids`

* is optional
* type: reference

##### product_ids Type


* []() â?? `#/definitions/products_t`







#### url

undefined

`url`

* is optional
* type: `string`

##### url Type


`string`

* format: `uri` â?? Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986))













## text


`text`

* is optional
* type: reference
* defined in this schema

### text Type


* []() â?? `#/definitions/non_empty_string_t`





## threats


`threats`

* is optional
* type: `object[]`
* at least `1` items in the array
* defined in this schema

### threats Type


Array type: `object[]`

All items must be of the type:
`object` with following properties:


| Property | Type | Required |
|----------|------|----------|
| `date`|  | Optional |
| `description`|  | **Required** |
| `group_ids`|  | Optional |
| `product_ids`|  | Optional |
| `type`|  | Optional |



#### date

undefined

`date`

* is optional
* type: reference

##### date Type


* []() â?? `#/definitions/date_t`







#### description

undefined

`description`

* is **required**
* type: reference

##### description Type


* []() â?? `#/definitions/non_empty_string_t`







#### group_ids

undefined

`group_ids`

* is optional
* type: reference

##### group_ids Type


* []() â?? `#/definitions/products_t`







#### product_ids

undefined

`product_ids`

* is optional
* type: reference

##### product_ids Type


* []() â?? `#/definitions/products_t`







#### type

undefined

`type`

* is optional
* type: `enum`

The value of this property **must** be equal to one of the [known values below](#threats-known-values).

##### type Known Values
| Value | Description |
|-------|-------------|
| `impact` |  |
| `exploit status` |  |
| `target set` |  |












## title


`title`

* is optional
* type: reference
* defined in this schema

### title Type


* []() â?? `#/definitions/non_empty_string_t`





## type


`type`

* is optional
* type: reference
* defined in this schema

### type Type


* []() â?? `#/definitions/note_type_t`





## url


`url`

* is optional
* type: `string`
* defined in this schema

### url Type


`string`

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]