NCMEC Toolkit for XenForo 2

Overview

Electronic Service Providers (ESP) are required to report instances of child sexual exploitation material (CSEM) to the National Center for Missing and Exploited Children (NCMEC) under 18 U.S. Code § 2258A.

XenForo 2 lacks a robust toolkit for dealing with sophisticated predators intending to propagate CSEM. This is a serious threat to service providers. This extension provides comprehensive tools for compliance with US federal law, robust anti-spam mechanisms, and urgent response capabilities to protect your community from child abuse material.

The United States Internet Preservation Society provides this code under the MIT license and it is free to use. We have no affiliation with the NCMEC or XenForo.

Requirements: NCMEC ESP credentials for report submission.

Features

Emergency Reporting System

• User-initiated emergency reports: Allows users to create emergency reports for suspected CSEM, triggering immediate moderation and staff notification
• Automatic content moderation: Reported content is automatically hidden from public view pending review
• Thread-level moderation: When a post is reported, the entire thread can be automatically moderated to prevent further exposure
• Enhanced staff notifications: Emergency reports trigger priority notifications to moderators with elevated urgency

Approval Queue Integration

• Flag CSAM action: Adds a "Flag as CSAM" action to the moderation approval queue for posts, threads, profile posts, and profile post comments
• Direct NCMEC flagging: Moderators can flag content directly from the approval queue, automatically creating incidents and preparing for NCMEC reporting
• Attachment preview: View attachments associated with flagged content directly in the approval interface

Report Center Integration

• Report state flagging: Moderators can resolve reports with the "Flag as CSAM" option directly from the report interface
• Automatic incident creation: Flagging a report creates or updates an incident, associating the reported content and user
• Time-based content collection: Automatically collects and associates all content posted by the reported user within a configurable time window (based on the default timespan option)
• Cascading report closure: All other open reports for the same content are automatically closed with the same CSAM flag message and incident reference
• Unified workflow: Provides the same functionality as approval queue flagging but integrated into the normal report handling workflow

Incident Management System

• Incident tracking: Create and manage investigation incidents for suspected CSEM cases
• User association: Track users involved in incidents with automatic flagging system
• Content aggregation: Collect and associate all relevant content (posts, threads, attachments) with incidents
• Bulk content operations: Add content in bulk or perform fine-tuned selection during investigations
• User content selector: Quickly review and select a user's content to add to an incident

User Flagging & Permissions

• Automatic user field: Users added to incidents receive a special usips_ncmec_in_incident field flag
• Instant user upgrades: The flag enables automatic user group promotions to apply instantly, allowing permission changes during active investigations
• Investigation-based permissions: Use the incident flag in user group promotion criteria to automatically adjust permissions (e.g., restrict posting, require approval, etc.)
• Automatic promotion updates: User promotions are automatically recalculated when users are added to or removed from incidents

NCMEC Report Creation & Submission

• Report builder: Create detailed CyberTipline reports with all required NCMEC fields
• Person management: Track and store information about:
  • Points of contact in your organization
  • Law enforcement contacts
  • Known victims
  • Suspected perpetrators
• Attachment handling: Associate attachment data with incidents and reports
• API integration: Submit reports directly to NCMEC via their CyberTipline Reporting API
• Report archiving: Maintain records of all submitted reports

Data Preservation (18 U.S.C. § 2703)

• Law Enforcement Compliance: Tools to handle data preservation requests under 18 U.S.C. § 2703(f).
• Data Snapshots: Captures user account details and content metadata at the moment of the request.
• Zero-Copy Attachments: Stores only attachment metadata and file paths—binary attachment data is not duplicated.

Administrative Interface

• Incident dashboard: Overview of all active and finalized incidents
• Attachment lookup: Search for and locate specific attachments across your site
• Attachment listing: View recently uploaded attachments with filtering capabilities
• Content preview: Preview flagged content and attachments within the admin panel
• Batch operations: Perform bulk actions on users and content associated with incidents

Audit & Compliance

