Skip to content
Back to search

dyetrace

Black-box tracer for authorized testing: plants signed tracers in web inputs to find leaks; proves SSRF in MCP servers

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/beardthelion--dyetrace/badge.svg)](/listings/beardthelion--dyetrace)

HTML

<a href="/listings/beardthelion--dyetrace"><img src="/api/listings/beardthelion--dyetrace/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Python 3.10 or newer. The core depends only on `httpx`; egress mode needs the `mcp` extra.

git clone https://github.com/beardthelion/dyetrace
cd dyetrace
pip install -e .            # black-box and OSS modes
pip install -e '.[mcp]'     # adds egress mode
pip install -e '.[dev]'     # adds pytest
dyetrace --help
dyetrace egress --help

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 468 lines
  1. # dyetrace
  2. Black-box dataflow tracer for authorized security testing. It plants unique, signed tracer strings into the inputs of a recorded web session, replays the session, and reports every place a tracer shows up again. A tracer that resurfaces somewhere it should not, such as another user's view or an unescaped HTML context, is the finding.
  3. A second mode, `dyetrace egress`, proves server-side request forgery in MCP servers: it calls a URL-taking tool with a tracer URL that points at a listener you control and records whether the server fetched it.
  4. Only use it against systems you are authorized to test.
  5. ## Why
  6. Source-level taint tools cannot follow data through an application you do not have the code for, and stored, second-order and cross-identity leaks are the cases static scans miss. dyetrace treats the app as a closed system: put a dye in every input, drive the app, and watch where the dye comes out. Each tracer is HMAC-signed per run (`DYE-<run_id>-<entry_id>-<nonce>-<mac>`), so a hit is authenticated rather than guessed, and the `entry_id` names the request and field it came from.
  7. ## Modes
  8. | Mode | Input | Question it answers |
  9. |---|---|---|
  10. | black-box (default) | a recorded session JSON | Where does each input resurface, and does it come back unescaped or under another identity? |
  11. | OSS (`--candidates`) | session JSON plus static candidates | Does this specific static finding actually flow at runtime? |
  12. | egress (`dyetrace egress`) | an MCP server plus SSRF candidates | Does this URL-taking tool make the server fetch an attacker-chosen URL? |
  13. ## Install
  14. Python 3.10 or newer. The core depends only on `httpx`; egress mode needs the `mcp` extra.
  15. ```bash
  16. git clone https://github.com/beardthelion/dyetrace
  17. cd dyetrace
  18. pip install -e . # black-box and OSS modes
  19. pip install -e '.[mcp]' # adds egress mode
  20. pip install -e '.[dev]' # adds pytest
  21. dyetrace --help
  22. dyetrace egress --help
  23. ```
  24. ## Black-box mode
  25. ### Session file
  26. A session is the recorded, authenticated traffic to replay:
  27. ```json
  28. {
  29. "version": "1",
  30. "cookies": {},
  31. "auth_headers": {"authorization": "Bearer ..."},
  32. "base_url": "https://app.example.com",
  33. "recorded_requests": [
  34. {"method": "GET", "url": "https://app.example.com/set?name=bob"},
  35. {"method": "GET", "url": "https://app.example.com/profile"}
  36. ]
  37. }
  38. ```
  39. Requests can also carry `headers` and a `body` (form, JSON or multipart). `tools/session_from_har.py` builds this file from a HAR capture (see below). Cookie and auth header values are masked as `***` in all output.
  40. ### Run
  41. ```bash
  42. dyetrace --session session.json --host app.example.com
  43. dyetrace --session session.json --second-session admin.json --host app.example.com --output html --out report.html
  44. ```
  45. The tool plants a tracer into every writable leaf (query and form fields, JSON values, path segments, custom headers, multipart values and filenames), in a raw form and in HTML-breaking, JS-string-breaking and attribute-breaking variants. It then re-drives the recorded read requests, under the second identity too when one is given, and checks every response body and header value.
  46. Safety defaults:
  47. - Only the exact `--host` is contacted. Loopback targets need `--allow-loopback` and plain HTTP needs `--allow-cleartext`; private, link-local and metadata addresses are always refused.
  48. - Recorded requests with any method other than GET or HEAD are not planted unless you pass `--confirm-mutating`, and are never re-driven as reads. `--post-read INDEX` marks a recorded POST as a read surface, and `--exclude INDEX` skips a request.
  49. - Requests are rate-limited (`--rate`, default 2 per second). `--raw-only` plants only the raw tracer.
  50. ### Output
  51. `--output terminal` (default), `html` or `json`. Each report has:
  52. - a flow table, one row per resurfacing: entry, source request and field, sink URL, identity, encoding variant, whether it crossed identities, severity (`tracked`, `injection-candidate`, `cross-context`), and the matched snippet
  53. - a findings list of the `injection-candidate` and `cross-context` rows with the request pair that reproduces them
  54. - a summary line with four separate outcome counts: `resurfaced`, `never` (never seen again), `noise` (a tracer-shaped string that failed signature checks) and `plant_rejected` (the plant itself failed, so silence means nothing)
  55. Example against a local page that stores and echoes a `name` query value without escaping:
  56. ```
  57. $ dyetrace --session session.json --host 127.0.0.1 --allow-loopback --allow-cleartext
  58. dyetrace flow table
  59. entry_id | source | sink_url | sink_identity | encoding | cross_context | severity | snippet
  60. 0 | GET http://127.0.0.1:8765/set?name=*** [query:name] | http://127.0.0.1:8765/set?name=*** | 1 | raw | False | tracked | DYE-f528...
  61. 0 | GET http://127.0.0.1:8765/set?name=*** [query:name] | http://127.0.0.1:8765/set?name=*** | 1 | html | False | injection-candidate | "><dye t=DYE-f528...>
  62. ...
  63. summary: verified leaks found: resurfaced=1, universe=3, never=2, noise=0, plant_rejected=0
  64. ```
  65. Exit codes: `0` when the run completed (with or without hits), `2` when it stopped fail-closed, for example on an invalid session, a forbidden host, or a session with nothing to plant. Read the summary line, not the exit code, to tell a clean run from a stop.
  66. ## OSS mode (dye-OSS)
  67. `--candidates` consumes a `candidates.json` from jevsec, a static taint scanner that is not public yet, and turns each static
  68. candidate into a runtime verdict: the tracer is planted only at the requests
  69. the candidate's source maps to, and a hit at the predicted surface proves the
  70. flow.
  71. ```bash
  72. dyetrace --session session.json --host app.example.com \
  73. --candidates runs/<run-id>/candidates.json
  74. ```
  75. Each candidate gets a verdict: `PROVEN` (tracer surfaced at the predicted
  76. surface), `new_flow` (surfaced elsewhere), `KILL` (executed, never surfaced),
  77. `unexercised` (plants never reached the handler), or `unmapable` (no
  78. guess-free map exists). Gate submission on `verdict == "PROVEN"`.
  79. ### Operator binds
  80. Candidates whose entry kind has no HTTP field (`exported`, `cli-handler`,
  81. `consumer`, `module-init`) stay `unmapable` unless bound explicitly:
  82. ```bash
  83. dyetrace --session session.json --host app.example.com \
  84. --candidates candidates.json --binds binds.json
  85. ```
  86. ```json
  87. {
  88. "cand-abc123": {
  89. "request_index": 4,
  90. "path_id": "query:q",
  91. "predicted": "propagate:7"
  92. }
  93. }
  94. ```
  95. `request_index` names the recorded request to plant; `path_id` restricts the
  96. plant to one leaf, using the same ids the plant layer emits:
  97. | site | path_id shape | example |
  98. | --- | --- | --- |
  99. | query / form leaf | `query:<key>` / `form:<key>` (dup keys get `[i]`) | `query:q`, `query:id[1]` |
  100. | path segment | `path:<route with {segN}>` | `path:/api/items/{seg1}/action` |
  101. | header | `header:<name>` | `header:x-target` |
  102. | JSON body leaf | `json:$<.key | [i] path>` | `json:$.user.name` |
  103. | multipart | `multipart:<name>.value` / `.filename` | `multipart:file.value` |
  104. `predicted` names where a resurfacing tracer proves the
  105. flow: `plant` (default: the candidate's own executed plant response body),
  106. `propagate:<index>` (the unplanted replay of recorded request `<index>`, for
  107. stored-then-reflected sinks), or `identity:<n>` (any observation under
  108. identity `<n>`). `--predicted-surface` sets the default for all candidates
  109. and per-candidate binds override it. Binds fail closed on unknown candidate
  110. ids, out-of-range indexes, or malformed JSON.
  111. ### Loopback harnesses
  112. `--allow-loopback` permits loopback target addresses (127.0.0.0/8, ::1) for
  113. local harness runs; it is off by default and every other forbidden range
  114. (private, link-local, metadata IPs) stays blocked. Plain HTTP still needs
  115. `--allow-cleartext`. Session `auth_headers` is the place for the bearer or
  116. cookie tokens the recorded session ran under.
  117. ### Mount prefixes and runs dirs
  118. `--route-prefix PREFIX` (repeatable) joins an operator-asserted mount prefix
  119. onto route details during matching: a `get /x` candidate maps a recorded
  120. `/api/x` under `--route-prefix /api`. Prefixes only join; nothing is
  121. discovered or stripped, and unmatched routes stay `unmapable`.
  122. `--candidates` also accepts a jevsec run dir, or a runs root holding exactly
  123. one run dir (the pick is printed on stderr). A runs root with several run
  124. dirs fails with a numbered list; pass one explicitly.
  125. ### Building the session
  126. `tools/session_from_har.py` converts a HAR capture into session JSON. It
  127. accepts loopback captures only (localhost / 127.x / ::1) unless
  128. `--allow-remote` is set:
  129. ```bash
  130. python tools/session_from_har.py capture.har -o session.json
  131. ```
  132. ### The full loop
  133. ```bash
  134. # a jevsec run prints its candidates path; feed it straight to dye-OSS
  135. python tools/session_from_har.py capture.har -o session.json
  136. dyetrace --session session.json --host app.example.com \
  137. --candidates <runs>/candidates.json --binds binds.json \
  138. --route-prefix /api --output json --out verdicts.json
  139. # gate submit only on verdict == "PROVEN"
  140. ```
  141. ## Egress prover mode
  142. `dyetrace egress` checks whether an MCP server's URL-taking tool makes the
  143. server fetch from inside the environment it runs in. For each static candidate
  144. (a URL-fetching handler found by `ssrf-guard-audit`, or a lead from
  145. `egress-plane`), it calls the matching tool with a URL argument that carries a
  146. fresh tracer and points at a listener you control. A request that reaches the
  147. listener with a verified tracer, attributed to that candidate's own call, is the
  148. proof. For authorized testing only, against servers you have the right to test.
  149. It is a separate subcommand. The black-box and OSS modes are unchanged.
  150. ### Install
  151. The MCP client SDK is an optional extra; the core install still needs only
  152. `httpx`.
  153. ```bash
  154. pip install 'dyetrace[mcp]'
  155. ```
  156. Without it, a run stops before spawning anything and prints this install line.
  157. ### Flags
  158. | flag | meaning |
  159. | --- | --- |
  160. | `--candidates FILE` | saved candidates file (required) |
  161. | `--candidates-format` | `normalized` (default), `ssrf-guard-audit` or `egress-plane` |
  162. | `--binds FILE` | operator binds: candidate id to tool, argument, optional static `arguments` |
  163. | `--target FILE` | operator target config JSON: stdio command or HTTP URL (required) |
  164. | `--listen HOST:PORT` | listener bind, an IP literal (default `127.0.0.1:0`; a real run needs a nonzero port) |
  165. | `--advertise URL` | http base URL the target is told to fetch; carries its own nonzero port |
  166. | `--allow-exposed-bind` | permit a non-loopback or wildcard listener bind |
  167. | `--allow-local-advertise` | permit a loopback or private advertised address |
  168. | `--redirect-hop URL` | 302 every well-formed request to this base URL on the `--listen` port; a tracer that resurfaces there proves the redirect hop was fetched without re-validation |
  169. | `--attest-listener-reachable NOTE` | operator note that the target can reach the listener; recorded verbatim, unverified; required for any KILL |
  170. | `--settle SECONDS` | wait for the token after each call (default 5) |
  171. | `--drain SECONDS` | final wait for late fetches (default 5) |
  172. | `--call-timeout SECONDS` | per-call timeout (default 30) |
  173. | `--rate N` | calls per second (default 1.0) |
  174. | `--max-calls N` | call-count cap, checked before any send (default 500) |
  175. | `--target-commit TEXT` | target commit or version, recorded verbatim in the report |
  176. | `--allow-cleartext` | permit a plain `http` MCP target (HTTP target only) |
  177. | `--allow-loopback` | permit a loopback MCP target (HTTP target only) |
  178. | `--output` | `terminal` (default), `html` or `json` |
  179. | `--out FILE` | write the report to a file instead of stdout |
  180. ### Worked example: a stdio server
  181. The target config names the command to spawn. It is operator input only: a
  182. list, never a shell string, and nothing from the candidates file or the
  183. server's output ever reaches it. The child gets only the SDK's default
  184. environment (`HOME`, `PATH`, and a few more), your `env` map, and any names
  185. listed in `env_passthrough`. `cwd` is optional.
  186. `target.json`:
  187. ```json
  188. {
  189. "transport": "stdio",
  190. "command": ["python", "server.py"],
  191. "env": {"LOG_LEVEL": "warning"},
  192. "env_passthrough": ["API_BASE"]
  193. }
  194. ```
  195. For an HTTP server use `{"transport": "http", "url": "https://mcp.example.com/mcp"}`.
  196. Those requests go through the same host allowlist, pinned-address, byte-cap and
  197. recheck rules as the other modes, so `--allow-loopback` and `--allow-cleartext`
  198. apply to them. Only streamable HTTP is supported.
  199. `candidates.json` comes from a saved scan:
  200. ```bash
  201. ssrf-guard-audit scan --json ./server > scan.json
  202. egress-plane scan --format json ./server > scan.json # or this one
  203. ```
  204. Pass it with `--candidates-format ssrf-guard-audit` or `egress-plane`. The
  205. adapters read the saved file; they never run either tool. You can also write the
  206. normalized form by hand (`"version": 1`, a `candidates` array; each entry needs
  207. `id`, `source_tool`, `source_version`, `file`, `start_line`, `end_line`;
  208. optional keys are `symbol` (null allowed; without it the candidate maps only via
  209. `tool_name` or a bind), `site_label`, `param_names`, `params_truncated`, `sinks`
  210. (a list of `file` and `line` objects), `guard_classes`, `destination_kind`,
  211. `lead`, `tool_name` and `arg_name`; unknown keys are ignored).
  212. A candidate is mapped to a tool and argument only when exactly one live tool
  213. name equals the candidate's symbol and exactly one string argument matches a
  214. parameter name. Neither scanner records MCP tool names, so most candidates
  215. need a bind. `binds.json`:
  216. ```json
  217. {
  218. "cand-abc123": {
  219. "tool": "proxy_fetch",
  220. "argument": "callback_url",
  221. "arguments": {"url": "https://example.com"}
  222. }
  223. }
  224. ```
  225. `argument` receives the tracer URL; `arguments` are static values for the
  226. tool's other required arguments (a tool whose required arguments are not all
  227. covered is `unmapable`). A bind naming a tool or argument that is not in the
  228. server's live `tools/list` stops the run before anything is sent.
  229. For tools whose URL sits inside a nested or union-typed argument (for
  230. example `{"action": {"type": "introspect", "endpoint": ...}}`), omit
  231. `argument` and place exactly one `{url}` placeholder in `arguments` instead;
  232. the tracer URL is substituted into that leaf and the placeholder's dotted
  233. path is recorded as the argument. A bind may not mix `argument` and `{url}`.
  234. The listener port contract: `--advertise` carries its own explicit port, and
  235. `--listen` must bind that exact port. A missing port, port 0 or a mismatch is a
  236. stop. Behind NAT or a container the two addresses differ, which is why they are
  237. separate flags.
  238. ```bash
  239. dyetrace egress \
  240. --candidates scan.json --candidates-format ssrf-guard-audit \
  241. --binds binds.json --target target.json \
  242. --listen 0.0.0.0:8099 --allow-exposed-bind \
  243. --advertise http://canary.corp.example:8099 \
  244. --attest-listener-reachable "egress-plane probe from target host reached 10.0.4.7:8099, 2026-10-27" \
  245. --target-commit 3f2a9c1 --output json --out egress.json
  246. ```
  247. For a local harness run (loopback only, so KILL is not available):
  248. ```bash
  249. dyetrace egress --candidates candidates.json --binds binds.json \
  250. --target target.json \
  251. --listen 127.0.0.1:8099 --advertise http://127.0.0.1:8099 \
  252. --allow-local-advertise
  253. ```
  254. Without `--advertise`, the advertised URL is derived from the address the
  255. listener bound, under the same rules.
  256. ### Redirect-hop mode
  257. `--redirect-hop URL` turns the listener into a two-hop harness. Any request
  258. whose `Host` does not already name the redirect authority gets a `302` to
  259. `URL` plus the request-target (the tracer path rides along); a request that
  260. does gets the usual empty 200, so one listener serves both hops with no loop.
  261. The redirect URL is validated like `--advertise` and must carry the `--listen`
  262. port. An arrival whose `Host` matches the redirect authority is marked
  263. `via_redirect` in the report: it could only have arrived by following the
  264. 302. Pair it with a control run showing the same address refused when asked
  265. directly and the evidence is a missing redirect re-validation (the G6 shape:
  266. hop 0 passes the guard, hop 1 does not get checked).
  267. ### Verdicts and exit codes
  268. The same five names as OSS mode, with these definitions:
  269. - `PROVEN`: a request reached the listener whose path carries a tracer that
  270. verifies for this run and maps, through the driver's own send record, to this
  271. candidate's call. Status codes, tool result text (even one that echoes the
  272. token), unverified requests, and tokens in a header or query never count.
  273. - `new_flow`: a verified arrival from a call to the same tool but a different
  274. argument than the candidate predicted. The note names the argument that was
  275. fetched.
  276. - `KILL`: the call returned without error, nothing arrived, and every
  277. condition for trusting that silence held: a settle window of at least 2 s, an
  278. operator reachability attestation, a healthy listener, no refused or
  279. deadline-closed connections or unattributed arrivals in the window, no
  280. silently closed (oversize, malformed or truncated) request heads and no
  281. unverified arrival carrying this run's prefix anywhere in the run (not only in
  282. the window), and a public-class advertised URL. A single such stray request
  283. (including scanner traffic on a public listener) therefore turns every
  284. would-be KILL into `unexercised` with `unattributed_arrival`.
  285. - `unexercised`: the call was not made, or failed (tool error, transport error,
  286. timeout, invalid params), or the conditions for KILL did not hold. The reasons
  287. are joined with `+`: `settle_window_too_short`,
  288. `listener_reachability_unconfirmed`, `listener_saturated`,
  289. `unattributed_arrival`, `local_class_only_no_arrival`,
  290. `address_class_unknown`, `tool_error`, `transport_error`, `timeout`,
  291. `server_rejected_input`, `not_called`, `listener_failed`, `run_incomplete`.
  292. - `unmapable`: no guess-free map to a tool and argument exists. Supply a bind.
  293. A guard that refuses loopback and private targets but still fetches public
  294. hosts is the common SSRF fix. A silent probe against a loopback or private
  295. canary therefore cannot clear a path, and gets `local_class_only_no_arrival`.
  296. Only a public-class advertised URL can produce KILL.
  297. Exit codes: `0` when the run completed and every candidate was exercised
  298. (PROVEN, new_flow or KILL); `3` when it completed with any `unmapable` or
  299. `unexercised` candidate, or when nothing mapped; `2` for every stop and for an
  300. incomplete run (the INCOMPLETE report is still written). A stop prints
  301. `dyetrace: stopped: <reason>` on stderr. The JSON report carries a `coverage`
  302. block with counts per verdict and the fraction exercised; do not read exit 0 as
  303. clearance.
  304. ### Safety rules
  305. - The listener binds `127.0.0.1` by default. Any other bind, wildcard included,
  306. needs `--allow-exposed-bind`. Bind hosts must be IP literals.
  307. - A loopback, private, ULA or CGNAT advertised address needs
  308. `--allow-local-advertise`. Cloud metadata and special addresses are refused
  309. with or without opt-ins (`169.254.0.0/16`, `fe80::/10`, `fd00:ec2::254`,
  310. `100.100.100.200`, `168.63.129.16`, and other special-purpose ranges).
  311. Embedded-IPv4 forms are canonicalized first, and non-canonical numeric hosts
  312. (decimal, hex, octal, short forms) are refused.
  313. - The advertised URL is validated before any socket opens or any tool is called.
  314. It must be `http`: the listener has no TLS, and an `https` URL is refused with
  315. its own error. No userinfo, fragment, query or whitespace, so no credentials
  316. go in the URL.
  317. - The listener answers every request with an empty 200 and closes the
  318. connection. It bounds head size, head time, body bytes, concurrent
  319. connections and retained records, and counts what it drops.
  320. - The stdio command comes from the target config only. Dyetrace never dials the
  321. model-chosen URL; it only hands it to the tool.
  322. - Calls are rate-limited (`--rate`), capped (`--max-calls`) and time-limited
  323. (`--call-timeout`). Tracers are inert identifiers; nothing is extracted.
  324. ### What a result does and does not mean
  325. `PROVEN` means the tracer URL reached the listener after that call. It does not
  326. show that the tool handler made the request itself: something else in the
  327. server's stack, or on the same host, could have fetched it. The report gives
  328. the call, the token, and each arrival's source address, time and order so you
  329. can judge that.
  330. `KILL` means no arrival was observed in this harness. It does not mean the path
  331. is safe. The reachability attestation is your assertion, recorded verbatim and
  332. labeled operator-asserted and unverified, with the advertised host:port and the
  333. bound port beside it so a stale note is visible. A tool that raises on a refused
  334. target ends as `unexercised` (`tool_error`), not KILL.
  335. A path that is not reported is not cleared. The candidates come from static
  336. scans, and this mode only tests what they name.
  337. Named limits:
  338. - Dyetrace's own outbound checks (HTTP target) resolve the host and then the
  339. transport re-resolves when it dials, so a DNS rebind in that window is not
  340. closed. The stdio leg dials nothing.
  341. - A fetch that happens after the drain window is missed. Raise `--settle` and
  342. `--drain` for slow or queued tools.
  343. - A network observer who sees the tracer URL can replay it during the run. Each
  344. arrival records source address, time and order; tokens are not bound to a
  345. source.
  346. - A tracer that appears in the target's logs is not detected here; use a log
  347. scanner on the target side.
  348. - Candidate-derived text and the target's stderr can contain bidi or escape
  349. characters. They are neutralized in terminal output by the existing report
  350. helper; treat the HTML and JSON surfaces as untrusted input to whatever reads
  351. them next.
  352. - Only `http` is exercised. Tools that require `https` are untested.
  353. ## Tests
  354. ```bash
  355. pip install -e '.[dev]'
  356. pytest -q
  357. ```
  358. The suite includes end-to-end runs against local fixture servers, including an MCP fixture server for egress mode.
  359. ## Limitations
  360. - HTTP only. No WebSocket, gRPC, email or PDF sinks are watched; only response bodies and header values of replayed requests.
  361. - A tracer that lands in logs, queues or out-of-band channels is not seen.
  362. - Coverage is limited to what the recorded session exercises. Pages the session never visits are not checked.
  363. - Black-box mode does not crawl or discover new endpoints.
  364. Design notes: [SPEC.md](SPEC.md) (black-box mode) and [SPEC-OSS.md](SPEC-OSS.md) (candidate-driven mode).
  365. ## Related tools
  366. - [ssrf-guard-audit](https://github.com/beardthelion/ssrf-guard-audit) and [mcp-ssrf-audit](https://github.com/beardthelion/mcp-ssrf-audit): static SSRF scans whose output egress mode can prove at runtime
  367. - [egress-plane](https://github.com/beardthelion/egress-plane): outbound-call inventory, also accepted as egress-mode candidates
  368. - [autocatalytic-harness](https://github.com/beardthelion/autocatalytic-harness): the audit harness that uses dyetrace as a runtime proof step
  369. ## License
  370. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.