feldstecher

Observe and record the behaviour of black-box systems through their HTTP API - without holding their credentials.

A Feldstecher is a pair of binoculars: you use it to watch something closely without disturbing it, and without getting close enough to be bitten. This one is meant to sit between you and an API you do not control - injecting credentials you never see, refusing to talk to any host you did not allowlist, scrubbing and recording every exchange, and tagging the test data you create so you can always tell your own tracks from the wild population.

Why

Sometimes the only documentation of an API is the API itself. Working it out means sending real requests to a real system, which raises three problems that the usual recording proxies do not solve:

• The credentials must not leak to whoever is driving the requests. That is especially true when the driver is an AI agent, but it is just as true for a shared debugging session or a CI job.
• The recordings are the deliverable, not a debug artifact. They need full bodies, query strings and timing, in a form you can reprocess offline months later.
• Writes to somebody else's system are permanent. Test data created while exploring stays there. You need it to be unique, recognisable, and written down.

feldstecher is built as a mitmproxy addon, so the proxying, TLS interception and flow persistence are handled by a mature and well-maintained tool, and feldstecher only adds the parts specific to careful observation.

What it is not

• Not a general-purpose secrets manager. It brokers credentials for observation sessions, nothing more.
• Not a mock server. It records what a system does; replaying that is a separate concern.
• Not a security boundary against a hostile process on the same machine. If the driver of the requests runs as the same user on the same host, it can read feldstecher's configuration. Isolation between the two is your job.

Development

This project uses uv and a src layout.

uv sync --group dev
uv run pytest unittests

Contributions are welcome via pull request against main.

Releases

Publishing to PyPI runs from .github/workflows/python-publish.yml on a GitHub release, using a trusted publisher rather than a token. It needs a repository environment named release, and the publisher registered on the PyPI side must name this repository and this workflow file.