tirreno

tirreno is an open-source PHP/PostgreSQL security framework that embeds event tracking, threat detection, and risk scoring directly into applications. Unlike firewalls, WAFs, and SIEM tools that operate at the network perimeter, tirreno detects threats where breaches actually happen: inside the product, through compromised accounts and application logic abuse.

With a five-minute installation and SDKs for PHP, Python, Node.js, and WordPress, teams can ingest behavioral events and immediately access a real-time threat dashboard. The rule engine evaluates sliding-window event patterns against twelve preset rules covering account takeover, credential stuffing, bot detection, promo abuse, insider threats, and more — or teams can write custom rules in a human-readable DSL.

tirreno is designed for self-hosted, air-gapped, and legacy deployments where network-layer tools fall short. It integrates into SaaS platforms, e-commerce sites, industrial control systems (ICS), API-first applications, and environments with non-human identities like service accounts and API keys. The field audit trail captures precise change history per field, enabling compliance workflows and forensic analysis without external tooling.

The project started as a proprietary system in 2021 and was open-sourced under AGPL-3.0 in December 2024. It is developed by Tirreno Technologies Sàrl and is not VC-backed, focusing on solving real cybersecurity challenges through minimal-dependency, hand-crafted PHP code.

What You Get

• SDKs and HTTP API - Official SDKs for PHP, Python, Node.js, and WordPress let you send structured events with full context — user ID, IP, device, resource, and custom payload — in a few lines of code from any application.
• Real-time threat dashboard - A built-in web interface shows live security events, risk score distributions, user timelines, and geographic threat maps without requiring any external SIEM or BI tooling.
• Single user view - Drill into any account to see its complete activity timeline, connected devices and IPs, associated email and phone identities, risk score history, and flagged behavior patterns across sessions.
• Rule engine with preset threat library - Twelve preset rules cover account takeover, credential stuffing, content spam, promo abuse, bot detection, insider threat, dormant accounts, multi-accounting, API protection, and high-risk regions — each configurable with threshold constants.
• Review queue with automated actions - Accounts that exceed risk thresholds are automatically flagged for manual review or suspended, enabling security operations teams to triage incidents without parsing raw logs.
• Field audit trail - Track precise changes to critical fields — email addresses, permissions, balances, and any custom field — with timestamps, previous and new values, and the user and session context at the time of change.
• Enrichment pipeline - IP addresses, email domains, devices, and phone numbers are enriched asynchronously using external data sources to add threat intelligence context to every event.

Common Use Cases

• Detecting account takeover on a SaaS platform - A B2B SaaS provider instruments their login, password reset, and settings-change endpoints with tirreno events; the rule engine flags accounts showing credential-stuffing patterns and routes them to the review queue before damage occurs.
• Protecting e-commerce from promo and payment fraud - An online marketplace sends order, coupon redemption, and checkout events to tirreno, which applies promo-abuse and multi-accounting rules to detect coordinated fraudsters exploiting discount codes across linked accounts.
• Monitoring insider threats in a legacy internal portal - A financial services firm embeds tirreno into a decade-old PHP intranet application to track field changes on sensitive records, flag dormant accounts that suddenly become active, and audit privileged actions without replacing the legacy system.
• Securing API-first applications against scraping and abuse - A data platform uses tirreno’s API-protection rules to detect high-frequency scraping patterns, rate-limit bypass attempts, and unauthorized access by monitoring API key usage events and resource access patterns.
• Protecting non-human identities in microservice environments - A platform engineering team tracks service account and API key behavior through tirreno to detect compromised machine identities exhibiting anomalous call patterns or accessing resources outside their normal scope.
• Air-gapped industrial control system security - An energy company deploys tirreno on an isolated OT network to monitor command sequences from operator accounts, detect unauthorized access attempts, and produce audit trails for regulatory compliance.

Under The Hood

Architecture tirreno uses a layered MVC architecture on the FatFree Framework, with HTTP routing defined declaratively in INI configuration files that map endpoints to controller actions — keeping routing logic entirely separate from business logic. A dedicated sensor sub-application handles event ingestion through its own repository/service layer, processing incoming events after immediately closing the HTTP connection to prevent latency impact on the calling application. The risk engine pattern treats each threat rule as a self-contained class that defines its own parameter preparation and condition logic using a composable operator DSL, enabling rules to be added or modified without touching the core scoring pipeline. A separate enrichment pipeline handles external data lookups asynchronously through a queue model. The overall design is modular and domain-driven, with clean boundaries between API ingestion, rule evaluation, enrichment, and dashboard serving — though direct class instantiation in some controllers introduces coupling that a dependency injection container would resolve.

