French README can be found here : README_fr.md

Introduction

Configuration tool for SIRP dfir-iris[1] based on yaml files, in a infra-as-code flavor. The goal of this tool is help admin to create and maintain iris object like customers, users, case templates, etc.

The tool try to make an RBAC approach, user customer memberships are set via groups, not directly.

The script is written in python and use official python iris-client[2]. Configuration files use yaml.

• [1] https://www.dfir-iris.org/
• [2] https://github.com/dfir-iris/iris-client

Configuration

Files tree

Like ansible inventory, each iris environnement or instance have his config directory. At runtime, we specify witch inventory to use. Here an inventory example :

.
├── example_env
│   ├── caseTemplates
│   │   ├── intrusion.yml
│   │   └── phishing.yml
│   ├── config.yml
│   ├── customAttributes
│   │   └── customers.yml
│   ├── customers.yml
│   └── groups.yml
├── configure-iris.py
...

You can copy example_env directory from this repo and rename it 'staging' or 'preprod'.

Main config file example_env/config.yml

This file contain global variables like iris url or user token. Script need a token of an iris admin account. File/dir mappin can be modified :

---
apiHost: "https://dfir-iris.toto.fr"
#apiKey: "123456"

logLevel: "logging.INFO"
logFile: "example_sync.log"

customerConfigFile: "customers.yml"
groupsConfigFile: "groups.yml"
caseTemplatesDir: "caseTemplates/"
customAttributesDir: "customAttributes/"

#defaultCustomerEntityId: "1"

Tips:

• Var defaultCustomerEntityId is optional, can be used for rename the default customer (with id 1). Specified entityId must exist in example_env/customers.yml.
• Var apiKey is optional. If not defined, can be prompted at runtime.

Config file example_env/customers.yml

This file is require and define iris customers objects and witch groups can access it. For example :

- name: "Site principal"
  entity_id: 1
  description: "Site principal de l'organisation"
  groups:
  - SOC
  - CISO
  - "admins site A"
  itsm_mapping: "Support_site_A"
  ipam_mapping: "01"
- name: "Site B"
  entity_id: 2
  description: "Site B de l'organisation"
  groups:
  - SOC
  - CISO
  - adminsB
  itsm_mapping: "Support_site_B"
  ipam_mapping: "02"

Tips:

• EntityId is used to ensure a customer not be recreate if we want to rename it.
• Extra vars itsm_mapping or ipam_mapping are iris custom attributes.

Config file example_env/groups.yml

Define both groups and users in iris. This file is also used to set permission in iris.

- name: SOC
  description: "Security Operation Center"
  profil: "admin"
  members:
  - toto
  - titi
- name: "admins site A"
  description: "IT admin of site A"
  profil: "user"
  members:
  - titi
  - tutu

Tips:

• Members is a list of user's login (must match sub if we use OIDC).
• A user can be member of multiple groups.
• Profil is a keyword for a list of iris permission, see irisConfigTool/group.yml.
• Users are created, activated or disactivated. Actually, there is no update or delete.

Directory example_env/customAttributes/

Custom attributes feature is usefull, we can add extra attributes to builtin iris object by define them in yaml files in this directory. For example, if you want add attributes to customers, add a file named customer.yml :

---
Config:
  entity_id:
    type: "input_string"
    mandatory: true
    value: ""
  ipam_mapping:
    type: input_string
    mandatory: false
    value: ""
  itsm_mapping:
    type: input_string
    mandatory: false
    value: ""

The script use filename (with out .yml) to match an object type.Valid values are : customer, case, task, evidence, note, asset, event, ioc.

Tips:

• Modify custom attributes can have impact, try to not rename them too much.
• The script accept also .json file.

Directory example_env/caseTemplates/

In this directory, we can put our case templates, in json or yaml format. Script can add, modify and delete templates without impact on existing cases. Yaml format can be more userfriendly, specially if you want complex string with markdown. A yaml example of template :

