celatim 0.1.0

Typed covert-channel research, measurement, and endpoint tooling for IETF protocol fields.

Celatim

Celatim is a typed Python 3.14+ toolkit for reproducible research on covert channels and steganographic carriers in IETF protocol fields. It provides channel codecs, protocol data-unit implementations, controlled endpoint transports, structural capacity models, detector and scrub guidance, scenario execution, and evidence artifacts from one distribution and one import namespace.

The project accompanies a survey and measurement paper. Its channel and defensive implementations are published together so researchers can reproduce the measurements, inspect assumptions, and evaluate both communication and normalization behavior.

Use Celatim only in controlled environments and on systems and networks you are authorized to test.

Requirements

• CPython 3.14 or newer.
• Linux for AF_PACKET, network-namespace, tcpdump, and QEMU/TAP workflows.
• No optional protocol stack is imported by the base package.

Installation

python -m pip install celatim
celatim --help

The wheel installs one primary command, celatim, plus four deterministic report generators from the same codebase:

• celatim-paper-figures
• celatim-paper-macros
• celatim-paper-tables
• celatim-support-matrix

Install profiles

Optional dependencies are grouped by capability:

Extra	Capability
celatim[packet]	Scapy packet construction, parsing, and pcap integration
celatim[crypto]	ECDSA and RSA-PSS transcript experiments
celatim[daemon]	hyper-h2 and aioquic production-stack paths
celatim[dns]	dnspython message paths
celatim[ssh]	Paramiko SSH message paths
celatim[iot]	aiocoap and paho-mqtt message paths
celatim[realtime]	WebSocket message paths

For example:

python -m pip install 'celatim[packet,crypto,daemon]'

Python API

The top-level API covers common endpoint operations and typed results:

from celatim import PayloadSource, roundtrip_payload

result = roundtrip_payload(
    "http2-ping-opaque",
    PayloadSource.hex("00 ff 80 41"),
)
assert result.ok
assert result.payload == b"\x00\xff\x80A"

Mechanism discovery exposes executable transport metadata without importing optional stacks:

from celatim import MechanismProfile

profile = MechanismProfile.from_catalog("http2-ping-opaque")
print([path.kind.value for path in profile.adapter.paths])

The public API also includes scenario discovery, evidence generation, pcap decode and scrub helpers, timing sweeps, installation checks, testbed requirements, and packaged document/schema inspection. Lower-level codecs, PDU implementations, detector rules, and transport classes remain available through focused celatim.* submodules.

Command line

Inspect mechanisms and packaged contracts:

celatim mechanism list
celatim mechanism show http2-ping-opaque
celatim scenario list
celatim docs list
celatim schema list
celatim testbed requirements

Run an in-memory binary-payload round trip:

celatim roundtrip \
  --mechanism http2-ping-opaque \
  --hex "00 ff 80 41"

Run a packaged non-privileged pcap scenario and write evidence:

celatim scenario run \
  --scenario-id http2-ping-opaque-real-pdu-smoke \
  --artifact-dir out/carriers \
  --pcap-dir out/pcaps \
  --log-dir out/logs \
  --output out/evidence.json

Generate defensive artifacts:

celatim detector rules \
  --output-dir out/detector-rules \
  --output out/detector-rules.json
celatim guidance generate --output out/detector-scrub-guidance.md
celatim guidance windows-capture --output out/windows-capture-guidance.md

Architecture

Celatim is one PEP 621 project with one celatim package:

• celatim.channel: bit packing, codecs, framing, and transport-agnostic drivers.
• celatim.pdu: parser-visible protocol data-unit implementations.
• celatim.transports: in-memory, file, pcap, timing, and production-path transports.
• celatim.testbed: netns/veth, AF_PACKET, daemon, tcpdump, and QEMU/TAP helpers.
• celatim.detect: detector predicates, executable replay, and offline scrub support.
• celatim.metrics: separate storage, timing, and subliminal capacity models.
• celatim.report: deterministic tables, figures, matrices, and defensive guidance.
• celatim.scenario: versioned scenario loading and controlled execution.

The wheel includes its default catalog, protocol-rate assumptions, JSON Schemas, scenario definitions, and operator documentation. CLI defaults resolve those resources with importlib.resources, so installed commands do not depend on a source checkout.

Optional integrations are imported only when their transport is selected. The installed package smoke verifies that a base import does not load Scapy, cryptography, aioquic, dnspython, Paramiko, aiocoap, paho-mqtt, or WebSockets.

Evidence boundaries

Celatim distinguishes structural capability from executed evidence:

• Storage carriers report field width and both header-relative and on-wire density.
• Timing/count carriers use a separate rate model.
• Subliminal cryptographic carriers use separate entropy bounds.
• Evidence records identify the transport, parser validation, controls, endpoint topology, artifact hashes, and claim status.
• Public indexes contain hashes and classifications rather than sensitive payloads, transcripts, host paths, or reviewer-only artifacts.

Privileged experiments live under experiments/. They require explicit operator action and do not run during normal installation, import, or non-privileged CI.

The chosen-nonce ECDSA transcript path is likewise research-only. It creates a fresh ephemeral key for each local transcript, uses cryptography/OpenSSL for curve operations and verification, and must not be used with production or long-lived signing keys.

The companion rfc-tunnel-survey repository vendors a manifest-verified snapshot of this project alongside the paper, RFC corpus, generated figures, and evidence indexes. This repository is the canonical package and PyPI release source.

Development

Install the locked development environment and run every package gate:

make ci

That target runs:

1. uv sync --locked --all-groups
2. uv lock --check
3. uv run ruff format --check .
4. uv run ruff check .
5. uv run ty check
6. uv run pytest
7. scripts/installed_wheel_smoke.py
8. pip-audit against every locked development and optional dependency

The type gate covers the package, tests, release scripts, and production experiment drivers. There are no directory-wide type-check exclusions; optional-stack boundaries use their concrete library modules so they remain statically resolvable. GitHub runs the same gate on pushes, pull requests, manual dispatches, and a weekly schedule so newly published dependency advisories are detected without waiting for a source change.

The installed-wheel smoke builds an sdist, builds the wheel from that sdist, installs it without dependencies into a fresh virtual environment, changes to a directory outside the checkout, and exercises all five console entry points plus representative public API and binary-payload workflows. After proving the base import does not load optional stacks, it installs every wheel-declared extra into the isolated environment, imports each integration dependency, and records the resolved versions.

Build and validate release distributions with:

uv build --out-dir dist
uvx twine check dist/*
uvx check-wheel-contents dist/*.whl

Release workflow

GitHub releases trigger .github/workflows/release.yml. The workflow requires a tag that exactly matches v<project.version>, reruns the full CI and installed-package gate, validates wheel metadata and contents, and passes verified artifacts to a separate PyPI publishing job.

Only that final job receives id-token: write, uses the protected pypi environment, and exchanges GitHub's OIDC identity for a short-lived PyPI credential. No PyPI token is stored in the repository. See RELEASING.md for the trusted-publisher identity and release procedure.

Celatim is licensed under the Apache License 2.0. Release validation requires the exact SPDX expression and packaged license file in the wheel.