mentat-gulp 1.6.51__tar.gz

mentat_gulp-1.6.51/.devcontainer/Dockerfile

@@ -0,0 +1,31 @@
+# .devcontainer/Dockerfile
+FROM mcr.microsoft.com/vscode/devcontainers/python:3.13-bullseye
+
+# Install OS dependencies
+RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor -o /usr/share/keyrings/yarn-keyring.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/yarn-keyring.gpg] https://dl.yarnpkg.com/debian stable main" | tee /etc/apt/sources.list.d/yarn.list > /dev/null && \
+    apt update && export DEBIAN_FRONTEND=noninteractive && \
+    apt -y install --no-install-recommends \
+    rustc \
+    libsystemd-dev \
+    jq \
+    inetutils-ping \
+    libpqxx-dev \
+    git-lfs \
+    rsyslog
+
+# Install pipx
+RUN python3 -m pip install --user pipx && \
+    python3 -m pipx ensurepath
+
+# setup docker
+RUN curl -fsSL https://get.docker.com | sh && \
+    apt -y install --no-install-recommends docker-compose && \
+    # Create docker group if it doesn't exist
+    groupadd -f docker && \
+    usermod -aG docker vscode && \
+    mkdir -p /run/docker 
+
+# Clean up
+RUN apt-get clean && rm -rf /var/lib/apt/lists/*
+

mentat_gulp-1.6.51/.devcontainer/devcontainer.json

@@ -0,0 +1,60 @@
+{
+  "name": "Gulp Dev Container",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "dev",
+  "workspaceFolder": "/gulp",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "bierner.markdown-mermaid",
+        "codezombiech.gitignore",
+        "DavidAnson.vscode-markdownlint",
+        "dracula-theme.theme-dracula",
+        "eliostruyf.vscode-hide-comments",
+        "foxundermoon.shell-format",
+        "fuadpashayev.bottom-terminal",
+        "Gerrnperl.outline-map",
+        "github.copilot-chat",
+        "github.vscode-github-actions",
+        "GitHub.vscode-pull-request-github",
+        "Gruntfuggly.todo-tree",
+        "kevinkyang.auto-comment-blocks",
+        "ms-python.black-formatter",
+        "ms-python.isort",
+        "ms-python.python",
+        "ms-vscode.cpptools-extension-pack",
+        "oderwat.indent-rainbow",
+        "tamasfe.even-better-toml",
+        "Tyriar.sort-lines",
+        "yzhang.markdown-all-in-one",
+        "zh9528.file-size"
+      ]
+    }
+  },
+  "features": {
+    "ghcr.io/meaningful-ooo/devcontainer-features/fish:1": {},
+    "ghcr.io/jungaretti/features/vim:1": {}
+  },
+  "remoteUser": "vscode",
+  "init": true,
+  "privileged": true,
+  "mounts": [
+    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind,consistency=cached",
+    // make these accessible in the container for development (must be cloned in the parent folder of this repo)
+    "source=${localWorkspaceFolder}/../gulp-paid-plugins,target=${containerWorkspaceFolder}/gulp-paid-plugins,type=bind,consistency=cached",
+    "source=${localWorkspaceFolder}/../muty-python,target=${containerWorkspaceFolder}/muty-python,type=bind,consistency=cached",
+    "source=${localWorkspaceFolder}/../gulp-sdk,target=${containerWorkspaceFolder}/gulp-sdk,type=bind,consistency=cached",
+    "source=${localWorkspaceFolder}/../gulp-cli,target=${containerWorkspaceFolder}/gulp-cli,type=bind,consistency=cached",
+    "source=${localWorkspaceFolder}/../gulpui-web,target=${containerWorkspaceFolder}/gulpui-web,type=bind,consistency=cached",
+    // map the config for development (references the gulp-paid-plugins above for the extra plugins and mapping files)
+    "source=${localEnv:HOME}/.config/gulp,target=/home/vscode/.config/gulp,type=bind,consistency=cached",
+    "source=${localWorkspaceFolder}/../gulp-paid-plugins/src/gulp-paid-plugins/plugins,target=/home/vscode/.config/gulp/plugins,type=bind,consistency=cached",
+    "source=${localWorkspaceFolder}/../gulp-paid-plugins/src/gulp-paid-plugins/mapping_files,target=/home/vscode/.config/gulp/mapping_files,type=bind,consistency=cached",
+    "source=${localEnv:HOME}/.config/fish,target=/home/vscode/.config/fish,type=bind,consistency=cached"
+  ],
+  "remoteEnv": {
+    "PATH": "${containerEnv:PATH}:/home/vscode/.local/bin"
+  },
+  "postCreateCommand": "chmod +x .devcontainer/devsetup.sh && .devcontainer/devsetup.sh",
+  "postStartCommand": "sudo mkdir -p /run/rsyslog && (pgrep -x rsyslogd >/dev/null || sudo rsyslogd)"
+}

mentat_gulp-1.6.51/.devcontainer/devsetup.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# set up permissions for docker socket
+echo "[.] Setting up docker permissions"
+sudo chmod 666 /var/run/docker.sock
+
+# set permission for pip cache
+sudo mkdir -p /home/vscode/.cache/pip && sudo chown -R vscode:vscode /home/vscode/.cache
+
+python3 -m venv ./.venv
+source ./.venv/bin/activate
+
+# install development packages
+echo "[.] Installing gulp"
+pip3 install --timeout=1000 -e .
+if [ $? -ne 0 ]; then
+	echo "[-] Failed to install gulp"
+	exit 1
+fi
+
+echo "[.] Installing muty-ptyhon"
+pip3 install --timeout=1000 -e ./muty-python
+if [ $? -ne 0 ]; then
+	echo "[-] Failed to install muty-python"
+	exit 1
+fi
+
+echo "[.] Installing gulp sdk (for tests, bridges, ...)"
+pip3 install --timeout=1000 -e ./gulp-sdk
+if [ $? -ne 0 ]; then
+	echo "[-] Failed to install gulp-sdk for python"
+	exit 1
+fi
+
+echo "[.] development environment setup complete"

mentat_gulp-1.6.51/.devcontainer/docker-compose.yml

@@ -0,0 +1,22 @@
+services:
+  dev:
+    build: .
+    volumes:
+      - ..:/gulp:cached
+      - /var/run/docker.sock:/var/run/docker.sock
+      # use a named volume for pip cache to persist it across container rebuilds
+      - pip-cache:/home/vscode/.cache/pip
+    command: sleep infinity
+    ports:
+      # gulp
+      - "8080:8080"
+    privileged: true
+    group_add:
+      - docker
+
+    network_mode: "host"
+    init: true
+
+volumes:
+  pip-cache:
+    driver: local

mentat_gulp-1.6.51/.env

@@ -0,0 +1,23 @@
+# python
+PYTHON_VERSION=3.13
+
+# postgres
+POSTGRES_DB=gulp
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=Gulp1234!
+POSTGRES_MAX_CONNECTIONS=500
+
+# opensearch
+OPENSEARCH_USER=admin
+OPENSEARCH_PASSWORD=Gulp1234!
+
+# redis
+REDIS_PASSWORD=Gulp1234!
+
+# sftpd
+SFTPD_USER=gulp
+SFTPD_PASSWORD=Gulp1234!
+
+# minio
+MINIO_USER=admin
+MINIO_PASSWORD=Gulp1234!

mentat_gulp-1.6.51/.gitattributes

@@ -0,0 +1,3 @@
+samples/mftecmd filter=lfs diff=lfs merge=lfs -text
+samples/win_evtx filter=lfs diff=lfs merge=lfs -text
+test_scripts/test_upload_with_metadata_json.zip filter=lfs diff=lfs merge=lfs -text

mentat_gulp-1.6.51/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+
+A clear and concise description of what the bug is, including **a significant output of the gulp console, i.e. last 50 lines**.
+
+> steps to enter gulp CLI for docker version:
+> ~~~bash
+> docker run --rm -it --entrypoint bash mentatis/gulp-core:latest
+> ~~~
+
+**To Reproduce**
+
+Steps to reproduce the behavior, i.e.
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. ...
+
+**Expected behavior**
+
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+
+If applicable, add screenshots to help explain your problem.
+
+**Version**
+
+- OS
+- Browser
+- Gulp Version (`python3 -m gulp --version` from the CLI)
+
+**Additional context**
+
+Add any other context about the problem here.

mentat_gulp-1.6.51/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

mentat_gulp-1.6.51/.github/copilot-instructions.md

@@ -0,0 +1,31 @@
+# gULP — Copilot instructions for coding agents
+
+gULP is a Python FastAPI service + workers that stores documents in OpenSearch and keeps collaboration metadata in PostgreSQL; Redis is used for the task queue & pub/sub. (see `docs/architecture.md`).
+
+- Main code lives in `src/gulp/` — important entry points: `src/gulp/__main__.py` (CLI), `src/gulp/api/server_api.py` (FastAPI server), `src/gulp/plugin.py` (plugin base).
+- Separate repositories are symlinked for the client SDK (`gulp-sdk/`), non-free plugins (`gulp-paid-plugins`), and utility library (`muty-python/`).
+
+## General instructions for coding agents 🤖
+- **ALWAYS** use memory to track progress and decisions made during implementation
+
+## Testing instructions
+- for tests, a gulp instance should be available on `localhost:8080`. 
+  - **if you cannot find the instance, you can start it with `gulp --reset-collab --create test_operation`, make sure to run the command inside the venv. any plugin extension startup errors can be ignored. be sure to stop the instance with `gulp --stop` when done.**
+- for authentication, initially only the `admin/admin` user (admin permissions) and `guest/guest` (read-only, i.e. no ingestion) are available
+- **after authentication, (most of) the gulp API requires that a websocket connection is started.**
+- for file ingestion tests, use the files in `/gulp/samples/win_evtx` with the `win_evtx` plugin
+- to test the ingest raw API, use a json with different `GulpDocument`s. test both the `/ingest_raw` API and the websocket version `/ws_ingest_raw`
+- to test the query_external API, use the `query_elasticsearch` plugin using the local gulp instance (setting the necessary parameters in the plugin, i.e. configure it for opensearch): for example, ingest some test documents with win_evtx first, then call `/query_external` with `query_elasticsearch` plugin to retrieve them
+- to test different `plugin_params` parameters during ingestion, use the `csv` plugin, see as an example the test inside `/gulp/tests_old/ingest/test_ingest.py in the `test_csv_standalone`, `test_csv_file_mapping` methods
+- **in every test, always make sure to verify that (for example) data has been ingested (i.e. via query), and make sure that any data created on collab is deleted (for example, if you create an operation, make sure to delete it at the end of the test)**
+- **make sure that any temporary files created during tests are deleted at the end of the test**
+- **always make sure at the beginning of each test to start from a clean state, for example by creating new operations or new documents with unique IDs, so as not to have interference with pre-existing data or with other tests**
+- **if you suspect bugs in the gulp backend, or if you notice strange behavior during tests, document them, stop and ask for clarifications**
+
+## Adding / changing functionality — checklist for PRs ✍️
+1. Update or add unit/integration tests under `tests/` (look at `tests/ingest/`, `tests/query/`, `tests/enrich/, `tests/extension/`).
+2. If plugin or mapping changes, add/update mapping in `mapping_files/` and tests that use `GulpMappingParameters`.
+3. If DB schema changes, add migration under `collab_migrate/`.
+4. Ensure tests starts with a clean state (use pytest fixtures as i.e. in `tests/ingest/test_ingest.py:::_setup` or `--reset-collab --create test_operation` to start gulp in a clean state with a test operation).
+5. Run tests and ensure they pass before submitting PR.
+

mentat_gulp-1.6.51/.github/workflows/docker-ci.yml

@@ -0,0 +1,61 @@
+name: docker-ci
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  # enables manual trigger
+  workflow_dispatch:
+
+env:
+  DOCKER_REPOSITORY: mentatis
+  DOCKER_IMAGE_NAME: gulp-core
+  PYTHON_VERSION: 3.13
+
+jobs:
+  docker:
+    name: Docker
+    runs-on: ubuntu-latest
+    # makes sure it doesn't finish the minutes quota if stalls
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          
+      - name: Get Docker tag (git version)
+        id: get-docker-tag        
+        run: |
+          GIT_DESCRIBE=$(git describe --tags --always)
+          echo "git_version=${GIT_DESCRIBE}" >> ${GITHUB_OUTPUT}
+              
+      - name: Output Docker tag
+        run: echo ${{ steps.get-docker-tag.outputs.git_version }}
+      
+      - name: Get app version
+        id: vars
+        run: |
+          echo "version=$(git describe --tags --always)" >> $GITHUB_OUTPUT
+      
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push [${{ env.DOCKER_IMAGE_NAME }}]  
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          no-cache: true
+          progress: plain
+          build-args: |
+            _VERSION=${{ steps.vars.outputs.version }}
+          tags: |
+            ${{ env.DOCKER_REPOSITORY }}/${{ env.DOCKER_IMAGE_NAME }}:latest
+            ${{ env.DOCKER_REPOSITORY }}/${{ env.DOCKER_IMAGE_NAME }}:${{ steps.vars.outputs.version }}
+      

mentat_gulp-1.6.51/.github/workflows/python-package.yml

@@ -0,0 +1,75 @@
+name: Python package
+
+on:
+  push:
+    tags: ['v*', 'test-v*']
+  workflow_dispatch: {}
+
+jobs:
+  test:
+    name: Test, lint and build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build setuptools_scm[toml] pytest
+
+      # TODO: write proper muty-python tests and enable this step
+      #- name: Run tests
+      #  run: |
+      #    pytest -q
+
+      - name: Build artifacts
+        run: |
+          python -m build
+
+      - name: Check package
+        run: |
+          python -m pip install twine
+          python -m twine check dist/*
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v') || startsWith(github.ref, 'refs/tags/test-v')
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install packaging dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build setuptools_scm[toml] twine
+
+      - name: Build
+        run: |
+          python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN_VALERINO }}
+          TWINE_PASSWORD_TEST: ${{ secrets.PYPI_API_TEST_TOKEN_VALERINO }}
+        run: |
+          if [[ "${GITHUB_REF##*/}" == test-v* ]]; then
+            export TWINE_PASSWORD="${TWINE_PASSWORD_TEST}"
+            python -m twine upload --verbose --repository-url https://test.pypi.org/legacy/ dist/*
+          else
+            export TWINE_PASSWORD="${TWINE_PASSWORD}"
+            python -m twine upload --verbose dist/*
+          fi

mentat_gulp-1.6.51/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.venv
+pyrightconfig.json
+venv
+dist
+
+# VSCode
+.vscode/
+
+# symlinks
+gulp-paid-plugins
+slurp
+gulpui-web
+# gulp-sdk-python
+
+#auto generated docs
+docs/html
+.VSCodeCounter
+
+# native
+src/gulp/libgulp
+*.so
+
+# misc
+.github/agents
+export.csv
+export.json
+gulp_cfg.json
+*.egg-info
+test.py
+build
+.DS_Store
+*log*.txt
+output.txt
+start_splunk.sh
+supported_formats.md
+build_paid.sh
+prompts.txt
+tests/query/sigma/windows
+build_test.sh
+.specstory
+.coverage
+gulp-cli
+muty-python
+gulp-sdk
+*plan*.md
+_version.py

mentat_gulp-1.6.51/CHANGELOG.md

@@ -0,0 +1,84 @@
+# v1.6.51
+
+## new features
+
+- architecture: observability via `Prometheus` metrics and `Grafana` dashboards (check the `docs/observability.md` for instructions)
+- core: added `synchronous` internal events callback, allows extension plugins to i.e. change chunks of documents during ingestion via `EVENT_CHUNK_PRE_INGEST` event
+- sdk: deprecated the old `gulp-sdk-python` and integrated new polished python SDK available at https://github.com/mentat-is/gulp-sdk, integration tests in `/tests` as usual (missing most of the old per-plugin tests, will be updated soon)
+- installation: removed submodules, welcome pypi installation! our Mentat's dependencies `gulp-sdk` and `muty-python` packages and also gulp itself (`mentat-gulp`) are now on pypi, check the [installation instructions](./docs/install_dev.md) for details.
+- cli: `gulp-cli` is now available to use most of the gulp features from the command line, get it at https://github.com/mentat-is/gulp-cli or via the `gulp-cli` package on pypi!
+
+- ci/cd: added github workflows to build pypi packages
+
+## bugfixes
+
+- core/logging: fixed syslog logging (integrated rsyslog both in the devcontainer and production Dockerfile deployment)
+- core/redis: reworked message routing and handling
+- all: multiple fixes
+ 
+# v1.6.5
+
+## new features
+
+- architecture: filestore via `minio` S3-compatible storage to be used by plugins to store binary files needed for the analysis (configuration must be updated, check the `gulp_cfg_template.json`)
+- architecture: removed `sftpd` from the default set of microservices (a management console may use the new API endpoints instead)
+- plugins/pcap: reworked to use the filestore
+- core/api: new API endpoints, `remove_enrich` to remove enriched data, endpoints to manage plugin/config/mapping files (`plugin_delete`, `plugin_upload`, `plugin_download`, `config_upload`, `config_download`, `mapping_file_delete_upload`), `mapping_file_download`, `mapping_file_delete`, endpoints to manage files from storage (`storage_delete_by_id`, `storage_get_file_by_id`, `storage_delete_by_tags`, `storage_list_files`)
+
+## bugfixes
+
+- **fixed a very long standing bug which leaked resources at every `ingest` operation and prevented clean shutdown of workers**.
+
+# v1.6.2
+
+## new features
+
+- realtime ingestion supported in the UI
+- new plugin: `otel_receiver` to ingest OpenTelemetry traces, logs and metrics from an OpenTelemetry Collector
+
+## improvements
+
+- core/query: major boost in parallel query handling and overall performance improvements (Redis)
+- core/collab: refactored advisory locks to be more robust and performant (PostgreSQL)
+- core/mapping: added `mapping.fields.timestamp_format` and `mapping.default_encoding` to the mapping engine, to respectively use a default timestamp format string and string encoding
+
+## unresolved issues
+
+`timestamp_format` in `plugin_params` is currently **NOT SUPPORTED** in the UI: in the `regex` plugin it is workarounded passing it via `plugin_params.custom_parameters`, other plugins using it (i.e. `apache_access_clf`) have hardcoded defaults (which is, of course, not ideal and will be fixed ASAP when the UI issue is resolved).
+
+# v1.6.1
+
+## fixes
+
+- solves issues with the devcontainer (https://github.com/yarnpkg/yarn/issues/9216)
+- some minor fixes
+
+# v1.6.0
+
+## major changes
+
+- core: introducing redis instead of a shared multiprocessing queue to exchange messages core<->workers - (major speedup and less memory usage!)
+- core: scaling horizontally using multiple instances of the core running simultaneously
+- plugins: allow caching and reusing values through `DocValueCache` in `plugin.py` (major speedup when used properly)
+- core: properly structured `GulpDocument`
+- api/ws: introducing WebSocket API for real-time ingestion `/ingest_ws_raw` (allow i.e. real-time ingestion from network sensors, try https://github.com/mentat-is/slurp-ebpf)
+
+## changes/improvements
+
+- all: our internal repos `muty-python` and `gulp-sdk-python` now included as submodules
+- core/collab: upgraded to OpenSearch latest (3.x)
+- core/collab: reworked most of the collab code to be more SQLAlchemy compliant
+- core/collab: stats (GulpRequestStats) processing completely reworked (now they are updated consistently across the whole modules)
+- core/mapping: allowing aliasies to be applied post-mapping (`value_aliases` in the mapping files/definitions)
+- core/mapping: support for windows filetime for `timestamp` fields
+- core/api: added `query_aggregation` to the API to allow aggregation queries
+core/ws: better backpressure handling for higher loads
+
+## plugins
+
+- plugins/extension: `ai-assistant` to help analsyts with investigations using LLMs (OpenRouter API support)
+- plugins/ingestion: `suricata`, `memprocfs`, `zeek` ingestion plugins/mappings added
+
+## all
+
+- all: generic fixes and improvements across the whole codebase

mentat_gulp-1.6.51/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing To Gulp
+
+We'd love the the community to be part of our project both as developers and as users!
+
+## For developers
+
+To submit PRs, just stick with these simple rules:
+
+1. follow [the install docs for developers](<./docs/install_dev.md>) to setup the dev environment.
+2. `be modular!`
+3. use (*and extend it*, you are welcome!) our utility library [muty-python](https://github.com/mentat-is/muty-python) instead of repeating common code, or to abstract complex functionality.
+4. use FFI if you need performances, i.e. as the [win_evtx](https://github.com/mentat-is/src/gulp/plugins/ingestion/win_evtx.py) plugin which uses a [pyevtx-rs rust's backend](https://github.com/omerbenamram/pyevtx-rs)
+
+and code writing guidilines:
+
+1. **Readability first** – write code as if the next maintainer has no context.  
+   - **No one-liner lambdas or list-comprehension trick-shots** unless the gain in performance is *dramatic*.  
+   - **Extensively comment code (function names, methods, variables, code flow, separate lines in logical blocks)**, except the obvious.
+   - **Type hint everything** (functions, methods, variables, class attributes).
+  
+   this is **accepted** code:
+
+   ```python
+   def connect_to_next_port(self, minimum: int) -> int:
+      """Connects to the next available port.
+
+      Args:
+         minimum: A port value greater or equal to 1024.
+
+      Returns:
+         The new minimum port.
+
+      Raises:
+         ConnectionError: If no available port is found.
+      """
+      if minimum < 1024:
+         # ports below 1024 are reserved.
+         raise ValueError("Min. port must be at least 1024, not {minimum}.")
+
+      port = self._find_next_open_port(minimum)
+      if port is None:
+         # no port provided
+         raise ConnectionError(
+            f'Could not connect to service on port {minimum} or higher.')
+      
+      if port < minimum:
+         # sanity check
+         raise RuntimeError(
+            f'Unexpected port {port} when minimum was {minimum}.')
+      return port   
+   ```
+
+   this code is  **NOT** accepted:
+
+   ```python
+   def connect_to_next_port(self, minimum):
+      if minimum < 1024:
+         raise ValueError()
+      port = self._find_next_open_port(minimum)
+      if port is None:
+         raise ConnectionError()
+      assert port >= minimum
+      return port
+   ```
+
+2. **Tests in `tests/`**  
+   - Put integration tests in `tests/` and generic test-helper scripts in `test_scripts/`  
+   - Use `pytest` conventions (`test_*.py`, fixtures, parametrization).  
+
+3. use [microsoft's black](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) formatter with the default settings.
+
+### notes for mantainers
+
+- > at release/tag time, use [the provided script](./update_requirements.txt) to freeze python requirements, **force push it to the target branch** and recreate the docker image.
+  
+## Bug reporting
+
+1. `gulp --version`
+   1. if [you are a developer](<./docs/install_dev.md>), output of the above command may not be correct if you updated the repository/ies manually: so, please provide the last commit hash of your local `gulp` and `muty-python` repositories.
+2. error dump from gulp's console, `issues with "this/that does not work" missing an error dump will be rejected`.
+3. steps for reproducing, `including OS flavor (linux, WSL, macos, ...), arch and version`.
+