aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
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)
treed7cce7ad41713775b68614af2f9b99b0dd5da141
parent987f31396ead2bb1425cd1be4538ead7c707bc15 (diff)
downloadpiecework-a3e421594f849639a564cf8c144221558cbc113a.tar.gz
piecework-a3e421594f849639a564cf8c144221558cbc113a.tar.bz2
piecework-a3e421594f849639a564cf8c144221558cbc113a.zip
Update README.md
-rw-r--r--README.md44
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.