tethered 0.1.0__tar.gz

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

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f  # v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run pre-commit checks
+        run: uv run pre-commit run --all-files
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f  # v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests with coverage
+        run: uv run pytest tests/ -v --cov=src/tethered --cov-report=xml --cov-report=term-missing
+
+      - name: Extract coverage percentage
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        id: coverage
+        run: |
+          RATE=$(python3 -c "import xml.etree.ElementTree as ET; print(ET.parse('coverage.xml').getroot().get('line-rate'))")
+          PCT=$(python3 -c "print(round(float('$RATE') * 100))")
+          echo "pct=$PCT" >> "$GITHUB_OUTPUT"
+
+      - name: Update coverage badge
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13' && github.ref == 'refs/heads/main'
+        uses: schneegans/dynamic-badges-action@e9a478b16159b4d31420099ba146cdc50f134483  # v1.7.0
+        with:
+          auth: ${{ secrets.GIST_TOKEN }}
+          gistID: ${{ vars.COVERAGE_GIST_ID }}
+          filename: tethered-coverage.json
+          label: coverage
+          message: ${{ steps.coverage.outputs.pct }}%
+          valColorRange: ${{ steps.coverage.outputs.pct }}
+          minColorRange: 50
+          maxColorRange: 100

tethered-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,30 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@c4a7bc332abaec03596ff2803dd7f3ca3a238975  # v3
+        with:
+          languages: python
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@c4a7bc332abaec03596ff2803dd7f3ca3a238975  # v3

tethered-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f  # v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # v1.13.0

tethered-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Virtual environments
+.venv/
+venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Linting
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*
+*.pem
+*.key
+credentials.json
+token.json
+
+# Claude Code
+.claude/

tethered-0.1.0/.markdownlint-cli2.yaml

@@ -0,0 +1,4 @@
+config:
+  line-length: false
+  first-line-heading: false
+  table-column-style: false

tethered-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 0839f92796ae388643a08a21640a029b322be5c2  # v0.15.2
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: 5387279b3b4c24822c0f86d4df4f28b37e3e8992  # v0.21.0
+    hooks:
+      - id: markdownlint-cli2
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: ea0d187d78b2e6365e35f676d2eb9b1be264c091  # 1.9.2
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml"]
+        additional_dependencies: ["bandit[toml]"]
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: 7179a42b3544e953e3683a670056ad385892365d  # v4.13.8
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: uv run pytest tests/ -x -q
+        language: system
+        types: [python]
+        pass_filenames: false

