Security

Security

FreeITSM ships with several layers of defence covering authentication, sensitive-data storage, and brute-force resistance. This page is the security reference for evaluators and administrators.

Authentication

Analyst login

• Username + password stored as bcrypt hashes in analysts.password_hash
• Hashing uses PHP's password_hash() with PASSWORD_DEFAULT; authentication uses password_verify() to re-hash the input and compare, so passwords are one-way — they cannot be reversed from the stored hash
• Per-hash salt: every call to password_hash() generates a unique random salt, so the same password produces a different hash each time
• Cost factor: bcrypt runs configurable work rounds (currently 2^12 = 4,096 iterations), keeping brute-force attacks slow
• Password expiry policy: a configurable maximum password age (30–365 days), with a forced password change on next login once expired
• Account lockout: a configurable maximum number of failed login attempts before a temporary account lock, with a configurable lockout duration
• Minimum password length: 8 characters (enforced on change and reset)
• Default admin: admin / freeitsm — change this immediately on first login. The SQL script ships a pre-computed hash for this account (once the password is changed, a new unique hash is generated), and the db_verify.php endpoint also seeds it at runtime — with a fresh hash — if no analysts exist

Multi-Factor Authentication (TOTP)

• Pure-PHP implementation of RFC 6238 (TOTP) and RFC 4226 (HOTP)
• No external dependencies — uses PHP's hash_hmac() and random_bytes()
• 6-digit codes, 30-second time step, ±1 window tolerance (90s)
• Compatible with any standard authenticator: Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden
• Setup: account menu → MFA → scan QR (or paste secret) → verify a code → enabled
• Secrets encrypted at rest with AES-256-GCM in analysts.totp_secret
• Disabling MFA requires the account password — preventing unauthorised deactivation from an unattended session
• Trusted devices: users can opt in to skip the OTP prompt on a trusted browser for a configurable number of days — cookie-based, with SHA-256-hashed tokens stored server-side

MFA is optional and per-analyst — analysts with MFA disabled log in with just username and password as normal. When an analyst has enabled MFA, the login flow adds a second verification step:

1. Analyst enters username and password on login.php
2. Password verified → MFA pending state stored in the session (mfa_pending_analyst_id etc.) — analyst_id is NOT set yet
3. Login page renders the OTP form (shield icon, 6-digit input, auto-submit)
4. Analyst enters the code from their authenticator app → JS calls api/myaccount/verify_login_otp.php
5. Server decrypts the stored TOTP secret and verifies the code (±1 time window)
6. On success: $_SESSION['analyst_id'] is set, the pending state is cleared, and the analyst is redirected to index.php

The "Cancel and return to login" link clears the pending state so a different analyst (who may not have MFA) can log in on the same browser.

Password reset by email

• "Forgot password" sends a single-use token via email (configurable mail provider)
• Token expires after a short window
• The expiry window is one hour
• Token comparison uses hash_equals() (timing-safe)

Single sign-on (SSO / OIDC)

• Optional OpenID Connect SSO alongside local login — works with Keycloak, Microsoft Entra ID, Okta, Google Workspace, Authentik, etc.
• Authorization Code + PKCE (S256), with state and nonce validation; ID-token signature verified against the provider's JWKS (vendored firebase/php-jwt)
• Client secrets encrypted at rest; local login retained as a break-glass fallback so a down IdP can't lock anyone out
• Full details: Single Sign-On (SSO / OIDC)

LDAP / Active Directory sign-in

• Optional directory sign-in alongside OIDC — passwords are checked against your existing directory (Active Directory, OpenLDAP, FreeIPA, 389) by bind, people can be auto-created on first login, and access is gated by directory group
• Guards against the RFC 4513 unauthenticated-bind trap: an empty (or NUL-containing) password is rejected before any network call
• The read-only service account's password is encrypted at rest and never returned to the browser
• Full details: LDAP & Active Directory

IP-based brute-force protection

• Repeated failed login attempts from the same IP are throttled
• Both username and IP-level lockouts to defend against credential stuffing
• Escalating bans for IPs attempting logins against non-existent or locked accounts, with configurable thresholds and 24-hour bans
• Login attempts (success + failure) logged with IP and user agent in the Reporting module

