webhookey/README.md

154 lines
3.8 KiB
Markdown
Raw Normal View History

# Webhookey
Webhookey is a webserver listening for requests as for example sent by
gitea's webhooks. Further, Webhookey allows you to specifiy rules
which are matched against the data received to trigger certain
actions.
## Build
### Install Rust
Install the Rust toolchain from [rustup.rs](https://rustup.rs).
Further, for Rocket we need to have the nightly toolchain installed:
``` sh
rustup toolchain install nightly
```
### Build Webhookey
The webhookey project can be built for development:
``` sh
cargo b
```
or for releasing:
``` sh
cargo b --release
```
### Install Webhookey
When a Rust toolchain installed you can also install Webhookey
directly without cloning it manualy:
``` sh
cargo install --git https://git.onders.org/finga/webhookey.git webhookey
```
or from within the project:
``` sh
cargo install webhookey
```
### Run Webhookey
Webhookey can either be run from the project directory with:
``` sh
cargo b
```
or you can copy the produced binary somewhere else from
`webhookey/target/{debug, release}/webhookey` depending on which one
you built.
## Configuration
Configuration syntax is YAML and it's paths as well as it's
configuration format is described in the following sections.
### Configuration paths
Following locations are checked for a configuration file:
- `/etc/webhookey/config.yml`
- `<config_dir>/webhookey/config.yml`
- `./config.yml`
Whereas `<config_dir>` depends on the platform:
- Linux: `$XDG_CONFIG_HOME` or `$HOME/.config`
- macOS: `$HOME/Library/Application Support`
- Windows: `{FOLDERID_RoamingAppData}`
### Configuration parameters
#### Hooks
With `hooks` you can configure a sequence of hooks. A single hook
consists of the following fields:
- command: A command to be executed if a filter matches
- allow/deny: An optional parameter to either allow or deny specific
source addresses or ranges.
- signature: Name of the HTTP header field containing the signature.
- secrets: List of secrets.
- filters: List of filters.
Example:
```yaml
hooks:
hook1:
command: /usr/bin/local/script_xy.sh {{ /repository/name }}
signature: X-Gitea-Signature
ip_filter:
allow:
- 127.0.0.1
- 127.0.0.1/31
secrets:
- secret_key_01
- secret_key_02
filters:
match_ref:
pointer: /ref
regex: refs/heads/master
```
##### Command
To pass data to a command following two different methods can be used.
Example: `script_foo {{ header X-Gitea-Event }} {{ /field/foo }}`
###### JSON Pointers
Use JSON pointers ([RFC 6901](https://tools.ietf.org/html/rfc6901))
point to values of a JSON field from the JSON data.
Example: `{{ /field/pointed/to }}`.
###### Header
Use values from header fields sent with the HTTP request.
Example: `{{ header X-Gitea-Event }}`.
##### Allow and Deny
To allow or deny specific network ranges source is an optional
configuration parameter which either contains an allow or a deny field
with sequences containing networks. Note that IPv6 addresses have to
be put in single quotes due to the colons.
Example:
```yaml
allow:
- 127.0.0.1
- 127.0.0.1/31
- "::1"
```
```yaml
deny:
- 127.0.0.1
- 127.0.0.1/31
- "::1"
```
##### Signature
Set the name of the HTTP header field containing the HMAC signature.
##### Secrets
Configure a list of secrets to validate the hook.
##### Filter
Each filter must have following fields:
- pointer: pointer to the JSON field according to [RFC
6901](https://tools.ietf.org/html/rfc6901)
- regex: regular expression which has to match the field pointed to by
the pointer
# TODOs
## Use `clap` to parse command line arguments
## Configure rocket via config.yml
## Security
### https support
basically supported, but related to "Configure rocket via config.yml".
### Authentication features
## Use proptest or quickcheck for tests of parsers