Metadata-Version: 2.4
Name: celatim
Version: 0.1.0
Summary: Typed covert-channel research, measurement, and endpoint tooling for IETF protocol fields.
Keywords: covert-channels,network-measurement,network-protocols,privacy,steganography
Author: Michael Bommarito
Author-email: Michael Bommarito <michael.bommarito@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: cryptography>=46.0.3 ; extra == 'crypto'
Requires-Dist: aioquic>=1.3.0 ; extra == 'daemon'
Requires-Dist: h2>=4.3.0 ; extra == 'daemon'
Requires-Dist: dnspython>=2.8.0 ; extra == 'dns'
Requires-Dist: aiocoap>=0.4.12 ; extra == 'iot'
Requires-Dist: paho-mqtt>=2.1.0 ; extra == 'iot'
Requires-Dist: scapy>=2.6.1 ; extra == 'packet'
Requires-Dist: websockets>=13.0 ; extra == 'realtime'
Requires-Dist: paramiko>=3.5.0 ; extra == 'ssh'
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/mjbommar/celatim
Project-URL: Issues, https://github.com/mjbommar/celatim/issues
Project-URL: Repository, https://github.com/mjbommar/celatim.git
Provides-Extra: crypto
Provides-Extra: daemon
Provides-Extra: dns
Provides-Extra: iot
Provides-Extra: packet
Provides-Extra: realtime
Provides-Extra: ssh
Description-Content-Type: text/markdown

# 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

```bash
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:

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

## Python API

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

```python
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:

```python
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:

```bash
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:

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

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

```bash
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:

```bash
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`](https://github.com/mjbommar/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:

```bash
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:

```bash
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`](RELEASING.md) for the trusted-publisher
identity and release procedure.

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