{"id":13815630,"url":"https://github.com/softdevteam/snare","last_synced_at":"2025-04-08T04:16:34.702Z","repository":{"id":35851366,"uuid":"219605018","full_name":"softdevteam/snare","owner":"softdevteam","description":"snare: GitHub webhooks daemon","archived":false,"fork":false,"pushed_at":"2025-02-28T16:42:10.000Z","size":491,"stargazers_count":64,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T16:23:11.719Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://tratt.net/laurie/src/snare/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softdevteam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-04T22:01:35.000Z","updated_at":"2025-02-28T16:42:09.000Z","dependencies_parsed_at":"2023-02-12T22:45:58.175Z","dependency_job_id":"9b53f1c6-2df5-4a4d-8108-8da76e619dd2","html_url":"https://github.com/softdevteam/snare","commit_stats":{"total_commits":179,"total_committers":3,"mean_commits":"59.666666666666664","dds":"0.011173184357541888","last_synced_commit":"94d2827497e93fec94ed247378b6f412ed6c1e77"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softdevteam%2Fsnare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softdevteam%2Fsnare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softdevteam%2Fsnare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softdevteam%2Fsnare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softdevteam","download_url":"https://codeload.github.com/softdevteam/snare/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247773720,"owners_count":20993639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T04:03:42.963Z","updated_at":"2025-04-08T04:16:34.687Z","avatar_url":"https://github.com/softdevteam.png","language":"Rust","funding_links":[],"categories":["Rust","others"],"sub_categories":[],"readme":"# snare\n\n`snare` is a GitHub webhooks daemon. When `snare` receives a webhook event from\na given repository, it authenticates the request, and then executes a\nuser-defined \"per-repo program\" with information about the webhook event.\n\n\n## Install\n\n`snare` requires rustc-1.40.0 or greater.\n\nTo install `snare` on a per-user basis, use `cargo install snare`.\n\nTo install `snare` globally and/or for packaging purposes, download the latest\nstable version from [`snare`'s homepage](https://tratt.net/laurie/src/snare/).\nYou may use `cargo` to build snare locally or you may use the `Makefile` to\nbuild and install `snare` in traditional Unix fashion. `make install` defaults\nto installing in `/usr/local`: you can override this by setting the `PREFIX`\nvariable to another path (e.g. `PREFIX=/opt/local make`).\n\n\n## Quick setup\n\n`snare` has the following command-line format:\n\n```\nUsage: snare [-c \u003cconfig-path\u003e] [-d]\n```\n\nwhere:\n\n * `-c \u003cconfig-path\u003e` is a path to a `snare.conf` configuration file. If not\n   specified, `snare` will assume the configuration file is located at\n   `/etc/snare/snare.conf`.\n * `-d` tells `snare` *not* to daemonise: in other words, `snare` stays in the\n   foreground. This can be useful for debugging.\n\nThe [man page for snare](https://softdevteam.github.io/snare/snare.1.html) contains\nmore details.\n\nThe minimal recommended configuration file is:\n\n```\nlisten = \"\u003cip-address\u003e:\u003cport\u003e\";\n\ngithub {\n  match \".*\" {\n    cmd = \"/path/to/prps/%o/%r %e %j\";\n    errorcmd = \"cat %s | mailx -s \\\"snare error: github.com/%o/%r: %x %?\\\" someone@example.com\";\n    secret = \"\u003csecret\u003e\";\n  }\n}\n```\n\nwhere:\n\n * `ip-address` is either an IPv4 or IPv6 address and `port` a port on which an\n   HTTP server will listen.\n * `cmd` is the command that will be executed when a webhook is received. In\n   this case, `/path/to/prps` is a path to a directory where per-repo programs\n   are stored. For a repository `repo` owned by `owner` the command:\n\n     ```\n     /path/to/prps/\u003cowner\u003e/\u003crepo\u003e \u003cevent\u003e \u003cpath-to-github-json\u003e\n     ```\n\n   will be run. The file `\u003crepo\u003e` must be executable. Note that commands are\n   run with their current working directory set to a temporary directory to\n   which they can freely write and which will be automatically removed when\n   they have completed.\n * `errorcmd` is the command that will be run when a `cmd` exits\n   unsuccessfully. In this example, an email is sent to `someone@example.com`\n   with a title indicating the reason for non-zero exit (`%x %?`) and a body\n   consisting of the comined stedrr/stdout. This assumes that you have\n   installed, set-up, and enabled a suitable `sendmail` clone.\n * `secret` is the GitHub secret used to sign the webhook request and thus\n   allowing `snare` to tell the difference between genuine webhook requests\n   and those from malfeasants.\n\nThe [man page for\nsnare.conf](https://softdevteam.github.io/snare/snare.conf.5.html) contains the\ncomplete list of configuration options.\n\n\n## Commands\n\n`snare` can be used to run any command runnable from the Unix shell. The\n\"per-repo program\" model as documented above is one common way of doing this.\nFor example, `snare`'s GitHub\nrepository is\n[`https://github.com/softdevteam/snare`](https://github.com/softdevteam/snare).\nIf we set up a web hook up for that repository that notifies us of pull request\nevents, then with the above `snare.conf`, the command:\n\n```sh\n/path/to/prps/softdevteam/snare pull_request /path/to/json\n```\n\nwill be executed, where: `pull_request` is the name of the GitHub event; and\n`/path/to/json` is a path to a file containing the complete GitHub JSON for\nthat event. The `softdevteam/snare` program can then execute whatever it wants.\nIn order to work out precisely what event has happened, you will need to read\n[GitHub's webhooks documentation](https://developer.github.com/webhooks/).\n\n\n## Example per-repo program\n\nUsers can write per-repo programs in whatever system/language they wish, so\nlong as the matching file is marked as executable. The following simple example\nuses shell script to send a list of commits and diffs to the address specified\nin `$EMAIL` on each `push` to master. It works for any public GitHub\nrepository:\n\n```sh\n#! /bin/sh\n\nset -eufx\n\n# A list of email addresses separated by spaces.\nEMAILS=\"someone@example.com someone.else@example.com\"\n# A GitHub URL either https or git.\nREPO_URL=\"git@github.com:owner/repo.git\"\n\nif [ \"$1\" != \"push\" ]; then\n    exit 0\nfi\n\nref=`jq .ref \"$2\" | tr -d '\\\"'`\nif [ \"$ref\" != \"refs/heads/master\" ]; then\n    exit 0\nfi\n\nrepo_fullname=`jq .repository.full_name \"$2\" | tr -d '\\\"'`\nrepo_url=`jq .repository.html_url \"$2\" | tr -d '\\\"'`\nbefore_hash=`jq .before \"$2\" | tr -d '\\\"'`\nafter_hash=`jq .after \"$2\" | tr -d '\\\"'`\necho \"$before_hash\" | grep -E \"^[a-fA-F0-9]+$\" 2\u003e\u00261 \u003e /dev/null\necho \"$after_hash\" | grep -E \"^[a-fA-F0-9]+$\" 2\u003e\u00261 \u003e /dev/null\n\ngit clone \"$REPO_URL\" repo\ncd repo\nfor email in `echo \"$EMAILS\"`; do\n    git log --reverse -p \"$before_hash..$after_hash\" | mail -s \"Push to $repo_fullname\" \"$email\"\ndone\n```\n\nwhere [`jq`](https://stedolan.github.io/jq/) is a command-line JSON processor.\nDepending on your needs, you can make this type of script arbitrarily more\ncomplex and powerful (e.g. not cloning afresh on each pull).\n\nNote that this program is deliberately untrusting of external input: it is\ncareful to quote all arguments obtained from JSON; and it uses a fixed\ndirectory name (`repo`) rather than use a file name from JSON that might\ninclude characters (e.g. `../..`) that would cause the script to leak data\nabout other parts of the file system.\n\n\n## Integration with GitHub\n\n`snare` runs an HTTP server which GitHub can send webhook requests to.\nConfiguring a webhook for a given GitHub repository is relatively simple: go to\nthat repository, then `Settings \u003e Webhooks \u003e Add webhook`. For `payload`,\nspecify `http://yourmachine.com:port/`, specify a `secret` (which you will then\nreuse as the `secret` in `snare.conf`) and then choose which events you wish\nGitHub to deliver. For example, the default `Just the push event` works well\nwith the email diff sending per-repo program above, but you can specify\nwhichever events you wish.\n\nOnce you have set up your webhook, GitHub will automatically send a test \"ping\"\nmessage. `snare` acknowledges pings (i.e. confirms to GitHub that it is\nrunning), but does not execute any commands in response to pings.\n\n\n## HTTPS/TLS\n\n`snare` runs an HTTP server. If you wish, as is recommended, to send your\nwebhooks over an encrypted connection, you will need to run a proxy in front of\nsnare e.g.\n[nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) or\n[relayd](https://man.openbsd.org/relayd.8).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftdevteam%2Fsnare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftdevteam%2Fsnare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftdevteam%2Fsnare/lists"}