pcap-doctor 0.2.0__tar.gz

pcap_doctor-0.2.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,43 @@
+---
+name: Bug
+about: Something the analyzer gets wrong, or cannot run at all
+title: "bug: "
+labels: bug
+assignees: ''
+---
+
+**What happened**
+
+**What it should have done**
+
+**Reproduce**
+
+```bash
+pcap-doctor analyze <capture> --out /tmp/x --no-cache
+```
+
+**Wrong output, verbatim**
+
+```
+<paste the finding, the note, or the traceback -- exactly as printed>
+```
+
+**Ground truth**
+
+How you know it is wrong. `tshark -r <capture> -Y '<filter>' -T fields -e <field>` output is ideal.
+
+- [ ] `tshark` version: `pcap-doctor doctor`
+- [ ] capture sha256: `pcap-doctor analyze <capture> | head -5`
+- [ ] cache cleared or `--no-cache` used
+
+**Scope**
+
+- [ ] parser/index (core-owned)
+- [ ] a detector
+- [ ] rendering
+- [ ] tshark field drift
+
+**Suggested location**
+
+File and function, if you know it. If this is a schema gap, propose the field rather than working
+around it in a detector: `AGENTS.md` §1.

pcap_doctor-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Severity and confidence policy
+    url: https://github.com/Vaibhav91one/pcap-forensics/blob/main/docs/severity-model.md
+    about: How to choose severity and confidence for a finding.
+  - name: Writing a detector
+    url: https://github.com/Vaibhav91one/pcap-forensics/blob/main/docs/detector-authoring.md
+    about: The detector contract, the index API, and the fixture rules.

pcap_doctor-0.2.0/.github/ISSUE_TEMPLATE/core-change.md

@@ -0,0 +1,34 @@
+---
+name: Core change
+about: Change models.py, index.py, tshark.py, data_ciphers.py or a renderer
+title: "core: "
+labels: core
+assignees: ''
+---
+
+Core changes are a **merge event**, not a parallel one (`docs/subagent-playbook.md`).
+
+**What changes**
+
+Paths: `models.py` / `index.py` / `tshark.py` / `data_ciphers.py` / `certificates.py` / `render/*`
+
+**Does `report.json`'s schema change?**
+
+- [ ] no — additive only, `schema_version` unchanged
+- [ ] yes, additive — bump minor
+- [ ] yes, breaking — bump major, and list the migration in the issue
+
+**If a new field is proposed**
+
+| Field | Type | Example from a real capture | Read by |
+|---|---|---|---|
+| | | | |
+
+**Which detectors are blocked without it**
+
+**Migration / rollout**
+
+- [ ] tests updated or added
+- [ ] `docs/` updated (tshark-fields, severity-model, cipher-policy as applicable)
+- [ ] `make verify` green
+- [ ] agents holding open branches told to rebase

pcap_doctor-0.2.0/.github/ISSUE_TEMPLATE/detector.md

@@ -0,0 +1,53 @@
+---
+name: Detector
+about: Add a detector (one check, one file, one claim)
+title: "detector: "
+labels: detector
+assignees: ''
+---
+
+**Which detector file**
+
+`src/pcapforensics/detectors/<name>.py` — new or existing.
+
+**What it detects**
+
+One sentence, in the words an analyst would use. Not "analyzes X" — "flags when Y".
+
+**Why it matters**
+
+What is the consequence if the condition is true and the tool is right?
+
+**Input that reproduces it**
+
+- capture: `<path or how to build it>`
+- observable: `<the exact frame, field, or shape>`
+- expected output:
+
+```
+<one line: the finding code, severity, confidence>
+```
+
+**Fields it needs from CaptureIndex**
+
+| Field | Type | Example value | Already present? |
+|---|---|---|---|
+| `index.…` | | | yes / no (file an issue if no) |
+
+**Fixture**
+
+- [ ] added to `scripts/make_fixtures.py` and regenerated (`make fixtures`)
+- [ ] deterministic (no randomness, no clock, no network)
+- [ ] negative case too: a fixture where this must stay silent
+
+**Checklist (AGENTS.md §3)**
+
+- [ ] pure `detect(index) -> list[Finding]`, no I/O
+- [ ] stable `code` and `scope`; ids stable across runs
+- [ ] every finding has frame-numbered evidence with a non-empty value
+- [ ] every finding has a `remediation`, plus references where a standard applies
+- [ ] unknown input yields a finding or a note, never a silent pass
+- [ ] no secret material can reach an artifact
+- [ ] tests assert on codes, not prose
+- [ ] README detector table has its row
+- [ ] `make verify` green, `pcap-doctor doctor` passes

