diff options
authorMichael Fincham <michael@hotplate.co.nz>2017-11-22 13:42:52 +1300
committerGitHub <noreply@github.com>2017-11-22 13:42:52 +1300
commita3e421594f849639a564cf8c144221558cbc113a (patch)
parent987f31396ead2bb1425cd1be4538ead7c707bc15 (diff)
Update README.md
1 files changed, 43 insertions, 1 deletions
diff --git a/README.md b/README.md
index eab74ec..a81b9af 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,44 @@
# piecework
-Barebones demo application using osquery to show out of date packages on Debian and Ubuntu hosts
+**This is a bit of an ugly fork of some open source code we've been building as part of a larger project at work, forked for BSides Wellington 2017. Once we decide how to structure the project better this repo will be replaced by a link to the official one over at [Catalyst](https://github.com/catalyst/).**
+## What is this?
+This demo combines both [osquery-controller](https://github.com/fincham/osquery-controller) and [advisory-feeds](https://github.com/fincham/advisory-feeds) to show a realtime feed of what packages are vulnerable to a security advisory on a set of osquery nodes.
+## How do I set it up?
+`python-apt` isn't installable easily from pip (it has silent deps on things which are not in PyPi), so you may need to:
+ ln -s /usr/lib/python3/dist-packages/apt* $VIRTUAL_ENV/lib/python*/site-packages
+And install the `python-apt` package outside of the virtualenv.
+Once the application is working you'll want to run `manage.py updateadvisories` periodically to update your database. Probably once every 24 hours is sufficient and shouldn't place undue burden on the upstream information sources.
+You'll need to set a few values in `settings.py` then deploy the demo as you usually would for Django (for instance, you might like to use a WSGI server such as `waitress`). Most importantly the database connection (sqlite is fine), and the `OSQUERY_ENROLL_SECRET` settings will need to be changed.
+### HTTPS in development
+`osqueryd` likes to talk to an HTTPS endpoint. The normal `python manage.py runserver` development server in Django doesn't do HTTPS.
+The easiest way to resolve this is to use something like `stunnel` to proxy incoming HTTPS connections back to the Django development server.
+An example `stunnel` configuration to do this:
+ cert = test_server.pem
+ key = test_server.key
+ foreground = yes
+ pid = /tmp/hotplate-hosts-stunnel-dev.pid
+ [api]
+ accept = localhost:4433
+ connect = 8000
+`stunnel` can then be launched from the directory where the configuration is kept, e.g. by running `stunnel ./stunnel.conf`
+Once `stunnel` is runnning then `osqueryd` may connect to `localhost` on port `4433`.
+## What is this for?
+This shows one way that having machine readable advisory information and realtime host package information can be used to produce actionable security alerts.