Security Assurance Case¶

This document is httptap's security assurance case. It explains why the project believes its security properties hold, not just what those properties are. It is structured according to the OpenSSF Best Practices silver-level assurance_case criterion.

Last reviewed: 2026-10-05.

The assurance case is a living document; it is reviewed at every major release and whenever the threat landscape or feature set changes materially. Proposals for amendments are accepted as pull requests against this file.

What httptap Is¶

httptap is a command-line diagnostic tool. A developer supplies a single URL (and optionally headers, a body, a proxy, a CA bundle, etc.) and httptap performs one HTTP request (or a short redirect chain) and renders per-phase timing and TLS information. It does not:

• accept network input from untrusted peers (it is not a server);
• manage user accounts, sessions, or long-lived credentials;
• execute remote code or evaluate server-supplied scripts;
• persist secrets or user data beyond the optional --json report, --har archive and --prometheus textfile;
• send measurements anywhere other than the OTLP collector the user names with the optional --otlp.

Security Requirements¶

The project commits to the following observable security properties. Each is mapped to supporting arguments in the sections below.

Trust Boundaries¶

   ┌─────────────────────┐
   │ CLI user            │   trusted
   │ (argv, stdin, env)  │
   └──────────┬──────────┘
              │
              ▼
   ┌─────────────────────┐  --json, --har, --prometheus  ┌─────────────────────┐
   │ httptap process     │ ────────────────────────────► │ Local files, stdout │  trusted
   │ (Python 3.11+)      │                               └─────────────────────┘
   │                     │  --otlp (OTLP/HTTP)           ┌─────────────────────┐
   │                     │ ────────────────────────────► │ OTLP collector      │  user-chosen
   └──────────┬──────────┘                               └─────────────────────┘
              │  TLS/HTTP  ◄─── untrusted: network, proxy, remote host
              ▼
   ┌─────────────────────┐
   │ Remote HTTP server  │   untrusted
   └─────────────────────┘

• User → httptap is trusted: the user is assumed to have legitimate reasons to issue any given request. Input validation still rejects malformed URLs, methods, timeouts, etc. to prevent operator mistakes.
• httptap → network → remote server is untrusted. All data crossing this boundary is treated as attacker-controlled: response headers, status codes, Location values, TLS certificates, content bodies.
• httptap → local outputs is trusted: --json writes the report to a file or stdout, --har writes a HAR 1.2 archive to a file or stdout, and --har and --prometheus write their files atomically (temporary file in the same directory, then rename). Prometheus labels carry only the hostname and redirect step number, never paths or query strings. Files land where the user points them and are readable by whoever can read that location.
• httptap → OTLP collector crosses the network to an endpoint the user supplies with --otlp (optional httptap[otel] extra), over http:// or https:// as given. Each request step becomes one span with child spans per phase, carrying the method, status code, body size, hostname, peer IP, HTTP and TLS versions, and the error message of a failed step. Spans never include the full URL (path, query string, credentials) or any headers. Delivery failures are reported as warnings and do not change the exit code.
• Build pipeline → PyPI / GitHub Releases is a separate trust boundary secured by GitHub OIDC (no long-lived keys), Sigstore signing, and SHA- pinned actions.

Threat Model¶

Threats are listed using the STRIDE categories that apply to a diagnostic HTTP client. Threats outside the scope of a client (e.g., server-side DoS) are explicitly excluded as non-goals.

Out-of-scope threats¶

• Adversary with local code execution on the developer's machine. Out of scope — that adversary already owns the process.
• Adversary controlling the user's terminal / TTY. Out of scope.
• Cryptanalytic attacks on TLS itself. Delegated to OpenSSL; mitigations are inherited from the system Python build.
• Post-quantum threats. Tracked upstream (OpenSSL / Python); out of scope for httptap itself.

Applied Secure-Design Principles¶

Mapped to Saltzer & Schroeder (1975) plus modern additions.

Countered Common Implementation Weaknesses¶

Derived from the CWE Top 25 (2023) and OWASP ASVS 4.0. Items not listed are either not applicable to an HTTP client or handled upstream.

Supply-Chain Assurance¶

Supporting the release-integrity property (SR-5):

• Publishing: PyPI (and TestPyPI as a pre-production smoke test) via GitHub OIDC Trusted Publishing — no long-lived PyPI tokens anywhere. PEP 740 attestations are surfaced on PyPI as "Verified publisher".
• Container images: multi-arch (linux/amd64, linux/arm64) images are built with Buildx and pushed to GHCR, signed keylessly with cosign, and accompanied by SLSA build provenance attached to the registry.
• Git signing: release commits and annotated tags are signed keylessly with gitsign (x.509 via Fulcio
• Rekor transparency log), using the release workflow's OIDC identity.
• Signing: Sigstore keyless signing through actions/attest-build-provenance and cosign. Signing keys are short-lived, issued per-run by Fulcio, and verifiable via the Rekor transparency log.
• Provenance: SLSA v1.0 attestation accompanies every wheel, sdist, and container image digest.
• Dockerfile linting: hadolint runs on every PR with a warning-level failure threshold.
• Pinning: every GitHub Action in every workflow is pinned by SHA; enforced by Scorecard Pinned-Dependencies and zizmor pedantic on every PR.
• Dependency tracking: SBOM in CycloneDX and SPDX formats is generated during release and attached as a GitHub Release asset.
• Exploitability disclosure: an OpenVEX document (httptap-X.Y.Z.openvex.json) ships alongside the SBOM, declaring for each dependency CVE whether httptap is actually affected. The source of truth is versioned in .vex/httptap.openvex.json; scanners that consume VEX (Grype, Trivy, Snyk) use it to suppress false-positive alerts on unreachable vulnerable code paths.

Users can verify a downloaded artifact independently:

gh attestation verify dist/httptap-X.Y.Z-py3-none-any.whl \
  --repo ozeranskii/httptap

Known Residual Risks¶

These are documented rather than mitigated. They represent trade-offs that are explicit rather than oversights.

• Solo maintainer. Bus factor is 1 (tracked in GOVERNANCE.md). The continuity plan mitigates single-point-of-failure for operations but not for code review: a single reviewer can merge changes without a second set of eyes. Pre-commit, CI gates, and public audit trail partly compensate.
• No runtime sandboxing. httptap executes with the user's full privileges. This is appropriate for a developer diagnostic tool but means a bug in httptap itself runs with the user's privileges.
• TLS trust anchors inherited from the OS. If the OS trust store is compromised (e.g., a corporate MITM proxy installs a private CA), httptap cannot detect this. The network.tls_custom_ca and proxy_source fields in the JSON export document whether a custom CA bundle or proxy was in use.

Change History¶

References¶

• SECURITY.md — vulnerability reporting process and supported versions.
• GOVERNANCE.md — project roles, decisions, and continuity plan.
• ROADMAP.md — scope, non-goals, and deprecation policy.
• Troubleshooting & FAQ — operational guidance.
• CWE Top 25 and OWASP ASVS 4.0 — reference catalogs of implementation weaknesses.