Once you have traffic going through Marasi, you will start seeing a lot of requests in your Ledger that may not be relevant to your scope. To configure your scope, use the Compass feature: click on the app rail menu icon or press ⌘/Ctrl+3.

Default Compass View

Under the hood, the Compass is an extension in Marasi. This means that you can configure it at runtime with Lua and use the built-in hooks to process both requests and responses.

Default Scope

Let’s break down the default scope that is configured for each project, starting with defining and using the scope object:

local scope = marasi:scope() 

-- Rule Management
scope:add_rule("rule", "type") -- Adds a rule to the scope, the first argument is a Regex string, and the type is either "host" or "url"
scope:remove_rule("rule", "type") -- Removes a rule from the scope, the first argument is a Regex string, and the type is either "host" or "url"
scope:clear_rules() -- Clear all defined rules on scope object

--  Default Policy
scope:set_default_allow(bool) -- Sets the default allow policy, by default this is true, this means that any request / response that does not match a specific rule is allowed through the proxy

-- Matching
scope:matches(req_or_res) -- Matches rules against a request / response object
scope:matches_string("input", "type") -- Matches rules for a given type against a string input.


-- Skipping Requests
function processRequest(request)
  if not scope:matches(request) then
      request:skip() -- This will skip the request, and forward it without processing through Marasi.
  end
end

-- Dropping Requests
function processRequest(request)
  if not scope:matches(request) then
      request:drop() -- This will drop the request, it will be dropped and not sent to the destination server.
  end
end

Using the Scope Tester

You can test your Compass configuration by using the scope tester. Press ⌘/Ctrl+P to toggle the top accordion or click Compass Settings.

Scope Tester

The scope tester will tell you which rule, and type (host / URL) it matched against.

Common Scenarios

Let’s go through a few scenarios and how you would configure Compass for them.

Only log traffic that is in-scope

This is a strict configuration that would only log the requests that match the scope, the rest are all passed through Marasi without logging.

Once you have updated the Lua code, press ⌘/Ctrl+Shift+R to reload with your changes.

local scope = marasi:scope()
scope:clear_rules()
scope:set_default_allow(false) -- Default Policy is set to not allow unmatched traffic
scope:add_rule([[marasi\.app]], "host") -- Only match requests with the host name matching marasi.app

function processRequest(request)
  if not scope:matches(request) then
      request:skip() -- Skip the request processing
  end
end

function processResponse(response)
  if not scope:matches(response) then
      response:skip()
  end
end

If you reload your Compass and begin browsing, you will notice that only requests to https://marasi.app are being logged, you can also confirm this with the scope tester. https://google.com is considered to be out of scope as the default allow policy is set to false.

Strict Scope

Drop traffic that is not in-scope

Imagine the same scenario, but you wanted to drop all the requests that are not strictly in-scope. The configuration would be the same with the drop() method being used instead of skip()

local scope = marasi:scope()
scope:clear_rules()
scope:set_default_allow(false) -- Default Policy is set to not allow unmatched traffic
scope:add_rule([[marasi\.app]], "host") -- Only match requests with the host name matching marasi.app

function processRequest(request)
  if not scope:matches(request) then
      request:drop() -- Drop the request
  end
end

function processResponse(response)
  if not scope:matches(response) then
      response:drop()
  end
end

Conditional Scoping

As the Compass is an extension, you are able to do some additional processing to build your scope. For example, if you have httpbin.org as an in-scope item but only want to log requests with a specific header value.

local scope = marasi:scope()
scope:clear_rules()
scope:set_default_allow(false)
scope:add_rule([[httpbin\.org]], "host")

function processRequest(request)
  if scope:matches(request) then
    if not request:headers():has("X-Scope-Test") then -- We check for the "X-Scope-Test" header if the request matches the scope
       request:skip() 
    end
  end
  if not scope:matches(request) then
      request:skip()
  end
end

function processResponse(response)
  if not scope:matches(response) then
      response:skip()
  end
end

The Compass is very powerful and is being enhanced to unlock more capabilities for dynamically working with your scope. Now that you are able to define a custom scope to match your needs, let’s move on to the Checkpoint, which will allow you to intercept and modify requests.