Skip to content

Latest commit

 

History

History
295 lines (202 loc) · 7.96 KB

templates.md

File metadata and controls

295 lines (202 loc) · 7.96 KB
Raw

Templates

This document describes the format of the templates used by fakedoc and how to use them.

Overview

The template has two main parts: The [types] section which maps type names to descriptions how instances of that type are generated and one top-level setting root which names the type to generate initially.

The generator always uses a built-in template derived from the CSAF JSON-schema. This template can be written to a file with the createtemplate command (see README.md). The fakedoc command can optionally be invoked with the --template option to specify a template file that overrides some or all of the types in the built-in template. In this file, only the [types] section is used and all the types in there are added to the types in the built-in template with types with the same name replacing the built-in ones. This way it's possible to override specific with a very short template.

For instance, to just override how name, category and namespace of the vendor are generated by forcing them to be specific strings, you could use the following file (publisher.toml):

[types]
  [types."csaf:#/properties/document/properties/publisher/properties/name"]
    enum = ["CSAF, Inc."]
    type = "string"
  [types."csaf:#/properties/document/properties/publisher/properties/namespace"]
    enum = ["https://csaf.example/"]
    type = "string"
  [types."csaf:#/properties/document/properties/publisher/properties/category"]
    enum = ["vendor"]
    type = "string"

The invoke fakedo like e.g. this:

go run cmd/fakedoc/main.go --template publisher.toml -o random-csaf.json

Types

For each type t the template file has a section [types.t] that describes that type. Each such section has an attribute called type that indicates which of several kinds of type it describes. These are described in detail below.

In the template generated by createtemplate the typenames are derived from URLs pointing to the relevant part of the CSAF JSON schema. These are typically quite long and contain characters that need to be quoted when used as the name for a single level of the hierarchy in the toml file, so typical section names looke like this: [types."csaf:#/$defs/acknowledgments_t/items"]

Kinds of Types

object

The object kind describes a JSON object and defines which properties the object can have and optionally how many of them.

Attributes

  • minproperties: The minimum number of properties the object must have. Optional. If omitted or -1, there's no lower bound on the number of properties

  • maxproperties: The maximum number of properties the object may have Optional. If omitted or -1, there's no upper bound on the number of properties

  • properties: Array of property descriptions (see below)

    The array is usually expressed using an array of tables (see the example below)

Properties

Each property has the following attributes:

  • name: The name of the attribute

  • type: String with the type of the attribute. The type must be one of the types in the types section

  • required: Boolean. If true, the object must always have this attribute. If omitted, it defaults to false.

Example

  [types."csaf:#"]
    type = "object"

    [[types."csaf:#".properties]]
      name = "document"
      type = "csaf:#/properties/document"
      required = true

    [[types."csaf:#".properties]]
      name = "product_tree"
      type = "csaf:#/properties/product_tree"

    [[types."csaf:#".properties]]
      name = "vulnerabilities"
      type = "csaf:#/properties/vulnerabilities"

array

The array kind describes a JSON array

Attributes

  • items: The type of the array items. The type must be one of the types in the types section

  • minitems: The minimum number of items in the array. Optional. If omitted or -1, the array may be empty

  • maxitems: The maximum number of items in the array. Optional. If omitted or -1, the array length is unbounded. The document generated will not generate arrays that are much longer than minitems, though.

  • uniqueitems: Boolean. If true, the items in the array must be unique.

Example
  [types."csaf:#/$defs/acknowledgments_t/items/properties/urls"]
    items = "csaf:#/$defs/acknowledgments_t/items/properties/urls/items"
    minitems = 1
    type = "array"

oneof

The oneof kind describes a choice between types.

Attributes
  • oneof: An array of strings with the names of the types. One of the types is chosen uniformly. The types must refer to types in the types section
Example
  [types."csaf:#/cvss_v3"]
    oneof = ["csaf:#/cvss_v3/oneOf/0", "csaf:#/cvss_v3/oneOf/1"]
    type = "oneof"

string

The string kind describes a JSON string.

Attributes

  • enum: Array of strings. Optional. If omitted, it defaults to an empty array.

  • pattern: A string with a regular expression. Optional.

  • minlength: The minimum length of the string. Optional. If omitted or -1, the string may be empty.

  • maxlength: The maximum length of the string. Optional. It omitted or -1, the length of the string is unbounded. In practice the string will not be much longer than minlength.

The value of the string is chosen as follows:

  1. If enum is not empty, the value is one of the strings in that array.

  2. If pattern was given. The value is a randomly chosen string that matches the pattern.

  3. Otherwise the string is a random string with length that fits the minlength and maxlength values.

Examples
  [types."csaf:#/$defs/notes_t/items/properties/category"]
    enum = ["description", "details", "faq", "general", "legal_disclaimer", "other", "summary"]
    type = "string"
  [types."csaf:#/properties/vulnerabilities/items/properties/cve"]
    pattern = "^CVE-[0-9]{4}-[0-9]{4,}$"
    type = "string"

number

The number kind describes a JSON number.

Attributes
  • minimum: Minimum value of the number. If omitted, there's no lower bound.
  • maximum: Maximum value of the number. If omitted, there's no upper bound.
Example
  [types."cvss20:?20170531#/properties/baseScore"]
    maximum = 10.0
    minimum = 0.0
    type = "number"

date-time

The date-time kind describes a JSON string containing a time stamp in ISO format.

Attributes
  • minimum: Minimum value of the date-time in TOML date time format. If omitted, there's no lower bound.
  • maximum: Maximum value of the date-time in TOML date time format. If omitted, there's no upper bound.
Example
  [types."csaf:#/properties/document/properties/tracking/properties/current_release_date"]
    maximum = 2025-01-01T00:00:00Z
    minimum = 2020-01-01T00:00:00Z
    type = "date-time"

lorem

The lorem kind describes a JSON string containing "lorem ipsum" style filler text. This is particularly useful for the parts of a CSAF document that contain prose text.

Attributes
  • unit: String with one of the values "words", "sentences" or "paragraphs". This roughly controls how much text is generated and whether its split into paragraphs. Paragraphs are separated by newline characters.
  • minlength: Minimum length in units
  • maxlength: Maximum length in units
Example
  [types."csaf:#/properties/vulnerabilities/items/properties/threats/items/properties/details"]
    minlength = 2
    unit = "sentences"
    type = "lorem"

book

The book describes a custom text file that is used as filler. This is particularly useful for the parts of a CSAF document that require custom text.

Attributes
  • path: File path to the text file
  • minlength: Minimum length in units
  • maxlength: Maximum length in units
Example
  [types."csaf:#/properties/vulnerabilities/items/properties/threats/items/properties/details"]
    minlength = 2
    type = "book"
    path = "moby-dick.txt"