Bugzilla – Attachment 193952 Details for
Bug 38365
Add Content-Security-Policy HTTP header to HTML responses
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Help
|
New Account
|
Log In
[x]
|
Forgot Password
Login:
[x]
[patch]
Bug 38365: Add CSP violation reporting API endpoint
Bug-38365-Add-CSP-violation-reporting-API-endpoint.patch (text/plain), 16.65 KB, created by
David Cook
on 2026-02-26 02:06:55 UTC
(
hide
)
Description:
Bug 38365: Add CSP violation reporting API endpoint
Filename:
MIME Type:
Creator:
David Cook
Created:
2026-02-26 02:06:55 UTC
Size:
16.65 KB
patch
obsolete
>From d0fef4ea2521598eea1f0cdd9c4957c1ba10b072 Mon Sep 17 00:00:00 2001 >From: Martin Renvoize <martin.renvoize@openfifth.co.uk> >Date: Mon, 2 Feb 2026 10:34:19 +0000 >Subject: [PATCH] Bug 38365: Add CSP violation reporting API endpoint > >Add /api/v1/public/csp-reports endpoint to receive and log >Content-Security-Policy violation reports from browsers. > >When CSP is configured with a report-uri directive pointing to this >endpoint, browsers will POST violation reports whenever a CSP rule >is violated. These reports are logged using Koha's logging system >for administrator review. > >Features: >- Public endpoint (no authentication required, as browsers send > these reports automatically) >- Logs violations at WARN level with key details (violated directive, > blocked URI, document URI, source location) >- Logs full report at DEBUG level for detailed analysis >- Accepts both application/csp-report and application/json content types > >Configuration example (in koha-conf.xml csp_header_value): > ...; report-uri /api/v1/public/csp-reports > >Log4perl configuration to capture CSP violations: > log4perl.logger.api.csp = WARN, CSP > log4perl.appender.CSP = Log::Log4perl::Appender::File > log4perl.appender.CSP.filename = /var/log/koha/csp-violations.log > log4perl.appender.CSP.layout = PatternLayout > log4perl.appender.CSP.layout.ConversionPattern = [%d] %m%n > >Also updates koha-conf.xml documentation with CSP configuration guidance. > >Signed-off-by: David Cook <dcook@prosentient.com.au> >Signed-off-by: Lari Taskula <lari.taskula@hypernova.fi> >Signed-off-by: David Cook <dcook@prosentient.com.au> >--- > Koha/REST/V1/CSPReports.pm | 94 ++++++++++++++++++++ > api/v1/swagger/definitions/csp_report.yaml | 47 ++++++++++ > api/v1/swagger/paths/public_csp_reports.yaml | 43 +++++++++ > api/v1/swagger/swagger.yaml | 4 + > debian/templates/koha-conf-site.xml.in | 30 +++++++ > etc/koha-conf.xml | 30 +++++++ > t/db_dependent/api/v1/public/csp_reports.t | 80 +++++++++++++++++ > 7 files changed, 328 insertions(+) > create mode 100644 Koha/REST/V1/CSPReports.pm > create mode 100644 api/v1/swagger/definitions/csp_report.yaml > create mode 100644 api/v1/swagger/paths/public_csp_reports.yaml > create mode 100755 t/db_dependent/api/v1/public/csp_reports.t > >diff --git a/Koha/REST/V1/CSPReports.pm b/Koha/REST/V1/CSPReports.pm >new file mode 100644 >index 00000000000..874ea9144e8 >--- /dev/null >+++ b/Koha/REST/V1/CSPReports.pm >@@ -0,0 +1,94 @@ >+package Koha::REST::V1::CSPReports; >+ >+# Copyright 2025 Koha Development Team >+# >+# This file is part of Koha. >+# >+# Koha is free software; you can redistribute it and/or modify it >+# under the terms of the GNU General Public License as published by >+# the Free Software Foundation; either version 3 of the License, or >+# (at your option) any later version. >+# >+# Koha is distributed in the hope that it will be useful, but >+# WITHOUT ANY WARRANTY; without even the implied warranty of >+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the >+# GNU General Public License for more details. >+# >+# You should have received a copy of the GNU General Public License >+# along with Koha; if not, see <https://www.gnu.org/licenses>. >+ >+use Modern::Perl; >+ >+use Mojo::Base 'Mojolicious::Controller'; >+ >+use Koha::Logger; >+ >+=head1 NAME >+ >+Koha::REST::V1::CSPReports - Controller for Content-Security-Policy violation reports >+ >+=head1 DESCRIPTION >+ >+This controller provides an endpoint to receive CSP violation reports from browsers. >+Reports are logged using Koha's logging system for analysis and debugging. >+ >+=head1 METHODS >+ >+=head2 add >+ >+Receives a CSP violation report and logs it. >+ >+Browsers send CSP violations as JSON POST requests when a Content-Security-Policy >+is violated. This endpoint logs those reports for administrator review. >+ >+=cut >+ >+sub add { >+ my $c = shift->openapi->valid_input or return; >+ >+ my $report = $c->req->json; >+ >+ # CSP reports come wrapped in a 'csp-report' key >+ my $csp_report = $report->{'csp-report'} // $report; >+ >+ my $logger = Koha::Logger->get( { interface => 'api', category => 'csp' } ); >+ >+ # Extract key fields for logging >+ my $document_uri = $csp_report->{'document-uri'} // 'unknown'; >+ my $violated_dir = $csp_report->{'violated-directive'} // 'unknown'; >+ my $blocked_uri = $csp_report->{'blocked-uri'} // 'unknown'; >+ my $source_file = $csp_report->{'source-file'} // ''; >+ my $line_number = $csp_report->{'line-number'} // ''; >+ my $column_number = $csp_report->{'column-number'} // ''; >+ >+ # Build location string if available >+ my $location = ''; >+ if ($source_file) { >+ $location = " at $source_file"; >+ $location .= ":$line_number" if $line_number; >+ $location .= ":$column_number" if $column_number; >+ } >+ >+ $logger->warn( >+ sprintf( >+ "CSP violation: '%s' blocked '%s' on page '%s'%s", >+ $violated_dir, >+ $blocked_uri, >+ $document_uri, >+ $location >+ ) >+ ); >+ >+ # Log full report at debug level for detailed analysis >+ if ( $logger->is_debug ) { >+ require JSON; >+ $logger->debug( "CSP report details: " . JSON::encode_json($csp_report) ); >+ } >+ >+ return $c->render( >+ status => 204, >+ openapi => undef >+ ); >+} >+ >+1; >diff --git a/api/v1/swagger/definitions/csp_report.yaml b/api/v1/swagger/definitions/csp_report.yaml >new file mode 100644 >index 00000000000..e175c911f2f >--- /dev/null >+++ b/api/v1/swagger/definitions/csp_report.yaml >@@ -0,0 +1,47 @@ >+--- >+type: object >+description: | >+ A Content-Security-Policy violation report as sent by browsers. >+ See https://www.w3.org/TR/CSP3/#violation-reports for specification. >+properties: >+ csp-report: >+ type: object >+ description: The CSP violation report object >+ properties: >+ document-uri: >+ type: string >+ description: The URI of the document where the violation occurred >+ referrer: >+ type: string >+ description: The referrer of the document where the violation occurred >+ violated-directive: >+ type: string >+ description: The directive that was violated (e.g., "script-src 'self'") >+ effective-directive: >+ type: string >+ description: The effective directive that was violated >+ original-policy: >+ type: string >+ description: The original CSP policy as specified in the header >+ disposition: >+ type: string >+ description: Either "enforce" or "report" depending on CSP mode >+ blocked-uri: >+ type: string >+ description: The URI of the resource that was blocked >+ line-number: >+ type: integer >+ description: Line number in the document where the violation occurred >+ column-number: >+ type: integer >+ description: Column number where the violation occurred >+ source-file: >+ type: string >+ description: The URI of the script where the violation occurred >+ status-code: >+ type: integer >+ description: HTTP status code of the document >+ script-sample: >+ type: string >+ description: First 40 characters of the inline script that caused the violation >+additionalProperties: true >diff --git a/api/v1/swagger/paths/public_csp_reports.yaml b/api/v1/swagger/paths/public_csp_reports.yaml >new file mode 100644 >index 00000000000..735b5c81ca4 >--- /dev/null >+++ b/api/v1/swagger/paths/public_csp_reports.yaml >@@ -0,0 +1,43 @@ >+"/public/csp-reports": >+ post: >+ x-mojo-to: CSPReports#add >+ operationId: addCSPReport >+ tags: >+ - csp >+ summary: Report a Content-Security-Policy violation >+ description: | >+ This endpoint receives Content-Security-Policy violation reports from browsers. >+ When a CSP violation occurs, browsers can be configured to POST a report to this >+ endpoint using the `report-uri` or `report-to` CSP directive. >+ >+ Reports are logged using Koha's logging system for administrator review. >+ >+ This is a public endpoint that does not require authentication, as browsers >+ send these reports automatically without user credentials. >+ consumes: >+ - application/csp-report >+ - application/json >+ produces: >+ - application/json >+ parameters: >+ - name: body >+ in: body >+ description: CSP violation report >+ required: true >+ schema: >+ $ref: "../swagger.yaml#/definitions/csp_report" >+ responses: >+ "204": >+ description: Report received successfully >+ "400": >+ description: Bad request >+ schema: >+ $ref: "../swagger.yaml#/definitions/error" >+ "500": >+ description: Internal server error >+ schema: >+ $ref: "../swagger.yaml#/definitions/error" >+ "503": >+ description: Under maintenance >+ schema: >+ $ref: "../swagger.yaml#/definitions/error" >diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml >index 9a9b7af7565..afd3e0331ea 100644 >--- a/api/v1/swagger/swagger.yaml >+++ b/api/v1/swagger/swagger.yaml >@@ -42,6 +42,8 @@ definitions: > $ref: ./definitions/circ-rule-kind.yaml > city: > $ref: ./definitions/city.yaml >+ csp_report: >+ $ref: ./definitions/csp_report.yaml > credit: > $ref: ./definitions/credit.yaml > debit: >@@ -565,6 +567,8 @@ paths: > $ref: "./paths/libraries.yaml#/~1public~1libraries~1{library_id}" > "/public/lists": > $ref: "./paths/lists.yaml#/~1public~1lists" >+ "/public/csp-reports": >+ $ref: ./paths/public_csp_reports.yaml#/~1public~1csp-reports > "/public/oauth/login/{provider_code}/{interface}": > $ref: ./paths/public_oauth.yaml#/~1public~1oauth~1login~1{provider_code}~1{interface} > "/public/patrons/{patron_id}/article_requests/{article_request_id}": >diff --git a/debian/templates/koha-conf-site.xml.in b/debian/templates/koha-conf-site.xml.in >index 03fbba33170..e90b7784b73 100644 >--- a/debian/templates/koha-conf-site.xml.in >+++ b/debian/templates/koha-conf-site.xml.in >@@ -500,6 +500,36 @@ __END_SRU_PUBLICSERVER__ > <parallel_loops_count>1</parallel_loops_count> > </auto_renew_cronjob> > >+ <!-- >+ Content-Security-Policy (CSP) configuration >+ ============================================ >+ CSP is a security feature that helps prevent XSS attacks by controlling which >+ resources the browser is allowed to load. >+ >+ csp_mode options: >+ - (empty/unset): CSP is disabled (default) >+ - report-only: CSP violations are reported but not enforced (for testing) >+ - enabled: CSP is fully enforced >+ >+ csp_header_value: The CSP policy directives. Special placeholders: >+ - _CSP_NONCE_: Replaced with a unique nonce for each request >+ >+ Recommended workflow: >+ 1. Start with report-only mode to identify violations >+ 2. Review logs and fix any legitimate violations >+ 3. Switch to enabled mode once violations are resolved >+ >+ To enable violation reporting, add report-uri to your policy pointing to Koha's >+ built-in CSP report endpoint. Example with reporting: >+ <csp_header_value>default-src 'self'; script-src 'self' 'nonce-_CSP_NONCE_'; style-src 'self' 'nonce-_CSP_NONCE_'; style-src-attr 'unsafe-inline'; img-src 'self' data:; font-src 'self'; object-src 'none'; report-uri /api/v1/public/csp-reports</csp_header_value> >+ >+ Reports are logged via Koha's logging system. Configure log4perl to capture them: >+ log4perl.logger.api.csp = WARN, CSP >+ log4perl.appender.CSP = Log::Log4perl::Appender::File >+ log4perl.appender.CSP.filename = /var/log/koha/__KOHASITE__/csp-violations.log >+ log4perl.appender.CSP.layout = PatternLayout >+ log4perl.appender.CSP.layout.ConversionPattern = [%d] %m%n >+ --> > <content_security_policy> > <opac> > <!-- supported values: report-only, enabled. Any other value, including unset, disables the feature. --> >diff --git a/etc/koha-conf.xml b/etc/koha-conf.xml >index 10336b9b09d..991d9318b86 100644 >--- a/etc/koha-conf.xml >+++ b/etc/koha-conf.xml >@@ -311,6 +311,36 @@ > <parallel_loops_count>1</parallel_loops_count> > </auto_renew_cronjob> > >+ <!-- >+ Content-Security-Policy (CSP) configuration >+ ============================================ >+ CSP is a security feature that helps prevent XSS attacks by controlling which >+ resources the browser is allowed to load. >+ >+ csp_mode options: >+ - (empty/unset): CSP is disabled (default) >+ - report-only: CSP violations are reported but not enforced (for testing) >+ - enabled: CSP is fully enforced >+ >+ csp_header_value: The CSP policy directives. Special placeholders: >+ - _CSP_NONCE_: Replaced with a unique nonce for each request >+ >+ Recommended workflow: >+ 1. Start with report-only mode to identify violations >+ 2. Review logs and fix any legitimate violations >+ 3. Switch to enabled mode once violations are resolved >+ >+ To enable violation reporting, add report-uri to your policy pointing to Koha's >+ built-in CSP report endpoint. Example with reporting: >+ <csp_header_value>default-src 'self'; script-src 'self' 'nonce-_CSP_NONCE_'; style-src 'self' 'nonce-_CSP_NONCE_'; style-src-attr 'unsafe-inline'; img-src 'self' data:; font-src 'self'; object-src 'none'; report-uri /api/v1/public/csp-reports</csp_header_value> >+ >+ Reports are logged via Koha's logging system. Configure log4perl to capture them: >+ log4perl.logger.api.csp = WARN, CSP >+ log4perl.appender.CSP = Log::Log4perl::Appender::File >+ log4perl.appender.CSP.filename = /var/log/koha/csp-violations.log >+ log4perl.appender.CSP.layout = PatternLayout >+ log4perl.appender.CSP.layout.ConversionPattern = [%d] %m%n >+ --> > <content_security_policy> > <opac> > <!-- supported values: report-only, enabled. Any other value, including unset, disables the feature. --> >diff --git a/t/db_dependent/api/v1/public/csp_reports.t b/t/db_dependent/api/v1/public/csp_reports.t >new file mode 100755 >index 00000000000..3be9bd845af >--- /dev/null >+++ b/t/db_dependent/api/v1/public/csp_reports.t >@@ -0,0 +1,80 @@ >+#!/usr/bin/env perl >+ >+# This file is part of Koha. >+# >+# Koha is free software; you can redistribute it and/or modify it >+# under the terms of the GNU General Public License as published by >+# the Free Software Foundation; either version 3 of the License, or >+# (at your option) any later version. >+# >+# Koha is distributed in the hope that it will be useful, but >+# WITHOUT ANY WARRANTY; without even the implied warranty of >+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the >+# GNU General Public License for more details. >+# >+# You should have received a copy of the GNU General Public License >+# along with Koha; if not, see <https://www.gnu.org/licenses>. >+ >+use Modern::Perl; >+ >+use Test::NoWarnings; >+use Test::More tests => 2; >+use Test::Mojo; >+use Test::Warn; >+ >+use t::lib::Mocks; >+ >+use Koha::Database; >+ >+my $schema = Koha::Database->new->schema; >+my $t = Test::Mojo->new('Koha::REST::V1'); >+ >+t::lib::Mocks::mock_preference( 'RESTBasicAuth', 1 ); >+ >+subtest 'add() tests' => sub { >+ >+ plan tests => 6; >+ >+ $schema->storage->txn_begin; >+ >+ # Test with standard CSP report format >+ my $csp_report = { >+ 'csp-report' => { >+ 'document-uri' => 'https://library.example.org/cgi-bin/koha/opac-main.pl', >+ 'referrer' => '', >+ 'violated-directive' => "script-src 'self' 'nonce-abc123'", >+ 'effective-directive' => 'script-src', >+ 'original-policy' => "default-src 'self'; script-src 'self' 'nonce-abc123'", >+ 'disposition' => 'enforce', >+ 'blocked-uri' => 'inline', >+ 'line-number' => 42, >+ 'column-number' => 10, >+ 'source-file' => 'https://library.example.org/cgi-bin/koha/opac-main.pl', >+ 'status-code' => 200, >+ } >+ }; >+ >+ # Anonymous request should work (browsers send these without auth) >+ $t->post_ok( '/api/v1/public/csp-reports' => { 'Content-Type' => 'application/csp-report' } => json => $csp_report ) >+ ->status_is( 204, 'CSP report accepted' ); >+ >+ # Test with application/json content type (also valid) >+ $t->post_ok( '/api/v1/public/csp-reports' => { 'Content-Type' => 'application/json' } => json => $csp_report ) >+ ->status_is( 204, 'CSP report accepted with application/json content type' ); >+ >+ # Test with minimal report >+ my $minimal_report = { >+ 'csp-report' => { >+ 'document-uri' => 'https://library.example.org/', >+ 'violated-directive' => 'script-src', >+ 'blocked-uri' => 'https://evil.example.com/script.js', >+ } >+ }; >+ >+ $t->post_ok( '/api/v1/public/csp-reports' => json => $minimal_report ) >+ ->status_is( 204, 'Minimal CSP report accepted' ); >+ >+ $schema->storage->txn_rollback; >+}; >+ >+1; >-- >2.39.5
You cannot view the attachment while viewing its details because your browser does not support IFRAMEs.
View the attachment on a separate page
.
View Attachment As Diff
View Attachment As Raw
Actions:
View
|
Diff
|
Splinter Review
Attachments on
bug 38365
:
174054
|
188487
|
188488
|
188489
|
188490
|
188491
|
188733
|
188734
|
188735
|
188736
|
188737
|
188881
|
188882
|
189465
|
189466
|
189467
|
189468
|
189469
|
189470
|
189471
|
189472
|
191618
|
191619
|
191620
|
191621
|
191622
|
191623
|
191660
|
191661
|
191662
|
191663
|
191664
|
191665
|
191666
|
191667
|
191668
|
192294
|
192295
|
192296
|
192297
|
192298
|
192299
|
192300
|
192301
|
192302
|
192303
|
192304
|
192305
|
192306
|
192412
|
192413
|
192414
|
192415
|
192416
|
192417
|
192418
|
192419
|
192420
|
192421
|
192422
|
192423
|
192424
|
192425
|
192426
|
192427
|
192428
|
192429
|
192524
|
192535
|
192536
|
192537
|
192553
|
192554
|
192555
|
192556
|
192557
|
192558
|
192559
|
192560
|
192561
|
192562
|
192563
|
192564
|
192565
|
192566
|
192567
|
192568
|
192569
|
192570
|
192571
|
192572
|
192573
|
192574
|
192684
|
192685
|
192686
|
192691
|
192692
|
192693
|
192694
|
192695
|
192696
|
192697
|
192698
|
192699
|
192700
|
192701
|
192702
|
192703
|
192704
|
192705
|
192706
|
192707
|
192708
|
192709
|
192738
|
192843
|
192844
|
192934
|
192935
|
192936
|
192937
|
193288
|
193289
|
193290
|
193291
|
193292
|
193293
|
193294
|
193295
|
193296
|
193297
|
193298
|
193299
|
193300
|
193301
|
193302
|
193303
|
193304
|
193305
|
193306
|
193307
|
193308
|
193309
|
193310
|
193311
|
193312
|
193335
|
193705
|
193706
|
193707
|
193708
|
193709
|
193710
|
193711
|
193712
|
193713
|
193714
|
193941
|
193942
|
193943
|
193944
|
193945
|
193946
|
193947
|
193948
|
193949
|
193950
|
193951
| 193952 |
193953
|
193954
|
193955
|
193956
|
193957
|
193958
|
193959
|
193960
|
193961
|
193962
|
193963
|
193964
|
193965
|
193966
|
193967
|
193968