Improve provider documentation

* Creates an example config.toml and replaces csaf_providers example with the autodoc to said example.

Co-authored-by: Jan Höfelmeyer <Jan Höfelmeyer jhoefelmeyer@intevation.de>
Co-authored-by: Bernhard Reiter <bernhard@intevation.de>
Co-authored-by: @mfd2007

docs/csaf_provider.md

@@ -6,45 +6,8 @@ explain how to wire this up with nginx and where the config file lives.
 
 ## Provider options
 
-Following options are supported in the config file:
+The following example file documents all available configuration options:
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../docs/examples/provider_config.toml) -->
+<!-- MARKDOWN-AUTO-DOCS:END -->
 
- - password: Authentication password for accessing the CSAF provider.
- - openpgp_public_key: The public OpenPGP key. Default: `/ust/lib/csaf/openpgp_public.asc`
- - openpgp_private_key: The private OpenPGP key. Default: `/ust/lib/csaf/openpgp_private.asc`
- - folder: Specify the root folder. Default: `/var/www/`.
- - web: Specify the web folder. Default: `/var/www/html`.
- - upload_signature: Send signature with the request, an additional input-field in the web interface will be shown to let user enter an ascii armored signature. Default: `false`.
- - canonical_url_prefix: start of the URL where contents shall be accessible from the internet. Default: `https://$SERVER_NAME`.
- - certificate_and_password: Require password and a valid Client Certificate for write access. Default: false
- - no_passphrase: Let the user send the request without having to send a password. If set to true, the input-field in the web interface will be omitted. Default: `false`.
- - no_validation: Skip validation of the uploaded CSAF document against the JSON schema. Default: `false`.
- - no_web_ui: Disable the web interface. Default: `false`.
- - dynamic_provider_metadata: Take the publisher from the CSAF document. Default: `false`.
- - upload_limit: Set the upload limit size of a file in bytes. Default: `52428800` (aka 50 MiB).
- - issuer: The issuer of the CA, which if set, restricts the writing permission and the accessing to the web-interface to only the client certificates signed with this CA.
- - write_indices: Write/update `index.txt` and `changes.csv`. Default: false
- - write_security: Write `CSAF:` entry into `security.txt`: Default: false
- - tlps: Set the allowed TLP comming with the upload request (one or more of "csaf", "white", "amber", "green", "red").
-   The "csaf" selection lets the provider takes the value from the CSAF document.
-   These affects the list items in the web interface.
-   Default: `["csaf", "white", "amber", "green", "red"]`.
- - create_service_document: Create ROLIE service document. Default: false
- - categories: Create ROLIE category document from a list of strings.
-   If a list item starts with `expr:` the rest of the string is used as a [JsonPath expression](https://goessner.net/articles/JsonPath/) to
-   extract a string from the incoming advisories. Strings not starting with `expr:` are took verbatim.
-   By default no category documents are created.
-   E.g: `categories = ["Example Company Product A", "expr:document.lang"]`
- - provider_metadata: Configure the provider metadata.
- - provider_metadata.list_on_CSAF_aggregators: List on aggregators
- - provider_metadata.mirror_on_CSAF_aggregators: Mirror on aggregators
- - remote_validator: Use a remote validator service. Not used by default.
-   `{ "url" = "http://localhost:3000", "presets" = ["mandatory"], "cache" = "/var/lib/csaf/validations.db" }`
- - provider_metadata.publisher: Set the publisher. Default:
-```toml
-[provider_metadata.publisher]
-category = "vendor"
-name = "Example Company"
-namespace = "https://example.com"
-issuing_authority = "We at Example Company are responsible for publishing and maintaining Product Y."
-contact_details = "Example Company can be reached at contact_us@example.com, or via our website at https://www.example.com/contact."
-```

docs/examples/provider_config.toml

@@ -0,0 +1,102 @@
+# Set the authentication password for accessing the CSAF provider.
+# It is essential that you set a secure password between the quotation marks.
+# The default being no password set.
+#password = ""
+
+# Set the path to the public OpenPGP key.
+#openpgp_public_key = "/etc/csaf/openpgp_public.asc"
+
+# Set the path to the private OpenPGP key.
+#openpgp_private_key = "/etc/csaf/openpgp_private.asc"
+
+# Specify the root folder.
+#folder = "/var/www/"
+
+# Specify the web folder.
+#web = "/var/www/html"
+
+# Allow sending a signature with the request.
+# An additional input-field in the web interface will be shown
+# to let user enter an ascii armored OpenPGP signature.
+#upload_signature = false
+
+# Set the beginning of the URL where contents are accessible from the internet.
+# If not set, the provider will read from the $SERVER_NAME variable.
+# The following shows an example of a manually set prefix:
+#canonical_url_prefix  = https://localhost
+
+# Require users to use a password and a valid Client Certificate for write access.
+#certificate_and_password = false
+
+# Allow the user to send the request without having to send a passphrase
+# to unlock the the OpenPGP key.
+# If set to true, the input-field in the web interface will be omitted.
+#no_passphrase = false
+
+# Make the provider skip the validation of the uploaded CSAF document
+# against the JSON schema.
+#no_validation = false
+
+# Disable the web interface.
+#no_web_ui = false
+
+# Make the provider take the publisher from the CSAF document.
+#dynamic_provider_metadata = false
+
+# Set the upload limit size of a file in bytes.
+# The default is equivalent to 50 MiB.
+#upload_limit =  52428800
+
+# Set the issuer of the CA.
+# If set, the provider restricts the writing permission and the
+# access to the web-interface to users with the client certificates
+# signed with this CA.
+# The following shows an example. As default, none is set.
+#issuer = "Example Company"
+
+# Make the provider write/update index.txt and changes.csv.
+#write_indices = false
+
+# Make the provider write a `CSAF:` entry into `security.txt`.
+#write_security = false
+
+# Set the TLP allowed to be send with the upload request
+# (one or more of "csaf", "white", "amber", "green", "red").
+# The "csaf" entry lets the provider take the value from the CSAF document.
+# These affect the list items in the web interface.
+#tlps = ["csaf", "white", "amber", "green", "red"]`
+
+# Make the provider create a ROLIE service document.
+#create_service_document = false
+
+# Make the provider create a ROLIE category document from a list of strings.
+# If a list item starts with `expr:`
+#   the rest of the string is used as a JsonPath expression
+#   to extract a string from the incoming advisories.
+# Strings not starting with `expr:` are taken verbatim.
+# By default no category documents are created.
+# This example provides an overview over the syntax,
+# adjust the parameters depending on your setup.
+#categories = ["Example Company Product A", "expr:document.lang"]
+
+# Make the provider use a remote validator service. Not used by default.
+# This example provides an overview over the syntax,
+# adjust the parameters depending on your setup.
+#[remote_validator]
+#url = "http://localhost:3000"
+#presets = ["mandatory"]
+#cache = "/var/lib/csaf/validations.db"
+
+[provider_metadata]
+# Indicate that aggregators can list us.
+list_on_CSAF_aggregators = true
+# Indicate that aggregators can mirror us.
+mirror_on_CSAF_aggregators = true
+
+# Set the publisher details.
+[provider_metadata.publisher]
+category = "vendor"
+name = "Example Company"
+namespace = "https://example.com"
+issuing_authority = "We at Example Company are responsible for publishing and maintaining Product Y."
+contact_details = "Example Company can be reached at contact_us@example.com, or via our website at https://www.example.com/contact."