Caso de garantía de seguridad¶

Este documento es el caso de garantía de seguridad de httptap. Explica por qué el proyecto cree que sus propiedades de seguridad se sostienen, no solo cuáles son esas propiedades. Está estructurado conforme al criterio assurance_case del nivel plata de las OpenSSF Best Practices.

Última revisión: 2026-10-05.

El caso de garantía es un documento vivo; se revisa en cada versión mayor y siempre que el panorama de amenazas o el conjunto de funcionalidades cambie de forma material. Las propuestas de enmiendas se aceptan como pull requests contra este archivo.

Qué es httptap¶

httptap es una herramienta de diagnóstico de línea de comandos. Un desarrollador proporciona una única URL (y opcionalmente cabeceras, un cuerpo, un proxy, un paquete de CA, etc.) y httptap realiza una solicitud HTTP (o una cadena corta de redirecciones) y muestra información de tiempos por fase e información de TLS. No:

• acepta entrada de red de pares no confiables (no es un servidor);
• gestiona cuentas de usuario, sesiones ni credenciales de larga duración;
• ejecuta código remoto ni evalúa scripts proporcionados por el servidor;
• persiste secretos ni datos de usuario más allá del informe opcional --json, el archivo --har y el textfile de --prometheus;
• envía mediciones a ningún sitio que no sea el collector OTLP que el usuario indica con la opción --otlp.

Requisitos de seguridad¶

El proyecto se compromete con las siguientes propiedades de seguridad observables. Cada una se asigna a argumentos de apoyo en las secciones siguientes.

Límites de confianza¶

   ┌─────────────────────┐
   │ 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
   └─────────────────────┘

• Usuario → httptap es confiable: se asume que el usuario tiene razones legítimas para emitir cualquier solicitud dada. La validación de entrada aún rechaza URLs, métodos, tiempos de espera, etc. mal formados para prevenir errores del operador.
• httptap → red → servidor remoto no es confiable. Todos los datos que cruzan este límite se tratan como controlados por el atacante: cabeceras de respuesta, códigos de estado, valores Location, certificados TLS, cuerpos de contenido.
• httptap → salidas locales es confiable: --json escribe el informe en un archivo o en stdout, --har escribe un archivo HAR 1.2 en un archivo o en stdout, y --har y --prometheus escriben sus archivos de forma atómica (archivo temporal en el mismo directorio y después un renombrado). Las etiquetas de Prometheus solo llevan el nombre de host y el número de paso de redirección, nunca rutas ni cadenas de consulta. Los archivos se crean donde el usuario indica y los puede leer cualquiera que tenga acceso a esa ubicación.
• httptap → collector OTLP cruza la red hacia un endpoint que el usuario proporciona con --otlp (extra opcional httptap[otel]), sobre http:// o https:// según se indique. Cada paso de la solicitud se convierte en un span con spans hijos por fase, que llevan el método, el código de estado, el tamaño del cuerpo, el nombre de host, la IP del par, las versiones de HTTP y TLS y el mensaje de error de un paso fallido. Los spans nunca incluyen la URL completa (ruta, cadena de consulta, credenciales) ni ninguna cabecera. Los fallos de entrega se informan como advertencias y no cambian el código de salida.
• Canalización de compilación → PyPI / GitHub Releases es un límite de confianza independiente, asegurado mediante GitHub OIDC (sin claves de larga duración), firma con Sigstore y actions fijadas por SHA.

Modelo de amenazas¶

Las amenazas se enumeran usando las categorías STRIDE que aplican a un cliente HTTP de diagnóstico. Las amenazas fuera del alcance de un cliente (por ejemplo, la denegación de servicio del lado del servidor) se excluyen explícitamente como no objetivos.

Amenazas fuera de alcance¶

• Adversario con ejecución de código local en la máquina del desarrollador. Fuera de alcance: ese adversario ya es dueño del proceso.
• Adversario que controla el terminal / TTY del usuario. Fuera de alcance.
• Ataques criptoanalíticos contra el propio TLS. Delegados a OpenSSL; las mitigaciones se heredan de la compilación de Python del sistema.
• Amenazas poscuánticas. Rastreadas de forma ascendente (OpenSSL / Python); fuera de alcance para el propio httptap.