• API logging: All NCMEC API interactions are logged for compliance tracking
• Incident history: Complete audit trail of incident creation, modifications, and report submissions
• User association tracking: Track when users are added to or removed from incidents
• Content association tracking: Track all content added to incidents with timestamps

Installation

1. Upload the extension files to src/addons/USIPS/NCMEC/
2. Install the add-on through the XenForo admin panel
3. Configure NCMEC API credentials in the add-on options
4. Set appropriate admin permissions for NCMEC management

Configuration

Admin Permissions

Grant the usips_ncmec admin permission to staff members who should have access to incident management and NCMEC reporting tools.

Options

Configure the following in the add-on options:

• NCMEC API endpoint and credentials
• Emergency report notification settings
• User field configuration for incident tracking

User Group Promotions

Create user group promotions using the usips_ncmec_in_incident user field criteria to automatically adjust permissions for users under investigation.

Usage

For End Users

Users can report suspected CSEM using the standard report function with emergency handling enabled, which will immediately hide the content and notify staff.

For Moderators

1. Via Approval Queue: Review flagged content in the approval queue and use the "Flag as CSAM" action to create an incident
2. Via Report Center:
   • View any report for potentially harmful content
   • Select "Flag as CSAM" from the report state dropdown
   • Add a comment (optional) explaining the action
   • Submit to automatically flag content, create/update incident, and close related reports
3. Content is automatically added to the incident for investigation

For Administrators

1. Access NCMEC tools via the admin panel navigation
2. Manage incidents and add relevant users/content
3. Build NCMEC reports from incident data
4. Submit reports to NCMEC CyberTipline
5. Track submitted reports and maintain compliance records

Submission completion and retained evidence

Upload and file-information receipts do not authorize removing local evidence. Originals remain until the report has a persisted successful /finish, its returned file list is verified, and cleanup passes the current preservation checks. An attachment also needs the persisted snapshot captured for its upload to match its current row. Upload staging refreshes stale cached entities before taking that snapshot. Before any upload, the complete staged bytes must match the stored size and MD5. Truncated reads, corruption and write failures discard only the temporary copy and retain the original.

A successful /finish is recorded before checking the returned file list. A verification mismatch is logged and retains originals; it does not erase the successful submission or cause another /finish on resume. The 1.3.4 migration adds files_verified and upload snapshots without backfilling unverifiable historical records. An old submitted timestamp alone cannot authorize cleanup.

Missing legacy source content is exported explicitly as unavailable association metadata, with content_exported=false. It is never represented as an exported copy of the missing content, and the metadata cannot authorize deletion if an original later reappears. An unfinished report whose immutable primary export omitted a missing association can receive a separately acknowledged <type>s.missing.json supplement. The primary archive remains unchanged.

Closed historical reports cannot accept that supplement. The operator recovery command below can record currently missing sources as unavailable, reconcile a verified terminal file list, or replace a confirmed expired attempt. Historical exports without a manifest cannot prove which still-existing rows were exported; live unacknowledged evidence still requires a separate report. Changed sources, independent holds and threads containing unrelated participants or descendants remain retained and logged for review; the report workflow does not grant permission to delete them. One subject requiring a separate report no longer prevents independent subjects' reports from progressing, although the case remains unsubmitted while its acknowledgement checks fail.

Preservation checks continue to use indexed current reads and shared locks. The change does not remove those guards or establish their production performance cost.

Validation on 2026-10-01 passed 105 pure tests (470 assertions) and 70 actual Submitter/FinalizeCase/recovery runtime cases (2,056 assertions) against isolated disposable XenForo database xf_prune_review3. Fake API responses covered expired unfinished reports, finish verification failure, missing-source legacy recovery, orphan file reconciliation, exact receipt identities, upload size/MD5 corruption, independent holds and subjects, cleanup-only resumption, transaction rollback, and stale prefetched jobs across same-second resets. Both real CLI commands ran through XenForo. The 1.3.5 schema migration also passed an idempotent rerun. No real NCMEC report was submitted.

