Add READMEHEADv0.1.0master

1 files changed, 65 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..44b7f0a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# Prometheus Exporter for Content Security Policy violations
+
+`csp_exporter` is a web server that listens for reports of [Content Security
+Policy][csp] violations and exposes the reports as Prometheus metrics so that
+you can incorporate CSP violations into your normal monitoring and alerting
+process.
+
+## How to Use
+
+First, download and build `csp_exporter`. If you have the Go compiler tools
+installed, this should be a familiar process. Either `git clone
+https://git.burwell.io/csp_exporter` and run `go build`, or `go get
+bnbl.io/csp_exporter`.
+
+Next, start the server. You'll probably want to run it under some kind of
+supervisor depending on your OS. By default, a web server accepting CSP reports
+is started on port 80 and a Prometheus metrics server is started on port 9477.
+You can override these by setting the `COLLECTOR_BIND_ADDR` and `PROM_BIND_ADDR`
+environment variables, respectively.
+
+Once you have the server running, add the appropriate `report-uri` directive to
+your content security policy. For example, you might add the following header to
+your HTTP responses:
+
+```
+Content-Security-Policy: default-src 'none'; report-uri https://csp-exporter.example.com/report/csp/mysite
+```
+
+Note the `/report/csp/mysite` path. The `csp_exporter` accepts reports sent to
+`/report/csp/<app>`, where `<app>` can be any URL path fragment. Whatever the
+`<app>` is set to will be included as the value for the `app` label in your
+metrics; this allows you to use `csp_exporter` to collect violation reports for
+different websites, test different policy versions, etc.
+
+Finally, configure Prometheus to scrape metrics from `csp_exporter` by adding
+something like the following to your `prometheus.yml`:
+
+```yml
+scrape_configs:
+- job_name: "csp"
+  static_configs:
+  - targets: ["cspexporter.intra.example.com:9477"]
+```
+
+You will now start to accumulate `csp_violation_reports_total` metrics in your
+Prometheus system. The labels are derived from the fields provided in the
+violation reports and should allow for very granular queries. If you are not
+interested in high granularity or are concerned with recording many discrete
+time series, you may want to add a [`relabel_config`][relabel] to your CSP
+scrape job to drop some of the labels.
+
+## Contributing
+
+Send patches to <ben@benburwell.com>. For instructions about how to mail
+patches, see [`git-send-email(1)`][gitsendemail], [the Pro Git book][progit], or
+<https://git-send-email.io>.
+
+## License
+
+MIT
+
+[csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+[relabel]: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config
+[gitsendemail]: https://git-scm.com/docs/git-send-email
+[progit]: https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_project_over_email