PyFlowintel

PyFlowintel is a Python library for interacting with Flowintel instances through their REST API. Flowintel is an open-source platform for security case management.

PyFlowintel is developed within SATRAP-DL, a sub-project of CyFORT (Cloud cybersecurity Fortress of Open Resources and Tools for resilience), carried out in the context of the IPCEI-CIS project.

Table of contents

• Overview
• Features
• Documentation
• Getting started
• Usage
• Testing
• Project status
• Roadmap
• License
• Acknowledgments
• Contact

Overview

PyFlowintel provides a Pythonic interface to Flowintel's REST API, enabling developers and security analysts to automate workflows integrating Flowintel with other security tools. It follows a layered architecture with dedicated endpoint modules (cases, tasks, templates, admin, importers), robust error handling, and flexible configuration.

For automated incident handling pipelines, see the SATRAP-DL technical documentation.

Features

Key Features

• API Coverage: Support for case, task, template, admin, and importer endpoints
• Clean Architecture: Dedicated endpoint modules with separation of concerns
• Error Handling: Custom exception hierarchy for different error scenarios
• Input Validation: Parameter validation with informative error messages
• Flexible Configuration: YAML files or direct arguments
• Centralized Logging: Package-wide logging with adjustable levels
• Context Manager: Automatic resource cleanup

Design Principles

• Free/libre and open source
• Modular and extensible design
• Minimal dependencies (requests, pyyaml)

Documentation

• Features Documentation - All available methods and endpoints
• Installation Guide - Containerized development environment setup

Getting started

Installation

Install either locally with Python/Poetry or using the containerized VS Code development environment.

Local environment with Python and Poetry

This project uses Poetry for dependency and environment management. If you already have (the required versions of) Python and Poetry installed, this is the simplest option.

Prerequisites

• Python 3.9 or higher
• Poetry 1.8 (see Poetry installation guide)

Set up

1. Clone the repository and go to the project folder.

git clone https://github.com/AbstractionsLab/PyFlowintel

cd pyflowintel

2. Install dependencies

poetry install

3. Activate the virtual environment

poetry shell

Development environment in VS Code

This project can also be run inside a Docker container, which comes with Poetry pre-installed, using Visual Studio Code with the Dev Containers extension. See the Installation guide for instructions on this deployment option.

Configuration

Prerequisites

• Access to a running Flowintel instance
• API key from the Flowintel instance

Flowintel API setup

1. Copy the configuration example into a config.yaml file:

   cp config-example.yaml config.yaml

2. Edit config.yaml with your settings:

   # Production instance
   flowintel:
     base_url: http://localhost:7006/api
     api_key: your-actual-api-key-here
   
   # Testing instance (used for integration tests)
   testing:
     base_url: http://localhost:7006/api
     api_key: your-test-api-key-here

Note: config.yaml is the default configuration file (searched at project root) and is gitignored.

Logging level setup

Adjust the overall logging level in pyflowintel/commons/logging_config.py.

Usage

Client Initialization

from pyflowintel import PyFlowintel

# Option 1: Default config.yaml (recommended)
client = PyFlowintel.from_config()

# Option 2: Custom config file
client = PyFlowintel.from_config("my_settings.yaml")

# Option 3: Explicit arguments
client = PyFlowintel.from_args(
    base_url="http://localhost:7006/api",
    api_key="your-api-key-here"
)

# Recommended: Use context manager for automatic cleanup
with PyFlowintel.from_config() as client:
    cases = client.cases.list_all()
    # Your code here

Working with Endpoints

See examples/ for working code examples and tests/ for usage patterns.

Testing

PyFlowintel includes unit and integration tests. For v0.1, tests cover the PyFlowintel client, templating endpoint, and utilities.

Running All Tests

./scripts/run_tests.sh

Unit tests always run.

Integration tests require a running Flowintel instance and API key. Add the testing section to your config.yaml (see Configuration section). Integration tests run automatically if testing settings are provided, otherwise they're skipped.

Running Specific Tests

Use the unittest module to run specific test cases. For example:

python -m unittest tests.test_template_endpoint.TestCaseTemplateOperations

Project Status

PyFlowintel v0.1 (Alpha) - February 2026. Provides selected coverage of the Flowintel REST API as outlined in Features.

⚠️ Alpha Software Disclaimer: Under active development. May include incomplete features and bugs. Not intended for production use.

Roadmap

• Extend support prioritizing the cases and tasks endpoints
• Add support for the custom_tags endpoint
• Add input validation and sanitization
• Add unit and integration testing for all endpoints
• Extend documentation and examples
• Release as a PyPi library

License

Copyright (c) 2026 itrust Abstractions Lab and itrust consulting. All rights reserved.

PyFlowintel is licensed under the BSD 2-Clause license.

Acknowledgments

PyFlowintel is developed under SATRAP-DL, which is co-funded by the Ministry of the Economy of Luxembourg, in the context of the CyFORT project.

Contact

For questions, feedback, or feature requests, feel free to contact us at Abstractions Lab: info@abstractionslab.lu