diff --git a/docs/csaf_provider.md b/docs/csaf_provider.md index d755398..ad99a77 100644 --- a/docs/csaf_provider.md +++ b/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: + + + - - 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." -``` diff --git a/docs/examples/provider_config.toml b/docs/examples/provider_config.toml new file mode 100644 index 0000000..09046f3 --- /dev/null +++ b/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."