Usage: snare [-c <config-path>] [-d]where:
-c <config-path> is a path to a snare.conf configuration
file. If not specified, snare will assume the configuration file
is located at /etc/snare/snare.conf.
-d tells snare not to daemonise: in other words, snare stays
in the foreground. This can be useful for debugging.
The minimal recommended configuration file is:
listen = "<ip-address>:<port>";
github {
match ".*" {
cmd = "/path/to/prps/%o/%r %e %j";
errorcmd = "cat %s | mailx -s \"snare error: github.com/%o/%r\" someone@example.com";
secret = "<secret>";
}
}
where:
<ip-address> is either an IPv4 or IPv6 address and
<port> a port on which an HTTP server will listen.
cmd is the command that will be executed when a webhook is received. In
this case, /path/to/prps is a path to a directory where per-repo programs
are stored. For a repository repo owned by owner the command:
/path/to/prps/<owner>/<repo> <event>will be run. The file
<repo> must be executable. Note that commands are
run with their current working directory set to a temporary directory to
which they can freely write and which will be automatically removed when
they have completed.
errorcmd is the command that will be run when a cmd exits
unsuccessfully. In this example, an email is sent to someone@example.com
with a body consisting of the comined stedrr/stdout. This assumes that you
have installed, set-up, and enabled a suitable sendmail clone.
<secret> is the GitHub secret used to sign the webhook
request and thus allowing snare to tell the difference between genuine
webhook requests and those from malfeasants.
/path/to/prps/softdevteam/snare pull_request /path/to/jsonwill be executed, where:
pull_request is the name of the GitHub event
/path/to/json is a path to a file containing the complete GitHub JSON for that event.
softdevteam_snare program can then execute whatever it wants. In order to
work out precisely what event has happened, you will need to read GitHub's webhooks
documentation.
$EMAIL on each push to master. It works for any public GitHub repository:
#! /bin/sh
set -euf
# A list of email addresses separated by spaces.
EMAILS="someone@example.com someone.else@example.com"
# A GitHub URL either https or git.
REPO_URL="git@github.com:owner/repo.git"
if [ "$1" != "push" ]; then
exit 0
fi
ref=`jq .ref "$2" | tr -d '\"'`
if [ "$ref" != "refs/heads/master" ]; then
exit 0
fi
repo_fullname=`jq .repository.full_name "$2" | tr -d '\"'`
repo_url=`jq .repository.html_url "$2" | tr -d '\"'`
before_hash=`jq .before "$2" | tr -d '\"'`
after_hash=`jq .after "$2" | tr -d '\"'`
echo "$before_hash" | grep -E "^[a-fA-F0-9]+$" 2>&1 > /dev/null
echo "$after_hash" | grep -E "^[a-fA-F0-9]+$" 2>&1 > /dev/null
git clone "$REPO_URL" repo
cd repo
for email in `echo "$EMAILS"`; do
git log --reverse -p "$before_hash..$after_hash" | mail -s "Push to $repo_fullname" "$email"
done
where jq is a command-line JSON
processor. Depending on your needs, you can make this type of script
arbitrarily more complex and powerful (e.g. not cloning afresh on each pull).
Note that this program is deliberately untrusting of external input: it is
careful to quote all arguments obtained from JSON; and it uses a fixed
directory name (repo) rather than use a file name from JSON that might include
characters (e.g. ../..) that would cause the script to leak data
about other parts of the file system.
Settings > Webhooks > Add
webhook. For payload, specify http://yourmachine.com:port/,
specify a secret (which you will then reuse as the secret in
snare.conf) and then choose which events you wish GitHub to
deliver. For example, the default “Just the push event” works well with the email
diff sending per-repo program above, but you can specify whichever events you
wish.