Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/phramz/webhug
🤗 A generic webhook dispatcher written in Golang
https://github.com/phramz/webhug
automation continuous-integration deployment webhook
Last synced: about 1 month ago
JSON representation
🤗 A generic webhook dispatcher written in Golang
- Host: GitHub
- URL: https://github.com/phramz/webhug
- Owner: phramz
- License: mit
- Created: 2020-01-25T18:08:48.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-06-20T12:01:54.000Z (5 months ago)
- Last Synced: 2024-06-21T03:37:09.796Z (5 months ago)
- Topics: automation, continuous-integration, deployment, webhook
- Language: Go
- Homepage:
- Size: 121 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Webhug 🤗
==========
A generic webhook dispatcher.
## Build & Run
```
git clone https://github.com/phramz/webhug.git
make build
./webhug
> INFO : 2020/01/25 18:25:03.520102 webhug.go:16: reading config ...
> INFO : 2020/01/25 18:25:03.521061 webhug.go:20: setting up webhook 'example' at path '/example/'
> INFO : 2020/01/25 18:25:03.521134 webhug.go:37: 🤗 webhug listening on :8080 ...
```
With the default config you should now be able to try this:
```
curl -H 'x-auth-token: top secret' -X POST -d '{"some": ["random", "json"]}' http://localhost:8080/example/
> [example] {"some": ["random", "json"]}HOSTNAME=fbc56923c4e7
> [example] SHLVL=1
> [example] HOME=/root
> [example] WEBHUG_WEBHOOK=example
> [example] WEBHUG_REQUEST_HEADER={"Accept":["*/*"],"Content-Length":["28"],"Content-Type":["application/x-www-form-urlencoded"],"User-Agent":["curl/7.64.1"],"X-Auth-Token":["top secret"]}
> [example] RELEASE_VERSION=d770d49e68
> [example] PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
> [example] CUSTOM_ENV_VAR1=hello
> [example] WEBHUG_REQUEST_REMOTE_ADDR=172.17.0.1:48240
> [example] CUSTOM_ENV_VAR2=world!
> [example] WEBHUG_REQUEST_METHOD=POST
> [example] PWD=/etc/webhug
```
## Docker
There is also a docker image available. If you prefer running webhug inside a container try this:
```
docker run --rm -p 8080:8080 gregthebunny/webhug
```
Within the image the default config is located at `/etc/webhug/config.yaml`. To provide your own config you
might either mount it into the container
```
docker run --rm -p 8080:8080 -v /path/to/your/config.yaml:/etc/webhug/config.yaml gregthebunny/webhug
```
or build your on image eg:
```Dockerfile
FROM gregthebunny/webhug
COPY /path/to/your/config.yaml /etc/webhug/config.yaml
```
As the image comes with a docker-in-docker setup (`FROM docker:19.03`) it enables you to
run docker commands within your actions. To do so you need to mount your hosts docker socket into the
container:
```
docker run --rm -p 8080:8080 \
-v /path/to/your/config.yaml:/etc/webhug/config.yaml \
-v /var/run/docker.sock:/var/run/docker.sock \
gregthebunny/webhug
```
## Config
All configuration has to be done in the `config.yaml` file. A working example can be found
in the project root:
```yaml
webhug:
listen: ":8080"
webhooks:
# "example" is the name of the webhook as well as the the endpoint uri eg:
# curl -H 'x-auth-token: top secret' -X POST -d '{"some": ["random", "json"]}' http://localhost:8080/example/
example:
security:
# one of "header" (match header value), "github" (match x-hub-signature), "none" (no security at all), "deny" (deny all)
type: header
key: x-auth-token
value: top secret
action:
# one of "shell" (execute shell command), "none" (do nothing)
type: shell
# if true stdout will be returned in the http response
response: true
# the executable to run
cmd: "/bin/sh"
# arguments that will be passed along to the executable
args: ["-c", "cat; env;"]
# some extra environment variables that will be injected.
env:
- "CUSTOM_ENV_VAR1=hello"
- "CUSTOM_ENV_VAR2=world!"
# ... of course you can configure more than one webhook!
# This one here uses githubstyle authentication:
# curl -H 'x-hub-signature: sha1=01f8da98455877d8beefe6e8276d59ac102857d5' -X POST -d '{"some": ["random", "json"]}' http://localhost:8080/example-github/
example-github:
security:
type: github
secret: super secret
action:
type: shell
response: true
cmd: "/bin/sh"
args: ["-c", "cat; env;"]
env:
- "CUSTOM_ENV_VAR1=hello"
- "CUSTOM_ENV_VAR2=world!"
# this example shows how to pass along values from the request:
# curl -v -X POST -d '{"some": [{"random": "value", "nested": {"value": "json"}}]}' -H 'Content-type: application/json' http://localhost:8080/example-with-template-insecure/
#
# WARNING: If your planing to use values from request as arguments
# beware of command-injection attacks. Take security measures, eg proper escaping etc
# https://owasp.org/www-community/attacks/Command_Injection
# NEVER DO IT THIS WAY!! It is just an example to show what is possible.
example-with-template-insecure:
security:
type: none
action:
type: shell
response: true
cmd: "/bin/sh"
args:
- '-c'
- |
echo 'CUSTOM_ENV_VAR_COMMAND=$CUSTOM_ENV_VAR_COMMAND';
echo 'Request from: {{ .Request.RemoteAddr }}';
echo 'Content-type: {{ index .Request.Header "content-type" }}';
echo 'Body: {{ .Request.Body }}';
echo 'Value: "{{ index .Request.Json.some 0 "random" }}" from "{{ index .Request.Json.some 0 "nested" "value" }}"';
env:
- 'CUSTOM_ENV_VAR_COMMAND={{ index .Env "PWD" }}'
# ... this example shows two more secure ways of doing the same
# curl -v -X POST -d '{"some": [{"random": "value", "nested": {"value": "json"}}]}' -H 'Content-type: application/json' http://localhost:8080/example-with-template/
example-with-template:
security:
type: none
action:
type: shell
response: true
cmd: "/bin/sh"
args:
- '-c'
- |
# either using environment variables like this
echo CUSTOM_ENV_VAR_COMMAND=${CUSTOM_ENV_VAR_COMMAND};
echo Request from: ${CUSTOM_ENV_VAR_REQUEST_FROM};
echo Content-type: ${CUSTOM_ENV_VAR_REQUEST_CTYPE};
echo Body: ${CUSTOM_ENV_VAR_REQUEST_BODY};
echo Value: ${CUSTOM_ENV_VAR_REQUEST_VALUE};
# or take the arguments directly
echo CUSTOM_ENV_VAR_COMMAND=${0};
echo Request from: ${1};
echo Content-type: ${2};
echo Body: ${3};
echo Value: ${4};
- '{{ index .Env "PWD" }}'
- '{{ .Request.RemoteAddr }};'
- '{{ index .Request.Header "content-type" }}'
- '{{ .Request.Body }}'
- '"{{ index .Request.Json.some 0 "random" }}" from "{{ index .Request.Json.some 0 "nested" "value" }}"'
env:
- 'CUSTOM_ENV_VAR_COMMAND={{ index .Env "PWD" }}'
- 'CUSTOM_ENV_VAR_REQUEST_FROM={{ .Request.RemoteAddr }}'
- 'CUSTOM_ENV_VAR_REQUEST_CTYPE={{ index .Request.Header "content-type" }}'
- 'CUSTOM_ENV_VAR_REQUEST_BODY={{ .Request.Body }}'
- 'CUSTOM_ENV_VAR_REQUEST_VALUE="{{ index .Request.Json.some 0 "random" }}" from "{{ index .Request.Json.some 0 "nested" "value" }}"'
```
### Security
The security section lets you configure the authentication for each webhook.
#### Deny
This will deny every request. Might be useful to temporary disable a certain webhook:
```yaml
webhug:
webhooks:
example:
security:
type: deny
```
#### None
*Please do not run any "open" webhooks in production .. nasty things can happen!*
The following example will leave your webhook open for everyone:
```yaml
webhug:
webhooks:
example:
security:
type: none
```
#### Header
The most basic way of access control lets you define a shared secret to be present in the request header.
This is not recommended but better then nothing. Always make sure that you make your endpoint SSL only!
```yaml
webhug:
webhooks:
example:
security:
type: header
key: x-any-header-you-like
value: abc123topsecrettoken
```
Trigger your webhook like that:
```
curl -H 'x-any-header-you-like: abc123topsecrettoken' -X POST http://localhost:8080/example/
```
#### Github
This will check for githubs `X-Hub-Signature` header and validates the digest using the shared secret:
```yaml
webhug:
webhooks:
example:
security:
type: github
secret: 123456789abcdefghi
```
Further readings:
- https://developer.github.com/webhooks/securing/
- https://developer.github.com/webhooks/
### Actions
By now there is only one action supported with more to come.
#### Shell
This will execute the given command and passes the request body to stdin (see example). The following
environment variables will be available by default:
- `WEBHUG_WEBHOOK`: Name of the webhook which triggered the action
- `WEBHUG_REQUEST_METHOD`: The request method
- `WEBHUG_REQUEST_REMOTE_ADDR`: The remote address which triggered the action
### Templating
Some config keys will be interpolated to add some further flexibility to your configuration.
The string interpolation will be done via Golang templating. If your not familiar with the syntax this
cheat sheet might come in handy:
https://curtisvermeeren.github.io/2017/09/14/Golang-Templates-Cheatsheet
The actual keys which values could be templated the following:
- `webhug.webhooks.<*>.security[type=header].key`
- `webhug.webhooks.<*>.security[type=header].value`
- `webhug.webhooks.<*>.security[type=github].secret`
- `webhug.webhooks.<*>.action[type=shell].args.<*>`
- `webhug.webhooks.<*>.action[type=shell].env.<*>`
During rendering you have access to this data:
```go
struct {
// all environment variable of the context webhug is running in are here
Env map[string]string
Webhook struct {
Name string
Format string
}
Request struct {
Body string
Method string
// if a POST request comes with a json content-type header
// the body will be automatically deserialized and could be access via
// this property.
Json interface{}
Uri string
Host string
RemoteAddr string
Query string
Scheme string
Username string
Password string
// all headers lowercase CanonicalMIMEHeaderKeys
Header map[string]string
// all variables from the requests query string
Get map[string][]string
// see https://golang.org/pkg/net/http/#Cookie
Cookie map[string]*http.Cookie
}
}
```
## Github Actions
If you want to trigger Webhugs out of your Github Actions you might find this useful:
https://github.com/phramz/webhug-action
## License
```
The MIT License (MIT)
Copyright (c) 2020 Maximilian Reichel
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```