Operator recovery

Version 1.3.5 adds usips-ncmec:recover-report. It defaults to a read-only preview and never calls the remote API. It requires exact local case/report IDs, the remote report ID, a numeric existing administrator ID with usips_ncmec (or super-admin status), and a reason. Applying a reviewed action requires --execute. Every applied decision records its actor, reason, identities and evidence in xf_usips_ncmec_recovery_log; old reports, receipts and exports remain intact. A busy case or recently running finalize job is refused.

Choose the action for the diagnosed condition:

• missing-review: record unacknowledged originals that are currently absent as missing-at-review metadata. The report must be finished. If its local timestamp was lost, supply an archived exact-report successful /finish or 5102 response, or a verified finished review file. This restores only the finished timestamp and leaves files_verified=0 until a separate verify-files decision. A disposition stops applying if the original returns or its association changes; it never grants permission to delete content. Existing unacknowledged originals are refused. For a combined legacy report, a single matching receipted users.json archive can establish the reviewed subject scope for case bookkeeping; this does not backfill its unknown deletion scope or authorize legacy cleanup.
• verify-files: reconcile a finished report using an archived successful /finish response (--api-log-id) or an independently verified complete terminal file list (--review-file). All local upload/file-information receipts must be complete and present in that list. Additional remote orphan IDs are recorded in the audit. This does not invent receipts or upload snapshots for historical files.
• replace-expired: require an archived exact-report 5001 response or independently verified remote absence. Local finish state, archived successful /finish, or archived 5102 blocks replacement. Available originals must pass size/hash validation. The old attempt is linked to a fresh local report, and any stopped finalize job restarts from initial state while retaining its job ID. The tool itself uploads nothing.

Preview, review its output, then repeat with --execute. These example IDs are placeholders:

php cmd.php usips-ncmec:recover-report 42 81 --remote-id=123456 --action=missing-review --operator=7 --reason='Reviewed unavailable legacy sources'
php cmd.php usips-ncmec:recover-report 42 81 --remote-id=123456 --action=verify-files --operator=7 --reason='Reconciled terminal file list' --api-log-id=901
php cmd.php usips-ncmec:recover-report 42 81 --remote-id=123456 --action=replace-expired --operator=7 --reason='Confirmed expired remote attempt' --review-file=/secure/review.json

Use an independently verified review file only when archived API evidence is insufficient. The JSON must have exactly these keys; IDs are integers, file IDs are strings, and reference identifies the actual external confirmation. Merely copying this example is not confirmation:

{"case_id":42,"report_id":81,"ncmec_report_id":123456,"status":"finished","reference":"NCMEC confirmation reference","file_ids":["FILE-A","FILE-B"]}

For confirmed expiry, replace status with "expired" and replace file_ids with "confirmed_absent":true. Do not supply both --api-log-id and --review-file.

Recovery retains evidence when proofs are missing, incomplete, or contradictory. It cannot recreate originals already lost before preservation guards existed. Follow the resume command printed after a successful decision; normal resume uses the guarded Submitter/FinalizeCase path and can upload evidence to a replacement report. If the case was already submitted, use php cmd.php usips-ncmec:resume-case CASE_ID --cleanup-only to preview, then add --execute to run the guarded cleanup phase. Cleanup-only requires finished and verified active reports; it cannot submit or finish a report again and retains independently held or unverifiable sources.

Technical Notes

• Incidents can be created manually or automatically through the flagging system
• Users are automatically unflagged when removed from all incidents
• User promotions are recalculated in real-time when incident associations change
• All moderation actions are logged and auditable
• The system is designed to work with XenForo's existing content types and can be extended to support custom content types

Support

This is open-source software provided as-is under the MIT license. For issues, feature requests, or contributions, please contact the United States Internet Preservation Society.

Legal Disclaimer

This tool is designed to assist with compliance but does not constitute legal advice. Service providers should consult with legal counsel regarding their obligations under 18 U.S. Code § 2258A and related laws.