Authorisation

Authorisation is three layers, each answering a different question, each enforced server-side and failing closed. Hiding a button is never the control; it is at most a courtesy on top of one.

Layer	Question	Gate	Default
1 — Module access	Can they enter this module?	requireModuleAccess() / requireModuleAccessJson()	Absence = everything (an analyst with no restriction gets all modules)
2 — Capabilities (Roles)	Can they administer this part of it?	requireCapability(Cap::X) / requireCapabilityJson(Cap::X)	Deny by default (no role, no settings)
3 — Administrator	Can they run the System module?	requireAdminJson() / the page gate	Deny by default (analysts.is_admin)

is_admin is a superset: an administrator implicitly holds every capability, which is what makes Layer 2's deny-by-default safe to switch on — the tightening can never lock the instance owner out.

Layer 1 — Module access control

• Per-analyst and per-team module grants, managed at System → Analysts / Teams; unioned at one choke-point (getAnalystAllowedModules()).
• Enforced on the launcher cards, the waffle menu, and on the pages and APIs themselves — a restricted analyst cannot simply type the URL.
• Checks are authoritative (re-read from the database per request), so a just-revoked analyst is stopped even on a stale session.
• See Module Access Control.

Layer 2 — Capabilities / Roles

• Permission goes down to the individual settings tab, so someone can maintain the ticket statuses without reaching the mailbox OAuth credentials two tabs along.
• A settings tab you lack is not rendered into the page at all — absent, not hidden. There is no DOM to un-hide.
• Every settings write endpoint carries its own guard. Operational reads are deliberately not guarded — they are what the everyday module needs to function. Except a read that returns credentials: ask what the response contains, not just what the endpoint does.
• Settings that share the generic save_system_settings.php endpoint are authorised per setting key (includes/settings_keys.php), because one guard cannot cover five callers with five audiences. A key no module claims cannot be written through it.
• See Roles & Permissions and the Developer Guide.

Layer 3 — Administrator (System)

• analysts.is_admin gates the whole System module — page and API (includes/admin_api_guard.php). Before this, every analyst was effectively an administrator and could self-escalate.
• The last administrator is protected from removal.
• See Admin Access Control.

Auditing it — the guard nobody wrote

Type-safe permissions catch a misspelled check. Nothing catches a check somebody simply forgot to write — no language feature saves you from a line that isn't there, and that omission has repeatedly turned out to be the real hole.

System → Debug tools → D005 (Endpoint permission coverage) reads every endpoint under api/ and reports what actually guards each one — a capability, administrator-only, module access, an API key, a webhook signature, a URL token, "logged in and nothing more", or nothing at all — ranked by how much damage the gap allows. It also flags capabilities offered on System → Roles that no endpoint enforces (a tick-box granting nothing), and capabilities passed as a bare string instead of a Cap:: constant.

Run it after adding endpoints and before a release. Endpoints that are public by design (login, self-service, the REST API, inbound webhooks) and those acting only on the caller's own account (your own password, your own MFA) are declared as exclusions with reasons, so the findings stay short enough to act on.

Multi-tenancy and team filtering

• Company (tenant) access is scoped per analyst and per team, unioned the same way, and applied at the query level.
• The Tickets module filters department visibility by team membership (get_my_departments.php vs get_departments.php).
• The analyst's team memberships are stored in the session at login, and API endpoints filter by team-accessible departments.
• An analyst with no team memberships sees everything — the unrestricted (admin) case.
• See Multi-Tenancy.

Encryption at Rest

AES-256-GCM authenticated encryption for sensitive database values.

• Key file: stored outside web root at C:\wamp64\encryption_keys\sdtickets.key
• Key: a 256-bit random key
• Nonce: a fresh 96-bit random IV per encryption, so the same value encrypted twice produces different ciphertext
• Auth tag: 128-bit — detects any tampering with encrypted data
• Format: ENC: + base64(IV + auth tag + ciphertext) — auth tag prevents tampering
• Migration-safe: values without ENC: prefix pass through unchanged for gradual rollout
• Key generation: one-click from System → Encryption (or php -r "echo bin2hex(random_bytes(32));")
• No regenerate button — preventing accidental key destruction is more important than convenience

