Skip to content

Commit

Permalink
Spruce up the readme
Browse files Browse the repository at this point in the history
  • Loading branch information
nsmith5 committed Jan 8, 2022
1 parent 14575f4 commit 04efedb
Showing 1 changed file with 108 additions and 3 deletions.
111 changes: 108 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,111 @@
# πŸ” Rekor Sidekick

Rekor Sidekick monitors a Rekor signature transparency log and forwards
events of interest where ever you like.
Rekor Sidekick monitors a Rekor signature transparency log and forwards events
of interest where ever you like.

> NB: πŸ› οΈ This software is prerelease!
```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Event Policies β”‚
β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β–²β”€β”€β”€β”€β”€β”€β”˜
β”‚ β”‚
Decision β”‚ β”‚ Should forward entry?
β”‚ β”‚
β”‚ β”‚
β”‚ β”‚ Outputs
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”
β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Rekor Log β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Ί Rekor Sidekick β”‚ ───────────────► Pager Duty β”‚
β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ Pull entries β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”¬β”€β”¬β”˜
β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ β”‚ └─────────────────► Stdout β”‚
β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚ β”‚
β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ └───────────────────► Loki β”‚
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
└─────────────────────► ... β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```

## Installation

To install `rekor-sidekick` grab the latest release from our [Github releases
page](https://github.com/nsmith5/rekor-sidekick/releases).

### Verifying a release

Releases are signed and can be verified as follows

```bash
export VERSION="0.1.0"
export ARCH="linux_amd64"
curl -sL "https://github.com/nsmith5/rekor-sidekick/releases/download/v${VERSION}/rekor-sidekick_${VERSION}_${ARCH}.tar.gz" > rekor-sidekick_${VERSION}_${ARCH}.tar.gz
curl -sL "https://github.com/nsmith5/rekor-sidekick/releases/download/v${VERSION}/checksums.txt" > checksums.txt
curl -sL "https://github.com/nsmith5/rekor-sidekick/releases/download/v${VERSION}/checksums.txt.sig" > checksums.txt.sig

export COSIGN_EXPERIMENTAL=1
cosign verify-blob --signature $(cat checksums.txt.sig) checksums.txt
```

The cosign verification step must output sometime to the affect of

```
Certificate is trusted by Fulcio Root CA
Email: []
URI: https://github.com/nsmith5/rekor-sidekick/.github/workflows/release.yml@refs/tags/v0.1.0
Issuer: https://token.actions.githubusercontent.com
Verified OK
tlog entry verified with uuid: "e530fe7cb3da2ab69535208e54d0c8c63accba35dd75b405c50f23a5093ca712" index: 1029416
```

> NB: The URI should having a version tag matchine `VERSION` and the issuer
> should be https://token.actions.githubusercontent.com. the tlog entry uuid
> and index are not important.
Finally, hash the release and make sure it matches what you see in `checksums.txt`

```
# Authorized checksums
cat checksums.txt
# Received checksum. Should be in the list of checksums above.
sha256sum rekor-sidekick_${VERSION}_${ARCH}.tar.gz
```

## Usage

`rekor-sidekick` requires a rekor server, alert policies and alert outputs to be configured. A basic
example configuration looks like the following:

```yaml
# config.yaml
server: https://rekor.sigstore.dev
policies:
- name: alert-all
description: |
Alert all policies alerts on every entry in the transparency log
body: |
package sidekick
default alert = true
outputs:
stdout:
enabled: true
```
Launch `rekor-sidekick` by pointing to the config file

```
rekor-sidekick --config /path/to/config.yaml
```
## Configuration
> TODO: write a thorough configuration guide including policy writing and
> description of all the output drivers?
### Writing Alert Policies
### Outputs

0 comments on commit 04efedb

Please sign in to comment.