From 677b0fdd4f04c85629d4878d7ae946d20dae8236 Mon Sep 17 00:00:00 2001 From: "Bernhard E. Reiter" Date: Mon, 25 Jul 2022 15:23:11 +0200 Subject: [PATCH 1/2] Add docs for a provider proxy (#255) * Add instructions for an internal proxy provider * Improve example test config * .. by moving CSAF_CONFIG out of the common fcgiwrap.conf, so it can more easily be changed in a different context. * Improve proxy-provider-for-aggregator.md * Add section to aggregator documentation. * Fix typos. * Improve instructions. * Fix one path * Complre proxy-provider-for-aggregator.md --- docs/csaf_aggregator.md | 7 ++ docs/provider-setup.md | 2 - docs/proxy-provider-for-aggregator.md | 137 +++++++++++++++++++++++ docs/scripts/TLSClientConfigsForITest.sh | 2 +- docs/scripts/setupProviderForITest.sh | 4 +- 5 files changed, 147 insertions(+), 5 deletions(-) create mode 100644 docs/proxy-provider-for-aggregator.md diff --git a/docs/csaf_aggregator.md b/docs/csaf_aggregator.md index f6c93fb..5cebc1b 100644 --- a/docs/csaf_aggregator.md +++ b/docs/csaf_aggregator.md @@ -163,3 +163,10 @@ insecure = true category = "lister" ``` + + +#### Publish others' advisories + +In case you want to provide CSAF advisories from others +that only qualify as CSAF publishers, see +[how to use the `csaf_aggregator` for it](proxy-provider-for-aggregator.md). diff --git a/docs/provider-setup.md b/docs/provider-setup.md index 473da1e..b54502b 100644 --- a/docs/provider-setup.md +++ b/docs/provider-setup.md @@ -51,9 +51,7 @@ location /cgi-bin/ { # Adjust non standard parameters (SCRIPT_FILENAME) fastcgi_param SCRIPT_FILENAME /usr/lib$fastcgi_script_name; - fastcgi_param PATH_INFO $fastcgi_path_info; - fastcgi_param CSAF_CONFIG /etc/csaf/config.toml; fastcgi_param SSL_CLIENT_VERIFY $ssl_client_verify; fastcgi_param SSL_CLIENT_S_DN $ssl_client_s_dn; diff --git a/docs/proxy-provider-for-aggregator.md b/docs/proxy-provider-for-aggregator.md new file mode 100644 index 0000000..bb4c106 --- /dev/null +++ b/docs/proxy-provider-for-aggregator.md @@ -0,0 +1,137 @@ +If an organisation publishes their advisories via the internet +as valid CSAF documents, with good filenames and using TLS, +the [CSAF specification](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.md) +calls it a *CSAF publisher*. + +After manually downloading the advisories from such a publisher, +the tools here can be used to offer the CSAF files for automated downloading +as *CSAF aggregator*. + +There are three necessary steps, easiest is to use +one single virtual maschine (or container) per internal provider. +Use a different port for each. +Other setups are possible of course, e.g. virtual hosts +or dynamic settings using nginx configuration methods. +(Of course: adapt it to your security needs and procedures, +ask someone with experience to administrate your web server.) + + +### Setup provider api via FastCGI + +Follow the [general instructions to setup the `csaf_provider` as FastCGI binary](provider-setup.md), +but differ in the following ways: + +Recommended is to use non-standard TLS port and an internal domain name. + +For each internal provider a customized configuration file +must point to a place which can be served via a web server internally +later, for e.g. here is a potential config file to be saved +at `/etc/csaf/internal-provider1.toml`: + +```toml +openpgp_private_key = "/etc/csaf/real_private.asc" +openpgp_public_key = "/etc/csaf/real_public.asc" +tlps = ["white"] +canonical_url_prefix = "https://nein.ntvtn.de:10443" +categories = ["Example Company Product B", "expr:document.lang"] +create_service_document = true +folder = "/var/www-p1/" +web = "/var/www-p1/html" +``` + +For `csaf_provider.go` to find this file, you need to adjust +the path via the variable, normally set in `/etc/nginx/fcgiwrap.conf`: +```nginx + fastcgi_param CSAF_CONFIG /etc/csaf/internal-provider1.toml; +``` + +(Careful: setting the variable a second time will transfer both values to +fcgiwrap via an array. It is not guaranteed that the last value will be +used. So if you are thinking about setting this variable dynamically, +you need to make sure only once.) + +For example you can clone the files +```bash +sudo cp /etc/nginx/fcgiwrap.conf /etc/nginx/fcgiwrap-p1.conf +sudo vim /etc/nginx/fcgiwrap-p1.conf +sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/internal-p1-cgi +sudo ln -s /etc/nginx/sites-available/internal-p1-cgi /etc/nginx/sites-enabled/ +sudo vim /etc/nginx/sites-available/internal-p1-cgi + +and then set the right config and port like +``` + +```nginx + include fcgiwrap-p1.conf; + listen 10001 ssl default_server; # ipv4 + listen [::]:10001 ssl http2 default_server; # ipv6 +``` + + +#### Networking +Make sure the people responsible for doing the manual uploads +can access the port where the CGI script can be called. + + +### Setup internal CSAF provider + +Now serve the written `html` directory via a webserver, but only +internally. For nginx, you can follow the setup docs and for example +limit the interfaces where it is listening in the `listen` directive. +The following setting will only respond to requests +on the loopback interface on port 10443 with TLS. + +```nginx + listen localhost:10443 ssl default_server; + listen [::1]:10443 ssl default_server; + root /var/www-p1/html; +``` + +(Don't forget to reload nginx, so it gets the config change.) + + +#### Networking +Make sure the port can be reached by the server +where the `csaf_aggregator` is started, but cannot be reached from +an outside system. + +This could be done by an ssh (or other VPN) tunnel. + + +### Add to aggregator configuration + +#### Networking +Make sure that you have a local domain name that resolves +to our internal provider host, but is fine to be exposed in public. +As the domain name can be seen in the resulting `aggregator.json`. + +One simple method to do this, is by using an entry in +`/etc/hosts`: + +``` +192.168.2.2 nein.ntvtn.de +``` + +Consult your network admin for a secure setup. + + +#### aggregator.toml +Add a section to the aggregator configuration file, +to it is used next time when `csaf_aggregator` does a full run, e.g.: + +```toml +[[providers]] + name = "example-proxy-provider" + domain = "https://nein.ntvtn.de:10443/.well-known/csaf/provider-metadata.json" +``` + +Only makes sense if aggregator.category is set to `aggregator` (mirror mode). + +Depending on how you do the "tunneling" you can add `insecure = true` +to the section, if you are sure if nobody can mess with your internal DNS. +This deactivates the checking of the root for the TLS certificate. +Alternatively you can import the cert of the root CA for the internal +provider to the system root certificate store, which `csaf_aggregator` +is using. + + diff --git a/docs/scripts/TLSClientConfigsForITest.sh b/docs/scripts/TLSClientConfigsForITest.sh index 3d11c3e..c9c64a9 100755 --- a/docs/scripts/TLSClientConfigsForITest.sh +++ b/docs/scripts/TLSClientConfigsForITest.sh @@ -35,7 +35,7 @@ echo ' if ($ssl_client_verify != SUCCESS){ return 403; } - } + } '> ~/${FOLDERNAME}/clientCertificateConfigs.txt sudo sed -i "/^server {/r ${HOME}/${FOLDERNAME}/clientCertificateConfigs.txt" $NGINX_CONFIG_PATH diff --git a/docs/scripts/setupProviderForITest.sh b/docs/scripts/setupProviderForITest.sh index e7df3f4..d7f6e46 100755 --- a/docs/scripts/setupProviderForITest.sh +++ b/docs/scripts/setupProviderForITest.sh @@ -43,8 +43,8 @@ location /cgi-bin/ { # Adjust non standard parameters (SCRIPT_FILENAME) fastcgi_param SCRIPT_FILENAME /usr/lib$fastcgi_script_name; - fastcgi_param PATH_INFO $fastcgi_path_info; + fastcgi_param CSAF_CONFIG /etc/csaf/config.toml; fastcgi_param SSL_CLIENT_VERIFY $ssl_client_verify; @@ -53,7 +53,7 @@ location /cgi-bin/ { } ' | sudo tee /etc/nginx/fcgiwrap.conf -sudo sed -i "/^server {/a include fcgiwrap.conf;" $NGINX_CONFIG_PATH +sudo sed -i "/^server {/a\ include fcgiwrap.conf;" $NGINX_CONFIG_PATH echo " # For atomic directory switches From 101dd6880cf215551526150f033ceb54d6cb5493 Mon Sep 17 00:00:00 2001 From: "s-l-teichmann s-l-teichmann@users.noreply.github.com" Date: Mon, 25 Jul 2022 13:24:11 +0000 Subject: [PATCH 2/2] Apply automatic changes --- docs/client-certificate-setup.md | 2 +- docs/provider-setup.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/client-certificate-setup.md b/docs/client-certificate-setup.md index d72eb68..5f95439 100644 --- a/docs/client-certificate-setup.md +++ b/docs/client-certificate-setup.md @@ -22,7 +22,7 @@ adjust the content of the `server{}` block like shown in the following example: if ($ssl_client_verify != SUCCESS){ return 403; } - } + } ``` diff --git a/docs/provider-setup.md b/docs/provider-setup.md index b54502b..288fdcc 100644 --- a/docs/provider-setup.md +++ b/docs/provider-setup.md @@ -53,6 +53,8 @@ location /cgi-bin/ { fastcgi_param SCRIPT_FILENAME /usr/lib$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; + fastcgi_param CSAF_CONFIG /etc/csaf/config.toml; + fastcgi_param SSL_CLIENT_VERIFY $ssl_client_verify; fastcgi_param SSL_CLIENT_S_DN $ssl_client_s_dn; fastcgi_param SSL_CLIENT_I_DN $ssl_client_i_dn;