snare.conf.5

.Dd 2020-02-10
.Dt SNARE.CONF 5
.Os
.Sh NAME
.Nm snare.conf
.Nd snare configuration file
.Sh DESCRIPTION
.Nm
is the configuration file for
.Xr snare 1 .
It consists of one or more top-level options and one GitHub block.
.Pp
The top-level options are:
.Bl -tag -width Ds
.It Sy listen = Qq Em address ;
is a mandatory address and port number to listen on.
The format of
.Em address
is either:
.Bl -tag -width -Ds
.It x.x.x.x:port
an IPv4 address and port.
For example,
.Ql 0.0.0.0:8765
will listen on port 8765 on for all IPv4 addresses.
.It [x:x:x]:port
an IPv6 address and port.
For example,
.Ql [::]:8765
will listen on port 8765 for all IPv4 and IPv6 addresses.
.El
.It Sy maxjobs = Em int ;
is an optional non-zero positive integer specifying the maximum number of
jobs to run in parallel.
Defaults to the number of CPUs in the machine.
.It Sy user = Qq Em user-name ;
is an optional username that
.Nm
will try and change into after it has bound to a network port.
Note that
.Nm
will refuse to run as root unless
.Sy user
is specified.
As part of changing user,
.Nm :
.Bl -bullet
.It
changes its uid, euid, suid to the UID of
.Em user-name .
.It
changes its gid, egid, sgid to the primary GID of
.Em user-name .
.It
sets the $HOME environment variable to the home directory of
.Em user-name .
.It
sets the $USER environment variable to
.Em user-name .
.El
.Pp
All other environment variables are passed through to commands unchanged.
.It Sy github { ... }
specifies GitHub specific options.
.El
.Pp
A
.Sq github
block supports the following options:
.Bl -tag -width Ds
.It Sy match Qo Em regex Qc { Em match-options }
where
.Em regex
is a regular expression in
.Lk https://docs.rs/regex/ Rust regex format
that must match against a
.Qq owner/repo
full repository name.
If it matches, then
.Em match-options
are applied.
.Qq regex
must match against the full repository name: in other words, it is equivalent
to
.Em ^regex$ .
Thus the regex
.Qq a/b
does not match against the full repository name
.Qq a/bc ,
but the regex
.Qq a/b.*
does match against
.Qo a/bc Qc .
.El
.Pp
A
.Sq match
block supports the following options:
.Bl -tag -width Ds
.It Sy cmd = Qq Em shell-cmd ;
optionally specifies a command to be run.
.Em shell-cmd
will be executed via
.Ql $SHELL -c .
The following escape sequences are recognised and replaced before execution:
.Bl -tag -width Ds
.It Sy %e
the GitHub event type (e.g.
.Ql pull_request ) .
.It Sy %j
the path to the GitHub JSON.
.It Sy %o
the repository owner.
.It Sy %r
the repository.
.It Sy %%
a literal
.Ql % .
.El
.Pp
Note that
.Ql %
may not be followed by any character other than those above.
.Pp
The escape sequences are guaranteed to satisfy the regular expression
.Qq [a-zA-Z0-9._-]+
and not to be the strings
.Qq \&.
or
.Qq .. .
This means that they are safe to pass as shell arguments and/or to be included
in file system paths.
.It Sy errorcmd = Qq Em shell-cmd ;
optionally specifies a command to be run when a job exits unsuccessfully.
.Em shell-cmd
will be executed via
.Ql $SHELL -c .
The following escape sequences are recognised and replaced before execution:
.Bl -tag -width Ds
.It Sy %e
the GitHub event type (e.g.
.Ql pull_request ) .
.It Sy %j
the path to the GitHub JSON.
.It Sy %o
the repository owner.
.It Sy %r
the repository.
.It Sy %s
the path to the file containing the job's combined stderr / stdout.
.It Sy %x
the exit type:
.Qq status
(i.e. normal exit);
.Qq signal ;
or
.Qq unknown .
.It Sy %?
the exit status / signal number (either an integer or the literal string
.Qq unknown )
that
.Em cmd
failed with.
.It Sy %%
a literal
.Ql % .
.El
.Pp
Note that
.Ql %
may not be followed by any character other than those above.
.Pp
The escape sequences are guaranteed to satisfy the regular expression
.Qq [a-zA-Z0-9._-]+
and not to be the strings
.Qq \&.
or
.Qq .. .
This means that they are safe to pass as shell arguments and/or to be included
in file system paths.
.It Sy queue = Po evict | parallel | sequential Pc ;
specifies what to do when multiple requests for the same repository
are queued at once:
.Bl -tag -width Ds
.It Sy evict
only run one job for this repository at a time.
Additional jobs will stay on the queue: if a new job comes in for that
repository, it evicts any previously queued jobs for that repository.
In other words, for this repository there can be at most one running job and
one queued job at any point.
.It Sy parallel
run as many jobs for this repository in parallel as possible.
.It Sy sequential
only run one job for this repository at a time.
Additional jobs will stay on the queue and be executed in FIFO order.
.El
.Pp
The default
.Sy match
block sets this to
.Sy sequential ,
which is always safe, though at the possible expense of lower job throughput
for any given repository.
.It Sy secret = Qq Em secret ;
is the optional GitHub secret used to sign the webhook request.
This allows
.Nm
to tell the difference between genuine webhook requests and those from
malfeasants.
Although this is optional, we
.Em highly
recommend setting it in all cases.
Note also that if a GitHub request is signed, but you have not specified a
secret, then snare will return the request as
.Dq unauthorised
to remind you to use the secret at both ends.
.It Sy timeout = Em period ;
specifies the elapsed time, as a positive integer, in seconds that a
process can run before being sent SIGTERM.
The default
.Sy match
block sets this to one hour (3600 seconds).
.El
.Pp
.Sy match
blocks are evaluated in order from top to bottom with each successful
match overriding previous settings.
A default
.Sy match
block is inserted before any user
.Sy match
blocks:
.Bd -literal -offset 4n
match ".*" {
  queue = sequential;
  timeout = 3600;
}
.Ed
.Sh EXAMPLES
The minimal recommended
.Nm
file is as follows:
.Bd -literal -offset 4n
listen = "<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>";
  }
}
.Ed
.Pp
where
.Qq /path/to/prps
is a path to a directory where per-repo programs are stored.
Each repository then has a unique program
.Qq %o/%r
which will be executed with two arguments: the GitHub event; and the path to
the GitHub JSON.
If a job exits unsuccessfully then an email will be sent to someone@example.com
containing the job's comined stderr and stdout output (assuming that a suitable
sendmail clone has been installed and activated).
.Pp
The top-to-bottom evaluation of match blocks allow users to specify defaults
which are only overridden for specific repositories.
For example, for the following configuration file:
.Bd -literal -offset 4n
listen = "<address>:<port>";
github {
  match ".*" {
    cmd = "/path/to/prps/%o/%r %e %j";
    errorcmd = "cat %s | mailx -s \\"snare error: github.com/%o/%r\\" abc@def.com";
    secret = "sec";
  }
  match "a/b" {
    errorcmd = "lpr %s";
  }
}
.Ed
.Pp
the following repositories will have these settings:
.Bd -literal -offset 4n
a/b:
  queue = sequential
  timeout = 3600
  cmd = "/path/to/prps/%o/%r %e %j";
  errorcmd = "lpr %s";
  secret = "sec"
c/d:
  queue = sequential
  timeout = 3600
  cmd = "/path/to/prps/%o/%r %e %j";
  errorcmd = "cat %s | mailx -s \\"snare error: github.com/%o/%r\\" abc@def.com";
  secret = "sec"
.Ed
.Pp
The following program expects to be called with an event and a JSON path (i.e.
.Qq %e %j )
and uses shell script to send a list of commits and diffs to the address
specified in $EMAIL on each
.Dq push
to master.
It works for any public GitHub repository:
.Bd -literal -offset 4n
#! /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
.Ed
.Pp
where
.Lk https://stedolan.github.io/jq/ jq
is a command-line JSON processor.
Depending on your needs, you can make this type of script arbitrarily more
complex and powerful (for example, not cloning afresh on each pull).
.Pp
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
.Pf ( Dq repo )
rather than a file name from JSON that might
include characters (such as
.Dq ../.. )
that would cause the script to leak data about other parts of the file system.
.Sh SEE ALSO
.Xr snare 1
.Pp
.Lk https://developer.github.com/webhooks/ GitHub's webhooks documentation .
.Sh AUTHORS
.An -nosplit
.Xr snare 1
was written by
.An Laurence Tratt Lk https://tratt.net/laurie/