Metadata-Version: 2.4
Name: apisniff
Version: 0.1.2
Summary: One tool for API recon: preflight defenses, capture real traffic, extract a usable spec.
Project-URL: Homepage, https://github.com/4LAU/apisniff
Project-URL: Issues, https://github.com/4LAU/apisniff/issues
Author: Aaron Lau
License-Expression: MIT
License-File: LICENSE
Keywords: api,mitmproxy,openapi,reverse-engineering,security
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: curl-cffi>=0.7.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mitmproxy<13.0,>=12.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tldextract>=5.0
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

# apisniff

One tool for API recon: preflight defenses, capture real traffic, extract a usable spec.

[![CI](https://github.com/4LAU/apisniff/actions/workflows/ci.yml/badge.svg)](https://github.com/4LAU/apisniff/actions)
[![PyPI](https://img.shields.io/pypi/v/apisniff)](https://pypi.org/project/apisniff/)
[![Python](https://img.shields.io/pypi/pyversions/apisniff)](https://pypi.org/project/apisniff/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## What you get

- Probe a URL in 10 seconds, classify 25+ vendor products (Cloudflare, Akamai, DataDome, PerimeterX, Imperva, Kasada, and more)
- Browse a site through a local [mitmproxy](https://github.com/mitmproxy/mitmproxy) instance. Noise is filtered automatically; you keep only API calls.
- Import HAR files or Burp Suite exports for offline analysis
- Generate an OpenAPI spec from captured traffic with schema inference and example values
- Replay captured calls against the live API and see what changed
- Export safely: derived artifacts only, no raw traffic, no credentials

## Install

```bash
brew tap 4LAU/tap && brew install apisniff
# or
pip install apisniff
# or
pipx install apisniff
# or
uv tool install apisniff
```

Requires Python 3.12+.

## Quick Start

```bash
# Check what defenses a site has
apisniff probe example.com

# Capture live traffic (opens Chrome + proxy)
apisniff recon example.com

# Generate an API spec from the capture
apisniff spec example.com -o spec.yaml

# Replay captured calls to detect drift
apisniff replay example.com

# Export a safe, shareable summary
apisniff share example.com
```

## Commands

| Command | Purpose | Docs |
|---------|---------|------|
| [`probe`](docs/commands/probe.md) | Defense preflight: assess defenses, detect vendors, check rate limits | [Reference →](docs/commands/probe.md) |
| [`recon`](docs/commands/recon.md) | Capture + classify: browse through proxy, filter noise, generate report | [Reference →](docs/commands/recon.md) |
| [`analyze`](docs/commands/analyze.md) | Offline analysis: import HAR, Burp XML, or JSONL captures | [Reference →](docs/commands/analyze.md) |
| [`replay`](docs/commands/replay.md) | Replay captured calls and detect API drift | [Reference →](docs/commands/replay.md) |
| [`spec`](docs/commands/spec.md) | Generate OpenAPI 3.0.3 from captured traffic | [Reference →](docs/commands/spec.md) |
| [`share`](docs/commands/share.md) | Export shareable summary (no raw traffic, no credentials) | [Reference →](docs/commands/share.md) |

Every command supports `--help` for full flag documentation. See the [CLI spec](docs/spec.md) for output format contracts and conventions.

## Guides

- [Getting started](docs/guides/getting-started.md): install to API map in 5 minutes
- [Workflow recipes](docs/guides/workflows.md): map an API, check for drift, compare defenses
- [Capture formats](docs/guides/capture-formats.md): HAR, Burp XML, JSONL explained

## Important Warnings

Only run apisniff against systems you own, administer, or have explicit permission to test. The tool is built for API discovery and debugging, but it sends real requests and can capture sensitive session data.

### Your IP address is exposed

**This tool sends real HTTP requests from your IP.** Aggressive or repeated probing can get you rate-limited or blocked. `apisniff probe rate` fires 20 rapid requests, so use it deliberately. Route through `--proxy` if you don't want to expose your IP.

Results reflect your IP's reputation. Residential IPs see fewer challenges than datacenter/cloud IPs. Use `--proxy` to compare results from different vantage points.

### Capture files contain sensitive data

`recon` and `analyze` capture **full HTTP traffic** including cookies, auth tokens, API keys, and form submissions. Raw bundles are stored locally with owner-only permissions and are **never safe to share, commit, or upload**.

Use `apisniff share` to create a safe export with only derived artifacts.

### Why recon needs the mitmproxy certificate

`apisniff recon` uses [mitmproxy](https://github.com/mitmproxy/mitmproxy), an open source SSL/TLS-capable intercepting proxy for HTTP/1, HTTP/2, and WebSockets. apisniff starts it locally, opens Chrome with that local proxy configured, then records the HTTP flows that pass through it.

HTTPS is encrypted between the browser and the origin server, so a proxy cannot read request paths, JSON bodies, headers, or responses unless the browser trusts the proxy during the TLS handshake. mitmproxy solves this by creating a local certificate authority the first time it runs, stored under `~/.mitmproxy`, and generating site certificates on the fly for the domains you visit. Installing or trusting that CA certificate tells the browser: "for this local capture session, allow this proxy to inspect HTTPS traffic."

Treat the certificate like sensitive local configuration. A trusted CA can decrypt proxied HTTPS traffic, so only install the mitmproxy CA on machines and browser profiles you control. apisniff uses a local proxy on `127.0.0.1` and launches Chrome with `--proxy-server=http://127.0.0.1:8080`; regular browsing and apps are unaffected unless you route them through that proxy. If Chrome shows certificate warnings, start `apisniff recon`, open `http://mitm.it` in the proxied Chrome window, and follow mitmproxy's platform-specific certificate instructions.

More detail: [mitmproxy certificate docs](https://docs.mitmproxy.org/stable/concepts/certificates/) and [how mitmproxy works](https://docs.mitmproxy.org/stable/concepts/how-mitmproxy-works/).

## What to do with the spec

```bash
# Generate a client library
openapi-generator generate -i spec.yaml -g python -o client/

# Import into Postman: File → Import → select spec.yaml

# Feed to an LLM
cat spec.yaml | llm "write a Python client for this API"
```

## Development

```bash
git clone https://github.com/4LAU/apisniff.git
cd apisniff
uv sync --dev
uv run pytest tests/ -v
uv run ruff check .
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the local development workflow and [SECURITY.md](SECURITY.md) for vulnerability reporting.

To regenerate command reference docs after changing CLI flags:

```bash
uv run python scripts/generate_command_docs.py
```

## License

MIT
