From 3a67fb52100dac0ca64719899afb431fbb8bd590 Mon Sep 17 00:00:00 2001
From: koplas <54645365+koplas@users.noreply.github.com>
Date: Wed, 31 Jul 2024 11:00:40 +0200
Subject: [PATCH] Add user-agent documentation

---
 docs/csaf_checker.md    | 13 +++++++++----
 docs/csaf_downloader.md | 13 +++++++++++--
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/docs/csaf_checker.md b/docs/csaf_checker.md
index 58f77cab..a5bc0bf1 100644
--- a/docs/csaf_checker.md
+++ b/docs/csaf_checker.md
@@ -30,9 +30,12 @@ Help Options:
 
 Will check all given _domains_, by trying each as a CSAF provider.
 
+If no user agent is specified with `--header=user-agent:custom-agent/1.0` then the default agent in the form of `csaf-distribution/version` is sent.
+
 If a _domain_ starts with `https://` it is instead considered a direct URL to the `provider-metadata.json` and checking proceeds from there.
 
 If no config file is explictly given the follwing places are searched for a config file:
+
 ```
 ~/.config/csaf/checker.toml
 ~/.csaf_checker.toml
@@ -41,6 +44,7 @@ csaf_checker.toml
 
 with `~` expanding to `$HOME` on unixoid systems and `%HOMEPATH` on Windows systems.
 Supported options in config files:
+
 ```
 output              = ""
 format              = "json"
@@ -58,9 +62,10 @@ validator_preset    = ["mandatory"]
 ```
 
 Usage example:
-` ./csaf_checker example.com -f html --rate=5.3 -H apikey:SECRET -o check-results.html`
+`./csaf_checker example.com -f html --rate=5.3 -H apikey:SECRET -o check-results.html`
 
 Each performed check has a return type of either 0,1 or 2:
+
 ```
 type 0: success
 type 1: warning
@@ -70,16 +75,16 @@ type 2: error
 The checker result is a success if no checks resulted in type 2, and a failure otherwise.
 
 The option `timerange` allows to only check advisories from a given time
-interval. It can only be given once.  See the
+interval. It can only be given once. See the
 [downloader documentation](csaf_downloader.md#timerange-option) for details.
 
-
 You can ignore certain advisories while checking by specifying a list
 of regular expressions[^1] to match their URLs by using the `ignorepattern`
 option.
 E.g. `-i='.*white.*' -i='*.red.*'` will ignore files which URLs contain
 the sub strings **white** or **red**.
 In the config file this has to be noted as:
+
 ```
 ignorepattern = [".*white.*", ".*red.*"]
 ```
@@ -88,7 +93,7 @@ ignorepattern = [".*white.*", ".*red.*"]
 
 The `role` given in the `provider-metadata.json` is not
 yet considered to change the overall result,
-see https://github.com/csaf-poc/csaf_distribution/issues/221 .
+see <https://github.com/csaf-poc/csaf_distribution/issues/221> .
 
 If a provider hosts one or more advisories with a TLP level of AMBER or RED, then these advisories must be access protected.
 To check these advisories, authorization can be given via custom headers or certificates.
diff --git a/docs/csaf_downloader.md b/docs/csaf_downloader.md
index fcf6634d..2831cb49 100644
--- a/docs/csaf_downloader.md
+++ b/docs/csaf_downloader.md
@@ -1,4 +1,5 @@
 ## csaf_downloader
+
 A tool to download CSAF documents from CSAF providers.
 
 ### Usage
@@ -39,6 +40,8 @@ Help Options:
 
 Will download all CSAF documents for the given _domains_, by trying each as a CSAF provider.
 
+If no user agent is specified with `--header=user-agent:custom-agent/1.0` then the default agent in the form of `csaf-distribution/version` is sent.
+
 If a _domain_ starts with `https://` it is instead considered a direct URL to the `provider-metadata.json` and downloading procedes from there.
 
 Increasing the number of workers opens more connections to the web servers
@@ -47,6 +50,7 @@ However, since this also increases the load on the servers, their administrators
 have taken countermeasures to limit this.
 
 If no config file is explictly given the follwing places are searched for a config file:
+
 ```
 ~/.config/csaf/downloader.toml
 ~/.csaf_downloader.toml
@@ -56,6 +60,7 @@ csaf_downloader.toml
 with `~` expanding to `$HOME` on unixoid systems and `%HOMEPATH` on Windows systems.
 
 Supported options in config files:
+
 ```
 # directory         # not set by default
 insecure            = false
@@ -90,6 +95,7 @@ option.
 E.g. `-i='.*white.*' -i='*.red.*'` will ignore files which URLs contain
 the sub strings **white** or **red**.
 In the config file this has to be noted as:
+
 ```
 ignorepattern = [".*white.*", ".*red.*"]
 ```
@@ -106,16 +112,18 @@ into a given intervall. There are three possible notations:
    and 'y' for years are recognized. In these cases only integer
    values are accepted without any fractions.
    Some examples:
+
    - `"3h"` means downloading the advisories that have changed in the last three hours.
-   - `"30m"`  .. changed within the last thirty minutes.
+   - `"30m"` .. changed within the last thirty minutes.
    - `"3M2m"` .. changed within the last three months and two minutes.
-   - `"2y"`   .. changed within the last two years.
+   - `"2y"` .. changed within the last two years.
 
 2. Absolute. If the given string is an RFC 3339 date timestamp
    the time interval between this date and now is used.
    E.g. `"2006-01-02"` means that all files between 2006 January 2nd and now going to being
    downloaded.
    Accepted patterns are:
+
    - `"2006-01-02T15:04:05Z"`
    - `"2006-01-02T15:04:05+07:00"`
    - `"2006-01-02T15:04:05-07:00"`
@@ -134,6 +142,7 @@ into a given intervall. There are three possible notations:
 All interval boundaries are inclusive.
 
 #### Forwarding
+
 The downloader is able to forward downloaded advisories and their checksums,
 OpenPGP signatures and validation results to an HTTP endpoint.  
 The details of the implemented API are described [here](https://github.com/mfd2007/csaf_upload_interface).