iocflow 0.1.0__tar.gz

iocflow-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+# Cancel an in-progress run when a newer commit is pushed to the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest -q

iocflow-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+# Publishes to PyPI when a version tag (e.g. v0.1.0) is pushed.
+# Uses PyPI Trusted Publishing (OIDC) — no API token is stored anywhere.
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Floor and ceiling of the supported range, so a tag can't publish
+        # something that breaks on the requires-python lower bound.
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest -q
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - run: python -m pip install --upgrade twine && python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/iocflow/
+    permissions:
+      id-token: write   # required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

iocflow-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.env

iocflow-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 (2026-05-30)
+
+- Initial release — Layer 1: threat-entity extraction.
+- `extract(text)` pulls IPs, domains, URLs, filenames, hashes (MD5/SHA1/SHA256),
+  CVEs, emails, MITRE technique IDs, threat actors, and malware families from
+  unstructured text.
+- `refang_text` re-fangs defanged IOCs (`[.]`, `[at]`, `hxxp`, …) before extraction.
+- Domain validation via `tldextract` (Mozilla Public Suffix List); broad
+  benign-domain / benign-IP allowlists; three-layer malware false-positive defense.
+- Pluggable enrichment sources: `MalwareNames` and `ActorAliases` — supply your
+  own name sets; the core has no external-data dependency and works fully without them.
+- Optional `iocflow[mitre]` extra: `mitre.mitre_malware_names()` fetches the public
+  MITRE ATT&CK STIX bundle and returns a ready-made `MalwareNames` (7-day disk cache).
+- `ExtractedEntities.iter_indicators()` yields flat `(kind, value)` indicators —
+  the input surface for future enrichment layers.
+- `iocflow` CLI / `python -m iocflow` with `--json`, `--no-refang`, `--mitre`.

iocflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinay Vobbilichetty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iocflow-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: iocflow
+Version: 0.1.0
+Summary: Extract threat indicators (IOCs) from unstructured text — IPs, domains, URLs, hashes, CVEs, MITRE techniques, threat actors, and malware families. Layer 1 of an IOC-lifecycle toolkit.
+Project-URL: Homepage, https://github.com/vinayvobbili/iocflow
+Project-URL: Repository, https://github.com/vinayvobbili/iocflow
+Project-URL: Issues, https://github.com/vinayvobbili/iocflow/issues
+Author-email: Vinay Vobbilichetty <vinayvobbilichetty11@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Vinay Vobbilichetty
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cve,cybersecurity,dfir,extraction,indicators-of-compromise,ioc,malware,mitre-attack,threat-actor,threat-intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: tldextract>=3.4
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: requests>=2.25; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: mitre
+Requires-Dist: requests>=2.25; extra == 'mitre'
+Description-Content-Type: text/markdown
+
+# iocflow
+
+[![CI](https://github.com/vinayvobbili/iocflow/actions/workflows/ci.yml/badge.svg)](https://github.com/vinayvobbili/iocflow/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/iocflow)](https://pypi.org/project/iocflow/)
+[![Python](https://img.shields.io/pypi/pyversions/iocflow)](https://pypi.org/project/iocflow/)
+[![License](https://img.shields.io/pypi/l/iocflow)](https://github.com/vinayvobbili/iocflow/blob/main/LICENSE)
+
+Pull **indicators of compromise** out of unstructured text — threat-intel
+reports, advisories, emails, tickets — in one call. iocflow extracts IPs,
+domains, URLs, filenames, file hashes, CVEs, MITRE ATT&CK technique IDs, threat
+actors, and malware families, with the false-positive defenses you'd otherwise
+write by hand: a Public Suffix List domain validator, benign-domain/IP
+allowlists, hash de-duplication across MD5/SHA1/SHA256, and re-fanging of
+defanged IOCs.
+
+```python
+from iocflow import extract
+
+text = """
+APT28 (a.k.a. Fancy Bear) staged Cobalt Strike from evil-domain[.]ru and
+185.220.101.5, dropping install.ps1 (MD5 a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4).
+Exploited CVE-2021-44228 via T1190. Contact: ops@evil-domain[.]ru.
+"""
+
+entities = extract(text)
+print(entities.summary())
+# 1 IPs, 1 domains, 1 filenames, 1 hashes, 1 CVEs, 1 emails, 1 threat actors, 1 MITRE techniques
+
+for ind in entities.iter_indicators():
+    print(ind.kind, ind.value)
+# ip 185.220.101.5
+# domain evil-domain.ru
+# ...
+```
+
+The defanged `evil-domain[.]ru` and `ops@evil-domain[.]ru` are re-fanged
+automatically; `185.220.101.5` is kept while private/benign IPs are dropped.
+
+## Install
+
+```bash
+pip install iocflow              # core — one dependency (tldextract)
+pip install "iocflow[mitre]"     # + a ready-made MITRE ATT&CK malware-name source
+```
+
+## What it extracts
+
+`extract(text)` returns an `ExtractedEntities` with:
+
+- `ips` — public IPv4, excluding private ranges, benign IPs, and version-number-like values
+- `domains` — validated against the Mozilla Public Suffix List via `tldextract`
+- `urls` — both `https://…` and bare `host/path` forms (so package-registry paths survive)
+- `filenames` — suspicious script/executable/macro/archive filenames
+- `hashes` — `{"md5": [...], "sha1": [...], "sha256": [...]}`, de-duplicated across lengths
+- `cves` — `CVE-YYYY-NNNN+`, normalized to uppercase
+- `emails`
+- `mitre_techniques` — `T1059`, `T1059.001`, …
+- `threat_actors` (+ `threat_actors_enriched`) — APT/UNC/FIN/TA/DEV/STORM designators,
+  a curated well-known list, and the `"<Name> ransomware"` pattern
+- `malware_families` — populated when you supply a malware-name source (see below)
+
+Each individual extractor is also importable and composable:
+
+```python
+from iocflow import extract_ips, extract_hashes, refang_text
+extract_ips(refang_text("c2 at 185[.]220[.]101[.]5"))   # ['185.220.101.5']
+```
+
+## Pluggable name sources
+
+The core has **no external-data dependency**. Two enrichment sources are
+optional and supplied by you, so iocflow drops cleanly into any environment —
+plug in your own feeds, or use the bundled MITRE extra.
+
+**Malware families.** Give `extract` a `MalwareNames` and it matches families
+(with alias-to-canonical normalization) behind a three-layer false-positive
+defense. Build one from your own list, from MITRE-shaped records, or from the
+optional extra:
+
+```python
+from iocflow import extract, MalwareNames
+
+# Your own list:
+names = MalwareNames.from_names(["Cobalt Strike", "Emotet", "Qakbot"])
+entities = extract(report_text, malware_names=names)
+
+# Or the bundled MITRE ATT&CK source (needs: pip install "iocflow[mitre]"):
+from iocflow.mitre import mitre_malware_names
+entities = extract(report_text, malware_names=mitre_malware_names())
+```
+
+**Threat-actor aliases.** Give `extract` an `ActorAliases` to match a custom
+name set and enrich actors with `common_name` / `region` / `all_names`. Without
+it, actors are still found by pattern and curated list:
+
+```python
+from iocflow import extract, ActorAliases
+
+aliases = ActorAliases.from_index({
+    "apt28": {"common_name": "APT28", "region": "Russia",
+              "all_names": ["Fancy Bear", "Sofacy", "Sednit"]},
+})
+entities = extract(report_text, actor_aliases=aliases)
+entities.threat_actors_enriched[0].region        # "Russia"
+entities.threat_actors_enriched[0].aliases_display()  # "Fancy Bear, Sofacy, Sednit"
+```
+
+## Command line
+
+```bash
+iocflow "APT28 used 185.220.101.5 and evil[.]example[.]com"
+echo "report text…" | iocflow --json
+iocflow --mitre "Emotet dropped Cobalt Strike"     # needs iocflow[mitre]
+```
+
+## Where this is going
+
+iocflow is **Layer 1** of an IOC-lifecycle toolkit. The plan is to grow it in
+independently-useful layers, each behind its own pip extra: enrichment
+(VirusTotal, Recorded Future, AbuseIPDB, Shodan, abuse.ch), AI commentary,
+suggested hunts, and optional perimeter blocking — each configured by plugging
+in your own API keys. `ExtractedEntities` (and its `iter_indicators()` view) is
+the stable hand-off type those layers consume.
+
+## License
+
+MIT

iocflow-0.1.0/README.md

@@ -0,0 +1,127 @@
+# iocflow
+
+[![CI](https://github.com/vinayvobbili/iocflow/actions/workflows/ci.yml/badge.svg)](https://github.com/vinayvobbili/iocflow/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/iocflow)](https://pypi.org/project/iocflow/)
+[![Python](https://img.shields.io/pypi/pyversions/iocflow)](https://pypi.org/project/iocflow/)
+[![License](https://img.shields.io/pypi/l/iocflow)](https://github.com/vinayvobbili/iocflow/blob/main/LICENSE)
+
+Pull **indicators of compromise** out of unstructured text — threat-intel
+reports, advisories, emails, tickets — in one call. iocflow extracts IPs,
+domains, URLs, filenames, file hashes, CVEs, MITRE ATT&CK technique IDs, threat
+actors, and malware families, with the false-positive defenses you'd otherwise
+write by hand: a Public Suffix List domain validator, benign-domain/IP
+allowlists, hash de-duplication across MD5/SHA1/SHA256, and re-fanging of
+defanged IOCs.
+
+```python
+from iocflow import extract
+
+text = """
+APT28 (a.k.a. Fancy Bear) staged Cobalt Strike from evil-domain[.]ru and
+185.220.101.5, dropping install.ps1 (MD5 a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4).
+Exploited CVE-2021-44228 via T1190. Contact: ops@evil-domain[.]ru.
+"""
+
+entities = extract(text)
+print(entities.summary())
+# 1 IPs, 1 domains, 1 filenames, 1 hashes, 1 CVEs, 1 emails, 1 threat actors, 1 MITRE techniques
+
+for ind in entities.iter_indicators():
+    print(ind.kind, ind.value)
+# ip 185.220.101.5
+# domain evil-domain.ru
+# ...
+```
+
+The defanged `evil-domain[.]ru` and `ops@evil-domain[.]ru` are re-fanged
+automatically; `185.220.101.5` is kept while private/benign IPs are dropped.
+
+## Install
+
+```bash
+pip install iocflow              # core — one dependency (tldextract)
+pip install "iocflow[mitre]"     # + a ready-made MITRE ATT&CK malware-name source
+```
+
+## What it extracts
+
+`extract(text)` returns an `ExtractedEntities` with:
+
+- `ips` — public IPv4, excluding private ranges, benign IPs, and version-number-like values
+- `domains` — validated against the Mozilla Public Suffix List via `tldextract`
+- `urls` — both `https://…` and bare `host/path` forms (so package-registry paths survive)
+- `filenames` — suspicious script/executable/macro/archive filenames
+- `hashes` — `{"md5": [...], "sha1": [...], "sha256": [...]}`, de-duplicated across lengths
+- `cves` — `CVE-YYYY-NNNN+`, normalized to uppercase
+- `emails`
+- `mitre_techniques` — `T1059`, `T1059.001`, …
+- `threat_actors` (+ `threat_actors_enriched`) — APT/UNC/FIN/TA/DEV/STORM designators,
+  a curated well-known list, and the `"<Name> ransomware"` pattern
+- `malware_families` — populated when you supply a malware-name source (see below)
+
+Each individual extractor is also importable and composable:
+
+```python
+from iocflow import extract_ips, extract_hashes, refang_text
+extract_ips(refang_text("c2 at 185[.]220[.]101[.]5"))   # ['185.220.101.5']
+```
+
+## Pluggable name sources
+
+The core has **no external-data dependency**. Two enrichment sources are
+optional and supplied by you, so iocflow drops cleanly into any environment —
+plug in your own feeds, or use the bundled MITRE extra.
+
+**Malware families.** Give `extract` a `MalwareNames` and it matches families
+(with alias-to-canonical normalization) behind a three-layer false-positive
+defense. Build one from your own list, from MITRE-shaped records, or from the
+optional extra:
+
+```python
+from iocflow import extract, MalwareNames
+
+# Your own list:
+names = MalwareNames.from_names(["Cobalt Strike", "Emotet", "Qakbot"])
+entities = extract(report_text, malware_names=names)
+
+# Or the bundled MITRE ATT&CK source (needs: pip install "iocflow[mitre]"):
+from iocflow.mitre import mitre_malware_names
+entities = extract(report_text, malware_names=mitre_malware_names())
+```
+
+**Threat-actor aliases.** Give `extract` an `ActorAliases` to match a custom
+name set and enrich actors with `common_name` / `region` / `all_names`. Without
+it, actors are still found by pattern and curated list:
+
+```python
+from iocflow import extract, ActorAliases
+
+aliases = ActorAliases.from_index({
+    "apt28": {"common_name": "APT28", "region": "Russia",
+              "all_names": ["Fancy Bear", "Sofacy", "Sednit"]},
+})
+entities = extract(report_text, actor_aliases=aliases)
+entities.threat_actors_enriched[0].region        # "Russia"
+entities.threat_actors_enriched[0].aliases_display()  # "Fancy Bear, Sofacy, Sednit"
+```
+
+## Command line
+
+```bash
+iocflow "APT28 used 185.220.101.5 and evil[.]example[.]com"
+echo "report text…" | iocflow --json
+iocflow --mitre "Emotet dropped Cobalt Strike"     # needs iocflow[mitre]
+```
+
+## Where this is going
+
+iocflow is **Layer 1** of an IOC-lifecycle toolkit. The plan is to grow it in
+independently-useful layers, each behind its own pip extra: enrichment
+(VirusTotal, Recorded Future, AbuseIPDB, Shodan, abuse.ch), AI commentary,
+suggested hunts, and optional perimeter blocking — each configured by plugging
+in your own API keys. `ExtractedEntities` (and its `iter_indicators()` view) is
+the stable hand-off type those layers consume.
+
+## License
+
+MIT

iocflow-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "iocflow"
+version = "0.1.0"
+description = "Extract threat indicators (IOCs) from unstructured text — IPs, domains, URLs, hashes, CVEs, MITRE techniques, threat actors, and malware families. Layer 1 of an IOC-lifecycle toolkit."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Vinay Vobbilichetty", email = "vinayvobbilichetty11@gmail.com" }]
+keywords = [
+    "ioc", "indicators-of-compromise", "threat-intelligence", "cybersecurity",
+    "extraction", "mitre-attack", "cve", "threat-actor", "malware", "dfir",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "tldextract>=3.4",
+]
+
+[project.optional-dependencies]
+# Bundled MITRE ATT&CK malware-name provider (fetches the public STIX bundle).
+mitre = ["requests>=2.25"]
+dev = [
+    "requests>=2.25",
+    "pytest>=7",
+    "ruff>=0.4",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+iocflow = "iocflow.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/vinayvobbili/iocflow"
+Repository = "https://github.com/vinayvobbili/iocflow"
+Issues = "https://github.com/vinayvobbili/iocflow/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/iocflow"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

iocflow-0.1.0/scripts/bump.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Bump the version, update the changelog, commit, and tag a release.
+
+Usage:
+    python scripts/bump.py patch          # 0.1.0 -> 0.1.1
+    python scripts/bump.py minor          # 0.1.0 -> 0.2.0
+    python scripts/bump.py major          # 0.1.0 -> 1.0.0
+    python scripts/bump.py 0.5.0          # set an explicit version
+    python scripts/bump.py patch --push   # also push main + the tag (triggers the PyPI publish)
+
+What it does, atomically:
+  1. Bumps `version` in pyproject.toml AND `__version__` in the package __init__
+     (the two must never drift apart).
+  2. Promotes the CHANGELOG "## Unreleased" section to "## X.Y.Z (today)" and
+     opens a fresh empty "## Unreleased" above it.
+  3. Commits "release: vX.Y.Z" and creates an annotated tag vX.Y.Z.
+
+Pushing the tag is what triggers .github/workflows/release.yml, which tests,
+builds, and publishes to PyPI via trusted publishing (no token).
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import pathlib
+import re
+import subprocess
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+PYPROJECT = ROOT / "pyproject.toml"
+INIT = ROOT / "src" / "iocflow" / "__init__.py"
+CHANGELOG = ROOT / "CHANGELOG.md"
+
+SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+
+
+def run(*args: str) -> str:
+    return subprocess.run(
+        args, cwd=ROOT, check=True, text=True, capture_output=True
+    ).stdout
+
+
+def die(msg: str) -> "None":
+    sys.exit(f"bump: {msg}")
+
+
+def current_version() -> str:
+    m = re.search(r'^version\s*=\s*"([^"]+)"', PYPROJECT.read_text(), re.M)
+    if not m:
+        die("could not find `version = \"...\"` in pyproject.toml")
+    return m.group(1)
+
+
+def next_version(cur: str, part: str) -> str:
+    m = SEMVER.match(cur)
+    if not m:
+        die(f"current version {cur!r} is not X.Y.Z")
+    major, minor, patch = (int(x) for x in m.groups())
+    return {
+        "major": f"{major + 1}.0.0",
+        "minor": f"{major}.{minor + 1}.0",
+        "patch": f"{major}.{minor}.{patch + 1}",
+    }[part]
+
+
+def ensure_releasable() -> None:
+    dirty = run("git", "status", "--porcelain").strip()
+    if dirty:
+        die("working tree is not clean; commit or stash first:\n" + dirty)
+    branch = run("git", "rev-parse", "--abbrev-ref", "HEAD").strip()
+    if branch != "main":
+        die(f"on branch {branch!r}; release from main")
+
+
+def replace_once(path: pathlib.Path, pattern: str, replacement: str) -> None:
+    text = path.read_text()
+    new, n = re.subn(pattern, replacement, text, count=1, flags=re.M)
+    if n != 1:
+        die(f"expected exactly one match for {pattern!r} in {path.name} (found {n})")
+    path.write_text(new)
+
+
+def roll_changelog(new: str) -> None:
+    text = CHANGELOG.read_text()
+    today = datetime.date.today().isoformat()
+    if re.search(r"^##\s+Unreleased\s*$", text, re.M | re.I):
+        # Promote Unreleased -> the new version, and open a fresh Unreleased above.
+        text = re.sub(
+            r"^##\s+Unreleased\s*$",
+            f"## Unreleased\n\n## {new} ({today})",
+            text,
+            count=1,
+            flags=re.M | re.I,
+        )
+    else:
+        # No Unreleased section: insert a stub right under the top heading.
+        lines = text.splitlines(keepends=True)
+        for i, line in enumerate(lines):
+            if line.lstrip().lower().startswith("# changelog"):
+                j = i + 1
+                while j < len(lines) and not lines[j].strip():
+                    j += 1
+                lines.insert(j, f"## {new} ({today})\n\n- TODO: describe changes.\n\n")
+                break
+        else:
+            lines = [f"# Changelog\n\n## {new} ({today})\n\n- TODO: describe changes.\n\n", *lines]
+        text = "".join(lines)
+    CHANGELOG.write_text(text)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Bump version, update changelog, commit, tag.")
+    ap.add_argument("version", help="patch | minor | major | explicit X.Y.Z")
+    ap.add_argument("--push", action="store_true",
+                    help="also push main and the tag (triggers the PyPI publish workflow)")
+    args = ap.parse_args()
+
+    ensure_releasable()
+    cur = current_version()
+    if args.version in ("patch", "minor", "major"):
+        new = next_version(cur, args.version)
+    elif SEMVER.match(args.version):
+        new = args.version
+    else:
+        die("version must be patch|minor|major or X.Y.Z")
+    if new == cur:
+        die(f"new version equals current ({cur})")
+
+    print(f"{cur} -> {new}")
+    replace_once(PYPROJECT, r'^version\s*=\s*"[^"]+"', f'version = "{new}"')
+    replace_once(INIT, r'^__version__\s*=\s*"[^"]+"', f'__version__ = "{new}"')
+    roll_changelog(new)
+
+    run("git", "add", "pyproject.toml", "src/iocflow/__init__.py", "CHANGELOG.md")
+    run("git", "commit", "-m", f"release: v{new}")
+    run("git", "tag", "-a", f"v{new}", "-m", f"iocflow {new}")
+    print(f"committed + tagged v{new}")
+
+    if args.push:
+        run("git", "push", "origin", "main")
+        run("git", "push", "origin", f"v{new}")
+        print(f"pushed main + v{new} — the Release workflow will publish to PyPI")
+    else:
+        print(f"next:  git push origin main && git push origin v{new}")
+
+
+if __name__ == "__main__":
+    main()