Menu
How to use, troubleshoot, and optimize the whisper-opencti CI/CD pipeline — local checks, GitHub Actions workflows, Docker builds, and releases
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Core conventions for building and modifying OpenCTI internal-enrichment connectors in this repo — the enrichment pipeline, connectors-sdk configuration, scope/TLP/playbook gates, the bundle-send contract, and the project's hard constraints. Use when implementing, reviewing, or debugging connector logic.
Process for contributing an OpenCTI connector upstream to OpenCTI-Platform/connectors — template structure, the connectors-sdk + pycti requirements, config-schema generation, conventional + signed commits, and the fork PR workflow. Use when preparing or updating an upstream PR.
Runbook for validating an OpenCTI connector locally — lint (isort/black/flake8 + STIX-ID pylint), pytest, Docker build, dev-stack end-to-end enrichment, and the qa-handoff TC matrix. Use before opening or updating a PR, or whenever connector behavior changes.
Rules for generating deterministic STIX 2.1 IDs in OpenCTI connectors — SCOs use the stix2 library's built-in IDs, SDOs/relationships/notes use pycti.*.generate_id. Never use a custom UUID namespace. Use whenever creating or reviewing STIX object construction.
| name | ci-cd-pipeline |
| description | How to use, troubleshoot, and optimize the whisper-opencti CI/CD pipeline — local checks, GitHub Actions workflows, Docker builds, and releases |
This skill covers the whisper-opencti CI/CD setup: local development checks, GitHub Actions workflows, Docker builds, and release process.
Always run these locally before pushing to avoid CI failures:
make lint # Check formatting + all linters (isort, black, flake8, pylint)
make test # Run 197 unit tests
make format # Auto-fix formatting issues (isort + black)
If all pass locally, your PR will almost certainly pass GitHub Actions CI.
Trigger: Push to main/develop or open a PR to main/develop
Runs 5 jobs in parallel (all must pass):
isort --profile black --check-only . + black --check .make format then pushflake8 --ignore=E,W . locally to see issueslinter_stix_id_generator pluginno_generated_id_stix — All SDOs must use pycti.*.generate_id()no-value-for-parameter — Functions have required argumentsunused-import — No dead importsmake test locally to diagnose failurespycti==7.260626.0 doesn't match connectors-sdk requirement (should be 7.260701.0)git in build deps (needed for connectors-sdk git+https install)src/requirements.txt matches connectors-sdk@master pinTrigger: Create a git tag matching v* (e.g., v1.0.0)
What it does:
ghcr.io/whisper-sec/whisper-opencti:v1.0.0 (always)ghcr.io/whisper-sec/whisper-opencti:latest (only if non-prerelease)Release a new version:
# 1. Ensure develop is merged to main
git checkout main
git pull
# 2. Create an annotated tag
git tag -a v1.0.1 -m "Release v1.0.1"
# 3. Push the tag (triggers Release workflow)
git push origin v1.0.1
# 4. Monitor in GitHub Actions → Release workflow
# → Image appears at ghcr.io/whisper-sec/whisper-opencti:v1.0.1
make dev-up # Start: OpenCTI + deps + connector (built from ./src/)
make dev-restart # Rebuild + restart just connector container
make dev-logs # Tail logs
make dev-down # Stop (keep volumes)
make dev-clean # Stop + wipe volumes
Use for: Iterative development, testing code changes, debugging
make qa-up # Start: OpenCTI + published connector image from ghcr.io
make qa-restart # Pull latest + restart connector
make qa-logs # Tail logs
make qa-down # Stop (keep volumes)
make qa-clean # Stop + wipe volumes
Use for: Testing a released version, validating prod-like setup
How to check:
# Check what connectors-sdk requires
curl https://raw.githubusercontent.com/OpenCTI-Platform/connectors/master/connectors-sdk/pyproject.toml | grep '"pycti'
# Verify local version
grep pycti src/requirements.txt
# They should match!
If updating pycti, update these files together:
src/requirements.txt (pycti pin).env.example (OPENCTI_VERSION)__metadata__/connector_manifest.json (support_version)CLAUDE.md (version reference)| Failure | Root Cause | Fix |
|---|---|---|
format job fails | Code not formatted correctly | make format |
flake8 job fails | Fatal linting errors | flake8 --ignore=E,W . to see issues |
stix_id_linter fails | Missing pycti.*.generate_id() calls | Check converter_to_stix.py for SDO/rel/note ID generation |
test job fails | Unit test failure | make test locally to reproduce |
build job fails | Docker build error | Check pycti version, requirements.txt deps, Dockerfile syntax |
Match GitHub Actions exactly:
# Install tools (if not already in venv)
pip install isort==7.0.0 black==26.3.1 flake8>=7,<8 pylint==3.3.1 astroid==3.3.5
# Run the same checks GitHub Actions runs
isort --profile black --line-length 88 --check-only --diff .
black --check --diff .
flake8 --ignore=E,W .
# STIX-ID plugin (requires pycti + runtime deps)
cd shared/pylint_plugins/check_stix_plugin && \
PYTHONPATH=. pylint ../../../src ../../../tests \
--disable=all \
--enable=no_generated_id_stix,no-value-for-parameter,unused-import \
--load-plugins linter_stix_id_generator
| File | Controls |
|---|---|
pyproject.toml | black (line-length: 88), isort (profile: black), pytest paths |
.flake8 | flake8 configuration |
.github/workflows/ci.yml | CI pipeline jobs |
.github/workflows/release.yml | Release + Docker publish |
Dockerfile | Container definition (python:3.12-alpine base) |
src/requirements.txt | Python dependencies |
make lint + make test before pushing — Catches 95% of CI failuresdev-up for development, qa-up for validation — Different stacks for different purposes# Before pushing
make lint && make test
# Local development
make dev-up && make dev-logs
# Fix formatting
make format
# Full pipeline locally (CI equivalent)
make format && make test && make lint
# Release
git tag v1.0.0 && git push origin v1.0.0