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:
- 00_MASTER_PLAN.md
- 02_ARCHITECTURE.md
- 03_GUI_DESIGN.md
- 05_WEBSITE_SCANNER.md
- 06_REPORTING.md
- audits/HOOK_AUDIT.md
- audits/NILOREA_AUDIT.md
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:
- an explicit
User-Agentrequest header the operator set (wins, and aUser-Agentline incfg->extra_headersis honored here too, without the builder synthesizing a duplicate); req->user_agent, a per-request override (the Repeater's request-bar picker, or the control-API/MCPuser_agentfield on a single send);cfg->user_agent, a per-run override (theuser_agentfield on a scan or intruder job);- the process default, set by
fissure_engine_set_default_user_agentfrom the active preset selection at boot and whenever the selection changes; - 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):
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 withnetw_make_listening(listen, "127.0.0.1", port, backlog, ip_version); - an accept loop thread calling
netw_accept_from(listen); each acceptedNETWORK*is dispatched to a per-connection worker (section 6); - a borrowed scope (
fissure_scope, section 8.2); - the captured flows: a list of
PROXY_FLOWrecords (private tofissure_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 withfissure_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_cookiesonPOST /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:
- The worker replies
HTTP/1.1 200 Connection Establishedto the client. - 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.
- It installs that leaf cert/key on the client-facing
NETWORK*(in-memory PEM) and completesSSL_accept()via n_network's server-side TLS path. - Separately it opens a TLS client connection to the real
upstream (
netw_ssl_connect_client_towith 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). - 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_socksshutdown handshake, section 6) spawns one worker per connection. The worker connects upstream (netw_connect_to, ornetw_ssl_connect_client_towhen the upstream leg is TLS) and pumps both directions withpoll()over the two sockets, TLS-aware on each leg (SSL_read/SSL_writevsrecv/send), exactly like the proxy'spump_bidirectional.
- per-connection detached workers + the
- 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 breakaccept, 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_newcallsn_x509_generate_cawithFISSURE_CA_CNandFISSURE_CA_DAYS("Fissure Proxy CA", 3650 days) and persistsca-cert.pem+ca-key.pemunder<config>/ca/, file mode 0600 on the key. Leaves are minted forFISSURE_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, aHASH_TABLEkeyed by lowercased host whose value holds the leaf cert + key PEM pair, with aleaf_orderlist for FIFO eviction pastFISSURE_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_FLOWrecord (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 withn_url_canonicalize_stringand 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_detachinfissure_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
runningflag (section 5.1b), so no worker depends on another thread'sshutdown(). - 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_workerscounter (__atomic) and registers its client socket;fissure_proxy_stopdrains the intercept queue, shuts every registered worker socket down, and loops untilactive_workersreaches zero, becausefissure_proxy_freedestroys 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) andfissure_intruder_run_request(method + URL + headers + body templates): send every generated request through the engine on ann_thread_poolofmax_threads, with a delay, retries, a stop flag, an optionalFISSURE_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_sslfor 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)), wheredirect://also means no upstream. - Config: a global upstream proxy URL + a
no_proxypassthrough list (exact host,.suffixfor 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
Upgradeand the upstream answers101 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 withn_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 nilorean_network), independently of the proxy's own verification mode. The result (trusted, orUNTRUSTED: <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.cis 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) andN_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 isn_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-Lengthlies about its body; instead the request stays on the HTTP/1.1 path unchanged. - An
Upgraderequest 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.