Rules
Rule Types

Rule Types

By writing rules, you can specify different outbound methods for different connections, such as forwarding through a proxy or intercepting. You can match based on the connection's IP, domain name, process name, or a combination of multiple conditions.

For each connection, rules are always matched from top to bottom.

Rules can be classified into two types, where IP type may trigger DNS resolution:

  • Based on domain name
  • Based on IP
  • Other composite types
💡

Want to write rules for URLs? Please read the HTTP Rewrite section.

💡

You can add the no-track parameter at the end of the rule to hide the connection matched by this rule, such as SCRIPT,quic,REJECT,no-track.

Typically, this is very effective in avoiding a large number of REJECT records filling the page.

DOMAIN

Exact match of domain name.

DOMAIN-SUFFIX

Match domain name suffix, such as DOMAIN-SUFFIX,google.com matches google.com and www.google.com.

DOMAIN-KEYWORD

Keyword match of domain name.

GEOIP

Match country code through MaxMind GeoIP, such as CN, and no-resolve can be added to avoid triggering DNS resolution.

💡

Stash allows users to replace databases that conform to the MaxMind GeoIP format. Users can choose a MaxMind GeoIP database that is more suitable for their own scenarios according to their needs.

IP-ASN

Match IP autonomous system number, such as 714, and no-resolve can be added to avoid triggering DNS resolution.

IP-CIDR / IP-CIDR6

IP CIDR range, and no-resolve can be added to avoid triggering DNS resolution.

DST-PORT

Destination port.

RULE-SET

Rule set, please refer to Rule Set.

PROCESS-NAME

Process name, such as Telegram, only valid for local processes.

⚠️

Due to the limitations of Network Extension, PROCESS-NAME rules are not supported in Stash for iOS (including the iOS version running on Apple silicon devices), and process-related rules in the configuration will be ignored.

PROCESS-PATH

Process path, such as /Applications/Telegram.app/Contents/MacOS/Telegram, only valid for local processes.

⚠️

Due to the limitations of Network Extension, PROCESS-PATH rules are not supported in Stash for iOS (including the iOS version running on Apple silicon devices), and process-related rules in the configuration will be ignored.

SCRIPT

Match requests through Python expressions, where the expression must return a Boolean value, and expressions that execute errors will be skipped.

The expression can read the following variables:

{
  "network": "string", // one of tcp / udp
  "host": "string", // may be empty
  "dst_ip": "string", // may be empty
  "dst_port": "number",
  "src_ip": "string", // only works with gateway mode
  "src_port": "number" // only works with gateway mode
}

The expression can call the following functions:

def resolve_ip(host: str) -> str:
    pass
 
def in_cidr(ip: str, cidr: str) -> bool:
    pass
 
def geoip(ip: str) -> str:
    pass
 
def ipasn(ip: str) -> int:
    pass
 
def match_provider(name: str) -> bool:
    pass

For example, to intercept requests using the QUIC protocol, you can write:

rules:
  - SCRIPT,quic,REJECT
  - SCRIPT,udp-cn,ProxyToCN
 
script:
  shortcuts: # can be referenced in rules
    quic: network == 'udp' and dst_port == 443 # match QUIC protocol
    udp-cn: network == 'udp' and geoip(dst_ip if dst_ip != '' else resolve_ip(host)) == 'CN' # match UDP to CN