pcap_doctor-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+Closes #
+
+## What I saw
+
+<!-- The bug or gap, with the capture/fixture and frame that shows it. -->
+
+## What changed
+
+<!-- Files touched and why. Stay inside the allowlist on the issue (AGENTS.md §1-§2). -->
+
+## What I verified
+
+<!-- Paste the evidence, not a claim. -->
+
+- [ ] The new test **fails on the old code** (paste the failing line) and passes after
+- [ ] `make verify` is green (ruff, mypy strict, pytest)
+- [ ] `pcap-doctor doctor` passes
+- [ ] New or changed fixtures are generated by `scripts/make_fixtures.py` and regenerate byte-for-byte
+
+## Deliberately not done
+
+<!-- Follow-ups, known limits, anything out of scope. File issues for them. -->
+
+## Checklist (AGENTS.md §3)
+
+- [ ] Every finding cites a real frame and has a stable `code` and `scope`
+- [ ] Every finding has a remediation and, when a standard applies, a reference a reader can look up
+- [ ] No secret can reach a report (redacted, with a test that greps the artifacts)
+- [ ] Heuristics report `confidence: low`; severity is about impact, not urgency
+- [ ] Tests assert on finding codes, not prose
+- [ ] README detector table and CHANGELOG updated if behaviour changed

pcap_doctor-0.2.0/.github/workflows/action-selftest.yml

