Skip to main content

Phantomwire

PyPI CI Coverage

Phantomwire is a defensive-offensive cybersecurity toolkit focused on auditable operations. It offers HTTP/TLS/JWT analysis, lightweight PCAP summarisation, DNS inspection, and a plugin system for custom checks. All active operations require explicit consent to ensure safe and ethical usage.

Features

  • Unified evidence model (Target → Evidence → Finding) for consistent reporting.
  • Safe-mode with explicit consent tokens controlling network operations.
  • HTTP security header analysis, TLS certificate auditing, JWT linting, and PCAP sessionisation.
  • Reporting in JSON, Markdown, and SARIF for integration with CI pipelines.
  • Plugin framework discoverable via entry points.
  • Minimal dependencies with optional extras for advanced capabilities.

Safety Model

Phantomwire never performs active network operations unless both of the following are true:

  1. The target host is within the configured allowed scopes.
  2. The environment variable PHANTOMWIRE_CONSENT is set to I_HAVE_PERMISSION.

Use phantom --consent --allowed-scope example.org ... to opt in for the current process. Always secure evidence, keep logs, and ensure legal authorization before operating on any non-lab environment.

Installation

pip install phantomwire
# optional extras
pip install "phantomwire[web,crypto,pcap,dns]"

Quickstart

# Analyze HTTP headers
phantom --consent --allowed-scope example.com scan http https://example.com

# Audit TLS configuration
phantom --consent --allowed-scope example.com audit tls example.com:443

# Lint a JWT token
phantom jwt lint "<token>"

# Inspect a PCAP file
phantom inspect pcap sample.pcap

# Generate Markdown report
phantom --consent --allowed-scope example.com --format md --output report.md scan http https://example.com

Reporting Formats

{
  "target": {"locator": "https://example.com"},
  "findings": [
    {"id": "HTTP-H-001", "severity": "Medium", "title": "Missing strict-transport-security header"}
  ]
}
# Phantomwire Security Report

| ID | Severity | Title |
| --- | --- | --- |
| HTTP-H-001 | Medium | Missing strict-transport-security header |

SARIF output is compatible with GitHub Advanced Security and other CI systems.

CLI Overview

Run phantom --help for full usage. Top-level commands include:

  • scan http <url> — HTTP security headers.
  • audit tls <host>:<port> — TLS certificate and cipher checks.
  • jwt lint <token> — JWT claim analysis and signature verification.
  • inspect pcap <path> — Sessionize PCAP captures.
  • dns resolve <host> — Consent-gated DNS lookups.
  • plugins list|run — Discover or execute plugins.

Exit codes: 0 success, 2 when high-severity findings exist, 1 for operational errors.

Development

git clone https://github.com/thesmartshadow/phantomwire.git
cd phantomwire
pip install -e .[dev]
pre-commit install
pytest

Use python -m build to create release artifacts. Pull requests must pass ruff, mypy, and pytest on Python 3.10+.

Ethical Use

Phantomwire is designed for responsible security testing. Do not use it on systems you do not own or operate without written permission. Evidence collection is auditable and should be stored securely to prevent misuse.

License

MIT License. See LICENSE for details.

Metadata

Release files for phantomwire 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phantomwire 0.1.1
File Size Uploaded Provenance Actions
phantomwire-0.1.1.tar.gz 22.2 kB With provenance Details for phantomwire-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phantomwire 0.1.1
File Interpreter ABI Platform Actions
phantomwire-0.1.1-py3-none-any.whl Python 3 none any Details for phantomwire-0.1.1-py3-none-any.whl

Total release size: 48.2 kB

Release files / phantomwire-0.1.1.tar.gz

Download URL phantomwire-0.1.1.tar.gz
Size 22.2 kB
Tags Source
SHA-256 checksum
How to use checksums
afa7f965491804f86de300f52eaec4fb993bf7992b2113d8323d168428e36fe3
BLAKE2b-256 checksum
How to use checksums
48313b03d6c1dbe8a6cade6cef20038aa37b938f17610bd6ae0266ab05c869c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2025.

Transparency log

Release files / phantomwire-0.1.1-py3-none-any.whl

Download URL phantomwire-0.1.1-py3-none-any.whl
Size 26.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4d1637c377097cf66c16465df9f819daa82838afee38656a1287e170b0d9797a
BLAKE2b-256 checksum
How to use checksums
791d586900bfa85da560c71e68ed666dd5d8f799cbdef69bec53bd0ca98e64d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2025.

Transparency log

Security for phantomwire 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for phantomwire-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page