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.

2. 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.