@@ -0,0 +1,30 @@
+# Runs this repository's own action (action.yml) on pull requests that change it, against the test fixtures.
+name: action-selftest
+
+on:
+  pull_request:
+    paths:
+      - action.yml
+      - scripts/pcap-doctor-action.sh
+      - src/**
+      - .github/workflows/action-selftest.yml
+
+permissions:
+  contents: read
+  pull-requests: write
+  security-events: write
+
+jobs:
+  selftest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - id: doctor
+        uses: ./
+        with:
+          captures: "tests/fixtures/*.pcap"
+          # This job proves the action runs end to end (install, analysis, comment, SARIF). The gate itself is
+          # tested in tests/test_ci_install.py; gating here would fail every PR that adds a fixture.
+          fail-on: none
+      - name: The summary lists every fixture
+        run: test "$(grep -c '^| `tests/fixtures/' "${{ steps.doctor.outputs.summary }}")" -eq "$(ls tests/fixtures/*.pcap | wc -l)"

pcap_doctor-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install tshark
+        run: |
+          sudo apt-get update
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y tshark
+          tshark --version | head -1
+      - uses: astral-sh/setup-uv@v5
+      - name: Install project
+        run: |
+          uv venv
+          uv pip install -e '.[dev]'
+      - name: Environment check
+        run: uv run pcap-doctor doctor
+      - name: Fetch regression corpus
+        run: ./scripts/fetch_captures.sh
+      - name: Fixtures are reproducible
+        run: |
+          make fixtures
+          static=$(.venv/bin/python -c "import sys; sys.path.insert(0, 'scripts'); import make_fixtures as m; print(' '.join('tests/fixtures/' + n for n in m.STATIC_FIXTURES))")
+          git diff --exit-code -- $static || (echo "byte-built fixtures drifted; commit the regenerated files" && exit 1)
+      - name: Lint
+        run: .venv/bin/ruff check .
+      - name: Typecheck
+        run: .venv/bin/mypy
+      - name: Tests
+        run: .venv/bin/python -m pytest -q
+      - name: Reports render end to end
+        run: |
+          for cap in captures/*.pcap captures/*.pcapng; do
+            .venv/bin/pcap-doctor analyze "$cap" --out /tmp/pf-ci --quiet || true
+          done
+          test -s /tmp/pf-ci/report.json
+          test -s /tmp/pf-ci/04-diagrams.md
+
+  npm-launcher:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Launcher tests
+        working-directory: npm
+        run: npm test

pcap_doctor-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: release
+
+# Publishes to PyPI when a version tag is pushed (issue #50), then the npm launcher (issue #51).
+# Both use trusted publishing (OIDC): no token or secret exists for either registry (#93).
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Tag matches the package version
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match pyproject version v$version"
+            exit 1
+          fi
+          npm_version=$(node -p "require('./npm/package.json').version")
+          if [ "$npm_version" != "$version" ]; then
+            echo "npm/package.json version $npm_version does not match pyproject version $version"
+            exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pcap-doctor
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  npm:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # npm trusted publishing: GitHub proves the workflow's identity; provenance is automatic
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: https://registry.npmjs.org
+      - name: npm with trusted publishing (needs 11.5.1+)
+        run: npm install -g npm@latest
+      - name: Launcher tests
+        working-directory: npm
+        run: npm test
+      - name: Publish unless the package is new or this version is already on npm
+        working-directory: npm
+        run: |
+          version=$(node -p "require('./package.json').version")
+          if ! versions=$(npm view pcap-doctor versions --json 2>&1); then
+            if grep -q E404 <<< "$versions"; then
+              echo "::notice::pcap-doctor is not on npm yet. A trusted publisher can only be added to an existing package: publish it once by hand (cd npm && npm login && npm publish --access public), then add this workflow as its trusted publisher."
+              exit 0
+            fi
+            echo "$versions"
+            exit 1
+          fi
+          if node -e 'process.exit([].concat(JSON.parse(process.argv[1])).includes(process.argv[2]) ? 0 : 1)' "$versions" "$version"; then
+            echo "::notice::pcap-doctor@$version is already on npm; nothing to publish."
+            exit 0
+          fi
+          npm publish --access public

pcap_doctor-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# environments
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# analysis output
+out/
+*.pf-report/
+
+# tshark pass cache
+.cache/
+
+# NOTE: captures/ is intentionally NOT ignored in this repo -- the regression
+# suite needs it and the files are small. Set PF_SKIP_CAPTURES=1 in CI to
+# download them at run time instead of storing them.

pcap_doctor-0.2.0/AGENTS.md

@@ -0,0 +1,118 @@
+# AGENTS.md — the contract for automated subagents
+
+This file is binding for any agent (human or not) working in this repository. It exists so that
+four agents can work at once, in isolation, without stepping on each other.
+
+Read this before you touch anything. Then read `docs/detector-authoring.md` if you are adding a
+detector, or `docs/subagent-playbook.md` if you are running a subagent loop.
+
+---
+
+## 1. Ownership map
+
+Exactly one owner per file class. If a task needs a file you do not own, you file an issue; you do
+not edit it.
+
+| Path | Owner | Notes |
+|---|---|---|
+| `src/pcapforensics/models.py` | **core** | the schema. frozen after Phase 0 |
+| `src/pcapforensics/index.py` | **core** | builds the only view detectors get |
+| `src/pcapforensics/tshark.py` | **core** | the tshark boundary |
+| `src/pcapforensics/data_ciphers.py` | **core** | crypto reasoning helpers |
+| `src/pcapforensics/certificates.py` | **core** | openssl enrichment |
+| `src/pcapforensics/data/*` | **core** | generated by `make regenerate` |
+| `src/pcapforensics/detectors/<yourname>.py` | **you** | one detector, one file |
+| `src/pcapforensics/render/*` | **core** | detectors must not add renderers |
+| `src/pcapforensics/cli/__init__.py`, `cli/_console.py` | **core** | the app and the command loader |
+| `src/pcapforensics/cli/<command>.py` | **you** (one command, one file) | exports `register(app)`; never edit another command's file |
+| `tests/test_cipher_registry.py`, `test_tshark_layer.py` | **core** | |
+| `tests/fixtures/<yours>.pcap` + its test | **you** | |
+| `README.md` detector table row for your detector | **you** (one line) | do not touch other sections |
+| `pyproject.toml` | **core** | new runtime dependencies require an issue |
+
+## 2. Isolation rules
+
+1. **Stay inside your allowlist.** Your allowlist is written on your issue. Edits outside it are
+   rejected in review even when they look like an improvement.
+2. **One issue, one branch, one PR.** Branch name `agent/<issue-number>-<slug>`.
+3. **Never import a sibling detector.** `detectors/a.py` must not import `detectors/b.py`. If you
+   need shared logic, it goes into `index.py` (core-owned) via an issue.
+4. **Never edit `models.py` to make your life easier.** Add the field in an issue with a proposed
+   shape. Schema changes are a merge event, not a parallel event.
+5. **No new runtime dependency** without an issue. Dev dependencies (pytest, scapy) are fine.
+6. **Do not rebase or force-push** other agents' branches. If you need a core change, land the
+   core issue first and rebase onto it.
+
+## 3. What "done" means
+
+A task is done when **all** of these are true. Review checks them mechanically.
+
+- [ ] The detector lives in its own file, is named `dN.<slug>`, and has `enabled = True` only if
+      it produces findings on at least one fixture.
+- [ ] `detect()` is a pure function of the `CaptureIndex`: no file I/O, no network, no globals.
+- [ ] Every finding has a **stable** `code` (SCREAMING_SNAKE) and a `scope` that is unique per
+      flow/host so `Finding.id` is stable across runs.
+- [ ] Every finding carries at least one `Evidence` with a real frame number and a non-empty value.
+- [ ] Every finding carries `remediation` and at least one `references` entry when a standard
+      applies. A finding a reader cannot act on is not finished.
+- [ ] Unknown or unparseable input produces a **finding or a note**, never a silent pass.
+- [ ] No secret material can reach a report. If you touch credentials, use
+      `index.redact_auth` or add a redaction of the same shape, and add a test.
+- [ ] A synthetic fixture exists under `tests/fixtures/`, is generated by
+      `scripts/make_fixtures.py`, and is deterministic.
+- [ ] Tests assert on **finding codes**, not on prose.
+- [ ] Every new finding `code` has a `RULES` entry in `rules.py` (category and title) and a
+      `rule_docs/<CODE>.md` with the four sections *What it means*, *Why it matters*, *How to fix*
+      and *How to verify*. `tests/test_rules_catalog.py` and `tests/test_prompts.py` fail otherwise.
+- [ ] The detector row in the README table is updated.
+- [ ] `make verify` is green: `ruff check .`, `mypy` (strict), `pytest`.
+- [ ] `pcap-doctor doctor` still passes.
+
+## 4. Honesty rules
+
+These are the project's rules about itself, and a reviewer will fail a PR that breaks them.
+
+- Do not claim a fact the capture does not contain. If forward secrecy is undecidable, the answer
+  is `None` with a reason, not `False`.
+- Do not round a heuristic into a certainty. If it is a heuristic, set `confidence="low"`.
+- Do not use a severity to express urgency rather than impact.
+- Do not suppress a finding because it is noisy. If it is noisy, that is a policy conversation,
+  and the policy lives in `docs/severity-model.md`.
+- If you find a bug in core while working, **do not fix it in your PR**. File it, link it, and keep
+  your detector working against the current contract.
+
+## 5. Severity and confidence
+
+Severity answers "how bad is this if true"; confidence answers "how sure am I from this capture".
+They are independent and both are required.
+
+| Severity | Use when |
+|---|---|
+| `critical` | credential or key material is exposed, or a prohibited cipher is negotiated |
+| `high` | confidentiality of captured traffic is at risk without user action (no PFS, deprecated version, cleartext media) |
+| `medium` | downgrade surface, policy violations, likely-relevant heuristics |
+| `low` | legacy fields, weak hints, context a reviewer should see |
+| `info` | inventory and clustering that is not a defect on its own |
+
+`confidence` is `high` only when the evidence is directly visible in the capture.
+
+## 6. Communication
+
+- Issue title: `detector: <what it detects>` or `core: <what changes>`.
+- Issue body must name the affected paths, the input that reproduces it, and the expected output.
+- PR description: what you saw, what you changed, what you verified, and what you deliberately did
+  not do.
+- If you could not finish, say so in the PR. A partial detector behind `enabled = False` is a
+  useful contribution; a half-working enabled detector is not.
+
+## 7. Where the truth lives
+
+| Question | File |
+|---|---|
+| What can I read from the index? | `src/pcapforensics/models.py` |
+| How is a cipher judged weak? | `docs/cipher-policy.md` |
+| How is severity chosen? | `docs/severity-model.md` |
+| Which tshark fields do we rely on? | `docs/tshark-fields.md` |
+| How do I write a detector? | `docs/detector-authoring.md` |
+| How do I run a fleet of subagents? | `docs/subagent-playbook.md` |
+| What is frozen and why? | `AGENTS.md` §1 |

pcap_doctor-0.2.0/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-09-30
+
+**pcap-forensics is now pcap-doctor**: one command gives a health score, findings grouped by category,
+explanations, a CI gate on new findings, and a handoff to AI coding agents. `pf` stays as an alias.
+`report.json` keeps `schema_version` `1.4.0`: everything new is computed around the report.
+
+### Added — pcap-doctor
+
+- Distribution and command `pcap-doctor`, `--version`; `npx pcap-doctor` launcher (runs the same
+  version through `uvx` or `pipx`); PyPI and npm releases by trusted publishing,
+  with no stored token (#46, #50, #51, #93).
+- The CLI is a package of self-registering command modules (#45).
+- A rule catalog with eight categories, `rules list` / `rules explain`, and a doc per finding code
+  (#47, #49, #61).
+- A local 0-100 health score and a summary grouped by category; `--score`, `--verbose` (#48, #53).
+- `--category`, strict option validation (unknown values exit 2 before tshark runs) (#52).
+- `--json` / `--json-out` envelope, `--sarif` (SARIF 2.1.0), `--baseline` to show and gate only new
+  findings (#54, #55, #56).
+- `pcap-doctor.toml` / `[tool.pcap-doctor]`: `disable`, `[severity]`, `[[allow]]` with a reason,
+  `categories`, `fail_on`, and the `ota` profile (`--config`, `--profile`); every suppression is
+  noted in the report (#57, #58).
+- `why <frame|id>` with `--prompt`; an AI handoff menu after interactive scans (Claude Code, Codex,
+  Cursor; `--safe`, `--no-handoff`), agent guidance inside agent shells, and a fenced
+  untrusted-data prompt builder (#49, #59, #60).
+- `install` writes agent guides (Claude Code skill, Cursor rule, AGENTS.md block) (#62).
+- `ci install` and a composite GitHub Action that compares each capture with its base-branch copy,
+  comments once on the PR and uploads SARIF (#63).
+- `watch -i IFACE`: ring-buffer live capture that prints each finding the first time it appears (#64).
+- `HTTP_CLEARTEXT`: plain HTTP is reported per flow, high when a request path looks like a firmware or
+  package download (so `--profile ota` fails it) and medium otherwise; query strings are never written
+  to a report (#91). A new fixture, `http_cleartext.pcap`, covers it.
+
+### Changed — pcap-doctor
+
+- The npm launcher is published with npm trusted publishing (OIDC) instead of an `NPM_TOKEN` secret;
+  the release job skips with a notice when the package is not on npm yet (its first publish is
+  manual) or the version is already published (#93).
+
+### Fixed — pcap-doctor
+
+- RFC citations in TLS version and cipher-policy text (#72).
+- The tool version in reports now comes from the installed package instead of a hard-coded string (#65).
+
+**MVP hardening since 0.1.0 (issues #1–#44):**
+
+`report.json` `schema_version` is `1.4.0` (additive: `Flow.first_frame`, `Flow` burst statistics,
+`RtpStream.first_frame`, `SshSession.offered_in`, `TelnetLogin`).
+
+### Added
+
+- Telnet logins: passwords typed after a `Password:` prompt are reported as `CLEARTEXT_CREDENTIAL`
+  (length and frame only, never the text); Telnet sessions now raise `CLEARTEXT_SERVICE` (#37).
+- `SSH_TERRAPIN_EXPOSED`: chacha20-poly1305, or an EtM MAC with a CBC cipher, offered without strict
+  key exchange on both sides (#24).
+- FTP `PASS` arguments and LDAP simple-bind passwords are reported as `CLEARTEXT_CREDENTIAL` (#14).
+
+### Fixed — secrets
+
+- SNMP community strings and MySQL queries are redacted where the index builds service details (#1).
+- A scheme-less `Authorization` value (bare token) no longer appears in a finding title or evidence (#15).
+
+### Fixed — evidence and correctness
+
+- Every finding cites a real frame: RTP, SYN scan, odd-port, beaconing and DNS resolver evidence no
+  longer cite frame 0 or a stream index (#4, #6); SSH evidence cites the KEXINIT, not the banner (#25).
+- The server's SSH KEXINIT no longer overwrites the client's offer (#25).
+- `BEACONING_SHAPE` measures regularity of gaps between bursts; the old check could never fail (#10).
+- `SERVICE_ON_ODD_PORT` no longer reports a client's ephemeral port (#16).
+- `DNS_EXTERNAL_RESOLVER` finds the resolver by port and covers IPv6 and all private ranges (#6);
+  `DNS_TUNNEL_SHAPE` names the querying host and no longer counts responses as queries (#18).
+- `chacha20-poly1305@openssh.com` is no longer listed as a weak SSH cipher (#2).
+- Invalid or wrong finding references replaced (e.g. `CWE- exfil`, RFC 8999 on TLS findings) (#3).
+- The service field list is shared with the tshark pass; four names that are not tshark fields were removed (#14).
+- `WELL_KNOWN_PORTS`: 506/522/1194 mapped to the wrong service (#23).
+
+### Changed — docs
+
+- README redesigned CLI-first: light/dark logo, badges, a numbered get-started path including a CI
+  gate, a table of contents, exit codes, and a privacy/telemetry section; the documented default
+  output folder is corrected to `<capture>.pf-report/` (#41).
+- CONTRIBUTING gains how-to-start, pull-request and other-ways-to-help sections; a pull request
+  template follows the AGENTS.md contract (#41).
+
+### Fixed — project
+
+- Mermaid: `04-diagrams.md` emitted an invalid RTP gantt for captures without RTP (28 of 179 generated
+  diagrams failed to render), and the README's sequence diagram broke on a `;` (#43).
+- CI could never pass (non-existent tshark preference, fixture drift check on randomly captured TLS
+  fixtures); it now runs the full suite (#12).
+
+## [0.1.0] — 2026-09-29
+
+First working release. `report.json` `schema_version` is `1.0.0`.
+
+### Added — parsing
+
+- `TsharkRunner`: 10 pinned tshark passes, `-T fields` with a documented
+  separator/aggregator, content-addressed disk cache keyed by capture SHA-256,
+  tshark version and pass arguments.
+- Field and display-filter drift handling: fields validated against
+  `tshark -G fields`, protocol tokens against `tshark -G protocols`, preferences
+  against `tshark -G defaultprefs`; every drop recorded as a report note.
+- `CaptureIndex`: flows, hosts, TLS/DTLS sessions, HTTP exchanges, DNS queries,
+  SIP messages with SDP, RTP streams, SSH sessions, QUIC sessions, and other
+  recognised services.
+- SDP-driven RTP decode-as, so media on dynamic ports is dissected at all.
+- Certificate enrichment through `openssl x509`, with an explicit
+  `name_source` field and a tshark-flattened fallback.
+- Cipher registry of 424 suites derived from tshark's own value table, with
+  weakness tags and forward-secrecy reasoning derived from the IANA name.
+
+### Added — detectors
+
+- `d1.tls_cipher`: deprecated versions, weak/prohibited suites, offered-but-unused
+  weak suites, missing forward secrecy, certificate expiry/key size/signature,
+  self-signed leaf, alerts, truncated handshakes, JA3 fleet clustering.
+- `d2.transport_exposure`: cleartext HTTP auth, Basic auth inside TLS, cookies
+  without `Secure`, cleartext services, leaked credentials, services on odd
+  ports, unanswered-SYN scan shape, beaconing shape.
+- `d3.sip_rtp`: SIP call graph, cleartext signalling with auth headers, SDP
+  without `a=crypto`, unprotected RTP, media volume anomalies.
+- `d4.dns_quic_ssh`: plaintext DNS leakage, DNS tunnelling heuristics, external
+  resolvers, QUIC version inventory and payload opacity, weak SSH negotiation.
+
+### Added — output
+
+- Six artifacts per run: `index.md`, `01-flows.md`, `02-ciphers.md`,
+  `03-findings.md`, `04-diagrams.md`, `report.json`.
+- Mermaid topology, crypto matrix, severity pie, per-detector bar chart, RTP
+  timeline and SIP sequence diagrams, all total functions.
+- Stable finding ids (`detector.code.sha256(scope)[:16]`) so reports diff.
+- `pf` CLI: `analyze`, `flows`, `ciphers`, `detectors`, `suites`, `doctor`,
+  `schema`, with `--fail-on` for CI gates.
+
+### Added — safety
+
+- Credential redaction at the model boundary, with tests that grep the artifacts
+  for the original material.
+- One detector raising an exception cannot sink a run; it is reported as a note.
+- Unknown cipher ids, unparseable certificates and missing tshark fields all
+  produce findings or notes, never silent passes.
+
+### Added — engineering
+
+- 85 tests across four layers: registry, tshark boundary, detectors with
+  synthetic fixtures, and regression assertions over the Wireshark sample
+  corpus checked by hand against `tshark -V`.
+- Fixtures generated deterministically; TLS fixtures captured from genuine
+  OpenSSL handshakes through a logging proxy.
+- `ruff`, `mypy --strict` and `pytest` are the CI gate (`make verify`).
+- `AGENTS.md` and `docs/subagent-playbook.md`: the subagent isolation contract
+  and a 54-item seed issue board (`docs/issue-board.md`).
+
+### Known limits
+
+- Encrypted payloads (QUIC, TLS 1.3 application data) are opaque without a keylog.
+- Certificate subject/issuer require openssl; without it the report says so.
+- DNS tunnelling and beaconing are heuristics, reported at low confidence.
+- Server/client orientation uses port heuristics; odd ports are flagged instead
+  of trusted.