Principios de diseño seguro aplicados¶

Asignados a Saltzer & Schroeder (1975) más añadidos modernos.

Debilidades de implementación comunes contrarrestadas¶

Derivadas del CWE Top 25 (2023) y de OWASP ASVS 4.0. Los elementos no enumerados o bien no aplican a un cliente HTTP o se manejan de forma ascendente.

Garantía de la cadena de suministro¶

En apoyo de la propiedad de integridad de la publicación (SR-5):

• Publicación: PyPI (y TestPyPI como prueba de humo de preproducción) mediante GitHub OIDC Trusted Publishing: ningún token de PyPI de larga duración en ningún sitio. Las atestaciones PEP 740 se muestran en PyPI como "Verified publisher".
• Imágenes de contenedor: las imágenes multiarquitectura (linux/amd64, linux/arm64) se compilan con Buildx y se publican en GHCR, se firman sin claves con cosign, y van acompañadas de procedencia de compilación SLSA adjunta al registro.
• Firma de Git: los commits de publicación y las etiquetas anotadas se firman sin claves con gitsign (x.509 mediante Fulcio
• registro de transparencia Rekor), usando la identidad OIDC del flujo de trabajo de publicación.
• Firma: firma sin claves de Sigstore mediante actions/attest-build-provenance y cosign. Las claves de firma son de corta duración, emitidas por ejecución por Fulcio, y verificables mediante el registro de transparencia Rekor.
• Procedencia: una atestación SLSA v1.0 acompaña a cada wheel, sdist, y digest de imagen de contenedor.
• Linting de Dockerfile: hadolint se ejecuta en cada PR con un umbral de fallo a nivel de advertencia.
• Fijación: toda GitHub Action en todo flujo de trabajo está fijada por SHA; impuesto por Scorecard Pinned-Dependencies y zizmor pedantic en cada PR.
• Seguimiento de dependencias: se genera un SBOM en formatos CycloneDX y SPDX durante la publicación y se adjunta como asset de GitHub Release.
• Divulgación de explotabilidad: un documento OpenVEX (httptap-X.Y.Z.openvex.json) se distribuye junto al SBOM, declarando para cada CVE de dependencia si httptap está realmente afectado. La fuente de verdad está versionada en .vex/httptap.openvex.json; los escáneres que consumen VEX (Grype, Trivy, Snyk) lo usan para suprimir las alertas de falsos positivos en rutas de código vulnerable inalcanzables.

Los usuarios pueden verificar un artefacto descargado de forma independiente:

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

Riesgos residuales conocidos¶

Estos están documentados en lugar de mitigados. Representan compensaciones que son explícitas en lugar de descuidos.

• Mantenedor único. El factor bus es 1 (rastreado en GOVERNANCE.md). El plan de continuidad mitiga el punto único de fallo para las operaciones, pero no para la revisión de código: un único revisor puede fusionar cambios sin un segundo par de ojos. El pre-commit, las barreras de CI y el registro de auditoría público compensan en parte.
• Sin sandboxing en tiempo de ejecución. httptap se ejecuta con los privilegios completos del usuario. Esto es apropiado para una herramienta de diagnóstico de desarrollador, pero significa que un fallo en el propio httptap se ejecuta con los privilegios del usuario.
• Anclas de confianza TLS heredadas del SO. Si el almacén de confianza del SO está comprometido (por ejemplo, un proxy MITM corporativo instala una CA privada), httptap no puede detectarlo. Los campos network.tls_custom_ca y proxy_source en la exportación JSON documentan si se usó un paquete de CA personalizado o un proxy.

Historial de cambios¶

Referencias¶

• SECURITY.md — proceso de reporte de vulnerabilidades y versiones soportadas.
• GOVERNANCE.md — roles del proyecto, decisiones y plan de continuidad.
• ROADMAP.md — alcance, no objetivos y política de obsolescencia.
• Resolución de problemas y preguntas frecuentes — orientación operativa.
• CWE Top 25 y OWASP ASVS 4.0 — catálogos de referencia de debilidades de implementación.