An incident case platform holds the most sensitive record your security team produces, from compromised account lists to attacker infrastructure and legal notes, yet many teams stand up open source case tools with default settings and an exposed web interface. DFIR-IRIS (Incident Response Investigation System) is an open source, LGPL-3.0 licensed web platform for incident responders to share technical details during investigations. This guide explains what it does, where it fits in a response team, how to deploy it safely, how its access model and API keys work, and which settings and advisories matter most. It is written for incident response leads, SOC engineers and the platform owners who run the tool. For choosing between case management approaches, see the Security Case Management Guide; this page goes deeper on one tool.
This is an independent guide from NHI Mgmt Group, based on DFIR-IRIS's public documentation as of November 2026. It is not sponsored or reviewed by DFIR-IRIS. Product features change, so confirm settings against DFIR-IRIS's current documentation.
Key takeaways
- Use a tagged stable release. As checked on 8 November 2026, the project README marks v3.0.0-beta.1 as not recommended for production and names v2.4.29 as the latest stable release; the master branch is never for production.
- Keep it off the internet. The maintainers state that the interface should not be exposed on the internet and recommend a private, dedicated and secured network.
- Four secrets decide whether authentication holds. IRIS_SECRET_KEY, IRIS_SECURITY_PASSWORD_SALT and the two PostgreSQL passwords must be set to random values; the documentation warns that otherwise authentication bypass may occur.
- Every user has an API key from day one. Keys are issued at account creation, sent as Bearer tokens, and revoked only by renewing them, so treat them as non-human credentials with owners and rotation.
- Patch on advisories, not on a calendar. The project's GitHub advisories include a critical arbitrary file deletion issue (January 2026), server-side template injection in reports (April 2024) and seven advisories published on 28 May 2026.
What the tool does
DFIR-IRIS organises an investigation as a case. Analysts record assets, indicators of compromise, timeline events, notes, tasks and evidence references in one shared place, so that handovers, reports and lessons learned draw on the same record. Report templates generate case reports from that data. Modules extend it: the documentation describes processor modules, which run when predefined actions (hooks) occur, such as enriching a new IOC with VirusTotal or MISP insights, and pipeline modules, which process uploaded evidence such as EVTX files. Built-in modules listed in the documentation include IrisVTModule, IrisMispModule, IrisWebHooksModule, IrisCheckModule and IrisEVTXModule. Almost everything the web interface does is also available through a REST API, which the interface itself uses.
From v3, the project ships as three repositories: iris-web (the umbrella, owning the Docker Compose stack), iris-backend (Python and Flask API and Celery workers) and iris-frontend (SvelteKit interface). The v3 stack runs six services:
| Service | Role | Security note |
|---|---|---|
| app | Flask API and web server (iris-backend image) | Holds session, authentication and authorisation logic; never expose its upstream port directly |
| worker | Celery job handler for modules and long tasks | Runs module code with the module's configured third-party API keys |
| db | PostgreSQL | All case data; v3 moves client authentication from md5 to scram-sha-256 |
| rabbitmq | Broker for Celery | Internal only; no published port needed |
| nginx | TLS termination and reverse proxy | The only service that should be reachable by users, on port 443 |
| frontend | SvelteKit server-side rendered interface | Rejects state-changing requests whose Origin is not a configured hostname |
The stable v2.4 line has the older interface served by the app service; check the documentation for the version you deploy.
Defender use cases
- Running a live incident: one case per incident with tasks assigned to analysts, a shared timeline and an IOC list that feeds blocking and hunting. See the Digital Forensics (DFIR) Guide.
- Multi-team or multi-client work: customers and group-based case access let an MSSP or a central CSIRT keep cases separated while bringing in people from different organisations to work on one case.
- Enrichment without copy and paste: processor modules query threat intelligence platforms when IOCs are added, so analysts see context in the case.
- Evidence tracking: the case records which evidence exists and where; pair it with a formal chain of custody process. See the Evidence Handling and Chain of Custody Guide.
- Credential compromise cases: list every affected human and non-human identity as an asset or IOC, track rotation tasks to completion, and keep the record for later audit. See the AI model provider API keys response guide for a worked example of key leak handling.
- Reporting and lessons learned: report templates turn the case into management and regulator-facing reports from the same data.
Deployment and safe use
- Pick the version deliberately. Use the latest stable tag (v2.4.29 as checked) for production and pin it. In v3, one IRIS_VERSION value pins all four image tags so services roll together.
- Place it on a private network. Put the platform in a management network reachable only from analyst workstations or a VPN with MFA. Do not publish ports other than 443 on nginx.
- Set the critical secrets. Replace every __MUST_BE_CHANGED__ value: POSTGRES_PASSWORD, POSTGRES_ADMIN_PASSWORD, IRIS_SECRET_KEY (Flask session key) and IRIS_SECURITY_PASSWORD_SALT, all random. The configuration reference supports reading settings from Azure Key Vault (AZURE_KEY_VAULT_NAME), then environment variables, then a config.ini file, in that priority order; prefer a vault over a .env file on disk.
- Replace the default certificate. IRIS uses a self-signed certificate by default, which the documentation says is only suitable for testing. Set KEY_FILENAME and CERT_FILENAME to certificates issued by your CA.
- Control the first administrator. By default an administrator account is created and its password printed to the app container log on first start. Pre-set IRIS_ADM_PASSWORD (it must meet the password policy) and IRIS_ADM_API_KEY (no complexity check is applied, so generate a long random value), then change both after first login and clear old container logs.
- Connect identity. The stable documentation supports IRIS_AUTHENTICATION_TYPE local or ldap, with LDAP_USE_SSL and LDAP_VALIDATE_CERTIFICATE for LDAPS. The v3 backend configuration reference adds OIDC options, including group sync from a token claim (OIDC_MAPPING_USERGROUP) and a trusted proxy list for header-based mode. If you use the header-based proxy mode, set OIDC_IRIS_PROXY_TRUSTED_IPS: the reference warns that otherwise anything reaching the backend directly could log in as any registered user.
- Design groups before users. Create groups for analysts, leads and administrators, and grant case access per group. Restrict server_administrator to a small set of named accounts.
- Back up and test restore. The maintainers ask operators to back up the database. The v3 upgrade procedure keeps a cold tarball and a pg_dumpall dump of the old PostgreSQL volume as rollback artefacts; keep them until the new version is verified, and rehearse a restore before relying on it.
- Upgrade with a window. Read release notes first. The v3 upgrade closes every open session (API keys keep working), removes the legacy v1 API and changes the database authentication method, so integrations need testing in a staging copy.
Access model and API keys
| Control | How IRIS implements it | Recommended setting |
|---|---|---|
| Permissions (RBAC) | Granted only through groups; standard_user or server_administrator | Two or three administrators; analysts as standard_user |
| Case access (ACL) | deny_all, read_only or full_access per group and per user; a user-level setting overrides groups | Default sensitive cases (insider, legal hold) to deny_all and grant by exception |
| API keys | Issued per user at creation; Bearer token in the Authorization header; Renew invalidates the old key | Separate service accounts for integrations; renew on staff exit and on suspected exposure |
| Login protection (v3) | IRIS_LOGIN_MAX_ATTEMPTS default 10, IRIS_LOGIN_LOCKOUT_SECONDS default 900, per-client ceiling default 50 | Keep defaults or tighten; set the client ceiling correctly behind a proxy |
| MFA (v3) | enforce_mfa setting sends unenrolled users to enrolment at next sign-in | Enable, or enforce MFA at the identity provider |
| Login banner (v3) | IRIS_LOGIN_BANNER_TEXT | Acceptable use and monitoring notice |
API keys are the platform's non-human identities. Integrations such as SOAR playbooks or ticketing connectors should use a dedicated account whose key is stored in a secrets manager, never a responder's personal key, because renewing a person's key on exit would otherwise break automation, and leaving it would keep a leaver's access alive. Module configurations also hold third-party API keys (for example to threat intelligence services); treat the module settings page as a secrets store and limit who can see it. See the API Key Management Guide.
Detection and hardening value
A case platform improves detection indirectly: IOCs, timelines and root causes recorded consistently become detection engineering input. It is also a target. The project's own advisory history shows the classes of flaw to plan for:
- Report template abuse: server-side template injection in reports (advisory published April 2024). In v3, IRIS_ALLOW_PRIVATE_EGRESS defaults to False so report templates cannot fetch internal addresses or the cloud metadata endpoint; keep it that way and limit template upload to administrators.
- File handling: arbitrary file deletion via mass assignment in datastore file management (critical, January 2026) and insecure file upload (May 2026). Keep evidence files in their proper storage and patch promptly.
- Authorisation and data exposure: improper authorisation, excessive data exposure, mass assignment and alerts falsely attributed to customers (May 2026). Multi-tenant deployments are most exposed.
- Web flaws: cross-site request forgery, open redirect and an XSS issue (February 2024).
Monitor the platform like any other sensitive application:
- Authentication events: failed logins and lockouts, logins from unexpected networks, administrator logins.
- Privilege changes: users added to administrator groups, case access changed to full_access on sensitive cases.
- API key use: volume and source of API calls per key; a responder's key used from a server is a red flag.
- Webhook and workflow egress: v3 keeps webhook delivery logs for 30 days by default (IRIS_WEBHOOKS_DELIVERY_RETENTION_DAYS); forward them centrally if you need longer.
Metrics that show the platform is working and safe: percentage of incidents with a case opened within one hour of declaration; percentage of cases closed with a completed lessons learned note; number of administrator accounts (target: small and stable); days from a published IRIS advisory to patched production; API keys renewed within one day of staff exit (target 100%).
| Area | NIST CSF 2.0 | NIST SP 800-53 Rev. 5 |
|---|---|---|
| Case handling and coordination | RS.MA-01, RS.AN-03 | IR-4, IR-5, IR-8 |
| Integrity of investigation records | RS.AN-06 | AU-9 |
| Reporting and notification | RS.CO-02 | IR-6 |
| Access to the platform | PR.AA-05 | AC-3, IA-2(1) |
Alternatives
| Option | Best fit | Trade-off against DFIR-IRIS |
|---|---|---|
| TheHive with Cortex | Teams wanting observable analysers and MISP integration | Check current licensing and editions; see the TheHive and Cortex Case Management Guide |
| SOAR or SIEM case modules | SOCs already standardised on one vendor platform | Tighter alert integration, less forensic depth and portability |
| IT service management tickets | Small teams with few incidents | Familiar; add access separation for sensitive cases and a separate IOC record |
| Shared documents | Very small teams, tabletop exercises | No audit trail or structured data; not suitable for regulated incidents |
DFIR-IRIS suits teams that want a self-hosted, forensic-oriented case record with an API and module system, and can patch and operate it. Small teams without platform operations capacity may be better served by a managed case module. Collection and analysis tools sit alongside it rather than replacing it; see the Velociraptor Guide and the Open Source DFIR Tools Landscape Guide.
Common failure patterns
- Default secrets left in place: unchanged IRIS_SECRET_KEY or salt values, which the documentation links to authentication bypass.
- Internet-facing instance: exposed for convenience during an incident and never taken back.
- Administrator password in logs: the first-boot password left in container logs that are shipped to a log platform with wide access.
- Personal API keys in automation: integrations using a responder's key, so offboarding breaks tools or leaves access alive.
- Running beta or master in production: against the maintainers' explicit advice.
Practitioner checklist
- Deploy a pinned stable release, not beta or master.
- Place the platform on a private network behind MFA-protected access; expose only nginx on 443.
- Set random values for IRIS_SECRET_KEY, IRIS_SECURITY_PASSWORD_SALT and both database passwords, ideally from a vault.
- Install a CA-issued certificate in place of the self-signed default.
- Pre-set and then change the first administrator password and API key; purge first-boot logs.
- Integrate LDAPS or OIDC, enable MFA, and restrict server_administrator to named individuals.
- Use dedicated integration accounts with vaulted API keys; renew keys on exit or exposure.
- Subscribe to the iris-web GitHub security advisories and patch within a defined window.
- Back up the database and rehearse restore before every major upgrade.
Standards and references
- DFIR-IRIS: iris-web repository and README
- DFIR-IRIS documentation: Configuration
- DFIR-IRIS documentation: Access control
- DFIR-IRIS documentation: API
- DFIR-IRIS documentation: Modules
- DFIR-IRIS: iris-web security advisories
- DFIR-IRIS: Upgrading IRIS to v3.0.0
- NIST: Cybersecurity Framework 2.0
Related NHI Mgmt Group resources: Security Case Management Guide · TheHive and Cortex Case Management Guide · Open Source DFIR Tools Landscape Guide · Docker and Docker Compose Security Guide