name: "phishing"
display_name: "Modèle pour campagne de phishing"
description: "Ce modèle peut être utilisé lorsqu'on nous signal une campagne de phishing ciblé"
author: "toto"
title_prefix: "[SPAM]"
classification: "fraud:phishing"
summary: |
  # Rapport
  - [ ] Analyser le mail suspect
  - [ ] Extraire les IOCs
  - [ ] Bloquer les urls
  ## Analyse mail
  Indiquer ici les détails de la campagne ciblé

  ## Analyse url piégée
  Présence malware, redirection, etc
tags:
  - "phishing"
  - "spam"
tasks:
  - title: "Signaler l'adresse expéditeur"
    description: "Si partenaire, signaler l'adresse à l'alias abuse"
    tags: []
  - title: "Bloquer l'url sur l'EDR"
    description: "Bloquer la ou les urls de sites piégés sur l'EDR"
    tags:
      - edr

Tips:

• The script accept also .json file.

Usage

Prerequisite

Script need dfir-iris-client module, it can be install with pip :

pip3 install dfir-iris-client

Execution

With a configured inventory, you can execute main script configure-iris.py from a computer with an iris network access :

python configure-iris.py example_env

If an error during conf reading occur, it display in stdout. If starting is ok, all others oprations are logged in a file defined in config.yml. Example of runtime logs :

2025-12-09 17:01:23,502 INFO irisSync.py:32 <module> : Run irisSync with config:pprod/config.yml loglevel:INFO
2025-12-09 17:01:23,779 INFO custom_attribute.py:53 updateRemoteCustomAttribute : Attribute updated id:8
2025-12-09 17:01:23,870 INFO custom_attribute.py:53 updateRemoteCustomAttribute : Attribute updated id:7
2025-12-09 17:01:24,074 INFO case_template.py:108 updateRemoteCaseTemplate : Case template updated name:spam_phishing
2025-12-09 17:01:24,192 INFO customer.py:163 setDefaultCustomerEntityId : Customer updated with customer_id 1
2025-12-09 17:01:24,359 INFO customer.py:123 updateRemoteCustomer : Customer updated Site principal with customerId 1
2025-12-09 17:01:24,431 INFO customer.py:123 updateRemoteCustomer : Customer updated Site B with customerId 2
2025-12-09 17:01:24,836 INFO group.py:103 updateRemoteGroup : Group updated SOC with group_id 4
2025-12-09 17:01:24,961 INFO group.py:103 updateRemoteGroup : Group updated admins site A with group_id 5
2025-12-09 17:01:25,607 INFO group.py:125 updateRemoteGroupMembers : Members updated with group_id 4 and members_id [4, 6]
2025-12-09 17:01:25,674 INFO group.py:125 updateRemoteGroupMembers : Members updated with group_id 5 and members_id [10, 9]
2025-12-09 17:01:25,987 INFO user.py:158 updateRemoteUserMemberships : User customers updated with user_id 10
2025-12-09 17:01:26,073 INFO user.py:158 updateRemoteUserMemberships : User customers updated with user_id 9
2025-12-09 17:01:26,162 INFO user.py:158 updateRemoteUserMemberships : User customers updated with user_id 4
2025-12-09 17:01:26,246 INFO user.py:158 updateRemoteUserMemberships : User customers updated with user_id 6

In my opinion, automatize the execution is no need. Run the script when you modify inventory. Script is not really idempotent but it can be rerun without impact.

Know limitations

Script try to use methods from dfir-iris-client as much as possible. If needed method is absent, it use directly pi_post et pi_get from Session class.

Customers

Acutally, a customer cant be deleted, there is an API error.

Users

API require a password at user creation, script set a random one. User deletion seem possible but i prefer desactivate an account.

License

AGPLv3

Author Information

Gilian GAMBINI @ SOC-SSI-INRAE