Fissuredocumentation v5.3.1
On this page

04 - Network core and the intercepting proxy

Fissure is a Linux desktop web-security toolkit in C99, built on the Nilorea library and using the same stack as the Hook API client (Allegro 5 + N_GUI + n_network + OpenSSL + zlib + PCRE2). This document designs Fissure's networking core and its intercepting HTTPS proxy, the centerpiece of the tool.

Sibling docs:

Design principle: do not reinvent the request engine. Fissure vendors/forks Hook's transport core (native n_network engine; Hook's optional curl backend is not ported) and builds the proxy, scanner, repeater/intruder, and reporting on top. The only genuinely new infrastructure is per-host TLS certificate minting (a blocking nilorea gap, see section 8).


1. Network audit: Hook (condensed)

Hook is the closest architectural sibling. Full detail in audits/HOOK_AUDIT.md sections 3 (network usage + curl backend) and 4 (threading). Summary of what Fissure reuses.

1.1 Native engine (hook_request.c) over n_network

Hook drives a single request through n_network with these calls:

Phase n_network calls
URL parse N_URL + n_url_parse
TCP connect netw_connect_to(netw, host, port, timeout_ms) (non-blocking connect + select; records connect_dns_usec / connect_tcp_usec)
TLS connect netw_ssl_connect_client(netw, host, sni), netw_ssl_connect_client_to(..., timeout_ms), netw_ssl_do_handshake(netw, sni)
TLS config netw_ssl_set_ca(netw, ca, NULL), netw_ssl_set_client_cert(netw, cert, key) (mTLS), netw_ssl_set_verify(netw, flag)
Send netw_send_data
Receive netw_recv_data and the internal netw_read_all, which frames the HTTP/1.x response and stops as soon as it is complete (all body bytes per Content-Length, the terminating zero chunk for Transfer-Encoding: chunked, or just the headers for a bodyless response: HEAD, 1xx, 204, 304). Only when neither framing header is present (HTTP/1.0-style delimiting) does it read until the peer closes, so a server that keeps the connection open despite Connection: close no longer stalls the read until the timeout. It still detects EAGAIN/EWOULDBLOCK on plain sockets and SSL_ERROR_WANT_READ/SSL_ERROR_SYSCALL on TLS to report "Request timed out after N ms" on a genuine stall rather than a misleading empty body
Close netw_close

TLS file handling (hook_ssl.c): probes system CA bundles at startup (Linux candidate paths + SSL_CERT_FILE; Windows ROOT store via CryptoAPI), supports a custom CA and per-request overrides, and pre-flights cert/key/CA file readability before calling n_network so failures surface in the in-app log instead of only on stderr (n_network's netw_ssl_print_errors drains the OpenSSL error queue).

Proxy support (native): n_proxy_cfg_parse, then per scheme n_proxy_connect_tunnel (HTTP CONNECT for HTTPS-via-HTTP-proxy), n_proxy_connect_tunnel_ssl (TLS CONNECT for HTTPS proxy), n_proxy_connect_socks5 (SOCKS5 handshake), n_proxy_cfg_free. Plain HTTP-via-HTTP-proxy uses absolute-URI rewrite. Auth via user:pass in the proxy URL becomes Proxy-Authorization Basic or SOCKS5 sub-negotiation. A no_proxy list (exact host, .suffix, *) bypasses.

Timeouts: overall request timeout via SO_RCVTIMEO/SO_SNDTIMEO (_set_sock_timeout, armed on every connect path); connect timeout via the _to connect variants.

1.2 curl backend (hook_curl.c)

Hook does NOT link libcurl. With use_curl_backend set it shells out to the curl binary. hook_curl_build_command emits: -X method, -H headers, --data-raw/-F, TLS flags (--insecure / --cacert / --cert / --key), auth (--digest, -u), proxy (--proxy / --noproxy, plus --noproxy "*" when none is set to dodge Windows WPAD delays), redirects (-L / --max-redirs), timeouts (--max-time / --connect-timeout), -A user-agent, --compressed, and a -w timing line (a sentinel followed by %{time_*} fields). Quoting is via SHELL_Q + _shell_escape (single quotes on sh, double quotes + % escaping on cmd.exe); the -w format is embedded raw (not shell-escaped, because % and {} must reach curl) with % doubled because the builder uses printf-family nstrprintf_cat. The subprocess is launched via hook_popen_detached, which forks /bin/sh -c "..." and calls setsid() in the child so curl survives the launching terminal closing; a single static pid is tracked because Hook serializes curl execution through one worker.

1.3 Cancellation (hook_cancel.c, both backends)

Process-global cancel token (Hook runs one request at a time). hook_cancel_begin / _trigger / _requested, hook_cancel_native_arm / _disarm. Native: arms netw->link.sock; Cancel calls shutdown(SHUT_RDWR) to break a blocking recv (same interrupt pattern as SSE/WS). curl: SIGTERM to the session pgrp then the pid. Arming after a cancel was already requested shuts the socket down immediately (closes the cancel-before-connect race); disarm runs before netw_close so a late trigger never shutdown()s a reused fd.

1.4 Timing (HOOK_TIMING)

One backend-agnostic struct stored by value in the response: prepare/dns/tcp/ssl/wait/download/process microseconds + total. Native uses N_TIME checkpoints plus the connect dns/tcp usec recorded in NETWORK; curl parses the -w line and computes segment deltas. Fissure keeps this for the per-request timeline shown in the proxy/repeater UI and the report.


2. Network audit: Nilorea n_network (condensed)

Full detail in audits/NILOREA_AUDIT.md section 2 (networking deep-dive), 5A (MITM gaps), 5E (HTTP body helpers). Summary of what exists in n_network.h/.c that Fissure builds on.

Capability n_network surface
Client connect netw_connect / _to / _ex / _ex_to (timeout, IP version, records dns/tcp usec)
TLS client netw_ssl_connect_client / _to, netw_ssl_do_handshake(netw, sni)
Listen / accept netw_make_listening(netw, addr, port, nbpending, ip_version), netw_accept_from / _ex / netw_accept_nonblock_from
Server-side TLS EXISTS: when the listening socket has a cert/key via netw_set_crypto, netw_accept_from_ex internally calls SSL_accept()
Cert management netw_set_crypto(netw, key_file, cert_file), netw_set_crypto_pem(netw, key_pem, cert_pem) (in-memory), netw_set_crypto_chain / _chain_pem, netw_ssl_set_ca, netw_ssl_set_verify, netw_ssl_set_client_cert
Send / recv blocking send_data/recv_data, SSL send_ssl_data/recv_ssl_data; non-blocking _once variants (NETW_IO_WANT_READ/WANT_WRITE); UDP variants
Non-blocking IO / epoll _once variants + n_reactor_new/register/run (Linux/Android epoll)
URL / HTTP n_url_parse/_build/_free, n_url_encode/_decode, netw_extract_http_request_type, netw_extract_http_info, netw_get_url_from_http_request, netw_parse_post_data, netw_guess_http_content_type, netw_get_http_status_message, netw_get_http_date, netw_build_http_response
Proxy n_proxy_cfg_parse, n_proxy_connect_tunnel (HTTP CONNECT), n_proxy_connect_tunnel_ssl (TLS CONNECT), n_proxy_connect_socks5
Higher protocols WebSocket n_ws_connect/send/recv/close/conn_free (RFC 6455), SSE n_sse_connect/stop/conn_free, mock HTTP server n_mock_server_*
Errors per-conn ring n_netw_get_error_count/get_error/clear_errors

2.1 The MITM gap (closed)

Server-side TLS originally served the same certificate for every inbound connection: nilorea had no per-host leaf minting, no X.509 / keypair / CA-signing helpers, and no way to read the client's SNI on accept. That was the blocking gap for transparent HTTPS interception, because a browser expects a certificate whose CN/SAN matches the host it asked for.

The gap is closed upstream in nilorea (cross-ref audits/NILOREA_AUDIT.md section 5A), and Fissure uses the additions (section 5):

Area nilorea API
X.509 (n_x509.h) n_x509_keypair_pem, n_x509_generate_ca, n_x509_mint_host_cert
Accept-side SNI (n_network.h) netw_sni_pick_cb, netw_ssl_get_sni, netw_set_crypto_pem_ctx, netw_accept_ssl_with_sni_cb
TLS upgrade of an accepted socket (n_network.h) netw_ssl_server_handshake, netw_ssl_server_handshake_ex (with an ALPN offer)

3. Fissure transport core design

Fissure forks the following from Hook as standalone modules (there is no separate fissure_transport subsystem; the modules below are the transport core). These are business-logic-light, infrastructure-heavy modules; forking (rather than depending on a Hook build) keeps Fissure self-contained and lets it extend the request struct with capture metadata.

Forked from Hook Fissure module Role
hook_request.c (native engine) fissure_engine.c (+ fissure_request.{c,h}) one request -> one response over n_network; also routes through an upstream proxy (section 8.1)
hook_response.{c,h} + HOOK_TIMING fissure_response.{c,h} response model + timing struct
hook_ssl.c fissure_tls.c system CA probe, custom CA, mTLS, file pre-flight
hook_cancel.c fissure_cancel.c cooperative cancel via socket shutdown, scoped to the calling thread so one tool's Cancel cannot abort another's requests (the proxy does not use it, see 6)
cookie jar fissure_cookiejar.c the process-global shared N_COOKIE_JAR the engine, Repeater and scanner consult
request auth (Basic / Bearer / API key) fissure_engine.c applied from the request's auth_* fields (fissure_auth.c is a different module: it verifies a target's configured login without running a scan)

Upstream chaining has no module of its own: the engine (fissure_engine.c) and the proxy (fissure_proxy.c) each call the nilorea n_proxy_* helpers. The proxy history is kept by fissure_proxy.c itself (section 9b). fissure_cookie.c is a different thing: the signed-cookie engine (Flask, Django, Rails, Express cookie-session signatures), not a jar.

3.0a Cross-tool traffic log (Logger)

