Skip to content

README.md

Latest commit

 

History

History
141 lines (95 loc) · 3.17 KB

README.md

File metadata and controls

141 lines (95 loc) · 3.17 KB

Reported

A Rails engine that collects, stores and notifies on Slack about Content Security Policy (CSP) violation reports.

Features

  • Public /csp-reports endpoint for browsers to POST CSP violations
  • Stores CSP reports in a database table
  • Tracks notification status with notified_at column
  • Optional Slack notifications for CSP violations
  • Easy integration with Rails applications

Requirements

  • Ruby >= 3.2
  • Rails >= 7.1
  • PostgreSQL (for JSONB support)

Installation

Add this line to your application's Gemfile:

gem 'reported'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install reported

Setup

  1. Run the install generator:
$ rails generate reported:install

This will create an initializer at config/initializers/reported.rb.

  1. Run the migrations:
$ rails reported:install:migrations
$ rails db:migrate

This creates the reported_reports table.

The CSP reports endpoint is automatically available at /csp-reports (no mounting required).

Configuration

Content Security Policy

Configure your application's CSP to send reports to the endpoint. In config/initializers/content_security_policy.rb:

Rails.application.config.content_security_policy do |policy|
  policy.default_src :self, :https
  policy.script_src  :self, :https
  # ... your other CSP directives ...
  
  # Configure the report URI
  policy.report_uri "/csp-reports"
end

Slack Notifications

To enable Slack notifications, configure the initializer at config/initializers/reported.rb:

Reported.configuration do |config|
  # Enable or disable Slack notifications
  config.enabled = true

  # Slack webhook URL for notifications
  config.slack_webhook_url = ENV['REPORTED_SLACK_WEBHOOK_URL']
end

Get your Slack webhook URL from Slack API.

Set the webhook URL as an environment variable:

REPORTED_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Usage

Once configured, the gem automatically:

  1. Receives CSP violation reports at /reported/csp-reports
  2. Stores them in the reported_reports table
  3. Sends notifications to Slack (if enabled)
  4. Marks reports as notified with the notified_at timestamp

Accessing Reports

You can access reports through the Reported::Report model:

# Get all reports
Reported::Report.all

# Get unnotified reports
Reported::Report.not_notified

# Get notified reports
Reported::Report.notified

# Mark a report as notified manually
report = Reported::Report.first
report.mark_as_notified!

Database Schema

The reported_reports table includes:

  • document_uri - The URI of the document where the violation occurred
  • violated_directive - The CSP directive that was violated
  • blocked_uri - The URI that was blocked
  • original_policy - The complete CSP policy
  • raw_report - The complete JSON report from the browser
  • notified_at - Timestamp of when the report was sent to Slack
  • created_at / updated_at - Standard timestamps

License

The gem is available as open source under the terms of the MIT License.