webhookey/README.md

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.

Further, for Rocket we need to have the nightly toolchain installed:

    rustup toolchain install nightly

Build Webhookey

The webhookey project can be built for development:

    cargo b

or for releasing:

    cargo b --release

Install Webhookey

When a Rust toolchain installed you can also install Webhookey directly without cloning it manualy:

    cargo install --git https://git.onders.org/finga/webhookey.git webhookey

or from within the project:

    cargo install webhookey

Run Webhookey

Webhookey can either be run from the project directory with:

    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:

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) 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:

allow:
  - 127.0.0.1
  - 127.0.0.1/31
  - "::1"

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
• 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