diff --git a/Makefile b/Makefile index ffda92b..7b0c608 100644 --- a/Makefile +++ b/Makefile @@ -77,7 +77,7 @@ dist: build_linux build_win cp README.md dist/$(DISTDIR)-windows-amd64 cp bin-windows-amd64/csaf_uploader.exe bin-windows-amd64/csaf_checker.exe dist/$(DISTDIR)-windows-amd64/bin-windows-amd64/ mkdir -p dist/$(DISTDIR)-windows-amd64/docs - #cp docs/csaf_uploader.md docs/csaf_checker.md dist/$(DISTDIR)-windows-amd64/docs + cp docs/csaf_uploader.md docs/csaf_checker.md dist/$(DISTDIR)-windows-amd64/docs mkdir dist/$(DISTDIR)-gnulinux-amd64 cp -r README.md docs bin-linux-amd64 dist/$(DISTDIR)-gnulinux-amd64 cd dist/ ; zip -r $(DISTDIR)-windows-amd64.zip $(DISTDIR)-windows-amd64/ diff --git a/README.md b/README.md index 0acf0e0..0c2886a 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,36 @@ # csaf_distribution -A proof of concept implementation of -an CSAF 2.0 trusted provider, checker and aggregator. -Includes an uploader command line tool for the trusted provider. +A proof of concept implementation of a [CSAF 2.0](https://docs.oasis-open.org/csaf/csaf/v2.0/csd02/csaf-v2.0-csd02.html) trusted provider, checker and aggregator. Includes an uploader command line tool for the trusted provider. Status: Alpha (all planned functionality, but known defects, see issues.) + +## [csaf_provider](docs/csaf_provider.md) +is an implementation of the role CSAF Trusted Provider, also offering +a simple HTTPS based management service. + +## [csaf_uploader](docs/csaf_uploader.md) +is a command line tool that uploads CSAF documents to the `csaf_provider`. + +## [csaf_aggregator](docs/csaf_aggregator.md) +is an implementation of the role CSAF Aggregator. + +## [csaf_checker](docs/csaf_checker.md) +is a tool for testing a CSAF Trusted Provider according to [Section 7 of the CSAF standard](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html#7-distributing-csaf-documents). + ## Setup +Note that the server side is only tested +and the binaries available for GNU/Linux-Systems, e.g. Ubuntu LTS. +It is likely to run on similar systems when build from sources. + +The windows binaries only include `csaf_uploader` and `csaf_checker`. + +### Prebuild binaries + +Download the binaries (from the most recent release assets on Github). + + +### Build from sources - A recent version of **Go** (1.17+) should be installed. [Go installation](https://go.dev/doc/install) @@ -23,65 +47,14 @@ Status: Alpha (all planned functionality, but known defects, see issues.) Binaries will be placed in directories named like `bin-linux-amd64/` and `bin-windows-amd64/`. + +### Setup (Trusted Provider) + - [Install](https://nginx.org/en/docs/install.html) **nginx** - To install server certificate on nginx see [docs/install-server-certificate.md](docs/install-server-certificate.md) - To configure nginx see [docs/provider-setup.md](docs/provider-setup.md) - To configure nginx for client certificate authentication see [docs/client-certificate-setup.md](docs/client-certificate-setup.md) -## csaf_uploader - -csaf_uploader is a command line tool that uploads CSAF documents to the trusted provider (CSAF_Provider). -Following options are supported: - -| Options | Description | -| ------------------------------------------ | ------------------------------------------------------------------------------------------ | -| -a, --action=[upload\|create] | Action to perform (default: upload) | -| -u, --url=URL | URL of the CSAF provider (default:https://localhost/cgi-bin/csaf_provider.go) | -| -t, --tlp=[csaf\|white\|green\|amber\|red] | TLP of the feed (default: csaf) | -| -x, --external-signed | CSAF files are signed externally. Assumes .asc files beside CSAF files | -| -k, --key=KEY-FILE | OpenPGP key to sign the CSAF files | -| -p, --password=PASSWORD | Authentication password for accessing the CSAF provider | -| -P, --passphrase=PASSPHRASE | Passphrase to unlock the OpenPGP key | -| -i, --password-interactive | Enter password interactively | -| -I, --passphrase-interacive | Enter passphrase interactively | -| -c, --config=INI-FILE | Path to config ini file | -| --insecure | Do not check TLS certificates from provider | -| --client-cert | TLS client certificate file (PEM encoded data) | -| --client-key | TLS client private key file (PEM encoded data) | -| -h, --help | Show help | - -E.g. creating the initial directiories and files - -``` -./csaf_uploader -a create -u http://localhost/cgi-bin/csaf_provider.go -``` - -E.g. uploading a csaf-document - -``` -./csaf_uploader -a upload -I -t white -u http://localhost/cgi-bin/csaf_provider.go CSAF-document-1.json -``` - -which asks to enter password interactively. - -csaf_uploader can be started with a config file like following: - -``` -./csaf_provider -c conf.ini -``` - -config.ini : - -``` -action=create -u=http://localhost/cgi-bin/csaf_provider.go -``` - -## csaf_checker - -Provider checker is a tool for testing a CSAF trusted provider according to [Section 7 of the CSAF standard](https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html#7-distributing-csaf-documents). -Usage example: -``` ./csaf_checker example.com -f html -o check-results.html``` ## License diff --git a/docs/csaf_aggregator.md b/docs/csaf_aggregator.md new file mode 100644 index 0000000..9182dcb --- /dev/null +++ b/docs/csaf_aggregator.md @@ -0,0 +1,12 @@ +## csaf_aggregator + +Following options are supported: + +| Options | Description | +| --------------------- | -------------------------------------------------------------- | +| -c, --config=CFG-FILE | File name of the configuration file (default: aggregator.toml) | +| -i, --interim | Perform an interim scan | +| --version | Display version of the binary | + +Usage example: +``` ./csaf_aggregator -c docs/examples/aggregator.toml ``` diff --git a/docs/csaf_checker.md b/docs/csaf_checker.md new file mode 100644 index 0000000..09d0656 --- /dev/null +++ b/docs/csaf_checker.md @@ -0,0 +1,16 @@ +## csaf_checker + +Following options are supported: + +| Options | Description | +| ------------------------------------------ | ---------------------------------------------- | +| -o, --output=REPORT-FILE | File name of the generated report | +| -f, --format=[json | html] | +| -t, --tlp=[csaf\|white\|green\|amber\|red] | Format of report (default: json) | +| --insecure | o not check TLS certificates from provider | +| --client-cert=CERT-FILE | TLS client certificate file (PEM encoded data) | +| --client-key=KEY-FILE | TLS client private key file (PEM encoded data) | +| --version | Display version of the binary | + +Usage example: +` ./csaf_checker example.com -f html -o check-results.html` diff --git a/docs/csaf_provider.md b/docs/csaf_provider.md new file mode 100644 index 0000000..311b006 --- /dev/null +++ b/docs/csaf_provider.md @@ -0,0 +1,24 @@ +## Provider options +Following options are supported: + + - password: Authentication password for accessing the CSAF provider. + - key: The private OpenPGP key. + - folder: Specify the root folder. Default: `/var/www/`. + - web: Specify the web folder. Default: `/var/www/html`. + - 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"]`. + - 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`. + - openpgp_url: URL to OpenPGP key-server. Default: `https://openpgp.circl.lu`. + - canonical_url_prefix: start of the URL where contents shall be accessible from the internet. Default: `https://$SERVER_NAME`. + - no_passphrase: Let user send password with the request, if set to true the input-field in the web interface will be disappeared. Default: `false`. + - no_validation: Validate 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`. + - provider_metadata: Configure the provider metadata. + - provider_metadata.list_on_CSAF_aggregators: List on aggregators + - provider_metadata.mirror_on_CSAF_aggregators: Mirror on aggregators + - provider_metadata.publisher: Set the publisher. Default: `{"category"= "vendor", "name"= "Example", "namespace"= "https://example.com"}`. + - upload_limit: Set the upload limit size of the file. Default: `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. diff --git a/docs/csaf_uploader.md b/docs/csaf_uploader.md new file mode 100644 index 0000000..5f95892 --- /dev/null +++ b/docs/csaf_uploader.md @@ -0,0 +1,48 @@ +## csaf_uploader + +Following options are supported: + +| Options | Description | +| ------------------------------------------ | ------------------------------------------------------------------------------------------ | +| -a, --action=[upload\|create] | Action to perform (default: upload) | +| -u, --url=URL | URL of the CSAF provider (default:https://localhost/cgi-bin/csaf_provider.go) | +| -t, --tlp=[csaf\|white\|green\|amber\|red] | TLP of the feed (default: csaf) | +| -x, --external-signed | CSAF files are signed externally. Assumes .asc files beside CSAF files | +| -k, --key=KEY-FILE | OpenPGP key to sign the CSAF files | +| -p, --password=PASSWORD | Authentication password for accessing the CSAF provider | +| -P, --passphrase=PASSPHRASE | Passphrase to unlock the OpenPGP key | +| -i, --password-interactive | Enter password interactively | +| -I, --passphrase-interacive | Enter passphrase interactively | +| -c, --config=INI-FILE | Path to config ini file | +| --insecure | Do not check TLS certificates from provider | +| --client-cert | TLS client certificate file (PEM encoded data) | +| --client-key | TLS client private key file (PEM encoded data) | +| --version | Display version of the binary | +| -h, --help | Show help | + +E.g. creating the initial directiories and files + +``` +./csaf_uploader -a create -u http://localhost/cgi-bin/csaf_provider.go +``` + +E.g. uploading a csaf-document + +``` +./csaf_uploader -a upload -I -t white -u http://localhost/cgi-bin/csaf_provider.go CSAF-document-1.json +``` + +which asks to enter password interactively. + +csaf_uploader can be started with a config file like following: + +``` +./csaf_provider -c conf.ini +``` + +config.ini : + +``` +action=create +u=http://localhost/cgi-bin/csaf_provider.go +``` diff --git a/docs/release-process-hints.md b/docs/release-process-hints.md new file mode 100644 index 0000000..0a0a21c --- /dev/null +++ b/docs/release-process-hints.md @@ -0,0 +1,3 @@ +When changing the structure of the documenation, +check the toplevel Makefile's dist target so that +the right things are included.