Skip to content
tfkr-aePublic

About

Application Security Testing Proxy Library

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

696 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Marasi

Go reference

Marasi

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.

marasi.app

Features

  • 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 .marasi projects 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.

Service mode and CLI

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.

Build and test commands

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=1

Reports 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.

Autobahn checks

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:

  1. 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.*'
  2. 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.

CLI flags

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.

Service commands

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 --json

service 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.

Update commands

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 older

marasi 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.

Traffic and CA certificate commands

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.pem

traffic 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 --json

traffic 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.

Marasi's own pages

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.

Storage and configuration

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 hours

marasi 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.

Library mode

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

Project documentation

About

Application Security Testing Proxy Library

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages