Improve Logging documentation following Markdownlint (#219)

* docs(specification): improve logging documentation following MD014 Specification reference: https://github.com/DavidAnson/markdownlint/ Signed-off-by: 诺墨 <zhangshengxiang@gitee.com> * docs(lint): follow `MD009` and `MD014` to improve docs and replace `console` with `bash` Resolves #225 Signed-off-by: 诺墨 <zhangshengxiang@gitee.com> --------- Signed-off-by: 诺墨 <zhangshengxiang@gitee.com>
sigstore · Aug 25, 2023 · 9396c99 · 9396c99
1 parent 0a6e574
commit 9396c99
Show file tree

Hide file tree

Showing 7 changed files with 91 additions and 93 deletions.
diff --git a/content/en/logging/CLI.md b/content/en/logging/CLI.md
@@ -19,29 +19,29 @@ Before using Rekor, you are required to sign your release. The following example
 
 You may use either armored or plain binary:
 
-```
+```bash
 gpg --armor -u jdoe@example.com --output mysignature.asc --detach-sig myrelease.tar.gz
 ```
 
 You will also need to export your public key
 
-```
+```bash
 gpg --export --armor "jdoe@example.com" > mypublickey.key
 ```
 
 ## Upload an entry rekor
 
 The `upload` command sends your public key / signature and artifact URL to the rekor transparency log.
 
-```
+```bash
 rekor-cli upload --rekor_server https://rekor.sigstore.dev --signature <artifact_signature> --public-key <your_public_key> --artifact <url_to_artifact>|<local_path_artifact>
 ```
 
 The Rekor command will first verify your public key and signature and download a local copy of the artifact. Then it will validate the artifact signing (no access to your private key is required).
 
 If the validations above pass correctly, the entry will be made to Rekor and an entry URL will be returned:
 
-```
+```bash
 Created entry at: https://rekor.sigstore.dev/api/v1/log/entries/b08416d417acdb0610d4a030d8f697f9d0a718024681a00fa0b9ba67072a38b5
 ```
 
@@ -51,10 +51,9 @@ This URL contains the UUID entry / merkle tree hash (in the above case `b08416d4
 
 The `verify` command allows you to send a public key / signature and artifact to the Rekor transparency log for verification of entry.
 
-You would typically use this command as a means to verify an 'inclusion proof'
-showing that your artifact is stored within the transparency log.
+You would typically use this command as a means to verify an 'inclusion proof' showing that your artifact is stored within the transparency log.
 
-```
+```bash
 rekor-cli verify --rekor_server <rekor_url> --signature <artifact-signature> --public-key <your_public_key> --artifact <url_to_artifact>|<local_path_artifact>
 ```
 
@@ -64,19 +63,19 @@ rekor-cli verify --rekor_server <rekor_url> --signature <artifact-signature> --p
 
 An entry in the log can be retrieved by using the `get` command with either the log index or the artifact UUID:
 
-```
+```bash
 rekor-cli get --rekor_server https://rekor.sigstore.dev --log-index <log-index>
 ```
 
-```
+```bash
 rekor-cli get --rekor_server https://rekor.sigstore.dev --uuid <uuid>
 ```
 
 ## Log Info
 
 The `loginfo` command retrieves the public key of the transparency log (unless already declared within the client `~/.rekor/rekor.yaml`) and then uses this public key to verify the signature on the signed tree head.
 
-```
+```bash
 rekor-cli loginfo --rekor_server https://rekor.sigstore.dev
 ```
 
@@ -86,11 +85,12 @@ If running a redis instance within Rekor, the `search` command performs a redis
 
 This command requires one of an artifact, a public key, or a SHA hash (should be prefixed by `sha256:`).
 
-```
+```bash
 rekor-cli search --rekor_server https://rekor.sigstore.dev --[artifact|public-key|sha]
 ```
 
 For example:
-```
+
+```bash
 rekor-cli search --rekor_server https://rekor.sigstore.dev --sha sha256:e2e90d1a25f90a3156a27f00f3a4179578e3132ed4f010dc3498d09175b6071a
 ```
diff --git a/content/en/logging/installation.md b/content/en/logging/installation.md
@@ -11,13 +11,13 @@ There are several ways to install both the `rekor-cli` and `rekor-server`.
 
 If you have Go installed, you can use go to retreive the `rekor-cli` binaries
 
-```
+```bash
 go install -v github.com/sigstore/rekor/cmd/rekor-cli@latest
 ```
 
 You may also do the same for `rekor-server`, but **please note** that the Rekor server also requires Trillian and a database. (see below for setup instructions).
 
-```
+```bash
 go install -v github.com/sigstore/rekor/cmd/rekor-server@latest
 ```
 
@@ -29,10 +29,9 @@ Releases are available for both `rekor-server` and `rekor-cli`.
 
 Review [Verifying Binaries](/logging/verify-release/) for details on how to verify Rekor release binaries.
 
-
 ## Build Rekor CLI manually
 
-```
+```bash
 git clone https://github.com/sigstore/rekor.git rekor-cli
 cd rekor-cli
 make rekor-cli
@@ -43,8 +42,8 @@ cp rekor-cli /usr/local/bin/
 
 There are a few ways you can deploy a Rekor Server:
 
-1.  We have a [docker-compose](https://github.com/sigstore/rekor/blob/main/docker-compose.yml) file available.
-2.  Alternatively, you can build a Rekor server yourself.
+1. We have a [docker-compose](https://github.com/sigstore/rekor/blob/main/docker-compose.yml) file available.
+2. Alternatively, you can build a Rekor server yourself.
 
 Note: The Rekor server manually creates a new Merkle tree (or shard) in the Trillian backend every time it starts up, unless an existing one is specified in via the `--trillian_log_server.tlog_id` flag. If you are building the server yourself and do not need [sharding](/rekor/sharding/) functionality, you can find the existing tree's TreeID by issuing this client command while the server is running:
 
@@ -74,25 +73,25 @@ Grab the Rekor source:
 
 Rekor requires a database. We use MariaDB for now (others to be explored later). Install and set up MariaDB on your machine.
 
-```
+```bash
 dnf install mariadb mariadb-server
 systemctl start mariadb
 systemctl enable mariadb
 mysql_secure_installation
 ```
- 
+
 The Rekor directory has a `scripts/createdb.sh` file that will set up a test database (default user: test; default password: zaphod) and populate the needed tables for Trillian. If you’re just trying out Rekor, keep the DB user name and password the same as in the script (test/zaphod). If you change these, you need to make the changes on Trillian’s side (visit the [Trillian repo](https://github.com/google/trillian) for details).
 
-```
+```bash
 cd $GOPATH/pkg/mod/github.com/sigstore/rekor@v0.4.0/scripts/
 sh createdb.sh
-``` 
- 
+```
+
 ### Build Trillian
 
 You also need to build Trillian, an append-only log:
 
-```
+```bash
 go get -u -t -v github.com/google/trillian
 cd $GOPATH/src/github.com/google/trillian/cmd/trillian_log_server
 go build
@@ -109,43 +108,45 @@ cp createtree /usr/local/bin/
 
 Next, run the Trillian log server:
 
-```
+```bash
 trillian_log_server --logtostderr ...
 ```
 
 Run the signer:
 
-```
+```bash
 trillian_log_signer --logtostderr --force_master --rpc_endpoint=localhost:8190 -http_endpoint=localhost:8191  --batch_size=1000 --sequencer_guard_window=0 --sequencer_interval=200ms
 ```
+
 > Note: you can log both to files and to stderr using `--alsologtostderr`
 
 Create the tree:
 
-```
+```bash
 createtree --admin_server=localhost:8090
 ```
 
 #### Build the Rekor Server
 
 With Trillian and MariaDB set up, you can now build the Rekor Server:
 
-```
+```bash
 cd $GOPATH/pkg/mod/github.com/sigstore/rekor@v0.4.0/cmd/rekor-server
 go build -v -o rekor-server
 cp rekor-server /usr/local/bin/
 ```
 
 #### Start the Rekor Server
 
-```
+```bash
 rekor-server serve --enable_retrieve_api=false
 
-2020-09-12T16:32:22.705+0100	INFO	cmd/root.go:87	Using config file: /Users/lukehinds/go/src/github.com/sigstore/rekor-server/rekor-server.yaml
-2020-09-12T16:32:22.705+0100	INFO	app/server.go:55	Starting server...
-2020-09-12T16:32:22.705+0100	INFO	app/server.go:61	Listening on 127.0.0.1:3000
+2020-09-12T16:32:22.705+0100  INFO  cmd/root.go:87  Using config file: /Users/lukehinds/go/src/github.com/sigstore/rekor-server/rekor-server.yaml
+2020-09-12T16:32:22.705+0100  INFO  app/server.go:55  Starting server...
+2020-09-12T16:32:22.705+0100  INFO  app/server.go:61  Listening on 127.0.0.1:3000
 ```
-> If you have a redis server running to enable searching your Rekor server, remove the `enable_reprieve_api` flag 
+
+> If you have a redis server running to enable searching your Rekor server, remove the `enable_reprieve_api` flag
 
 #### Next Steps
 

diff --git a/content/en/logging/overview.md b/content/en/logging/overview.md
@@ -21,21 +21,16 @@ Rekor fulfils the signature transparency role of sigstore’s software signing i
 
 You can download and setup the Rekor Server and Rekor CLI by following the instructions on the [Installation](/logging/installation/) page.
 
-A public instance of Rekor can be found at [rekor.sigstore.dev](https://rekor.sigstore.dev). The public instance offers an SLO
-of 99.5% availability and is monitored by an oncall team.
+A public instance of Rekor can be found at [rekor.sigstore.dev](https://rekor.sigstore.dev). The public instance offers an SLO of 99.5% availability and is monitored by an oncall team.
 
 ## Auditing the Public Instance
 
-Rekor is built on top of a [verifiable data structure](https://transparency.dev/verifiable-data-structures/). Auditors
-can monitor the log for consistency, meaning that the log remains append-only and entries are never mutated or removed.
+Rekor is built on top of a [verifiable data structure](https://transparency.dev/verifiable-data-structures/). Auditors can monitor the log for consistency, meaning that the log remains append-only and entries are never mutated or removed.
 Verifiers can also monitor the log for their identities.
 Learn more about transparency logs [here](https://transparency.dev/), and about binary transparency [here](https://binary.transparency.dev/).
 
 There are few options for auditing and monitoring the Rekor log. We've built a monitor that runs on GitHub Actions,
-[Rekor monitor](https://github.com/sigstore/rekor-monitor). Follow the instructions to set up a new repository and
-use the [provided reusable workflow](https://github.com/sigstore/rekor-monitor/blob/main/.github/workflows/reusable_monitoring.yml)
-to audit the log. You can also monitor the log for specified identities, though
-this feature is a work in progress and supports a limited set of identities and entry types.
+[Rekor monitor](https://github.com/sigstore/rekor-monitor). Follow the instructions to set up a new repository and use the [provided reusable workflow](https://github.com/sigstore/rekor-monitor/blob/main/.github/workflows/reusable_monitoring.yml) to audit the log. You can also monitor the log for specified identities, though this feature is a work in progress and supports a limited set of identities and entry types.
 
 You can also run [omniwitness](https://github.com/transparency-dev/witness/tree/main/cmd/omniwitness) to
 audit the log, built by the team who created Trillian, which provides Rekor's verifiable log.
diff --git a/content/en/logging/sign-upload.md b/content/en/logging/sign-upload.md
@@ -8,11 +8,14 @@ weight: 1835
 This documentation contains information on how to sign and upload data in different [pluggable types](/logging/pluggable-types/).
 
 The following are covered:
+
 - [Minisign](#minisign)
 - [SSH](#ssh)
 - [PKIX/X509](#pkixx509)
-- RPM (TODO)
-- TSR (TODO)
+- [RPM](#rpm)
+- [Alpine](#alpine)
+- [RPM](#rpm-1)
+- [TSR](#tsr)
 - [TUF](#tuf)
 
 ## Minisign
@@ -161,7 +164,7 @@ writing EC key
 Sign the file with:
 
 ```console
-$ openssl dgst -sha256 -sign ec_private.pem -out README.md.sig README.md
+openssl dgst -sha256 -sign ec_private.pem -out README.md.sig README.md
 ```
 
 Upload it to rekor with:
@@ -221,15 +224,15 @@ Generate a TUF repository (for example, with the [Python reference implementatio
 With go-tuf:
 
 ```console
-$ tuf init
-$ tuf gen-key root
-$ tuf gen-key targets
-$ tuf gen-key snapshot
-$ tuf gen-key timestamp
-$ tuf add path/to/some/target.txt
-$ tuf snapshot
-$ tuf timestamp
-$ tuf commit
+tuf init
+tuf gen-key root
+tuf gen-key targets
+tuf gen-key snapshot
+tuf gen-key timestamp
+tuf add path/to/some/target.txt
+tuf snapshot
+tuf timestamp
+tuf commit
 ```
 
 You will find the signed metadata in your TUF `repository/` directory:
@@ -286,5 +289,4 @@ Body: {
     }
   }
 }
-
 ```