README.md in csp_report-0.3.0 vs README.md in csp_report-0.4.0
- old
+ new
@@ -16,16 +16,22 @@
page. However, elements have a class so you can add some CSS style before I
add some clean ones in the gem.
I promise something cleaner when I'll get to v1.
+[Installation](#install) | [Upgrade](#upgrade-notes) |
+[Configuration](#trying-it-out) | [Description](#what-is-csp)
+
**Careful**: If migrating from 0.1.x, please follow
[these instructions](#upgrade-from-01x)
**Careful**: If migrating from 0.2.x or below, you can follow
-[these instructions](#upgrade-from-02x). This is not mandatory.
+[these instructions](#upgrade-from-02x-or-below). This is not mandatory.
+**Careful**: If migrating from 0.3.x or below, you can follow
+[these instructions](#upgrade-from-03x-or-below). This is mandatory.
+
What is CSP
===========
CSP (Content Security Policy) is a way to limit cross site scripting by relying
on the browser as a last line of defense. It does not mean the other anti XSS
@@ -46,12 +52,33 @@
Features
========
* Provides a *csp_report* resource that stores the reported violations.
* Displays the violation for analysis
+* Keeps up-to-date with the CSP W3C RFC
* Future: provide visualization aids on the report data
+Why using this gem
+==================
+
+CSP is yet another layer of protection, basically relying on the browser to do
+some level of control. This is a way to prevent some man in the middle attack
+where someone intercepts the server response and try to change it. While not
+foolproof, it's a good additional security layer.
+
+This gem comes in handy for 2 reasons:
+* First, when activating CSP directives on your existing site, it is likely
+that you'll have a hard
+time figuring out all the sources you are using. By recording all the breaches,
+ this gem allows you to setup a policy, run a crawler for example, and then
+look at what is reported as breaches. It will help you getting rid of your
+inline js and so on.
+* Second, in normal production mode, it'll help you monitor the situation and
+see if your server has been victim of some injection (if some input is not
+sanitize properly) or if your users are being attacked in some way (in which
+case you might gather stats and maybe warn them in one way or another).
+
Install
=======
1. In your *Gemfile*, add the following
```
@@ -115,49 +142,52 @@
in one of your HTML rendered file and launch it in a browser. If the setup is
correct and you browser supports CSP, the script will not play (no pop-up) and
you'll have one more record in the /csp/csp_reports list.
+Tuning the engine
+=================
+
+#### Overriding the engine's CSS
+
+The engine comes packages with some CSS so that the page do not look ugly.
+Since it is meant to be available for site admins or developers, the look&feel
+is a secondary concern. Still you might want to customize it for consistency
+with your site.
+This is easy to do. Indeed, all the classes used are namespaced with *csp-report*.
+To customize the CSS, just create the following file:
+*app/assets/stylesheets/csp_report/csp_report.css*
+
+Careful though, this is going to remove all the styles definition, so you'll
+have to redefine every single one of them.
+
+#### Changing the CSP rule per controller/action
+
+TODO - gbataille - Fill in this section
+
Utilities
=========
* For general usage, a constant CspReport::MOUNT_POINT is defined with the
namespace provided while running the install generator. This constant is
typically used in the response header construction.
* For "plugability", as for any engine, rails gives some helper objects. While
I could not get it to work as I wanted, in a view you can use *csp_report.routes.url_helpers*
and it will give you access to all the engine URL helpers.
-Why using this gem
-==================
-
-CSP is yet another layer of protection, basically relying on the browser to do
-some level of control. This is a way to prevent some man in the middle attack
-where someone intercepts the server response and try to change it. While not
-foolproof, it's a good additional security layer.
-
-This gem comes in handy for 2 reasons:
-* First, when activating CSP directives on your existing site, it is likely
-that you'll have a hard
-time figuring out all the sources you are using. By recording all the breaches,
- this gem allows you to setup a policy, run a crawler for example, and then
-look at what is reported as breaches. It will help you getting rid of your
-inline js and so on.
-* Second, in normal production mode, it'll help you monitor the situation and
-see if your server has been victim of some injection (if some input is not
-sanitize properly) or if your users are being attacked in some way (in which
-case you might gather stats and maybe warn them in one way or another).
-
To come
=======
* Customization instructions
* Support of CSP 1.1 draft spec
* Eased data mining
+Upgrade notes
+=============
+
Upgrade from 0.1.x
-==================
+------------------
CAREFUL, 0.2.0 comes with DB changes. I won't do that in a minor after we are at
v1, but for the moment, I thought it would not trouble too many people.
Make sure to run
@@ -165,12 +195,12 @@
rake csp_report:install:migrations
rake db:migrate
```
before continuing
-Upgrade from 0.2.x
-==================
+Upgrade from 0.2.x or below
+---------------------------
Version 0.3.0 comes with a configurable mount point and a couple of helpers that
are accessible through the generators.
While not strictly necessary (at least for the moment nothing depends on it),
I would advise to
@@ -182,9 +212,19 @@
```
* run the initializer generator
```shell
rails generate csp_report:initializer_install
```
+
+Upgrade from 0.3.x or below
+---------------------------
+
+Version 0.4.0 and above introduce a new javascript integration point to add the
+highchart library used to produce some visualization of the reporting data.
+The install generator would provide the additional hook. Rather than re-running
+the entire install (not tested), you can either
+* run the `csp_report:highcharts_include` generator
+* or add the `//= require csp_report` in your application.js file.
License
=======
This project is under a MIT-LICENSE.