netaudit 0.1.0__tar.gz

netaudit-0.1.0/.claude/commands/commit.md

@@ -0,0 +1,22 @@
+Look at the current git diff (staged + unstaged) and create a GPG-signed conventional commit.
+
+Steps:
+1. Run `git diff HEAD` to see all changes (staged and unstaged). If nothing, run `git status` to check for untracked files.
+2. Determine the commit type from the diff:
+   - `feat`: new user-visible functionality
+   - `fix`: bug fix
+   - `refactor`: restructuring without behavior change
+   - `test`: test additions or changes only
+   - `docs`: documentation only
+   - `chore`: tooling, config, build, CI, deps
+3. Stage all relevant changes with `git add` (specific files, not `-A`).
+4. Write a single-line commit message: `<type>(<scope>): <short description>` — scope is optional, description is lowercase, no trailing period, under 72 chars total.
+5. Commit with `git commit -S -m "<message>"` (GPG-signed, no co-author line).
+
+Rules:
+- No co-author trailer.
+- No body or footer unless the change genuinely needs explanation.
+- Do not skip hooks (`--no-verify`).
+- If GPG signing fails, report the error and stop — do not commit unsigned.
+- Do not push.
+- Never reference phase numbers (e.g. "phase 0", "phase 1") in the commit message — describe what was done, not which plan phase it belongs to.

netaudit-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Title
+<!-- conventional commit format: type: short subject (e.g. feat: add HTTP/SSE transport) -->
+
+## What
+<!-- one or two sentences describing what was built or changed -->
+
+## Why
+<!-- what problem it solves or what it enables -->
+
+## Acceptance criteria
+- [ ] <!-- mark with x if the criterion is verified -->

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

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+      - name: ruff check
+        run: ruff check .
+      - name: ruff format
+        run: ruff format --check .
+      - name: mypy
+        run: mypy netaudit/
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+      - name: mkdocs build
+        run: mkdocs build --strict
+
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest --cov=netaudit --cov-fail-under=80
+
+  integration:
+    name: Integration Tests (strace)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install strace
+        run: sudo apt-get install -y strace
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Run integration tests
+        run: pytest -m integration -v

netaudit-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtual environment
+.venv/
+
+# netaudit
+.strace-out/
+
+# Docs
+site/
+
+# Distribution
+*.whl
+*.tar.gz
+MANIFEST

netaudit-0.1.0/.instructions/plan.md

