Marasi is an application security testing proxy controlled through the marasi CLI.
It captures HTTP, HTTPS, and WebSocket traffic, stores assessment data in SQLite
projects, and supports Lua extensions. The proxy is also available as a Go library.
- Captured traffic with complete HTTP requests and responses, metadata, and notes.
- Checkpoint to hold, forward, and drop in-flight requests, responses, and WebSocket messages.
- WebSocket inspection, frame injection, and live connection control.
- Launchpad to group captured pairs and launch modified raw HTTP requests.
- Armory request templates with payload positions and wordlist-driven runs.
- Test cases, findings, and artifacts to record assessment work and link evidence.
- Report generation with configurable templates.
- Lua extensions with settings, logs, and callable functions.
- Scope rules and waypoints for traffic filtering and host-and-port routing.
- Chrome profiles and launch with proxy settings.
- SQLite
.marasiprojects that store traffic and assessment data.
New projects include the compass, checkpoint, and workshop Lua extensions.
compass manages scope rules. checkpoint supplies rules for which traffic
Checkpoint holds. workshop provides a Lua development environment.
Each named service instance runs as a detached process and owns one open project.
service start returns after the instance is ready. The CLI sends HTTP control API
requests over a per-instance Unix-domain socket on macOS, Linux, and Windows.
The control listener and proxy listener are separate. Stopping the proxy listener
leaves the service instance available for inspection. service stop shuts down
the service instance. service restart hands the instance name, open project,
and proxy listener address to a new instance started from the installed build.
If the new instance does not become ready, the old one keeps running. A restart
ends Armory runs, held Checkpoint items, live connections, and launches. It is
refused while Checkpoint items are held unless --force is given.
Projects are SQLite .marasi files. A project can be owned by only one service
instance at a time. project open changes the open project without restarting
the proxy listener.
The source requires Go 1.26 or later. These commands run from the repository root.
| Command | Result |
|---|---|
make build |
Builds dist/marasi for this machine without CGO. |
make install |
Builds and installs marasi in $HOME/.local/bin. PREFIX overrides $HOME/.local. |
make windows-amd64 |
Builds dist/marasi-windows-amd64.exe. |
make all |
Builds the targets listed by TARGETS in Makefile. |
make test |
Runs go test ./.... |
make autobahn |
Runs the Autobahn WebSocket testsuite in Docker through a Marasi service instance. It prints each case whose verdict, close code, or clean close differs from the committed direct baseline, and exits non-zero on any deviation outside 9.x. |
make autobahn-baseline |
Runs the selected cases with no proxy and merges them into internal/autobahn/baseline/. |
The Autobahn targets need Docker with host networking. Both modes
(fuzzingclient, fuzzingserver) run against two peers: Autobahn's strict
testee and the harness's lenient echo peer. make autobahn runs four runs:
proxy (no interception), checkpoint-forward (global WebSocket Checkpoint
with an auto-resolver that forwards each item unchanged), checkpoint-edit (the
resolver forwards each item as an edit with the same bytes), and extension (a
workshop processWebSocketMessage sets each payload to itself). Variables narrow
a run:
make autobahn CASES='3.*,7.9.*' RUNS=proxy MODES=fuzzingclient PEERS=strict
make autobahn EXCLUDE='9.*,12.*,13.*' VERBOSE=1Reports are written to dist/autobahn/<run>/<mode>-<peer>/ and the run log to
dist/autobahn/autobahn.log. RUNS=direct,proxy refreshes the baseline before
comparing. On an arm64 Mac, where the amd64 image runs under emulation, the
direct baseline takes about 20 minutes and a full make autobahn about 30. The
strict peers negotiate permessage-deflate, so 12.x and 13.x are most of a direct
strict suite.
The Autobahn workflow in GitHub Actions runs the full suite on every pull
request that changes a path in its paths filter, every Monday, and when you
start it manually. The filter includes db/ and proxy.go because a WebSocket
relay waits on the database writer's queue: a change that slows the writer can
fail a case even though it touches no WebSocket code. A job fails on any
deviation from the committed baseline. On a failure, the job's artifact holds
the per-case reports, Marasi's log, and a resource log, and the job log shows
kernel OOM messages.
Run it locally on a change to the same paths:
-
Before you push, run the quick check. It skips the large-message (9.x) and compression (12.x, 13.x) sections and takes about 7 minutes:
make autobahn EXCLUDE='9.*,12.*,13.*' -
Before you merge, run the full suite. It takes about 1.5 to 2 hours on an arm64 Mac:
make autobahn
Both commands exit non-zero on a deviation from the committed baseline. The
6.4.1 to 6.4.4 cases are allowed and listed separately. If a deviation looks
unrelated to the change, run make autobahn-baseline and compare the
baseline diff before you commit it: the baseline changes only with the pinned
Autobahn image or the harness.
A build without Make uses go build -o marasi ./cmd/marasi, or
go build -o marasi.exe ./cmd/marasi on Windows. If a parent go.work excludes
the checkout, GOWORK=off disables that workspace for builds and tests.
marasi --help lists commands. Each command's --help lists its subcommands,
arguments, and flags. The examples below use an installed marasi binary.
The global flags are:
| Flag | Meaning |
|---|---|
--instance NAME |
Selects a service instance. Defaults to default. |
--config-dir PATH |
Selects the machine config directory. |
--json |
Prints command output as JSON. events, update install, and update reinstall emit one JSON object per line. |
This start command creates or opens the named project assessment and starts
the service instance assessment with a proxy listener at 127.0.0.1:8080:
marasi --instance assessment service start --project-name assessment --address 127.0.0.1 --port 8080 --json--port 0 requests an allocated port. The start result reports the bound address.
Without a project flag, service start opens the named project scratchpad.
Other service and project commands include:
marasi --instance assessment service status --json
marasi service list --json
marasi project list --json
marasi --instance assessment project open --name another-assessment --json
marasi --instance assessment service restart --json
marasi --instance assessment service stop --jsonservice status and service list report restart required: yes when the
installed build changed after the instance started. service restart moves the
instance to the installed build and keeps its name, project, and proxy listener.
A running service instance checks for and installs updates. With no running
instance, the update commands fail and tell you to start one with
marasi service start.
marasi update # installed build, channel, available update
marasi update check # check the channel now
marasi update install # install the update and follow its progress
marasi update channel # print the channel
marasi update channel nightly # switch to release or nightly
marasi update reinstall --yes # install the latest build on the channel, even if oldermarasi update shows the first lines of the update's release notes and a link
to the release page. --json returns the full notes. update install writes
its steps (download, verify, install) to stderr. With --json it writes each
update.progress, update.installed, or update.failed event as one JSON
line. It exits 1 when the install fails. Ctrl-C stops following, but the
install continues on the instance. marasi update shows its state.
The instance replaces its own executable, with symlinks resolved. Running
instances keep their build until service restart. Switching channel never
installs a build. From nightly to release, the installed nightly stays until a
newer release exists. update reinstall installs the latest release now. It
requires --yes, because projects opened in a newer build may not open in it.
These commands inspect stored traffic, subscribe to live events, and export the loaded CA certificate:
marasi --instance assessment traffic list --limit 20 --json
marasi --instance assessment traffic list -q 'host = "example.com" AND method = "GET" AND status_code = 200' --json
marasi --instance assessment traffic get UUID --json
marasi --instance assessment events --json
marasi --instance assessment certificate get > marasi-ca.pemtraffic list -q (or --query) takes an AIP-160 query, sent to the control API
as GET /traffic?q=. It combines exact field conditions such as
host = "api.example.com" with text search such as response_body:"password",
note:"idor candidate", metadata:"workshop", or bare "hbGci". Run marasi traffic list --help for the fields. In a
query, OR binds tighter than AND, so a AND b OR c means a AND (b OR c).
An invalid query returns 400
{"error":"invalid_query","message":"...","position":N}.
traffic list --exclude 'image/*' (repeatable, GET /traffic?exclude=) hides
pairs of a content type: an exact type, or a whole major type such as image/*.
Pairs with no content type yet are never hidden. Each page reports
next_cursor, prev_cursor and as_of. Cursors are opaque: pass one back with
--cursor, adding --backward to walk toward newer pairs, and pass as_of
back with --as-of so later pages leave out pairs captured since the first.
--order-by (order_by=) sorts by one of requested_at, number, method,
host, path, status_code, content_type or length, with an optional
desc; the default is requested_at desc. Pairs with no response sort last.
Every pair has a number, its position in capture order from 1. Numbers never
change and are never reused, and -q 'number = 10' finds one pair.
A malformed cursor, or one from another sort, returns 400
{"error":"invalid_cursor","message":"..."}.
These commands count, check, and change traffic in bulk, and manage background jobs and client settings:
marasi --instance assessment traffic count -q 'status_code >= 500' --json
marasi --instance assessment traffic types --json
marasi --instance assessment traffic sitemap --node 'https://api.example.com' --json
marasi --instance assessment traffic validate -q 'host = "api.example.com"'
marasi --instance assessment traffic bulk highlight 3 --id UUID --id UUID
marasi --instance assessment traffic bulk note append 'checked' -q 'path = "/api/*"' --as-of UUID
marasi --instance assessment traffic bulk delete --ids-file ids.txt
marasi --instance assessment jobs list --json
marasi --instance assessment settings list my-client --jsontraffic bulk commands (highlight, link, unlink, metadata set,
metadata clear, note append, note clear, delete) take exactly one
selection: --id (repeatable) or --ids-file (- for stdin), or -q with a
required --as-of and optional --exclude. They print the number of pairs
changed and do not ask for confirmation. traffic validate exits non-zero
with the message and position when a query, exclusion, or sort is invalid.
settings manages client settings: JSON values a client stores in the project
under its own name and a key.
UUID denotes an ID returned by traffic list. Raw request and response bytes
are base64-encoded in JSON output. Events are live notifications with no replay.
Traffic events can arrive before the matching row is persisted.
HTTPS inspection requires the client to trust Marasi's CA certificate. The exported CA certificate contains no private key. All service instances that use the same config directory share the CA.
A client that uses the proxy listener can reach Marasi's own pages at the host
marasi, over HTTP or HTTPS. Marasi answers these requests itself. They are
never captured, held by Checkpoint, or shown to extensions.
| URL | Answer |
|---|---|
http://marasi/cert |
The CA certificate in DER form, as marasi-cert.der. |
http://marasi/view/{uuid} |
A browser view of the pair with that UUID. |
A browser view shows a pair's stored response, unchanged, at the pair's
original URL, without contacting the origin. http://marasi/view/{uuid}
redirects to the original URL with Cache-Control: no-store. The next request
to that exact URL from the same client address, with any method, gets the
stored response, including its Set-Cookie, HSTS and cache headers. Only that
one request is served from storage. Everything the page then loads goes to the
live site and is captured as usual. A browser view expires if its redirect is
not followed within 10 seconds, and a newer browser view of the same URL from
the same client address replaces it. Launches and Armory runs never use one.
The URL takes the pair's UUID, not its number. Clients build it themselves; there is no control API or CLI call to make first. Marasi answers in plain text with 404 when the open project has no pair with that UUID, and with 409 when the pair has no response yet or is a WebSocket upgrade.
The default config directory is Marasi under os.UserConfigDir():
| Platform | Default location |
|---|---|
| macOS | ~/Library/Application Support/Marasi |
| Linux | $XDG_CONFIG_HOME/Marasi, or ~/.config/Marasi when unset |
| Windows | %AppData%\Marasi |
Named projects live at <config-dir>/projects/<name>.marasi. Project files store
traffic, notes, metadata, proxy logs, extensions, waypoints, launchpads, Armory
templates and runs, test cases, findings, and artifacts.
The config directory also contains marasi_config.yaml, shared CA material,
Chrome configuration, wordlists/, and report templates/. Each service instance has
an instances/<name>.sock control socket and an instances/<name>.log process log.
Proxy logs are stored in the project, not in the process log.
marasi_config.yaml has an updates section:
updates:
channel: nightly # release or nightly; unset follows the installed build's channel
auto_check: false # unset or true checks on start and every 6 hoursmarasi update channel writes updates.channel. Instances share the last
check of each channel in update_check.json, guarded by update_check.lock,
so instances on one config directory call GitHub once per 6 hours. A
development build never checks for updates.
The control socket path, including its terminating byte, cannot exceed 104 bytes.
Windows also requires an absolute socket path. A short absolute --config-dir
avoids both limits.
The Go library uses marasi.New and option functions to configure the proxy.
Callback data types live in domain. The service package provides the HTTP
control API and its Unix-socket client.
go get github.com/tfkr-ae/marasi- Go package reference documents the library API.
- CLI startup implementation shows how the service connects the proxy and project resources.
- Glossary defines the project's terms.
- Architecture decisions record API and lifecycle contracts.
- Live CLI verification guide covers verification with isolated service instances.
- GitHub Discussions hosts questions and feedback.