fissure_request_execute is the single choke point every engine-driven tool routes through (repeater, intruder, scanner, discover, crawler, autorepeater, auth-matrix, scripts, login). It carries an optional cross-tool traffic log on the config: when cfg.traffic_log (a borrowed FISSURE_TRAFFICLOG*, owned by the app) is set, the engine appends one record per request just before returning, tagged with cfg.traffic_tool (for example "repeater"), with the method, URL, host, status, length, and elapsed time. The main GUI tools set those two fields on the config they build, so their traffic is attributed automatically. The proxy bypasses the engine (it forwards raw bytes for a MITM flow), so fissure_gui_proxy mirrors each newly captured flow into the log tagged "proxy". fissure_trafficlog (fissure_trafficlog.{c,h}) is a mutex-guarded, drop-oldest-capped list that copies strings in and out, so worker threads append while the Logger popup (fissure_gui_logger) reads. The log is engagement-scoped in memory (not persisted) and is cleared from the popup.

Key struct (src/fissure_request.h, abridged; mirrors Hook, extended):

typedef struct FISSURE_REQUEST {
    char* method;              /* GET, POST, and so on */
    N_STR* url;                /* absolute request URL */
    LIST* headers;             /* FISSURE_HEADER* list (order preserved) */
    LIST* params;              /* FISSURE_PARAM* query parameters */
    int body_type;             /* FISSURE_BODY_NONE / RAW / JSON / FORM */
    N_STR* body;               /* raw bytes, may be binary */
    int tls_verify;            /* TLS (per Hook) */
    char* tls_custom_ca_file;
    char* tls_client_cert;     /* mTLS */
    char* tls_client_key;
    int timeout_ms;            /* 0 = none */
    int connect_timeout_ms;    /* 0 = OS default */
    char* proxy_override;      /* per-request proxy URL; "direct://" bypasses */
    int follow_redirects;
    int max_redirects;
    int http2_prior_knowledge; /* h2c prior knowledge */
    char* user_agent;
    int auth_type;             /* FISSURE_AUTH_NONE / BASIC / BEARER / APIKEY, plus credential fields */
    char* origin;              /* capture origin: "repeater", "proxy" or another tool */
    uint64_t flow_id;          /* links request and response across history */
    N_COOKIE_JAR* cookie_jar;  /* borrowed jar: sends cookies, absorbs Set-Cookie */
} FISSURE_REQUEST;

There is no scope flag on the request: scope is checked by the caller (the proxy per flow, the scanner in fissure_scan.c, section 8.2). The native engine reuses Hook's connect/handshake/read-all loop. The proxy does NOT run its forwarding through this struct: it relays raw bytes over its own legs (section 4), and the engine serves the Repeater, Intruder, scanner and the other tools.

Redirect following resolves the Location header as a URI reference (RFC 3986 section 5.3) rather than pasting it onto the authority. An absolute http(s):// target is parsed as-is; //host/path inherits the current scheme; /path replaces the path; and anything else is path-relative and resolves against the base path's directory, so GET /app/page.php with Location: next.php follows to /app/next.php. The relative form matters in practice because it is legal and PHP applications emit it constantly (DVWA's / answers Location: login.php). Concatenating it instead failed two ways: against a non-default port the resulting URL did not parse, so the redirect was silently skipped and the caller saw the bare 3xx; against a default port it parsed as a bogus host (example.comlogin.php), sending a DNS lookup for a name the target chose and then failing to connect. Each part of the rebuilt URL is length-bounded, so an over-long Location truncates the path and can never reshape the authority.

3.0b User-Agent selection

Every outgoing request funnels through one User-Agent decision in the request builder (build_http_request in fissure_engine.c), so a single mechanism sets the User-Agent for the scanner, repeater, intruder, active checks, recon, workflows, and the raw-smuggling and HTTP/3 probes. The precedence, highest first:

  1. an explicit User-Agent request header the operator set (wins, and a User-Agent line in cfg->extra_headers is honored here too, without the builder synthesizing a duplicate);
  2. req->user_agent, a per-request override (the Repeater's request-bar picker, or the control-API/MCP user_agent field on a single send);
  3. cfg->user_agent, a per-run override (the user_agent field on a scan or intruder job);
  4. the process default, set by fissure_engine_set_default_user_agent from the active preset selection at boot and whenever the selection changes;
  5. the compile-time FISSURE_HTTP_USER_AGENT (Fissure/<version>).

The presets themselves live in a small, engine-independent library (fissure_useragent.c): a named {name, value, builtin} set seeded with the Fissure default plus common browser, crawler, and CLI-tool strings, with the operator's own presets and the active selection persisted to <config>/useragents.json. The GUI manager popup, the CLI/serve boot path, and the /api/useragents control route all load that library, resolve the active preset to its value, and push it into the engine via the setter above, so the active User-Agent is process-wide and takes effect immediately. The active User-Agent applies process-wide; the per-request and per-run overrides let one tool or one send present a different identity without changing the global selection.

3.1 HTTP/2

The engine speaks HTTP/2 when the target does. For an https request (with cfg->enable_http2, the default) it offers ALPN "h2,http/1.1" on the client SSL_CTX before the handshake (SSL_CTX_set_alpn_protos on netw->ctx, which is set up but not yet handshaked by netw_ssl_connect_client_to) and, after the handshake, checks the negotiated protocol (SSL_get0_alpn_selected). When the server chose "h2", the same already-built HTTP/1.1 request is reframed and sent over HTTP/2 instead of the h1 send/read; otherwise the h1 path runs unchanged, so h2 is transparent with a full HTTP/1.1 fallback. A request may also set http2_prior_knowledge to speak h2 directly over a cleartext connection (h2c prior knowledge), which is how the engine's h2 path is exercised in tests without TLS.

The engine's HTTP/2 client is fissure_http2_exchange (one request/response on a single stream per call; the engine opens a connection per fetch and does not multiplex) built on the Nilorea framing + HPACK codec (n_http2). Multiplexing does exist in one place: fissure_http2_single_packet sends several requests on parallel streams of one connection for the Repeater's single-packet group send (section 7.1). The exchange sends the client preface and a SETTINGS frame (server push off, a large stream window), enlarges the connection window, HPACK-encodes the request into a HEADERS frame (fragmented into CONTINUATION past the max frame size) plus DATA for a body, then reads the response frames, decoding the HEADERS with HPACK (handling padding/priority and CONTINUATION), collecting DATA, replenishing the flow-control windows per consumed DATA frame, answering PING and ACKing SETTINGS (best-effort), and stopping at END_STREAM to build the FISSURE_RESPONSE.

The intercepting proxy speaks HTTP/2 upstream

The MITM proxy offers ALPN "h2,http/1.1" on its upstream TLS leg (fissure_http2_offer_alpn, called just before the handshake in upstream_ensure) and records what the origin chose (fissure_http2_alpn_is_h2). When the origin selects h2, the rewritten request is reframed and sent over HTTP/2 with the same fissure_http2_exchange the engine uses, and the response is re-framed back into the HTTP/1.1 bytes the proxy's client leg speaks (fissure_http2_response_to_http11). Everything downstream of that seam (flow capture, match/replace, the passive audit, the history) keeps seeing exactly one wire format. When the origin does not select h2, the unchanged HTTP/1.1 send/read path runs, so the fallback is complete.

An h2 upstream leg carries exactly one exchange and is never reused for the next request: fissure_http2_exchange is single-shot (it sends the connection preface and SETTINGS and opens stream 1 with a fresh HPACK encoder on every call), so a second exchange on a kept connection would be a protocol error at the origin. upstream_ensure therefore opens a new connection for each request bound to an h2 origin, while an HTTP/1.1 leg keeps its keep-alive reuse. tests/test_proxy_h2upstream drives several keep-alive requests through one tunnel to an h2 origin and asserts each lands on its own connection with no protocol error.

Before this, the proxy advertised no ALPN at all and hardcoded " HTTP/1.1" on the forward, so every browser flow that passed through it was silently downgraded and the origin never saw the protocol the browser would really have used. That both hid protocol-dependent behaviour (an h2-only route, a header a server treats differently per protocol) and made the proxy's traffic distinguishable from the browser's.

Re-framing the response recomputes Content-Length from the body actually received and drops the hop-by-hop names HTTP/2 forbids (Content-Length, Transfer-Encoding, Connection, Keep-Alive, Upgrade, Proxy-Connection) along with any pseudo-header, since none of those has a valid HTTP/1.1 spelling in a relayed message. Content-Encoding is deliberately kept: fissure_http2 never decompresses, so the body reaches the browser exactly as the origin sent it and the browser decodes it itself.

The negotiated protocol is recorded in the flow's TLS note, which reads "trusted, h2" or "trusted, http/1.1" (and "UNTRUSTED (h2): " when the origin certificate does not verify), so an operator can tell an h2 flow from a downgraded one after the fact rather than having to guess.

That note covers the UPSTREAM leg only. The protocol the CLIENT spoke is recorded separately, on its own flow field (client_proto: "h2", "http/1.1" or "http/1.0"), because the two legs routinely differ: a browser can speak h2 to the proxy while the proxy speaks HTTP/1.1 to an origin that offers nothing else. It is shown in the Proxy view's "Client" column, returned by fissure_proxy_flow_client_proto(), carried in the NDJSON history so it survives a reopen, and included in GET /api/proxy/history and /api/proxy/history/{index} (hence in the proxy_history and proxy_flow MCP tools). Without it, once the client leg could terminate HTTP/2 nothing said which requests the client could only have sent over h2.

One request shape is deliberately kept on HTTP/1.1, because the h1-to-h2 reframing cannot express it: a request carrying an Upgrade header (a WebSocket handshake). HTTP/2 forbids the header and the reframing drops it, so the handshake would fail silently and the flow would never be captured as a WebSocket. upstream_ensure takes a no_h2 argument for that case, which suppresses the ALPN offer and refuses to reuse an already-negotiated h2 connection for such a request.

A chunked request body used to be the second such shape, because the proxy relays chunked bodies with their framing intact (read_chunked_capped keeps the size lines), which is correct over HTTP/1.1 and would reach the origin as literal chunk bytes inside a DATA frame. It is now de-chunked into a plain body with a real Content-Length before the reframing (fissure_http2_dechunk_request), so such a request goes out over h2 like any other; malformed chunk framing is refused and left on the h1 path rather than half-converted into a request whose length lies about its body.

Bodies too large to hold

A body is buffered whole so it can be intercepted, rewritten and captured, and its length is the peer's claim rather than ours. Without a ceiling, one large transfer (or one origin that simply keeps sending) grows a worker's buffer until the process dies, and the client sees nothing at all until the last byte has arrived: a 2 GB download through the proxy is a 2 GB allocation and a browser that appears hung for the whole transfer.

FISSURE_PROXY_BODY_MAX (16 MB) bounds what is held, never what is delivered. Up to the limit the body is buffered exactly as before. Past it, read_n_capped / read_chunked_capped / read_close_capped stop and record how the remainder is framed (BODY_REST_LENGTH, BODY_REST_CHUNKED, BODY_REST_CLOSE), and relay_rest moves those bytes straight from one leg to the other in FISSURE_PROXY_RELAY_CHUNK slices. A chunked body is stopped on a chunk BOUNDARY, which is what makes the remainder relayable: the leg is left positioned at a chunk-size line, exactly where relay_chunked resumes. The transfer completes at full size and full speed, and it starts reaching its destination while it is still arriving.

What a capped flow gives up is real, so it is never silent. Everything that could change the length of what was buffered is skipped for that one message, because the bytes that follow are framed for the ORIGINAL body and an edit would desynchronise the connection rather than rewrite anything: no interception hold, no match-and-replace, no extension request hook, no OAST injection, no Content-Length recompute. A capped request is also forced onto the HTTP/1.1 upstream path (HTTP/2 frames a body from a complete buffer, so it cannot stream one) and cannot be retried on a stale keep-alive connection (the bytes it streamed are gone from the client leg). pwnfox_strip_buf still runs: it removes a header and leaves the body and its declared length untouched.

The operator is told three ways: proxy_note_capped sets the pending notice the GUI pops up and writes a WARN line to the event log (the durable record a headless run can read), the captured flow carries body_capped so its stored bytes are never mistaken for a complete small message, and the Proxy grid shows it in a Body column. body_capped is exposed by fissure_proxy_flow_body_capped(), serialized in the NDJSON history, and returned by GET /api/proxy/history and /api/proxy/history/{index} (hence by the proxy_history and proxy_flow MCP tools). Read it before concluding anything from what a body does NOT contain: on a capped flow, "the canary is not in the response" is unproven, not negative.

One path deliberately keeps reading the whole body: the HTTP/2 CLIENT leg. It re-frames the response from a complete buffer before it can write a single frame, so there is nothing to stream into and capping there would truncate the download instead of bounding memory. connect_pipeline therefore passes SIZE_MAX as the cap when it is serving an h2 client leg, and FISSURE_PROXY_BODY_MAX otherwise. Streaming that leg needs a DATA-frame streaming API in n_http2_server.

The client leg terminates HTTP/2 from the browser

The intercepted TLS handshake offers ALPN "h2" then "http/1.1" (netw_ssl_server_handshake_ex, the ALPN-aware form of the SNI handshake), and when the browser picks h2 the connection is served by the HTTP/2 server state machine (Nilorea n_http2_server) instead of the HTTP/1.1 read loop. It is on by default and toggled by Settings -> "Accept HTTP/2 from the browser on the intercepted leg", by fissure_proxy_set_client_http2(), and by the control API's client_http2 field on POST /api/proxy/start (reported back in the proxy status and by the proxy_start MCP tool).

Each stream's request is re-framed as HTTP/1.1 bytes (fissure_http2_request_to_http11) and handed to connect_pipeline(), the SAME function the HTTP/1.1 client leg calls: interception, match and replace, the PwnFox identity, the extension request hook, OAST canary injection, the upstream exchange, and the flow capture all run unchanged, and the response is re-framed back into HTTP/2 (fissure_http2_response_from_http11) before it goes out. Nothing downstream of that seam knows which protocol the browser used, so every check, rule, view and report keeps working as it did.

Two details of the re-framing matter in practice. HTTP/2 lets a client split its cookies into one field per crumb (RFC 7540 8.1.2.5), which HTTP/1.1 cannot express, so the crumbs are joined back into a single Cookie header: without that, the session cookie an engagement depends on would reach both the origin and the capture as only its first crumb. And a chunk-framed response from the origin is de-chunked before it goes out over h2, which has no chunked transfer encoding, or the size lines would arrive at the browser as page content.

Failures stay per-stream rather than per-connection: a request interception blocks answers 403 on its own stream, an upstream failure answers 502, and a dropped message resets just that stream, exactly as an HTTP/2 origin would, so a connection still carrying other requests is not torn down.

Turning the toggle off restores the previous behaviour exactly: no ALPN is offered, so every client falls back to HTTP/1.1. Note what the feature does and does not change: the target sees no difference either way (the upstream leg already negotiates h2 on its own). What it adds is that the proxy can observe and EDIT a request a browser could only express over h2, and that an h2-only client can use the proxy at all.

The h1-request-to-h2 reframing (fissure_http2_headers_from_raw) turns the built "METHOD TARGET HTTP/1.1" request into the :method / :scheme / :authority (from Host) / :path pseudo-headers plus the regular headers with lowercased names, dropping the connection-specific headers HTTP/2 forbids (Host, Connection, Keep-Alive, Proxy-Connection, Transfer-Encoding, Upgrade) and every header the request's own Connection header nominates (Connection: Keep-Alive, TE makes TE hop-by-hop; Content-Length is exempt so a hostile nomination cannot strip the framing). TE is forwarded only as te: trailers, the single form HTTP/2 accepts, and dropped when the client did not offer that token: an HTTP/1.1 client (a mobile game's HTTP stack, for example) that sends TE: gzip, deflate used to have it relayed verbatim to an h2 origin, which reset the stream and surfaced as a 502 in the client. Byte I/O is abstracted behind read/write callbacks so the same exchange core runs over TLS (SSL_read/SSL_write) or a plain socket. The exchange, the reframing, and the full engine path are covered by tests (test_http2 over a socketpair, test_http2_engine end-to-end through the engine), and HPACK by the RFC 7541 vectors in Nilorea's ex_http2. The request body is sent under send-side flow control (RFC 7540 6.9): a shared per-frame handler tracks the stream and connection send windows (both start at the 65535 default, then follow the peer's WINDOW_UPDATE frames and any SETTINGS_INITIAL_WINDOW_SIZE change), the body is chunked to the smaller window, and when a window is exhausted the client pumps incoming frames until it reopens, so bodies larger than the initial window are sent (test_http2 drives a 200KB body through several wait cycles). The single-packet attack variant that builds on HTTP/2 shipped: fissure_groupsend prepares a group of streams and releases their enders together, exposed as POST /api/groupsend (sequential / parallel / HTTP-2 single-packet mode) and the groupsend MCP tool.

