Security Model
bulletinbored is built for a single trusted administrator who installs plugins, themes, language packs, and updates. The security model therefore assumes that installing code is a deliberate act of trust in its source (the author / the repository).
What is hardened
- Zip Slip is mitigated everywhere a package is extracted.
PluginManager,ThemeManager,UpdateManager, and the sharedextract_zip()all validate every archive entry and reject..path traversal and absolute paths before writing. - Repository and package installs are non-destructive. Installing or updating a plugin/theme from a ZIP or a Git repository never deletes the working version before the replacement is validated. The new package is downloaded to a staging directory (
ZIPextracted throughPackageInstaller; repositories cloned/downloaded throughinstall_repo_package()) and validated with the same checks — manifest plus core/PHP constraints and, when the per-type verify toggle is enabled, thefilesintegrity list. Only then is the existing directory moved to_old_{name}_{uniqid}and the staged package swapped in; the backup is discarded only on success. On any failure the backup (and for plugins the previousinstalled.jsonrecord) is restored. Package names derived from external input (expectedName,name) are validated against^[a-z0-9][a-z0-9_-]*$before they are used to build a path underplugins/orthemes/. - Package rollback is filesystem-only. When a plugin install/update fails after a lifecycle hook (
on_install/on_update) has run, the previous files and metadata are restored, but database changes made by that hook are not automatically reverted. Plugin authors must keep migrations idempotent or revert them explicitly. - Language packs are JSON only — no
eval(). Uploaded or installed translation files are parsed as plain JSON data. PHP language files are no longer supported, eliminating the supply-chain RCE vector. - TLS verification is enforced. All update downloads (core, plugins, themes) verify the server certificate with
CURLOPT_SSL_VERIFYPEER=trueandCURLOPT_SSL_VERIFYHOST=2. When cURL is unavailable and the code falls back tofile_get_contents(), the stream context explicitly setsverify_peer/verify_peer_nametotrueandallow_self_signedtofalse, so the fallback never silently weakens TLS. - Attachment authorization.
/download/{id}verifiescan_view_thread()before serving files. Attachments belonging to hidden/pending threads are protected by the same policy as the thread itself. Uploads are linked to threads viathread_idor indirectly viapost_id(looking up the thread through the post). Orphan uploads (with no thread association) and uploads whose thread is not viewable return404 Not Foundfor every user, so their existence is not disclosed. - Plugin dependency graph. Circular dependencies are detected and rejected. Disabling a plugin recursively disables all plugins that depend on it.
- Core update aborts if backup fails. The updater no longer proceeds without a safety net — if the backup step fails, the update is aborted.
- Application state centralized where practical. The
Appclass is the primary container for config, PDO, AuthZ, i18n and the managers, but some legacy global access remains: the exception handler reads$GLOBALS['config'](src/bootstrap.php:145),views/header.phpreads$GLOBALS['config']and$GLOBALS['pluginManager'], andAuthZlooks up the plugin permission hook throughglobal $pluginManager(lib/AuthZ.php:85). This reduces, rather than eliminates, hidden coupling. - CSP tightened. Scripts and styles require a nonce (
script-srcandstyle-srcboth include'nonce-{nonce}').object-src 'none',base-uri 'self',form-action 'self',frame-ancestors 'none'are enforced. Stylesheets are otherwise restricted tostyle-src 'self'plus the CDN allow-list; inlinestyle="…"attributes are permitted viastyle-src-attr 'unsafe-inline'(needed for dynamic values like avatars and progress bars), while injected<style>blocks remain blocked. The fallback avatar is rendered as an inline<svg>and needs no inline style at all. - TrustedProxies IPv6 support. The trusted proxy detection now supports IPv6 addresses and CIDR notation.
shell_exec()removed. Git detection in diagnostics and repo_install now usesexec()with return code checking instead ofshell_exec().- Code modularized.
helpers.phpfully split intosrc/Helpers/(Url, AuthHelpers, Upload, Mail, Notifications, Text, Avatar, Data).posts.phpsplit intoposts-thread.php,posts-new.php,posts-edit.php. Handlers useApp::getInstance()instead ofglobal $pdo, and PluginManager and ThemeManager i18n usesApp::getInstance()->i18n. This reduces file complexity and most global state coupling, though a few legacy globals remain (see the application state note above). - Test coverage. Regression tests verify: no
eval()in source files, SSL verification never disabled, download requires thread access (functional tests for guest/moderator/user on hidden/pending/visible threads, orphan uploads, and post_id-based thread association). Syntax check test validates all source files viaphp -l. - No trust in raw user HTML. The core renders Markdown only.
bb_parse_inline()HTML-escapes all text before matching Markdown tokens (src/markdown.php:30-34), andbb_parse_markdown()only emits tags generated from recognised syntax, so pasted HTML is shown as literal text (src/markdown.php:12-13).bb_render_content()is the single rendering path; a plugin can replace it through therender_contenthook (src/markdown.php:195-219). There is nosanitize_html()function and no raw-HTML sanitizer to configure. Output is served under a per-request nonce-based CSP. - Query hardening.
fetch_threads()uses whitelist + placeholders for status filter instead of string interpolation. - Installer files do not re-appear after a core update.
applyCoreUpdate()removes only the setup wizardsinstall.php,install2.php, andinstall3.phpfrom a deployed root once the forum is installed (config.jsonpresent); on a fresh install (noconfig.json) they are kept so setup can run.api/install.phpis deliberately not removed (lib/UpdateManager.php:884-903): it is a runtime admin endpoint for catalog installs. It boots withoutsrc/bootstrap.php, so it resolves the administrator against the database withAdminAuth::connect()/AdminAuth::verifySession(), requires a CSRF token, and is rate-limited to 20 requests per hour (api/install.php:44-67). - CSRF tokens rotate on every successful validation. Each POST request validates the token and immediately issues a new one, preventing replay attacks. Use
csrf_validate_request()in POST handlers. All state-changing operations (including watch/unwatch/logout) use POST with CSRF protection. - Input sanitization is centralized. The
Bulletin\Requestclass provides a single entry point for all user input (get(),post(),input()), ensuring consistent sanitization and eliminating the risk that a new handler forgets to escape input. - Most admin actions are audit-logged. User create/update/delete/ban/unban/suspend/disconnect, role changes, category changes, thread moderation (approve/hide/delete/lock/sticky/move/copy), and plugin/theme management are logged to
data/logs/security.logwith admin identity, IP, timestamp, and context. Settings, SMTP, site image, catalog, and language changes are not currently written to the admin audit log (src/actions/admin/settings.php,catalog.php,langs.php). - Secrets and CLI/dev files are never served.
config.json,config.php,bb.phpandrouter.phpare denied on Apache (.htaccess), Nginx (nginx.conf), IIS (web.config) and the PHP built-in server (router.php). The built-in server only serves allow-listed static asset extensions and blocksdata/anduploads/private/. - The installer is hardened. All three steps enforce CSRF tokens, the re-run guard fails closed (a
config.jsonwith adb_driveris authoritative even if the DB is unreachable), and the SQLitedb_pathis confined to the application directory before any file/mkdir()is created. Failures are logged server-side, not echoed. It also refuses to reuse an existing, populated database when noconfig.jsonis present, so a “fresh” install can never silently present the previous forum’s threads and users; the message explains how to migrate a forum instead. - Rate limiting covers all mutations. Beyond auth/posting, the file-based limiter throttles edit/delete, watch/unwatch, image and avatar uploads, profile edits, and every admin operation. Sensitive actions (authentication, account changes, destructive content operations and all admin actions) fail closed: if the bucket cannot be opened, the lock cannot be acquired, the stored data is corrupt, or the updated hit cannot be persisted, the request is denied rather than allowed. Only non-sensitive actions degrade open. Stale buckets (>24 h) are removed opportunistically so
data/ratelimit/does not grow without bound. - Client IP behind proxies. When the request comes from a configured trusted proxy, the client IP is taken as the first valid
X-Forwarded-Forvalue. Deployments that chain several proxies must list every hop intrusted_proxiesand make sure the front proxy normalises/appends the header; the parser does not attempt to reconstruct an arbitrary chain. - Response headers. Every response sets
X-Content-Type-Options,X-Frame-Options,Referrer-PolicyandPermissions-Policy;Strict-Transport-Securityis sent over HTTPS. - Download filename sanitization.
Content-Dispositionstrips control characters and uses an RFC 5987 encoded filename, preventing header injection from user-supplied upload names. - Plugin JSON APIs do not leak internals.
bellboredandtextmeboredreturn a genericinternal_errorand log the exception server-side. - Telemetry is anonymous, opt-out and non-identifying. The daily heartbeat sends only a random
install_id, the core and PHP versions, the database driver, plugin/theme counts and the language. No IP address, domain, user data, posts or content is ever transmitted or stored. It can be disabled with"telemetry": falseinconfig.jsonor via Admin → Settings → “Send anonymous statistics”, after which no network request is made. See Configuration.
Installing code is an act of trust
Plugins and themes are PHP code that is included by the forum. A malicious package therefore means remote code execution. Because distribution is decentralized (anyone can publish a plugin/theme on any Git host), there is no central signing authority and bulletinbored does not implement cryptographic signature verification of packages.
Consequences for the operator:
- Installing or updating a plugin/theme means you trust its author and its source. This is by design for a decentralized ecosystem. There is no “safe” automatic path: even when a package comes from the curated catalog, an update applies a new package from that same source without a human re-reviewing the diff. You cannot pre-approve updates in a meaningful way without trusting the source — doing so would undermine the decentralized nature of the system.
- As defense-in-depth, keep
plugin_verify_files/theme_verify_filesenabled (on by default). At install time the package is checked against thefileslist in itsmanifest.json; a package that ships files not declared in the manifest (e.g. a dropped-in backdoor) is rejected. Note: this catches added files, not a manifest that itself was updated to include the malicious file — so it is a guard, not a guarantee. catalog-onlymode (allow_catalog_only) restricts installation toofficial: trueentries from the curated catalog. It reduces the set of sources to curated ones, but it does not give you pre-approval of updates: a curated source can still publish a new version at any time.
Curated catalog: first-party vs third-party
The catalog mixes components developed by the bulletinbored team (first-party) and components developed by the community (third-party). The catalog UI labels each one accordingly (“Developed by bulletinbored team” vs “Developed by third party”)
so you can see at a glance what is first-party and what is not.
Every catalog entry — first-party or third-party — is reviewed by the bulletinbored team before being added to the catalog. Even so, bulletinbored does not assume any responsibility for the code, security, or behavior of third-party plugins/themes: installing one remains an act of trust in its author. If a third-party (or first-party) component is later found to be malicious, bulletinbored will remove it from the catalog as soon as it is reported by a user — see Reporting below.
The pre-catalog review reduces risk but is not a guarantee: a component can be
compromised after publication (e.g. via an update), and reviews are best-effort.
Keep*_verify_filesenabled and treat any installation as trusting the source.
Bottom line: only install plugins/themes/updates from sources you trust. Keep
*_verify_filesenabled, prefercatalog-onlymode if you want a smaller trusted
surface, and review third-party code before deploying it on a production forum with
untrusted users.
Hardening options in config.json
| Key | Default | Effect |
|---|---|---|
plugin_verify_files |
true |
Reject plugin packages whose extracted files don’t match manifest.json files. |
theme_verify_files |
true |
Same check for themes. |
allow_catalog_only |
true |
When true, only official: true catalog entries can be installed. The settings UI enables it by default too (views/admin_settings.php:167). |
allow_prerelease_updates |
false |
Offer prerelease core/extension updates. A prerelease may also follow the next prerelease. |
hsts_max_age |
31536000 |
Strict-Transport-Security max-age in seconds, sent over HTTPS. 0 disables HSTS. |
hsts_include_subdomains |
false |
Add includeSubDomains to the HSTS header. Opt-in because it also binds every subdomain to HTTPS. |
rate_limit_multiplier |
1 |
Global multiplier for the request allowance of every rate limit (0.1 to 10; clamps in src/Security.php:183-193). 1 keeps the documented limits. |
trusted_proxies |
["127.0.0.1", "::1"] |
List of trusted proxy IPs (supports CIDR notation). Only trust X-Forwarded-* headers from these IPs. |
CSRF Protection
CSRF tokens are per-session and rotate on every successful validation:
// In POST handlers:
if (!csrf_validate_request()) {
throw new \Bulletin\ForbiddenException('CSRF token invalid');
}
// Token is now rotated — old token is invalidated
// In forms:
echo csrf_field(); // generates <input type="hidden" name="csrf_token" value="...">
The csrf_validate_request() function validates the token from $_POST['csrf_token'] or $_SERVER['HTTP_X_CSRF_TOKEN'], and if valid, issues a new token immediately. This prevents replay attacks.
Input Sanitization
The Bulletin\Request class centralizes all user input:
use Bulletin\Request;
$name = Request::post('name'); // sanitized (trim + stripslashes)
$page = Request::get('page', 1); // with default
$raw = Request::raw('query'); // un-sanitized (for prepared statements)
$has = Request::has('field'); // existence check
$email = Request::email('email'); // validated email or empty string
$status = Request::enum('status', ['visible', 'hidden']); // allowlist
Output escaping remains the view layer’s responsibility via escape() at render time.
Authorization
All authorization is centralized through the AuthZ service (lib/AuthZ.php). Handlers must never check is_admin() or $_SESSION['user_role'] directly — they use $authz->can() and $authz->canOnOwned() instead.
global $authz;
$userId = (int)$_SESSION['user_id'];
// Check a permission
if (!$authz->can($userId, 'posts.edit')) {
throw new \Bulletin\ForbiddenException('Not authorized');
}
// Check with ownership (uses "permission_own" variant for owners)
if (!$authz->canOnOwned($userId, 'posts.edit', (int)$post['user_id'])) {
throw new \Bulletin\ForbiddenException('Not authorized');
}
Permissions use resource.action notation (e.g., posts.edit, threads.delete, admin.access). The full registry is documented in lib/AuthZ.php.
| Permission | Description |
|---|---|
admin.access |
Access admin panel |
threads.create |
Create new threads |
threads.edit / threads.edit_own |
Edit any / own thread |
threads.delete / threads.delete_own |
Delete any / own thread |
threads.lock |
Lock/unlock threads |
threads.sticky |
Sticky/unsticky threads |
threads.approve |
Approve pending threads |
threads.move |
Move thread to another category |
threads.split / threads.merge / threads.copy |
Split/merge/copy threads |
posts.create |
Create replies |
posts.edit / posts.edit_own |
Edit any / own post |
posts.delete / posts.delete_own |
Delete any / own post |
users.create / users.edit / users.delete |
User management |
users.ban / users.suspend |
Ban/suspend users |
roles.manage |
Manage roles and permissions |
categories.manage |
Category management |
settings.manage |
Modify site settings |
plugins.manage |
Plugin management |
themes.manage |
Theme management |
langs.manage |
Manage language files |
Admin Audit Log
All state-changing admin actions are logged to data/logs/security.log:
[2026-08-29T16:00:00+02:00] admin_user_ban ip=127.0.0.1 {"admin_id":1,"admin_user":"admin","target_id":42}
Logged actions include: user create/update/delete/ban/unban/suspend/disconnect, role create/update/delete, category create/update/delete, thread approve/hide/delete/lock/sticky/move/copy, plugin enable/disable/delete, and theme activate/delete. Settings, SMTP, site image, catalog, and language changes are not written to the admin audit log.
Authentication Hardening
- Session lifecycle: Sessions are regenerated on login. Role and status changes bump
users.session_version, so the new privileges are not picked up by the existing session: the nextis_logged_in()check invalidates it and the affected account must log in again (src/actions/admin/users.php:82-97). - Token security: Email verification and password reset tokens are stored as SHA-256 hashes (never raw). Tokens expire after 24 hours (email) or 1 hour (reset) and are single-use.
- Account enumeration prevention: Login errors are generic (“Invalid credentials”) — they don’t reveal whether the username exists.
- CSRF protection: Tokens rotate on every successful validation via
csrf_validate_request(). Usecsrf_validate_request()in all POST handlers. - Rate limiting: Login (5/15min), register (5/hr), forgot-password (5/hr), reset-password (10/hr) are rate-limited per client IP. Auth actions fail-closed (denied) when rate limit is exceeded.
- Uncaught exceptions are contained: a global handler in
src/bootstrap.phplogs the error and returns a generic500(JSON for API/JSON requests) instead of a raw fatal error, so internal paths and messages are not disclosed whendisplay_errorsis enabled.
New Security Fixes
Attachment Access Control
Attachments in hidden/pending threads are now protected:
- Files stored in
uploads/private/instead ofuploads/ - Download endpoint
/download/{id}checkscan_view_thread()before serving .htaccessinuploads/private/denies all direct access (Apache)nginx.confuseslocation ^~ /uploads/private/ { deny all; }(Nginx)- Orphan uploads (no thread association) and non-viewable threads return
404for all users - Uploads record their
thread_id/post_idbefore the file is moved, and the context is validated up front - The private uploads directory is created and given a deny-all
.htaccessbyensure_private_uploads_dir()(called fromsrc/setup.phpon every request and before each upload), so the protection exists on a fresh deployment and does not depend on a runtime directory being present
SMTP Injection Prevention
send_email() validates email addresses with FILTER_VALIDATE_EMAIL and rejects any headers containing \r or \n (CRLF injection prevention).
Session Invalidation
session_versioncolumn added to users tableis_logged_in()verifies the session version against the database and invalidates the session when it is missing, stale, or the user row no longer exists (deleted account) (src/Helpers/AuthHelpers.php:22-72)- Password reset increments the version, invalidating old sessions
- A role or status change in the admin user editor increments the version (
src/actions/admin/users.php:82-97) - Ban, unban, and suspend increment the version (
src/actions/admin/users.php) - Legacy sessions (created before the
session_versionmigration) are rejected because they have no stored version POST /logout-othersincrements the current user’s version and refreshes only this device, signing out every other device (index.php:163,src/actions/users.php:213)POST /admin/disconnect-userincrements another non-admin user’s version without changing the account (index.php:210,src/actions/admin/users.php:195)- Deleted accounts are rejected on the next request (
src/Helpers/AuthHelpers.php:54-57)
Watch/Unwatch Hidden Thread Protection
handle_watch() and handle_unwatch() now validate thread visibility before performing watch/unwatch operations. Users cannot watch or unwatch hidden/pending threads they cannot view, preventing information leakage about thread existence.
Host Header URL Generation
Absolute URLs now use configured base_url instead of $_SERVER['HTTP_HOST'], preventing host header injection via spoofed headers.
PluginManager Hook Fix
Hook callbacks now use return false instead of continue, ensuring hooks don’t accidentally skip subsequent handlers.
Content Hardening
- Markdown fuzzing: Tested against nested markdown, Unicode normalization, very long input (15000+ chars), malformed tags, attribute breakout vectors.
- Upload validation: Extension whitelist, MIME type verification, size limits, content validation. Uploaded files use generated IDs (not user-supplied names).
- Plugin manifest validation: v1 schema validated at install time — missing name, invalid ID format, incompatible core/PHP versions, and unmet dependencies are rejected.
Reporting
If you encounter a malicious or problematic plugin/theme, report it on the official forum: www.bulletinbored.net/forum.