Tech Stack PHP 8.0–8.3 on the FatFree Framework handles all routing, template rendering, and application lifecycle management. PostgreSQL 12+ is the sole datastore, accessed via PDO_PGSQL with schema migrations applied at startup. Matomo Device Detector classifies user-agent strings for device and browser fingerprinting. The Ruler library provides the composable condition DSL that powers the rule engine. PHPMailer handles transactional email for alerts and account management. PHPStan performs static analysis and PHPCS enforces PSR coding standards, with PHPUnit 10 running the test suite. Docker Compose enables containerized deployment with a single curl command, while Composer Packagist allows tirreno to be embedded as a library into existing PHP projects.

Code Quality The codebase enforces declare(strict_types=1) throughout and uses PHPStan for static analysis alongside PHPCS for coding standards — both configured in committed phpstan.neon and phpcs.xml files. PHPUnit 10 covers utilities, model layers, and rule assets with fake implementations for the filesystem, HTTP client, and transport layer enabling proper unit isolation. Error handling uses explicit HTTP status codes with localized error messages loaded from the dictionary system. Test strictness settings in phpunit.xml enable failure-on-risky and strict output checks. Test coverage is most comprehensive in the utilities layer, with lighter coverage of complex domain models. The sensor sub-application maintains its own independent test infrastructure, reflecting its microservice-like role.

What Makes It Unique tirreno addresses a gap that most security tooling ignores: the application layer where account takeovers and logic abuse happen after authentication succeeds. The sliding-window event analysis in rule conditions enables detection of time-sensitive patterns like credential stuffing bursts without requiring external stream processing infrastructure. The sensor’s early connection-close pattern means security instrumentation adds no perceptible latency to protected applications. The field audit trail goes beyond activity logging to capture the precise before/after state of individual fields with session context — enabling forensic reconstruction of exactly what changed, when, and under what circumstances. Twelve production-ready threat rule templates mean teams can deploy meaningful detection coverage on day one without security engineering expertise.

Self-Hosting

tirreno is licensed under the GNU Affero General Public License version 3.0 (AGPL-3.0). The AGPL is a strong copyleft license that allows commercial use, modification, and self-hosting without cost, but with a significant network obligation: if you modify tirreno and provide it as a service to others over a network, you must make your modified source code available to those users. For most self-hosting scenarios — deploying tirreno internally to monitor your own product — this network obligation does not apply. However, if you plan to offer tirreno as a managed service to customers, you would need to release your modifications. The name “tirreno” is a registered trademark of Tirreno Technologies Sàrl, and no trademark license is granted under the AGPL, so forks cannot use the name.

Running tirreno yourself requires a PHP-capable web server (Apache with mod_rewrite), PostgreSQL 12+, and the PDO_PGSQL and cURL PHP extensions. Minimum hardware is modest — 512 MB RAM for PostgreSQL (4 GB recommended for production load) and 128 MB for the application — but storage scales with event volume at approximately 3 GB per million events. You are responsible for database backups, schema migrations on upgrade, SSL termination, and cron-based background job scheduling for the enrichment pipeline and queue processing. Docker Compose simplifies initial deployment, but ongoing operations require standard database administration practices. There is no built-in high-availability or clustering support in the open-source release.

Tirreno Technologies Sàrl is the commercial entity behind the project, though as of open-sourcing in December 2024 tirreno operates as a community-supported AGPL project without a publicly advertised paid managed tier. Support is available through the Mattermost community channel and GitHub issues. Users who need enterprise SLAs, dedicated support, or a managed hosted option should contact Tirreno Technologies Sàrl directly, as commercial arrangements may exist that are not publicly documented. Compared to a hypothetical hosted version, self-hosters absorb the full operational burden of uptime, upgrades, backup management, and scaling — but gain complete data sovereignty and the ability to run in air-gapped or restricted network environments where SaaS tools are not an option.