SystemSh0cker/gocsaf
1
0
Fork 0
mirror of https://github.com/gocsaf/csaf.git synced 2025-12-21 23:20:10 +01:00
Code Issues Releases Activity Actions

Improve documentation and its structure

Browse source 
* Add short description for each component in the main README
* Move more Info in separated files.
* Add hint that csaf_provider offers a service interface.
* Explain why windows only has uploader and checker.

Co-authored-by: Bernhard Reiter <bernhard@intevation.de>
This commit is contained in:
Fadi Abbud 2022-05-13 11:04:38 +02:00 • committed by GitHub
parent cd9f29ef2f
commit 6f02e6f5a5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 134 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Makefile
View file

@ -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/

87
README.md
View file

@ -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:<span></span>//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

12
docs/csaf_aggregator.md Normal file
View file

@ -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 ```

16
docs/csaf_checker.md Normal file
View file

@ -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`

24
docs/csaf_provider.md Normal file
View file

@ -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.

48
docs/csaf_uploader.md Normal file
View file

@ -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:<span></span>//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
```

3
docs/release-process-hints.md Normal file
View file

@ -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.