@@ -0,0 +1,271 @@
+# Netaudit Development Plan (Refined)
+
+## Context
+
+netaudit is a Python CLI/library that wraps processes under `strace`, captures `connect()` syscalls, and validates them against a declarative YAML allowlist. Goal: CI-native network egress auditing — commit a config, run tests, get pass/fail.
+
+Starting from scratch on `main` (README + LICENSE only, no remote). Each phase produces a testable, CI-validated increment.
+
+### Decisions
+
+- **Versioning:** 0.x semver until API stabilizes, then 1.0
+- **First public release:** Phase 3 (when CLI is usable), tagged 0.1.0
+- **Docs:** MkDocs Material, deployed to GitHub Pages — deferred until Phase 3 (docstrings + README before that)
+- **CI:** Ubuntu-only for integration tests, cross-platform for unit tests
+- **Changelog:** None until v1
+- **pytest plugin:** Session-level first, per-test attribution second commit in same phase
+- **Type checking:** mypy strict from Phase 0, `py.typed` marker included
+- **Skills:** Only `/commit` from day one; others added when needed
+
+---
+
+## Phase Overview
+
+```
+Phase 0: Scaffold ──► Phase 1: Core Engine ──► Phase 2: Runner + Integration
+    │                  (parser+allowlist+       (strace subprocess,
+    │                   reporter)                end-to-end tests)
+    │                                                │
+    ▼                                                ▼
+  CI v1 (lint+test)                         CI v2 (+integration on Ubuntu)
+                                                     │
+                                                     ▼
+                                            Phase 3: CLI + Docs
+                                             (click CLI, mkdocs,
+                                              first release 0.1.0)
+                                                     │
+                                                     ▼
+                                            Phase 4: pytest Plugin
+                                             (session-level, then
+                                              per-test attribution)
+                                                     │
+                                                     ▼
+                                            Phase 5: Release Engineering
+                                             (PyPI, Docker, GH Pages,
+                                              hardening)
+```
+
+---
+
+## Phase 0 — Scaffold
+
+**Goal:** Buildable, installable, lintable skeleton with CI.
+
+- `pyproject.toml`: metadata, deps (`click`, `pyyaml`), dev deps (`pytest`, `ruff`, `mypy`, `pytest-cov`), entry point `netaudit = netaudit.cli:main`
+- Package: `netaudit/__init__.py` (version string), `netaudit/integrations/__init__.py`
+- `py.typed` marker
+- `.gitignore` (Python template + `.strace-out/` + `.venv/`)
+- Ruff config: `line-length=100`, `select = ["E", "F", "W", "I"]`
+- Mypy config: `strict = true`
+- Empty `tests/conftest.py`
+- `.venv` local development — created via `python -m venv .venv`, editable install with dev deps
+- `Makefile` with `venv`, `lint`, `test`, `clean` targets for one-command local workflow
+- GitHub Actions CI (`.github/workflows/ci.yml`): lint (ruff check + ruff format --check + mypy), test (pytest, no tests yet)
+- `.claude/commands/commit.md`: conventional commit skill — auto-detects type from diff, GPG-signed, no co-author
+
+**Exit:** `make venv && make lint && make test` works, CI green, `netaudit --help` prints placeholder.
+
+**Files:**
+```
+pyproject.toml
+Makefile
+.gitignore
+netaudit/__init__.py
+netaudit/py.typed
+netaudit/cli.py              # placeholder: click group, --version
+netaudit/integrations/__init__.py
+tests/conftest.py
+.github/workflows/ci.yml
+.claude/commands/commit.md
+```
+
+---
+
+## Phase 1 — Core Engine (Parser + Allowlist + Reporter)
+
+**Goal:** Parse strace output, match against rules, report violations. All tested without strace.
+
+**Parser** (`netaudit/parser.py`):
+- `ConnectEvent` dataclass: `pid`, `timestamp`, `family`, `addr`, `port`, `raw_line`, `result`
+- `StraceParser.parse_line(line) -> ConnectEvent | None`
+- `StraceParser.parse_stream(lines: Iterable[str]) -> list[ConnectEvent]`
+- Handle: AF_INET, AF_INET6, AF_UNIX, AF_NETLINK
+- Handle: EINPROGRESS (non-blocking connect — not a failure), resumed lines (`<... connect resumed>`)
+
+**Allowlist** (`netaudit/allowlist.py`):
+- `Rule` protocol: `matches(event: ConnectEvent) -> bool`
+- Concrete: `IPv4Rule(cidr)`, `IPv6Rule(cidr)`, `UnixSocketRule(path_glob)`, `NetlinkRule`
+- `AllowList`: load from YAML, `includes_builtins: true` by default (loopback 127.0.0.0/8, ::1/128, all AF_UNIX, all AF_NETLINK)
+- `AllowList.is_allowed(event) -> bool`
+
+**Reporter** (`netaudit/reporter.py`):
+- `Violation`: groups events by `(family, addr, port)` — tracks PIDs, count, first timestamp
+- `Reporter.check(events, allowlist) -> list[Violation]`
+- `Reporter.format(violations, stream)` — box-formatted human-readable output
+
+**Tests:** hardcoded strace lines for parser (all families, EINPROGRESS, resumed, malformed), YAML loading + CIDR matching + builtins for allowlist, grouping + formatting for reporter.
+
+**CI update:** Tests run with `--cov=netaudit --cov-fail-under=80`.
+
+**Exit:** All three modules compose together. Tests pass, coverage >= 80%.
+
+---
+
+## Phase 2 — Runner + Integration Tests
+
+**Goal:** Spawn strace, capture output, validate end-to-end on real syscalls.
+
+**Runner** (`netaudit/runner.py`):
+- `StraceRunner.run(command, output_path) -> CompletedProcess` — spawn under `strace -e trace=connect -f -tt -o <path>`
+- `StraceRunner.start(command, output_path) -> StraceProcess` / `.stop() -> CompletedProcess`
+- Runtime check: `StraceNotFoundError` if `shutil.which("strace")` is None
+
+**Test target** (`tests/integration/egress_target.py`):
+- Starts a local `http.server`, connects to it
+- Opens a Unix socket
+- Triggers DNS/netlink via `socket.getaddrinfo`
+- Attempts external connect to `198.51.100.1:443` (TEST-NET-2 — won't route, no flaky external deps)
+
+**Integration tests** (`tests/integration/test_end_to_end.py`, marked `@pytest.mark.integration`):
+- strace output file created and non-empty
+- Parser extracts expected event types from real output
+- External IP `198.51.100.1` produces violation
+- Loopback + unix + netlink allowed by default
+- Custom allowlist passes external IP
+
+**CI update:** Add `integration` job on `ubuntu-latest` (installs strace via apt). Unit tests remain cross-platform.
+
+**Exit:** Full pipeline works end-to-end. Integration tests green in CI.
+
+---
+
+## Phase 3 — CLI + Docs (First Release 0.1.0)
+
+**Goal:** User-facing CLI, documentation site, tagged 0.1.0.
+
+**CLI** (`netaudit/cli.py`):
+- `netaudit run --allowlist <yaml> -- <command>` — trace, analyze, report, exit 1 on violations
+- `netaudit analyze --allowlist <yaml> <strace-log>` — offline analysis
+- `--format {text,json}` for machine-readable output
+- `--allowlist` defaults to `netaudit.yaml` in cwd if it exists
+- Exit codes: 0 clean, 1 violations, 2 strace missing
+
+**Tests** (`tests/test_cli.py`):
+- Click `CliRunner` tests (mocked runner for `run`, real file for `analyze`)
+- Exit code semantics
+- Integration test: real `netaudit run` invocation
+
+**Docs** (`docs/` + `mkdocs.yml`):
+- MkDocs Material: nav, search, code highlighting
+- Pages: index (overview + quickstart), cli-reference, allowlist-dsl, architecture
+- README.md updated with badges, install instructions, quickstart
+
+**CI update:** Add `mkdocs build --strict` to lint job.
+
+**Exit:** Both CLI commands work. Docs build. Tagged `v0.1.0`.
+
+---
+
+## Phase 4 — pytest Plugin
+
+**Goal:** Automatic network auditing during pytest runs.
+
+**Session-level** (first commit):
+- `netaudit/integrations/pytest_plugin.py`, registered via `pytest11` entry point
+- `pytest_addoption`: `--netaudit`, `--netaudit-allowlist`
+- `pytest_sessionstart`: start strace tracing the test process
+- `pytest_sessionfinish`: stop, parse, check, report violations, set exit code
+- Allowlist resolution: CLI flag > `[tool.netaudit]` in pyproject.toml > `netaudit.yaml` in cwd
+
+**Per-test attribution** (second commit):
+- `pytest_runtest_protocol`: write timestamp markers to sidecar file at test boundaries
+- Correlate ConnectEvents with test items by timestamp range
+- Reporter enriched: violations grouped by test name
+
+**Tests:** `pytester`-based tests for both modes.
+
+**Docs:** `docs/pytest-plugin.md` — usage, config, examples.
+
+**Exit:** `pytest --netaudit` traces and reports. Per-test attribution shows which test caused each violation.
+
+---
+
+## Phase 5 — Release Engineering
+
+**Goal:** Automated publishing, Docker image, hardening.
+
+- **PyPI workflow** (`.github/workflows/release.yml`): build + publish on GitHub release
+- **Docs deploy** (`.github/workflows/docs.yml`): `mkdocs gh-deploy` on push to main
+- **Dockerfile**: `python:3.12-slim` + strace, `ENTRYPOINT ["netaudit"]`
+- **Docker CI**: build + push to GHCR on release
+- **Hardening**: truncated strace output, binary garbage in paths, long lines, permission errors, signal handling
+- **Docs:** Docker usage page, contributing guide
+
+**Exit:** `pip install netaudit` from PyPI, `docker run` works, docs live on GH Pages.
+
+---
+
+## Skills
+
+| Skill | Created in | Description |
+|---|---|---|
+| `/commit` | Phase 0 | Auto-detect conventional commit type from diff (feat/fix/refactor/test/docs/chore), minimal description, GPG-signed, no co-author |
+
+Additional skills (`/phase-docs`, `/coverage-check`, `/release-prep`) to be created when the need arises, not upfront.
+
+---
+
+## Verification
+
+Each phase verified by:
+1. `ruff check . && ruff format --check . && mypy netaudit/` — lint clean
+2. `pytest --cov=netaudit --cov-fail-under=80` — tests pass with coverage
+3. `pytest -m integration` (Linux only) — real strace tests (from Phase 2)
+4. `mkdocs build --strict` — docs build (from Phase 3)
+5. CI green on push
+
+---
+
+## Key Files (final state)
+
+```
+pyproject.toml
+Makefile
+.gitignore
+mkdocs.yml
+Dockerfile
+netaudit/
+  __init__.py
+  py.typed
+  parser.py
+  allowlist.py
+  reporter.py
+  runner.py
+  cli.py
+  integrations/
+    __init__.py
+    pytest_plugin.py
+tests/
+  conftest.py
+  test_parser.py
+  test_allowlist.py
+  test_reporter.py
+  test_cli.py
+  integration/
+    conftest.py
+    egress_target.py
+    test_end_to_end.py
+docs/
+  index.md
+  architecture.md
+  cli-reference.md
+  allowlist-dsl.md
+  pytest-plugin.md
+  docker.md
+.github/workflows/
+  ci.yml
+  docs.yml
+  release.yml
+.claude/commands/
+  commit.md
+```

netaudit-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

netaudit-0.1.0/CLAUDE.md

@@ -0,0 +1,111 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this project is
+
+`netaudit` is a Python library and CLI that wraps a process or test suite under `strace`, collects all `connect()` syscalls, filters them against a declarative allowlist, and reports violations. The goal: commit a config file declaring what's allowed, run tests normally, get pass/fail with readable output instead of raw strace noise.
+
+`strace` is a **system dependency** — documented, not bundled. No other runtime dependencies. `pytest` is optional (only needed for the plugin).
+
+## Commands
+
+```bash
+# Set up venv (Python 3.11+)
+python3.11 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+
+# Run all tests
+.venv/bin/pytest
+
+# Run a single test
+.venv/bin/pytest tests/test_parser.py::TestStraceParser::test_parse_af_inet_connect
+
+# CLI usage
+.venv/bin/netaudit run --allowlist netaudit.yaml -- <command>
+.venv/bin/netaudit analyze --allowlist netaudit.yaml /tmp/strace.log
+```
+
+## Architecture
+
+Two-layer design: a **language-agnostic core** (syscall tracing + analysis) and **framework-specific integrations** that add execution context (e.g. test attribution). The core must not import anything from integrations.
+
+### Core (`netaudit/`)
+
+| Module | Role |
+|---|---|
+| `runner.py` | `StraceRunner` — spawns strace as a subprocess wrapping a command, or attaches to an existing PID via `attach(pid)` |
+| `parser.py` | `StraceParser` — line-by-line regex parser producing `ConnectEvent` dataclasses |
+| `allowlist.py` | `AllowList` + rule types: `IPv4`, `IPv6`, `UnixSocket`, `Netlink` — loaded from YAML or constructed programmatically |
+| `reporter.py` | `Violation`, `Reporter` — groups events, formats output; enriched with test attribution when markers are available |
+| `cli.py` | CLI entry point (`netaudit run` / `netaudit analyze`) |
+
+### `ConnectEvent` (central data type)
+
+```python
+@dataclass
+class ConnectEvent:
+    pid: int
+    timestamp: float
+    family: str       # "AF_INET", "AF_INET6", "AF_UNIX", "AF_NETLINK", ...
+    addr: str | None  # IP or socket path
+    port: int | None
+    result: int       # 0 = success; negative errno (e.g. -ECONNREFUSED)
+```
+
+### Parser edge cases to handle
+
+- `EINPROGRESS`: non-blocking connect in flight — not a failure, should still be evaluated against the allowlist
+- Multi-line strace continuations (syscall split across lines)
+- Thread interleavings when strace is run with `-f`
+
+### AllowList DSL
+
+YAML format committed to the repo:
+
+```yaml
+version: 1
+allowlist:
+  - comment: "GVM Unix socket"
+    family: AF_UNIX
+    path_prefix: /run/gvmd/
+  - comment: "GVM TCP proxy"
+    family: AF_INET
+    addr: 127.0.0.1
+    port: 9393
+  - comment: "IPv6 loopback"
+    family: AF_INET6
+    addr: "::1"
+  - comment: "glibc resolver internals"
+    family: AF_NETLINK
+```
+
+`Netlink()` and loopback are reasonable built-in defaults — users opt **out** rather than explicitly allowing them.
+
+### pytest integration (`netaudit/integrations/pytest_plugin.py`)
+
+Registered via `entry_points` in `pyproject.toml` (not imported directly). Re-execs the pytest process with strace as parent. Emits timestamp markers at session and test boundaries so violations can be attributed to individual test cases. Calls `pytest.fail()` after `pytest_sessionfinish` if violations exist.
+
+Activated via `pyproject.toml`:
+```toml
+[tool.netaudit]
+allowlist = "netaudit.yaml"
+enabled = true
+```
+
+### Future integrations
+
+Node.js (Jest/Vitest/Mocha) and other runners are explicitly in scope. All integrations follow the same pattern: **emit execution markers → correlate with syscall timestamps → enrich violation reports**. New integrations go in `netaudit/integrations/` and must not require changes to core modules.
+
+## Key design constraints
+
+- The core is entirely framework-agnostic — no pytest imports outside `integrations/`
+- Exit code is non-zero on any violation (CI-native)
+- The CLI (`netaudit run`) must work with any executable, not just Python test suites
+- Regex is sufficient for parsing strace output — the format is stable and well-documented
+- `mypy --strict` enforced from day one; `py.typed` marker included
+- `ruff` for linting and formatting (line-length=100, select E,F,W,I)
+
+## Development plan
+
+See [`.instructions/plan.md`](.instructions/plan.md) for the full phased development plan (6 phases, agile approach with CI/CD from Phase 0).