3.2 HTTP/3 (over QUIC)

Fissure speaks HTTP/3 through the general-purpose Nilorea n_http3 client: ngtcp2 provides the QUIC transport, nghttp3 the HTTP/3 framing and QPACK, and OpenSSL the TLS 1.3 handshake (via ngtcp2's native "ossl" crypto shim). Because QUIC is a large, dependency-heavy stack, HTTP/3 is optional and auto-detected at build time: the Makefile probes pkg-config for libngtcp2/libngtcp2_crypto_ossl/libnghttp3 and, only when present, defines HAVE_HTTP3 and links them; otherwise n_http3 compiles as a not-available stub and the default build (and the MSYS2/mingw64 cross build) is unchanged. The client runs a single request/response over a fresh QUIC connection (ALPN "h3"), with GET/POST, caller-supplied headers, and a response of status + headers + body. Fissure exposes it as the "HTTP/3 fetch" tool (a mini Repeater for HTTP/3) across the GUI popup, the /api/http3 control route, and the http3 MCP tool (wrapper fissure_http3, tested by test_http3; the live exchange is validated against a public HTTP/3 host since DVWA is HTTP/1.1 only). An existing captured request is re-sent over h3 from the request context menu ("Send over HTTP/3") or POST /api/request {..., "http3": true} (the send_request(http3=True) MCP tool), so the Repeater/engine send path reaches HTTP/3 too, not only the standalone fetch. It is a lead-extending capability: mainstream intercepting proxies do not fully ship HTTP/3 yet. The replayed request loses the HTTP/1.1 hop-by-hop headers HTTP/3 forbids, the same way the HTTP/2 reframing does: the fixed connection-specific names, every header the Connection header nominates, and TE unless it offers trailers (then sent as exactly te: trailers). The filter is Nilorea's n_http3_request_header_filter; only the smuggling probe bypasses it on purpose.

An HTTP/3-specific attack builds on this: the HTTP-version differential ("Diff h1/h2/h3", POST /api/http3-diff, the http3_diff MCP tool) sends the same request over HTTP/1.1, HTTP/2 and HTTP/3 and reports cross-version response differences (CWE-436). A status-code mismatch between h3 and an older version is the money signal that a WAF, cache, load balancer, or reverse proxy inspects the older protocols but forwards h3 to a different back-end or past the control; on a difference it records a LOW finding, and the pure comparator is unit-tested.

HTTP/3 is also folded into the intercepting proxy itself. The h3 MITM listener (fissure_h3proxy, built on the ngtcp2/nghttp3 server side) terminates inbound HTTP/3 on a UDP port with a per-SNI leaf minted by the local MITM CA (fissure_ca, the same CA the HTTP/1.1 / HTTP/2 proxy uses), reconstructs each request, forwards it upstream through the engine and captures the exchange (so it appears in the report), and relays the response back over HTTP/3. It is controlled by the "HTTP/3 proxy" GUI popup, POST /api/h3proxy {action}, and the h3proxy MCP tool; scope is enforced by the forward (an out-of-scope host is blocked with 403). Because a browser configured to use a classic HTTP proxy downgrades h3 to the older protocols, the listener is reached by a transparent UDP redirect or an explicit h3 client pointed at it (curl --http3 --connect-to host:443:127.0.0.1:port). The listener binds ONE UDP socket. A listen thread reads every datagram and routes it by the packet's destination connection id to the queue of the connection that owns that id, where that connection's own thread picks it up; replies go out on the same socket, addressed to the path ngtcp2 wrote each packet for, which is also how a validated connection migration keeps working. Each QUIC connection still runs on its own thread, so many h3 clients are handled at once, and the forward is synchronous per request within a connection. The routing keys are the connection ids the listener has handed out or been given: the client's original destination id and the server's chosen source id are registered when the connection is accepted (before its thread starts, so the client's very next packet cannot look like a second connection), every id later offered to the client is registered before the frame carrying it leaves, and an id the peer retires is dropped. This is the portable QUIC-server shape and needs no UDP port sharing, so the listener runs on every platform the ngtcp2/nghttp3 stack builds on, Windows included; the only reason it can report unavailable is a build without that stack (fissure_h3proxy_unavailable_reason, surfaced by the popup, the /api/h3proxy 501 body and the log). When interception is on, each h3 request is held (as an editable raw HTTP/1.1 request) in the same intercept queue as the h1/h2 proxy (/api/proxy/intercept), so it can be inspected, edited, or dropped before it is forwarded (a drop returns 403 to the client; an edit is re-parsed and sent upstream). HTTP/3 downgrade request smuggling is also covered: the POST /api/http3-smuggle probe (MCP http3_smuggle) sends a clean HTTP/3 request and the same request carrying a transfer-encoding header that RFC 9114 forbids in HTTP/3 (via the Nilorea n_http3_request_ex allow-illegal-headers mode); an endpoint that answers the illegal-framing request rather than rejecting it does not validate framing before a possible HTTP/1.1 downgrade (the h3 analogue of the H2.TE smuggle), the HTTP/3-to-HTTP/1.1 downgrade-desync precondition.


4. The intercepting proxy (centerpiece)

4.1 Architecture

            browser / app
                 |
        (HTTP absolute-URI or CONNECT)
                 v
   +---------------------------------+
   |  Fissure listening proxy        |   netw_make_listening on 127.0.0.1:8080
   |  accept loop (thread)           |
   +----------------+----------------+
                    | netw_accept_from  -> NETWORK* client
                    v
   +---------------------------------+
   |  per-connection worker thread   |   one detached pthread per accepted
   |                                 |   client connection
   +----------------+----------------+
        parse req   |   open upstream leg (direct, or via n_proxy_*)
                    v
   +---------------------------------+
   |  intercept queue, REQUEST (if   |   GUI edits, then forward/drop
   |  enabled and host in scope)     |
   +----------------+----------------+
                    v
        read the response from the origin
                    v
   +---------------------------------+
   |  intercept queue, RESPONSE (if  |   GUI edits, then forward/drop
   |  responses armed as well)       |
   +----------------+----------------+
                    v
        relay bytes both directions, capture into:
          - endpoint inventory   (-> 05_WEBSITE_SCANNER.md)
          - HTTP history         (-> 06_REPORTING.md / 02_ARCHITECTURE.md)

Response interception

Interception runs in both directions. The master toggle holds requests on their way to the origin; a second toggle ("Responses" in the Proxy view, "responses" on POST /api/proxy/intercept) additionally holds each response on its way back to the client. The two are separate because holding every reply is far more intrusive than holding requests: arming interception must not suddenly pause the whole browsing session, so a response is queued only when both toggles are on.

A held message reports its direction (fissure_intercept_peek_dir, direction in the API, "HELD REQUEST" / "HELD RESPONSE" in the GUI). The operator needs it: Forward on a request sends it to the origin, on a response it releases it to the client, and the two are edited differently.

Editing a response rewrites what the application sees client-side, which is how a client-side-only control is demonstrated: flip an "admin": false in a JSON reply, strip a disabled attribute from a returned form, change a status code, then show that the server accepts the action the tampered response unlocks. The edited bytes are what the flow capture records, because the capture is a log of what actually crossed the wire to the client, not of what the origin sent.

Dropping a response closes the connection: unlike a dropped request (which simply never reaches the origin) there is no reply left to send, so the client is not left waiting.

A 101 is never held. Those bytes are the handshake that switches the connection to frame pumping, and pausing them would strand both peers mid-upgrade; WebSocket frames have their own interception path.

Naming the minted leaf, and IP-addressed targets

fissure_ca_pick names the leaf after the SNI the client sent, and when there is none, after the host from the CONNECT target. RFC 6066 forbids sending SNI for an IP literal, so a client connecting to https://127.0.0.1 sends no server name at all; with only a "localhost" fallback the proxy minted a CN=localhost leaf, the client failed hostname verification and refused the connection. Interception itself worked (the leaf was Fissure-issued and chained to the CA), but every IP-addressed target, which is normal for thick clients and internal services, needed verification disabled to test.

The proxy already parses host and port off the CONNECT target, so the address is available at mint time; it travels to the callback in a FISSURE_CA_PICK context alongside the CA. Nilorea's n_x509_mint_host_cert already emits an iPAddress SAN rather than a DNS one when the name is a literal, so nothing upstream needed changing: a leaf for 127.0.0.1 comes out as CN=127.0.0.1 with IP Address:127.0.0.1 and verifies.

The port in a captured HTTPS URL

A captured HTTPS flow records its non-default port (https://host:8443/path). The URL is the only place a flow says WHICH service it hit, so dropping the port made re-sending one from the Repeater, the organizer or a control-API replay go to 443 instead: it silently tested a different service, or nothing at all. The difference is visible in the replay error, "TLS handshake failed" against the real port versus "TLS connection failed" against 443 with nothing listening. Plain HTTP flows were never affected, since they carry an absolute URI that already includes the port.

What the flow capture records

The captured request is the request that was SENT, not the one the client wrote. By the time a flow is recorded the bytes have been through match/replace, the PwnFox identity strip, OAST canary injection and any extension request hooks, and on the plain path the head has been rewritten to origin form, which is what the origin actually received. Capturing the client's copy meant a report could cite a request that was never sent, and the discrepancy grew with each rewriting feature.

Two things do not follow the forwarded bytes. The flow's absolute URL is stored as its own field, so re-sending a captured request still resolves its target even though the captured head is in origin form (the re-send paths take the URL from that field and read only the headers and body from the raw bytes). And the PwnFox container identity is read from the CLIENT's request, because the forwarded copy has had that header stripped by design; taking it from the forwarded buffer silently drops every flow's identity.

Responses follow the same rule: an intercepted-and-edited response is captured as edited. So both directions agree, and the history is a log of what crossed the wire.

Conditional intercept rules

A single Intercept switch is unusable on a real site: arm it and every image, font and analytics beacon stops the browser, so an operator either turns it off or spends the session clicking Forward. fissure_interceptrules narrows it. The set is ORDERED and the FIRST matching rule decides hold or skip, so a specific rule can sit above a broad one; when nothing matches, the set's default action applies.

A rule constrains any of: direction (request, response, or both), host substring, exact method, path or URL substring (which covers an extension such as .js), Content-Type substring, and a response status range. A field left empty means "any", so a rule is written by naming only what it constrains. Text matching is case-insensitive substring, which is what an operator means by "the /api/ calls".

An empty set holds everything, exactly as the plain toggle always did, so the rule engine changes no behaviour until a rule is actually written. That is what makes it opt-in rather than a migration.

The rules live per project (<project>/interceptrules.json), because which traffic you want to stop on belongs to one engagement. They are edited in the "Intercept rules" popup (Capture toolbar category, and the command palette), which shows the table in evaluation order with Move up / Move down, since order is the whole point. Headless parity: GET/POST /api/proxy/intercept/rules and the intercept_rules / intercept_rules_set MCP tools, which replace the table wholesale rather than incrementally, because order decides the outcome.

Top-level module fissure_proxy.c owns:

  • a listening NETWORK* created with netw_make_listening(listen, "127.0.0.1", port, backlog, ip_version);
  • an accept loop thread calling netw_accept_from(listen); each accepted NETWORK* is dispatched to a per-connection worker (section 6);
  • a borrowed scope (fissure_scope, section 8.2);
  • the captured flows: a list of PROXY_FLOW records (private to fissure_proxy.c: method, URL, status, request/response bytes and sizes, flow_id, WebSocket flag, TLS note, client protocol, PwnFox identity, comment, highlight, body-capped flag), read by the GUI through accessor functions;
  • a borrowed interception queue, FISSURE_INTERCEPT (fissure_intercept.{c,h}, set with fissure_proxy_set_intercept), consumed by the Proxy view's intercept strip (03_GUI_DESIGN.md).

FISSURE_INTERCEPT is opaque: a mutex-guarded FIFO of pending items (label, direction FISSURE_INTERCEPT_REQUEST / _RESPONSE, the raw bytes, and the verdict once resolved) with one condition variable the workers wait on. The worker calls fissure_intercept_submit / fissure_intercept_submit_dir, which blocks until the GUI resolves the head item; the GUI uses fissure_intercept_peek_dir and fissure_intercept_resolve with FISSURE_INTERCEPT_FORWARD (optionally with edited bytes) or FISSURE_INTERCEPT_DROP, and fissure_intercept_drain releases every waiter.

Edit-and-forward: when intercept is on and the flow's host is in scope, the worker submits the raw message and blocks for a verdict. The GUI displays the bytes in an editable text view; the user edits or drops. Editing can be done on the raw bytes directly or through the structured Inspector (the held-request strip's Inspector button: it splits the raw request with fissure_inspect_split_raw, edits headers / query params / cookies / body params as fields, and reassembles the raw request on Apply, see docs/03). The worker then sends the (possibly edited) bytes upstream (FORWARD) or answers the client and ends the flow (DROP). When intercept is off, flows are forwarded immediately and only captured.

Match-and-replace (automatic, rule-driven): where interception is the manual path, FISSURE_MATCHREP (fissure_matchrep.{c,h}) rewrites traffic in flight without a prompt. A rule names a leg (request or response), an optional case-insensitive host filter, a match, and a replacement, and is individually enabled. A rule is either a binary-safe literal substring replace-all or, when its regex flag is set, a PCRE regex whose replacement is a template with $N / ${N} capture-group backreferences applied globally (via the Nilorea npcre_replace helper, pcre2_substitute), so for example id=(\d+) -> id=${1}0. The proxy applies the enabled rules on all four forward points (the plain and MITM legs, the request just before it goes upstream and the response just before it returns to the client and is captured) via fissure_proxy_set_matchrep. The apply is binary-safe and pure, so the same function is the "test against a sample" path. Rules live in <config>/matchrep.json (fissure_matchrep_cfg), are owned by the app, loaded at startup, and handed to the proxy on Start; the in-app rule editor exposes the literal/regex toggle. The same persistent ruleset is reachable headless over the control API (GET/POST /api/matchrep, list/add/set/enable/remove/clear, incl the is_regex flag; a regex that will not compile is rejected) and the matchrep MCP tool, and it applies to control scans as well as the control proxy, so an agent has the same match-and-replace power as the GUI operator. Common uses: spoof an X-Forwarded-For, strip a security header, normalize a request, or rewrite an id/token consistently with a capture-group substitution.

Session capture: the proxy records the session it is relaying

The proxy watches the operator's own authenticated browsing, which is the one place a live session already exists, and for a long time it was the one component that did not record it: fissure_proxy.c is a relay and never mentioned the cookie jar, so only the request engine ever absorbed a Set-Cookie, and it never sees this traffic.

capture_flow, the single funnel every recorded exchange passes through, now offers that exchange's cookies to an installed sink: the response's Set-Cookie headers, and the request's own Cookie header. The second matters as much as the first, because a session established BEFORE the proxy was attached will never produce another Set-Cookie, and without reading the request leg it could not be captured at all.

The sink is a seam rather than a direct call into fissure_cookiejar_shared(). That keeps fissure_proxy.c free of the jar dependency (its unit test links neither), and lets tests/test_proxy assert exactly what the proxy OFFERED without needing a jar at all. The GUI and the control server each install a sink that writes into the shared jar.

Two gates, both deliberate:

  • Off by default. It changes what every later tool sends, so it is opt-in: "Capture cookies" in the Proxy view (persisted in settings) or capture_cookies on POST /api/proxy/start.
  • Scope-gated. Only in-scope hosts are offered, so an engagement's jar does not fill with every unrelated site the browser touches on the way.

What this buys is the shortest authenticated-scan route there is: browse the target logged in through the proxy, then scan. No login config, no session action, no cookie copied by hand. Measured against the DVWA lab, a scan on a session captured this way and nothing else found 59 findings and 4 high, against 10 and 0 for the same scan run anonymously.

Highlighter / Extractor (HaE)

FISSURE_HAE (fissure_hae.{c,h}) is a passive ruleset applied to every captured flow: each rule is a regex (compiled once via the n_pcre wrapper), a scope (request/response/any), and an action set (highlight and/or extract) with a color. On a captured exchange the GUI runs fissure_hae_apply on the same GUI-thread pass that runs the passive user scripts (single-threaded, so the shared compiled patterns are never matched concurrently); a highlight rule sets the flow's color (the highest-priority color wins a "color upgrade" when several match) and an extract rule records its first capture group. The proxy grid PAINTS the matching flow's row with that color (n_gui_datagrid_set_row_color, an upstream per-row tint that follows the row through a column sort; the cell text flips to black or white per the tint luminance, and a selected tinted row is darkened and outlined instead of filled), and also keeps the color name in a "Highlight" column and the values in an "Extracted" column, so the tag is still readable, sortable and filterable as text. The color names, in priority order, are gray, blue, purple, cyan, green, yellow, orange, pink, red; fissure_gui_theme_hilite maps a name (from HaE or from a manual per-flow highlight) to the tint. A starter ruleset (JWTs, AWS keys, api-key params, bearer tokens, emails, private IPs, Set-Cookie, server banners, error traces) seeds <config>/hae.json on first run; the app owns the ruleset and the "HaE" toolbar popup (fissure_gui_hae) edits it (scope/color cycles, highlight/extract/enabled toggles), saving on every change. The popup's own rule list previews each highlight rule by painting its row in the color it applies, and its Literal button escapes the Pattern field (fissure_hae_quote_literal) so plain text an operator typed (a disposable mail address, an order number) matches exactly instead of being read as a regex.

The ruleset is also driven headless over the control API (GET/POST /api/hae, plus POST /api/hae/apply to score one exchange or a captured flow) and the hae / hae_apply MCP tools, sharing the same <config>/hae.json; a rule added in either surface applies to the other. Captured flows carry their verdict over the API too: GET /api/proxy/history/{index} always returns highlight and extracted, and GET /api/proxy/history?hae=1 adds them to each listed flow (opt-in, since it re-scans every returned body), so an agent can triage a browsing session by tag instead of re-reading every body.

4.1a Manual per-flow annotation (comment + highlight)

Separate from HaE's automatic coloring, each captured flow carries two optional user fields: a free-text comment and a manual highlight color name (PROXY_FLOW in fissure_proxy.c). They are set from the Proxy view on the selected flow: the Comment button opens the shared single-line prompt dialog (fissure_gui_prompt) and the Highlight button cycles a fixed palette (none, red, orange, yellow, green, blue, purple). fissure_proxy_flow_set_comment / _set_highlight update the flow and rewrite the whole NDJSON history so the edit survives a restart or project reload; the getters back the grid's Note column and the Highlight override (a manual highlight takes precedence over the HaE color for that flow, both in the Highlight cell and in the painted row tint). Because the datagrid appends rows incrementally and has no per-cell update, an edit sets a one-shot regrid flag that rebuilds the display rows; the passive-audit high-water mark (s_passive_done) is kept separate from the grid high-water (s_last_count) so a display-only rebuild never re-audits a flow. The passive audit is decoupled from the grid build and throttled: each frame spends a bounded wall-time budget (FISSURE_PROXY_PASSIVE_TICK_MS, at least one flow) so starting the proxy over a large reloaded history spreads the audit across frames (with an auditing N/M status) instead of freezing the view, and a response body over FISSURE_PROXY_PASSIVE_MAX_BODY (a multi-megabyte asset or download) is skipped by the passive suite, whose regex/scripted/nuclei passes would otherwise run for seconds on a single flow.

4.2 HTTP proxying (plain)

For a plain HTTP request the client sends an absolute-URI request line:

GET http://example.com/path HTTP/1.1
Host: example.com

The worker parses the request with netw_extract_http_request_type + netw_get_url_from_http_request, opens an upstream connection to the target host:port with the native engine (netw_connect_to), rewrites the request line to origin-form (GET /path HTTP/1.1) like Hook's absolute-URI handling, forwards it, reads the response with _netw_read_all, captures both, and relays the response back to the client. Keep-alive is honored when the client and upstream both allow it; otherwise the worker closes after one exchange.

Transparent mode (opt-in, fissure_proxy_set_transparent, wired to the Settings "Transparent mode" toggle, proxy_transparent) also accepts a non-proxy-style request that arrives in origin form (GET /path HTTP/1.1) with only a Host header: parse_req_info captures the Host value, and handle_plain_one synthesizes http://<Host>/path into the target so the request routes, captures, and is interceptable exactly like a proxy-style one. This lets clients that cannot set an HTTP proxy (thick clients, or traffic redirected/pointed at the listener) be tested; the bind stays loopback by default and the mode is off by default. Covered by run_transparent_test in test_proxy. Full transparent interception of redirected TLS (SO_ORIGINAL_DST / SNI) is a possible later addition; today transparent mode is the plain-HTTP origin-form path.

4.3 HTTPS proxying via CONNECT (MITM)

For HTTPS the client first sends:

CONNECT example.com:443 HTTP/1.1

Transparent interception (the whole point of Fissure) does NOT blind- tunnel. Instead:

  1. The worker replies HTTP/1.1 200 Connection Established to the client.
  2. It now needs to become a TLS server to the client. It reads the client's SNI from the incoming ClientHello (the host from the CONNECT line is the fallback) and mints a per-host leaf certificate signed by the local Fissure CA (section 5), caching it.
  3. It installs that leaf cert/key on the client-facing NETWORK* (in-memory PEM) and completes SSL_accept() via n_network's server-side TLS path.
  4. Separately it opens a TLS client connection to the real upstream (netw_ssl_connect_client_to with the real host as SNI), validating the real server's certificate against the system CA bundle (so Fissure detects genuinely broken upstream TLS, surfaced as a finding, see 05_WEBSITE_SCANNER.md).
  5. It now has plaintext on both sides and relays, intercepting/capturing each request/response exactly like the plain path.
client --TLS(leaf for example.com)--> Fissure --TLS(real example.com)--> server
        ^ signed by Fissure CA                 ^ validated vs system CA

This requires new nilorea functions (section 5 + 8): X.509 CA generation, per-host cert minting, SNI read on accept, and a per-accepted-connection in-memory cert install with an SNI callback. Cross-ref audits/NILOREA_AUDIT.md section 5A.

4.4 OAST canary injection

An opt-in passive mode (fissure_proxy_set_oast, wired to the Settings "Inject OAST canary headers into in-scope requests" toggle, oast_inject) seeds every forwarded in-scope request with a curated set of forwarding headers (Referer, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Server, X-Host, X-Real-IP, True-Client-IP, X-Client-IP, X-Originating-IP, Forwarded, CF-Connecting-IP, Via), each carrying a freshly minted OAST canary URL. If the target reflects any of them into an out-of-band request (a common blind-SSRF shape), the request reaches the OAST collector, which correlates the path token and raises a certain out-of-band-interaction finding: the exact OAST canary-injection workflow.

The canary is unique per request (fissure_oast_mint), so a pingback pins the exact exchange. Injection is a no-op when the toggle is off, when no OAST collector is running (start it from the OAST tab), or when the head is malformed. It happens at both upstream-send sites (plain HTTP and the HTTPS MITM leg), after match-and-replace and PwnFox stripping, before the bytes hit the wire, and only for in-scope hosts (out-of-scope hosts are blind-tunnelled and never touched). Detection is free: the OAST tab's per-frame bridge turns any recorded pingback into a finding whether or not the tab is open. Enable it only against authorized targets.

4.5 Generic non-HTTP relay (raw TCP/UDP interception)

The intercepting proxy understands HTTP and WebSocket; a separate, protocol-agnostic relay (fissure_rawrelay) covers everything it cannot parse: a proprietary binary protocol, a database wire protocol, a game protocol, a custom TLV. It is a non-HTTP intercepting proxy. The operator points a client at a local listen port and the relay forwards every byte to a fixed upstream host:port, capturing each chunk in both directions and, when interception is on, holding each chunk for edit-and-forward.

  • TCP: an accept loop (mirroring the proxy's netw_make_listening + netw_accept_from
    • per-connection detached workers + the active_workers/worker_socks shutdown handshake, section 6) spawns one worker per connection. The worker connects upstream (netw_connect_to, or netw_ssl_connect_client_to when the upstream leg is TLS) and pumps both directions with poll() over the two sockets, TLS-aware on each leg (SSL_read/SSL_write vs recv/send), exactly like the proxy's pump_bidirectional.
  • UDP: one bound socket (netw_bind_udp) plus one connected upstream socket (netw_connect_udp); a single loop relays a client datagram to the upstream (netw_udp_recvfrom -> send_udp_data) and its reply back to the last client (recv_udp_data -> netw_udp_sendto), one datagram per captured chunk.
  • Interception reuses fissure_intercept (the same hold/edit/forward/drop FIFO the HTTP proxy uses, section 4.1), so a held chunk is peeked, edited, and resolved through the exact same control-API and GUI machinery. stop() follows the proxy discipline (shutdown(SHUT_RDWR) on the listener to break accept, drain the intercept queue to release a worker blocked on a verdict, then wait out the detached workers).

Fissure-owned business logic (relay orchestration + the intercept/capture workflow), built on the existing n_network listen/accept/connect and UDP primitives, exactly as fissure_proxy is. Exposed in the GUI (the "Raw proxy" toolbar popup), over the control API (/api/relay/start|stop|status|history|intercept|intercept/resolve, chunk bytes base64-encoded), and as MCP tools (relay_*). TLS upstream wrapping does not verify the upstream certificate (this is an interception tool). Active against authorized targets only; the operator, not the relay, chooses what to point at it.


5. HTTPS MITM: certificates and the SNI callback

5.1 Nilorea X.509 helpers (module n_x509, OpenSSL-gated)

These ship in nilorea (include/nilorea/n_x509.h, cross-ref NILOREA_AUDIT 5A; nilorea conventions: int returns 0=OK, N_STR** out-params owned by the caller) and are called by fissure_ca.c:

/*! @brief Generate a self-signed CA keypair + cert (PEM) the user installs in
 *  their trust store. days = validity. Returns 0 on success. */
int n_x509_generate_ca(const char* cn, int days,
                       N_STR** ca_cert_pem, N_STR** ca_key_pem);

/*! @brief Mint a per-host leaf cert signed by the given CA, with a SAN for
 *  host (and IP SAN if host is a literal IP). Fissure caches the result. */
int n_x509_mint_host_cert(const char* host,
                          const N_STR* ca_cert_pem, const N_STR* ca_key_pem,
                          int days,
                          N_STR** leaf_cert_pem, N_STR** leaf_key_pem);

/*! @brief Generate an RSA/EC keypair in PEM (helper for the above). */
int n_x509_keypair_pem(int bits, N_STR** key_pem);

Implementation notes: n_x509_generate_ca builds an X509 with basicConstraints=CA:TRUE, keyUsage=keyCertSign,cRLSign, a random serial, and self-signs with SHA-256. n_x509_mint_host_cert builds a leaf with basicConstraints=CA:FALSE, extendedKeyUsage=serverAuth, a subjectAltName=DNS:<host> (or IP:<host>), a fresh serial, and signs with the CA key. Each leaf gets a fresh serial, since browsers reject duplicate serials from the same issuer.

5.1b Stopping: no blocking read may outlive the stop flag

fissure_proxy_stop clears running, wakes the accept loop, then spins until every per-connection worker has drained, because fissure_proxy_free destroys the locks and lists those workers touch. Whether that spin finishes quickly depends entirely on how long a worker can stay inside one read.

A worker waiting for the NEXT request on a kept-alive connection is the case that matters: a browser leaves several open and silent (Chrome pre-connects and keeps six or more per host). Shutting the socket down releases such a read on POSIX, and that is what the stop path does, but Winsock does not reliably wake a thread already blocked in recv, so on Windows each of those workers ran to the full FISSURE_PROXY_TIMEOUT_MS and the proxy looked like it would not stop until the browser was closed.

The rule the proxy follows now is the one the accept loop already followed: never depend on another thread's shutdown() to end a wait. A client leg is marked interruptible (leg_set_interruptible), which narrows its RECEIVE timeout to FISSURE_PROXY_READ_POLL_MS and gives leg_fill a running flag and an idle deadline. The read then happens in slices, and between slices the leg distinguishes a receive-timeout (retry) from a real close or error (end the leg), gives up at once when running goes to 0, and otherwise enforces the real idle timeout against the deadline, which traffic resets. The SEND timeout is deliberately left long: a large upload through the proxy must not fail because the read slice is short. Upstream legs are left uninterrupted, so their behaviour is unchanged.

Both request loops (handle_client, and the decrypted loop in handle_connect) also test running before starting another request, so a worker that is between requests leaves immediately rather than at its next read.

5.2 Nilorea n_network accept-side functions

These ship in nilorea n_network.h:

/*! SNI cert-pick callback: given the client SNI host (may be NULL), fill
 *  *cert_pem / *key_pem (newly allocated; n_network frees them). 0 = proceed. */
typedef int (*netw_sni_pick_cb)(const char* sni, N_STR** cert_pem, N_STR** key_pem, void* user_data);

/*! the SNI server_name the peer requested in its ClientHello, or NULL */
const char* netw_ssl_get_sni(NETWORK* netw);

/*! install an in-memory cert/key on THIS connection's SSL only
 *  (per-connection, unlike the context-wide netw_set_crypto_pem) */
int netw_set_crypto_pem_ctx(NETWORK* netw, const N_STR* key_pem, const N_STR* cert_pem);

/*! accept a TLS connection, selecting the server cert per client SNI via pick() */
NETWORK* netw_accept_ssl_with_sni_cb(NETWORK* listen, netw_sni_pick_cb pick, void* user_data);

/*! upgrade an already-accepted plaintext connection to a TLS server, selecting
 *  the cert per client SNI via pick() (for proxy CONNECT); _ex adds an ALPN offer */
int netw_ssl_server_handshake(NETWORK* netw, netw_sni_pick_cb pick, void* user_data);
int netw_ssl_server_handshake_ex(NETWORK* netw, netw_sni_pick_cb pick, void* user_data,
                                 const char* const* alpn, size_t alpn_count);

5.3 SNI callback, as used by the proxy

The proxy's listener is plain TCP: a browser first sends CONNECT host:port, so the TLS handshake happens on an already-accepted socket. After answering the CONNECT, fissure_proxy.c upgrades the client socket with netw_ssl_server_handshake_ex (offering ALPN when HTTP/2 toward the client is enabled) or netw_ssl_server_handshake, passing fissure_ca_pick as the pick callback. Inside nilorea the pick runs from the OpenSSL servername callback, with the SNI read via SSL_get_servername; fissure_ca_pick returns the leaf for the SNI host (or for the CONNECT host when the client sent no SNI, see "Naming the minted leaf" in section 4) and the handshake completes with that host-specific certificate. netw_accept_ssl_with_sni_cb is the same mechanism for a listener that speaks TLS directly.

fissure_ca_get_leaf looks the lowercased host up in the CA's leaf cache and mints with n_x509_mint_host_cert on a miss, so later connections to the same host reuse the cert with no keygen cost.

5.4 CA trust lifecycle

  • First run: fissure_ca_new calls n_x509_generate_ca with FISSURE_CA_CN and FISSURE_CA_DAYS ("Fissure Proxy CA", 3650 days) and persists ca-cert.pem + ca-key.pem under <config>/ca/, file mode 0600 on the key. Leaves are minted for FISSURE_LEAF_DAYS (825).
  • The GUI exposes "Export CA certificate" which writes the CA cert PEM to a user-chosen path and shows install instructions for Firefox / Chromium / OS trust store. Until the user installs it, the browser shows a cert warning - this is expected and documented.
  • Minted leaf certs are cached per host in FISSURE_CA.leaf_cache, a HASH_TABLE keyed by lowercased host whose value holds the leaf cert + key PEM pair, with a leaf_order list for FIFO eviction past FISSURE_CA_CACHE_MAX_LEAVES. The cache is mutex-guarded because multiple connection workers mint concurrently. It is in memory only.

5.5 Capturing into inventory + history

Every proxied request/response (plain or MITM) is recorded after the verdict is applied:

  • HTTP history: the worker appends a PROXY_FLOW record (method, URL, status, request/response bytes and sizes, flow_id, TLS note, client protocol) to the proxy's in-memory flow list under its flows lock, and to the on-disk history <project>/proxy-history.ndjson (section 9b). Feeds the history grid (03_GUI_DESIGN.md), the passive audit and the findings the report renders (06_REPORTING.md).
  • Endpoint inventory: the captured history seeds a FISSURE_INVENTORY (fissure_inventory, which canonicalizes each URL with n_url_canonicalize_string and dedups by method + canonical URL, recording the observed parameters). This passive discovery feeds the scanner (05_WEBSITE_SCANNER.md).

6. Concurrency model

Intercepting proxies are inherently concurrent: many browser connections at once. Fissure uses per-connection worker threads (Hook's threading pattern, generalized from one-at-a-time to many), citing audits/HOOK_AUDIT.md section 4.

Pattern (mirrors Hook's SSE/WS worker discipline):

  • The accept loop dispatches each accepted NETWORK* to one detached pthread per connection (pthread_create + pthread_detach in fissure_proxy.c); there is no thread pool on the proxy path.
  • Stopping: the stop path shuts the sockets down to break blocking reads, and client legs also read in short slices that check the running flag (section 5.1b), so no worker depends on another thread's shutdown().
  • Shared state (intercept queue, flow list, WebSocket captures, leaf-cert cache) is guarded by mutexes; every GUI reader takes the same mutex it was written under.
  • Worker-exit handshake: each worker increments an active_workers counter (__atomic) and registers its client socket; fissure_proxy_stop drains the intercept queue, shuts every registered worker socket down, and loops until active_workers reaches zero, because fissure_proxy_free destroys the flows lock and lists right after and a still-running worker would be a use-after-free.

Lock-order and atomics are validated under ASan/UBSan and ThreadSanitizer (make DEBUG=1 / DEBUG_THREADS=1), per the nilorea build conventions.

6.1 WebSocket and SSE pass-through

Once a request carrying Upgrade gets a 101 Switching Protocols, the worker switches to a poll-based bidirectional relay. The bytes seen in each direction are fed to a per-connection FISSURE_WSCAP (fissure_wscap.{c,h}), which accumulates them and parses individual frames with the nilorea n_ws_frame_parse codec (unmasking client frames) for the Proxy WS history view. When interception is enabled, relay_ws_frames parses each direction's accumulator and holds every complete single-frame TEXT message in the intercept queue; a forwarded (possibly edited) message is re-framed with n_ws_frame_build, and a dropped one is not forwarded. Other frames, and all frames when interception is off, are relayed as received. There is no dedicated SSE handling: an event stream is relayed as an ordinary response body.


7. Repeater and Intruder features

7.1 Repeater (replay)

Any captured flow can be sent to the Repeater: it loads the flow's captured raw request into an editable Repeater tab and replays it through the same transport core (section 3) - the native n_network engine. The response and timing are shown side by side; repeated sends are new flows with their own flow_id, so the history grid shows the diff across attempts. No new network code: Repeater is a thin GUI + a call into the engine. For multipart/form-data bodies the Repeater adds "MP inspect" (parse the parts, using the boundary from the Content-Type header, into the response pane) and "MP repack" (rebuild the body with clean framing), over n_http_parse_multipart / n_http_build_multipart.

Request grouping with synchronized send

DONE (fissure_groupsend, test_groupsend). The Repeater can send a whole collection of tabs together as one group, the mechanism for race-condition and connection-state testing (request groups). The "Send group" control on the Repeater toolbar gathers every tab that shares the active tab's collection (the existing per-tab group field) and sends them in one of three topologies, picked from a selector:

  • separate connections (FISSURE_GROUPSEND_SEQ_SEPARATE): each request on its own fresh connection, one after another, through the full transport engine (so redirects off, but TLS, mTLS-less, and an upstream proxy still apply). The baseline.
  • single connection (FISSURE_GROUPSEND_SEQ_SINGLE): every request over one kept-alive connection in order (connection warming), so per-connection server state is shared across the group.
  • parallel (FISSURE_GROUPSEND_PARALLEL): one connection per request, every request written except its final byte, then all the withheld final bytes released back to back, HTTP/1 last-byte synchronization, to land the requests as close together as possible. The classic race-condition primitive.
  • HTTP/2 single-packet (FISSURE_GROUPSEND_H2_SINGLE_PACKET): the stronger race primitive over one HTTP/2 connection (fissure_http2_single_packet). Every request is multiplexed onto its own stream (odd ids 1, 3, ...) and its HEADERS (plus all but the final byte of any body) is sent WITHOUT END_STREAM, so the server parks every stream; after a brief hold the stream-ending frames (an empty END_STREAM DATA, or the withheld last body byte) are released together in one write, so the requests complete in a single packet with no inter-request jitter. It connects once with ALPN "h2" (or h2c prior knowledge on cleartext) and fails if the target will not speak HTTP/2; the combined pre-release bodies must fit the initial 65535 window, matching the small requests typical of race attacks. Covered by test_http2 (the core, six multiplexed streams) and test_groupsend (the mode, over a loopback h2c server).

The single-connection, parallel, and single-packet modes drive raw sockets directly (direct connections only, no upstream proxy) so the byte timing is controlled, set TCP_NODELAY, and connect to the first request's host:port:scheme; the separate mode reuses the engine. Each request's collected result (status, rendered response, elapsed time) is appended to that tab's send history, so the responses are reviewed by switching tabs and stepping the per-tab history. The send runs on a worker thread (the toolbar shows "Sending group", the buttons are disabled while it runs) and a summary line reports how many of the group got a response. A group is formed by giving two or more tabs the same collection name (the per-tab field below the tab list); blank-starter URLs are skipped, and a collection with fewer than two sendable requests is refused with an on-screen explanation rather than silently sending one. Each tab's send history can be pruned with the per-tab Del send button. Like the rest of the active tooling this targets authorized scope only.

7.2 Intruder (fuzzing / payload positions)

DONE (Intruder view + fissure_intruder, default F10). The implementation marks payload positions by wrapping each span in a backtick marker (FISSURE_INTRUDER_MARKER, configurable per run), supports the four modes, and runs each generated request through the transport engine on an n_thread_pool, collecting status/length/time per attempt into a sortable grid. fissure_intruder_generate (the pure text fan-out) and fissure_intruder_run (the threaded send) are unit-tested (tests/test_intruder); a single payload list is reused across positions for pitchfork/clusterbomb, and a request cap guards against clusterbomb blow-up.

Intruder marks one or more payload positions in a request template and substitutes payloads from a wordlist or generator. There is no Intruder object; the API (src/fissure_intruder.h) is a set of functions over plain arguments:

  • FISSURE_INTRUDER_MODE: FISSURE_INTRUDER_SNIPER, _BATTERING_RAM, _PITCHFORK, _CLUSTERBOMB.
  • fissure_intruder_generate(tmpl, marker, mode, payloads, nsets, max_requests, out): the pure text fan-out of a template into concrete requests.
  • fissure_intruder_run (URL template) and fissure_intruder_run_request (method + URL + headers + body templates): send every generated request through the engine on an n_thread_pool of max_threads, with a delay, retries, a stop flag, an optional FISSURE_INTRUDER_GREP (literal match and PCRE extract) and an optional pre-send hook (fissure_intruder_pre_fn).
  • FISSURE_INTRUDER_RESULT: one attempt's outcome (the request sent, status, length, time_us, error, retries, grep_hit, grep_value, reflected).

Results land in a sortable grid.

Payload sources tie into the scanner's payload library and the external ffuf plugin (05_WEBSITE_SCANNER.md): Fissure can either run Intruder natively (its own engine) or hand a position+wordlist off to ffuf via the plugin host and ingest ffuf's results. Substitution is a span replace between marker pairs in the template text.


8. Upstream proxy chaining, SOCKS5, and scope

8.1 Upstream chaining

Fissure's listening proxy can forward through an upstream proxy (corporate proxy, Tor, another intercepting proxy), reusing the n_proxy helpers Hook already uses:

  • HTTP/HTTPS upstream: n_proxy_connect_tunnel (CONNECT) / n_proxy_connect_tunnel_ssl for the upstream leg, then Fissure's own MITM still terminates TLS toward the browser.
  • SOCKS5 upstream: n_proxy_connect_socks5 (handshake + optional user/password sub-negotiation).
  • Per-request override (engine): FISSURE_REQUEST.proxy_override; direct:// bypasses the chain for one request. The proxy has one upstream setting (fissure_proxy_set_upstream_proxy(proxy, url, no_proxy)), where direct:// also means no upstream.
  • Config: a global upstream proxy URL + a no_proxy passthrough list (exact host, .suffix for subdomains, * = all) parsed with the same rules Hook uses. Hosts on the passthrough list are blind-tunneled (no MITM, no capture) so non-target traffic stays untouched.

As-built (outbound transport): the native engine (fissure_engine.c) routes its own outbound requests through an upstream proxy. effective_proxy is the per-request proxy_override else the config proxy_enabled ? proxy_url. A host_in_no_proxy match against FISSURE_CONFIG.no_proxy (exact, leading-dot or bare domain suffix, or *) and a direct:// URL both force a direct connection. Otherwise n_proxy_cfg_parse selects the scheme and the engine tunnels via n_proxy_connect_socks5 (socks5), n_proxy_connect_tunnel_ssl (https proxy), or n_proxy_connect_tunnel (http proxy); the returned socket is wrapped in a NETWORK with the nilorea netw_adopt_client_fd primitive and, for an https target, promoted to TLS with netw_ssl_start_client before the normal verify / client-cert / handshake path runs. The Settings popup edits the proxy URL ("Upstream proxy") and bypass list ("No-proxy hosts"); the Target view feeds them to the scan transport and the Repeater to its sends.

As-built (MITM listener): the intercepting proxy chains its upstream leg through the same upstream proxy. fissure_proxy_set_upstream_proxy(url, no_proxy) stores the chain on the FISSURE_PROXY; upstream_ensure (the single point that opens the connection to each target, plain or TLS) tunnels through it, selecting n_proxy_connect_socks5 / _tunnel_ssl / _tunnel by scheme, adopting the tunnel socket with netw_adopt_client_fd, and (for an https target) starting client TLS with netw_ssl_start_client before the existing verify-note + handshake path. A host on the no_proxy list (fissure_no_proxy_match, shared with the engine) or a "direct://" URL connects directly. The Proxy view applies the settings on Start.

As-built (per-host routing): beyond the single global upstream, fissure_hostroute is an ordered ruleset (Settings "Host routes", persisted as host_routes, parsed with fissure_hostroute_from_text) matched by exact host or a "*.suffix" wildcard. A "host = addr[:port]" rule is a DNS rewrite: the engine dials that address for the direct connection while the Host header, TLS SNI, scope, and captured URL stay the original host, so a staging IP is hit by name without editing /etc/hosts. A "host via url" rule routes only that host through a chosen upstream proxy (split routing), overriding the global default for it. cfg->hostroute is borrowed by the engine (fissure_hostroute_resolve at connect); the scan transport rebuilds it from settings each run. Covered by test_hostroute (parse + resolve) and a DNS-rewrite case in test_engine.

As-built (scope): fissure_scope (an allow/deny host-pattern set, see 8.2) is borrowed by the proxy via fissure_proxy_set_scope. handle_connect blind-tunnels an out-of-scope CONNECT, it answers 200, opens a raw tunnel to the target with upstream_ensure (which still honors the upstream-proxy chain) and pumps bytes both ways, so the browser negotiates TLS end-to-end with the real server and Fissure mints no leaf cert, intercepts nothing, and captures nothing. handle_plain_one decides scope from the target host before interception and forwards an out-of-scope plain-HTTP request without holding it in the intercept queue or recording a flow. A NULL scope (the default until the user configures one) treats every host as in scope, preserving the capture-all behavior.

8.2 Scope / allowlist

A security tool must not intercept or attack out-of-scope hosts. The scope engine (fissure_scope.c) holds an allowlist (and optional denylist) of host patterns (exact, .suffix, regex via n_pcre). On each CONNECT / absolute-URI:

  • If the host is out of scope, the worker blind-tunnels the bytes (no MITM, no leaf cert minted, no capture) - the browser still works, Fissure stays passive.
  • If the host is in scope, full MITM + capture + (optional) interception.

There is no scope flag on the request: each consumer checks the scope itself. The proxy calls fissure_scope_in_scope_ex per flow, and the scanner calls it per endpoint in fissure_scan.c, so passive and active checks only ever run against in-scope endpoints. Scope is shared with the scanner and reporting (02_ARCHITECTURE.md).

As-built: fissure_scope (src/fissure_scope.{c,h}, test_scope) holds the allow and deny pattern lists; patterns are case-insensitive * (all), .suffix (domain), re:<regex> (n_pcre), or an exact host. An exact or suffix pattern may carry an explicit port (example.com:8080, .example.com:8080) to constrain to that port; a bare host matches every port. A regex is tested against both the bare host and the host:port authority, so re:^host:8080$ pins a port while re:^host$ still matches any port. fissure_scope_in_scope (port-agnostic) and fissure_scope_in_scope_ex (port-aware; callers thread the effective port via fissure_scope_effective_port) both return true when no deny pattern matches and either the allowlist is empty or an allow pattern matches (deny wins; a NULL scope means no restriction). The proxy, crawler, scanner, and control API pass the URL port, so a co-hosted service on another port of an in-scope host is correctly kept out when the scope names a port. fissure_scope_from_text turns the in-scope / out-of-scope pattern lists (edited in the dedicated Scope editor popup as multi-row lists, held in memory as scope_allow / scope_deny and persisted per-project to <project>/scope.json) into a scope. The proxy borrows it (fissure_proxy_set_scope) and blind-tunnels out-of-scope hosts (section 8.1 as-built); the Target view refuses to start a scan whose seed host is out of scope. The scan and crawler also borrow the same scope (fissure_scan_set_scope, which propagates to fissure_crawler_set_scope): when set, the crawl follows in-scope links across several authorized hosts and the audit probes only in-scope endpoints (fissure_scope_in_scope), instead of the seed-host-only default. The Target view rebuilds the scope from the current (per-project) scope on each Start (after the prior scan worker is joined, so the borrowed scope is replaced safely); switching projects reloads the new project's scope.


9. Nilorea network additions (as built)

These are the nilorea additions Fissure needed, all now shipped in nilorea and used by Fissure. Each follows nilorea conventions (module_action naming, ALL_CAPS typedefs, new_*/*_free, Doxygen, an examples/ex_*.c, a Makefile link rule, a run_tests.sh entry, one commit per point). Cross-ref audits/NILOREA_AUDIT.md sections 5A and 5E.

Tier 1 (the proxy cannot exist without these)

Module n_x509 (OpenSSL-gated, n_x509.h): n_x509_keypair_pem, n_x509_generate_ca, n_x509_mint_host_cert (signatures in section 5.1), used by fissure_ca.c.

n_network accept-side SNI + per-connection cert: netw_sni_pick_cb, netw_ssl_get_sni, netw_set_crypto_pem_ctx, netw_accept_ssl_with_sni_cb, and the CONNECT-path upgrade netw_ssl_server_handshake / netw_ssl_server_handshake_ex (signatures in section 5.2). The proxy uses the handshake pair with fissure_ca_pick as the pick callback (section 5.3).

Tier 2 (correct capture + scanner feed)

n_network URL canonicalization + HTTP body helpers (NILOREA_AUDIT 5E):

N_STR* n_url_canonicalize(const N_URL* u);          /* lowercase scheme/host,
                                                       drop default port, decode
                                                       unreserved, simplify path */
N_STR* n_url_canonicalize_string(const char* url);

int    n_http_decompress_body(const N_STR* body, const char* encoding,
                              N_STR** out);          /* gzip/deflate/br */
LIST*  n_http_parse_multipart(const N_STR* body, const char* boundary);

Hook's cookie jar is promoted into nilorea as the n_cookies module (domain/path/secure/expiry-aware, Netscape format, rwlock-guarded) so the engine, repeater, and scanner can share one jar. As built:

N_COOKIE_JAR* n_cookiejar_new(void);
void          n_cookiejar_free(N_COOKIE_JAR** jar);
int           n_cookiejar_add_from_header(N_COOKIE_JAR* jar,
                                          const char* set_cookie_value,
                                          const char* request_domain);
N_STR*        n_cookiejar_build_header(N_COOKIE_JAR* jar, const char* domain,
                                       const char* path, int is_secure);
size_t        n_cookiejar_count(N_COOKIE_JAR* jar);
void          n_cookiejar_clear(N_COOKIE_JAR* jar);

The engine attaches a (borrowed) jar to a request via FISSURE_REQUEST.cookie_jar: it emits a Cookie header built from the jar for the request host/path/scheme (skipped when the user set their own Cookie) and absorbs every Set-Cookie response header per hop. The Repeater keeps a persistent session jar across sends with a "Session: N cookies" indicator and a "Clear cookies" action.

Not added

No non-blocking SSL accept variant was added (a worker's handshake runs under the leg's socket timeouts), and leaves are issued directly under the Fissure CA, so no intermediate chain is served.


9b. As-built proxy

The proxy described above is implemented in src/fissure_proxy.c and exercised by tests/test_proxy, tests/test_proxy_mitm, tests/test_history and tests/test_intercept. Concretely:

  • Message framing and keep-alive. A buffered, TLS-aware leg reader frames every request and response by Content-Length, Transfer-Encoding: chunked, the no-body status rules (1xx/204/304/HEAD), or connection close. One client connection therefore carries many requests (and pipelined requests), and an HTTP/1.1 upstream connection is kept open and reused while the target host/port are unchanged (an h2 upstream leg is not reused; see "The intercepting proxy speaks HTTP/2 upstream"). Hop-by-hop headers are stripped (Connection, Keep-Alive, Proxy-Connection and any header the Connection header nominates, such as TE; never Host, Content-Length or Transfer-Encoding) and Connection is normalized.
  • WebSocket / Upgrade relay. When a request carries Upgrade and the upstream answers 101 Switching Protocols, the tunnel switches to a poll-based bidirectional relay (TLS-aware, draining buffered SSL records) until either side closes. The upgrade handshake is captured as a flow, and the frames are parsed and captured (FISSURE_WSCAP, n_ws_frame_parse) and, with interception on, text frames are held and re-built with n_ws_frame_build (section 6.1).
  • Upstream TLS trust note. After the upstream handshake the real peer certificate is evaluated against the system trust store and hostname (netw_ssl_get_verify_result, added to nilorea n_network), independently of the proxy's own verification mode. The result (trusted, or UNTRUSTED: <reason>) is stored on the flow and shown in the history; the exchange still proceeds so the operator can see the traffic.
  • On-disk history. Each captured flow is appended to <project>/proxy-history.ndjson (the active project's directory) as one base64-framed JSON object per line (cJSON + n_base64, binary-safe) and reloaded on start (fissure_proxy_set_history_file). An optional history cap (fissure_proxy_set_max_flows, set from the "Proxy history" setting) keeps only the most-recent N flows in memory, drops the oldest as new ones arrive, and trims/rewrites the file on load so it stays bounded across sessions.
  • Interception / edit-and-forward. src/fissure_intercept.c is a thread-safe FIFO. When interception is enabled the worker submits the request and blocks for a verdict: forward, forward-edited (the edited bytes are re-parsed and forwarded), or drop (answered with 403). Stopping the proxy drains the queue so no worker stays blocked.
  • GUI widgets. The Proxy view is built on four widgets added upstream to nilorea n_gui: N_GUI_DATAGRID (sortable history table), N_GUI_SYNTAXVIEW (HTTP-highlighted request/response panes), N_GUI_SPLITPANE (draggable region dividers) and N_GUI_HEXVIEW (binary view, available for raw bodies). The syntax-view panes are read-only but selectable: drag to select text and press Ctrl+C to copy it, Ctrl+A to select all (the same n_gui selection model as the labels). The selection API is n_gui_syntaxview_get_text / n_gui_syntaxview_get_selected_text / n_gui_syntaxview_set_selection / n_gui_syntaxview_select_all, so every syntax view in the app (Repeater pretty views, Inspector) is copyable, not only the Proxy panes.

10. Summary

Fissure's networking is Hook's transport core (native n_network engine, TLS config, proxy support, cancellation, timing; Hook's optional curl backend is not ported) forked and wrapped in a concurrent, per-connection intercepting proxy. The one piece Hook never needed - and nilorea did not originally provide - is per-host TLS leaf certificate minting behind an SNI callback, added (Tier 1 of section 9) as the n_x509 module plus the n_network accept-side SNI functions. With those in place, the proxy terminates TLS toward the browser with a host-correct leaf signed by a user-installed Fissure CA, re-originates a validated TLS connection upstream, and captures every flow into the endpoint inventory and HTTP history that feed the scanner (05_WEBSITE_SCANNER.md) and the report (06_REPORTING.md). Repeater and Intruder reuse the same engine; scope, upstream chaining, and a passthrough list keep out-of-scope traffic untouched.

Chunked request bodies over HTTP/2

HTTP/2 has no chunked transfer encoding: length is a property of the DATA frames, not of the body bytes. A chunk-framed body handed to the h1-to-h2 reframing would reach the origin with its size lines and CRLFs as literal content, so the proxy used to route such requests down the HTTP/1.1 path instead (correct, just not h2).

fissure_http2_dechunk_request rewrites the request first: the chunk data is concatenated, Transfer-Encoding is dropped, and a real Content-Length is stated. The rest of the head is untouched. The proxy runs it before choosing the upstream protocol, so a chunked request now goes over h2 like any other.

Two deliberate limits:

  • Malformed chunk framing is REFUSED, not half-converted. A truncated chunk would otherwise produce a request whose Content-Length lies about its body; instead the request stays on the HTTP/1.1 path unchanged.
  • An Upgrade request still cannot go over h2 at all, because HTTP/2 forbids the header. A WebSocket handshake sent over h2 would silently fail, so those keep taking the h1 path.