Encrypted columns

system_settings:

• vcenter_server, vcenter_user, vcenter_password
• knowledge_ai_api_key, knowledge_openai_api_key
• intune_tenant_id, intune_client_id, intune_client_secret
• (Per-feature AI keys — <ns>_api_key for knowledge_ai, cmdb_ai, workflow_ai, forms_ai, tickets_reply_cleanup, plus RFP Builder — each encrypted and masked separately; see AI Providers)

target_mailboxes:

• azure_tenant_id, azure_client_id, azure_client_secret
• oauth_redirect_uri, imap_server, target_mailbox
• imap_username, imap_password, smtp_server (basic IMAP/SMTP mailboxes)

analysts:

• totp_secret

Masked API responses

A subset of true secrets listed in MASKED_SETTING_KEYS are returned as ****<last4> rather than plaintext by api/settings/get_system_settings.php. The corresponding save endpoints treat blank or asterisk-prefixed submissions as "leave unchanged" so the user can re-save the settings form without re-typing the secret each time.

The masked set covers vcenter_password, knowledge_ai_api_key, knowledge_openai_api_key and intune_client_secret, plus every per-feature AI key (see AI Providers) — i.e. the values that are secrets, as opposed to encrypted-but-displayable configuration such as server names. The "leave unchanged" convention is applied by api/settings/save_system_settings.php.

Session Management

• Standard PHP sessions (session_start())
• Session key: $_SESSION['analyst_id'] for analyst auth, $_SESSION['ss_user_id'] for self-service portal users (separate auth domains)
• Password-expiry guard in includes/waffle-menu.php — if $_SESSION['password_expired'] is set, every page redirects to force_password_change.php until resolved

Injection Defences

• SQL injection: PDO prepared statements throughout — parameters are never concatenated into SQL
• XSS: server-side output encoding with htmlspecialchars(); client-side rendering escapes untrusted values via the DOM textContent → innerHTML pattern

Audit Trails

• Every ticket change is written to the ticket's audit trail
• Login attempts (success and failure) are logged with IP and user agent — see IP-based brute-force protection above

Email Security

• OAuth 2.0 for Microsoft 365 and Google Workspace mailboxes — no plaintext mailbox passwords
• Mailbox whitelist: per-mailbox domain and email-address whitelisting (mailbox_email_whitelist table); non-whitelisted senders are rejected and logged. A mailbox with no whitelist entries accepts all senders — the whitelist only restricts once at least one entry exists
• Mailbox activity log: every email imported or rejected during mailbox processing is recorded in mailbox_activity_log (action, sender, subject, reason, resulting ticket)
• Rejection actions: configurable per-mailbox actions for rejected emails (delete, move to Deleted Items, mark as read)
• Import actions: configurable post-import actions (delete, move to folder) with folder existence verified via Graph API before saving

File Uploads

• Module-specific upload folders (e.g. tickets/attachments/, lms/content/, forms/uploads/) — each is gitignored
• Generated filenames; original names stored in DB for display
• Served via PHP endpoints that check session auth before serving the file

API Keys (External Access)

For the browser extension and external integrations (e.g. PowerShell asset inventory):

• API keys generated at Software → Settings → API Keys
• Rate limited: 60 requests per minute per key (configurable in System Settings)
• Bearer-token style header
• Revocable per-key with last-used tracking

Going Live Checklist

When moving from evaluation to production:

1. Change the default admin password
2. Delete the /setup folder — it contains diagnostic info useful only during install
3. Generate a unique encryption key if you used a sample one
4. Back up the encryption key file — losing it makes encrypted columns unrecoverable
5. Configure OAuth for any mailboxes — avoid IMAP/password where possible
6. Enable MFA on the admin account
7. Restrict module access per analyst at System → Modules
8. Configure the password reset email so analysts can recover access without admin intervention
9. Review whitelist entries for each mailbox to limit who can create tickets via email