tethered-0.1.0/AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md — Tethered
+
+## What is Tethered
+
+Tethered is a zero-dependency Python library for runtime network egress control. It uses `sys.addaudithook` (PEP 578) to intercept outbound socket connections and enforce an allow list of permitted destinations. One function call, no sidecar containers, no infrastructure changes.
+
+```python
+import tethered
+
+tethered.activate(allow=["*.stripe.com:443", "db.internal:5432"])
+```
+
+## Architecture
+
+```text
+src/tethered/
+    __init__.py    # Public API surface: activate(), deactivate(), EgressBlocked, TetheredLocked
+    _policy.py     # AllowPolicy — pattern parsing and matching (pure logic, no side effects)
+    _core.py       # Audit hook, _Config bundle, state management, IP-to-hostname resolution
+tests/
+    conftest.py     # Test-suite egress guard — uses AllowPolicy
+    test_policy.py  # Unit tests for AllowPolicy (no hooks, no network)
+    test_core.py    # Integration tests with real sockets (sync and async)
+```
+
+### Module responsibilities
+
+- **`_policy.py`** is pure logic. `AllowPolicy` is immutable after construction and thread-safe to read. It handles hostname wildcards (`*.stripe.com`), CIDR ranges (`10.0.0.0/8`), port filtering (`host:443`), and localhost detection. It has zero side effects and no imports beyond stdlib (`fnmatch`, `ipaddress`, `logging`, `dataclasses`).
+
+- **`_core.py`** owns the audit hook lifecycle. It installs a single `sys.addaudithook` that intercepts `socket.getaddrinfo` and `socket.gethostbyname`/`gethostbyaddr` (to enforce DNS-level policy and map IPs back to hostnames) and `socket.connect`/`sendto`/`sendmsg` (to enforce the connection policy). All per-activation state (`policy`, `log_only`, `fail_closed`, `on_blocked`, `locked`, `lock_token`) is bundled into a frozen `_Config` dataclass that is swapped atomically — this eliminates TOCTOU bugs between separate state reads and is safe on free-threaded Python (PEP 703). The IP-to-hostname map is an `OrderedDict` with LRU eviction. The hook is installed once and can never be removed — `deactivate()` sets `_config` to `None`, making the hook a no-op.
+
+- **`__init__.py`** re-exports the public API. Nothing else lives here.
+
+### Key design decisions
+
+1. **Fail-open by default, fail-closed optional.** If the matching logic itself raises an unexpected exception, the connection is allowed and a warning is logged (fail-open). Users can set `fail_closed=True` for stricter environments where errors should block rather than allow.
+
+2. **Audit hooks are irremovable.** `sys.addaudithook` has no corresponding remove function. This is a feature for security (malicious code can't unhook it) but means tests must use `deactivate()` + `_reset_state()` for cleanup rather than removing the hook.
+
+3. **IP-to-hostname mapping via getaddrinfo interception.** When `socket.getaddrinfo("api.stripe.com", 443)` fires, we resolve it ourselves (with a reentrancy guard) and store `{resolved_ip: "api.stripe.com"}`. When `socket.connect(sock, (resolved_ip, 443))` fires later, we look up the hostname and check it against the policy.
+
+4. **Thread safety.** `AllowPolicy` is immutable. The `_Config` bundle is a frozen dataclass swapped atomically (single reference assignment). `_ip_to_hostname` is an `OrderedDict` guarded by `_ip_map_lock` with LRU eviction. Reentrancy guard uses `threading.local()`.
+
+5. **Zero dependencies.** Everything uses stdlib only: `sys`, `socket`, `threading`, `collections`, `ipaddress`, `fnmatch`, `logging`, `dataclasses`.
+
+## Conventions
+
+### Code style
+
+- Use `from __future__ import annotations` in all modules.
+- Private modules are prefixed with `_` (e.g., `_core.py`, `_policy.py`).
+- Type hints on all public function signatures.
+- No docstrings on private helpers unless the logic is non-obvious.
+- Keep modules small and focused. If a module exceeds ~200 lines, consider splitting.
+
+### Testing
+
+- **Egress guard** (`conftest.py`): An independent audit hook that uses `AllowPolicy` to block unexpected network access between tests (when tethered is deactivated). Only `dns.google` and localhost are allowed. When tethered IS active, its own hook handles enforcement and the guard is a no-op.
+- **Unit tests** (`test_policy.py`): Test `AllowPolicy` in isolation. No audit hooks, no network calls. This is where the bulk of pattern-matching coverage lives.
+- **Integration tests** (`test_core.py`): Test `activate()`/`deactivate()` with real sockets (sync and async). Use the `_cleanup` autouse fixture that calls `_reset_state()` after each test. Async tests use `pytest-asyncio` with `asyncio_mode = "auto"`.
+- Run tests with: `uv run pytest tests/ -v`
+- Run with coverage: `uv run pytest tests/ -v --cov`
+- Tests must not depend on external network availability for correctness. Use known IPs, localhost, and `settimeout()` to handle network-level failures gracefully.
+
+### Linting and formatting
+
+- Ruff handles linting and formatting. Configuration is in `pyproject.toml` under `[tool.ruff]`.
+- Bandit handles security scanning. Configuration is in `pyproject.toml` under `[tool.bandit]`. Tests are excluded. Intentional suppressions use inline `# nosec BXXX` comments.
+- Lint: `uv run ruff check .` (auto-fix with `--fix`)
+- Format: `uv run ruff format .`
+- Security: `uv run bandit -c pyproject.toml -r src/`
+- Pre-commit hooks run ruff, bandit, markdownlint, and pytest on every commit, and commitizen on commit messages. All hooks are pinned by commit SHA for supply-chain integrity. Install with `uv run pre-commit install --hook-type pre-commit --hook-type commit-msg`.
+- CI runs `pre-commit run --all-files` (lint job) and the full test matrix. GitHub Actions are pinned by commit SHA. The workflow uses `permissions: { contents: read }` for least privilege. A separate CodeQL workflow runs on push to main, on PRs, and weekly.
+
+### What NOT to do
+
+- Do not add runtime dependencies. This library must remain zero-dep.
+- Do not monkey-patch `socket.socket` or any other stdlib class. The audit hook API is the only interception mechanism.
+- Do not catch `EgressBlocked` inside tethered itself (except in tests). It must propagate to the caller.
+- Do not add framework-specific code (Django, Flask, etc.) to the core package. Framework integrations belong in documentation, not code.
+- Do not add features speculatively. Every addition must serve a concrete, current use case.
+- Do not stage or commit changes. The developer reviews and commits manually.
+
+### Adding new allow rule types
+
+If adding a new rule type (e.g., regex patterns, deny lists):
+
+1. Add a new `_XxxRule` dataclass in `_policy.py`.
+2. Parse it in `AllowPolicy.__init__`.
+3. Check it in `is_allowed()` or `_check_hostname()`/`_check_ip()`.
+4. Add unit tests in `test_policy.py` first, then integration tests if needed.
+
+### Python version support
+
+- Python 3.10–3.14. `sys.addaudithook` was added in 3.8, so this is well within range.
+- Do not use syntax or features unavailable in 3.10 (e.g., no `type` statement from 3.12, no `except*` from 3.11).

tethered-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "Tethered"
+abstract: "Runtime network egress control for Python"
+version: 0.1.0
+date-released: 2026-02-24
+license: MIT
+repository-code: "https://github.com/shcherbak-ai/tethered"
+url: "https://github.com/shcherbak-ai/tethered"
+authors:
+  - family-names: "Shcherbak"
+    given-names: "Sergii"
+keywords:
+  - security
+  - egress
+  - network
+  - audit
+  - supply-chain
+  - python

tethered-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+See @AGENTS.md for project context, architecture, and conventions.

tethered-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to Tethered
+
+## Setup
+
+```bash
+git clone https://github.com/shcherbak-ai/tethered.git
+cd tethered
+uv sync
+uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
+```
+
+## Running tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+With coverage:
+
+```bash
+uv run pytest tests/ -v --cov
+```
+
+## Linting and formatting
+
+Pre-commit hooks run all checks automatically on every commit, but you can also run them manually:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+Individual tools:
+
+```bash
+uv run ruff check .        # lint
+uv run ruff check --fix .  # lint with auto-fix
+uv run ruff format .       # format
+uv run bandit -c pyproject.toml -r src/  # security scan
+```
+
+## Commit messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by [commitizen](https://commitizen-tools.github.io/commitizen/). The commit-msg hook validates every commit message automatically. Run `uv run cz commit` for an interactive session that guides you through the format.
+
+## Project structure
+
+```text
+src/tethered/
+    __init__.py    # Public API: activate(), deactivate(), EgressBlocked
+    _policy.py     # AllowPolicy — pattern parsing and matching (pure logic)
+    _core.py       # Audit hook, state management, IP-to-hostname resolution
+tests/
+    test_policy.py  # Unit tests for AllowPolicy (no network)
+    test_core.py    # Integration tests with real sockets
+```
+
+## Network safety in tests
+
+### IP addresses
+
+Use only reserved, unroutable ranges for IP addresses in tests:
+
+| Range | Name | RFC |
+|---|---|---|
+| `192.0.2.0/24` | TEST-NET-1 | RFC 5737 |
+| `198.51.100.0/24` | TEST-NET-2 | RFC 5737 |
+| `203.0.113.0/24` | TEST-NET-3 | RFC 5737 |
+| `2001:db8::/32` | Documentation IPv6 | RFC 3849 |
+| `127.0.0.0/8`, `::1` | Loopback | — |
+
+Never use real, routable IPs (e.g., `8.8.8.8`, `93.184.215.14`). Even in "allow" tests, TEST-NET addresses ensure no packets reach real servers.
+
+### Hostnames
+
+Some integration tests need real DNS resolution to verify that allowed hostnames pass through correctly. Use `dns.google` or `localhost` for this. These are the only real hostnames permitted in tests — they perform only a harmless DNS lookup, no application-level connection is made.
+
+Never use hostnames that could trigger unexpected connections to services with side effects (e.g., API endpoints, webhook URLs).
+
+## Code conventions
+
+- Zero runtime dependencies — stdlib only.
+- `from __future__ import annotations` in all modules.
+- Private modules prefixed with `_`.
+- Type hints on all public functions.
+- Python 3.10+ only — no syntax from 3.12+ (`type` statement) or 3.11+ (`except*`).
+
+## Testing conventions
+
+- **Policy tests** (`test_policy.py`): Pure logic, no audit hooks, no network. Bulk of coverage lives here.
+- **Integration tests** (`test_core.py`): Use real sockets. The `_cleanup` autouse fixture calls `_reset_state()` after each test.
+- Tests must not depend on external network availability for correctness.
+- Blocked connection tests verify `EgressBlocked` is raised before any packet leaves the machine.

tethered-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergii Shcherbak
+
+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.

tethered-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: tethered
+Version: 0.1.0
+Summary: Runtime network egress control for Python
+Project-URL: Homepage, https://github.com/shcherbak-ai/tethered
+Project-URL: Repository, https://github.com/shcherbak-ai/tethered
+Project-URL: Issues, https://github.com/shcherbak-ai/tethered/issues
+Author: Sergii Shcherbak
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,egress,network,security,supply-chain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.10