Customizing Rules
Relevant source files
The following files were used as context for generating this wiki page:This project, based on ACL4SSR, provides a system for managing and customizing network traffic diversion rules for proxy clients like Clash and sing-box. The core of the system is a collection of simple .list files that serve as the source of truth. These lists are processed by Python scripts to generate client-specific configuration files, enabling a centralized and automated way to maintain complex rule sets.
The primary goal is to create tailored rule configurations for different use cases, such as proxying specific services, bypassing local traffic, and blocking ads. The repository includes comprehensive rule lists like a GFW list, a "lite" proxy list, and specialized rule sets for services like AI, developers, and academic websites.
Sources: README.md, update_providers.py, update_sing_box.py
Rule Generation Workflow
The repository uses Python scripts to automate the conversion of source .list files into formats compatible with Clash and sing-box. This workflow ensures that all rule sets are consistently generated from a single source.
The following diagram illustrates the general data flow from source files to final client configurations.
Sources: update_providers.py, update_sing_box.py
Clash Provider Generation
The update_providers.py script scans the Clash directory (excluding config and Providers subdirectories) for .list files. For each .list file found, it generates a corresponding .yaml provider file in the Clash/Providers/ directory.
The script performs the following actions:
- Reads each line from the source
.listfile. - Adds a
payload:header to the output.yamlfile. - Converts rule lines into a YAML list format (e.g.,
DOMAIN-SUFFIX,example.combecomes- DOMAIN-SUFFIX,example.com). - Comments out lines that are not standard Clash rules, such as
USER-AGENT,URL-REGEX, andPROCESS-NAME. - Preserves comments from the original file.
This process is visualized in the flowchart below.
Sources: update_providers.py:12-38
sing-box Rule Generation
The update_sing_box.py script converts .list files into compiled .srs rule sets for the sing-box client. This involves an intermediate step of creating a JSON file.
The script's workflow is as follows:
- It searches for
.listfiles in theClashdirectory, similar to the provider script. - It parses each line of a
.listfile and maps it to a corresponding field in aHeadlessRulePython object. - The
HeadlessRuleobject is wrapped in aRuleobject, which is then serialized into a JSON file in thesing-box/directory. - The
sing-box rule-set compilecommand is executed on the generated JSON file to create a binary.srsfile. - The intermediate JSON file is deleted.
The Python data structures used for this conversion are defined as follows:
# Source: update_sing_box.py:15-50
@dataclass
class HeadlessRule:
query_type: typing.List[typing.Union[int, str]] = None
network: list[str] = None
domain: list[str] = None
domain_suffix: list[str] = None
domain_keyword: list[str] = None
domain_regex: list[str] = None
source_ip_cidr: list[str] = None
ip_cidr: list[str] = None
source_port: list[int] = None
source_port_range: list[str] = None
port: list[int] = None
port_range: list[str] = None
process_name: list[str] = None
process_path: list[str] = None
package_name: list[str] = None
wifi_ssid: list[str] = None
wifi_bssid: list[str] = None
invert: bool = None
# ... methods ...
@dataclass
class Rule:
version: int = 2
rules: list[HeadlessRule] = None
# ... methods ...
The following diagram shows the class relationship.
Sources: update_sing_box.py:15-50
Rule Formats
The repository uses several file formats for defining and generating rules.
| File Type | Directory | Purpose |
|---|---|---|
.list | Clash/ | Source of truth for rule definitions. Manually edited. |
.yaml | Clash/Providers/ | Generated rule providers for the Clash client. |
.json | sing-box/ (temporary) | Intermediate JSON format for sing-box rule generation. |
.srs | sing-box/ | Compiled binary rule set for the sing-box client. |
.acl | Tool/ | A custom rule format, with tooling for conversion from Surge. |
.xml | Tool/ | Notepad++ configuration for syntax highlighting and macros. |
Sources: update_providers.py, update_sing_box.py, Tool/Surge转acl工具/acl自定义语言格式文件.xml
Source .list Format
The .list files use a simple TYPE,VALUE format. The update_sing_box.py script shows which types are parsed and mapped to sing-box rules.
| Rule Type | Description | Example |
|---|---|---|
DOMAIN | Matches a specific domain. | DOMAIN,example.com |
DOMAIN-SUFFIX | Matches a domain and all its subdomains. | DOMAIN-SUFFIX,example.com |
DOMAIN-KEYWORD | Matches if a keyword is present in the domain. | DOMAIN-KEYWORD,example |
DOMAIN-REGEX | Matches a domain against a regular expression. | DOMAIN-REGEX,^.*\.example\.com$ |
IP-CIDR / IP-CIDR6 | Matches an IP address or range. | IP-CIDR,192.168.1.0/24 |
SOURCE-IP-CIDR | Matches the source IP address. | SOURCE-IP-CIDR,10.0.0.0/8 |
SRC-PORT | Matches the source port. | SRC-PORT,80 |
DST-PORT | Matches the destination port. | DST-PORT,443 |
PROCESS-NAME | Matches by process name. | PROCESS-NAME,curl.exe |
PROCESS-PATH | Matches by full process path. | PROCESS-PATH,/usr/bin/curl |
Sources: update_sing_box.py:86-119
ACL Format
The repository includes tools for working with a custom .acl format, likely for use with other clients or for conversion. A Notepad++ User Defined Language file defines its syntax, highlighting section headers as keywords.
Key sections defined in the ACL format:
[proxy_all][bypass_all][outbound_block_list][bypass_list][proxy_list]
Sources: Tool/Surge转acl工具/acl自定义语言格式文件.xml:28
Macros are provided in shortcuts.xml to convert Surge rules into this ACL format using regular expressions.
Key Configuration & Rule Sets
Clash General Configuration
The Clash/GeneralClashConfig.yml file contains general settings for the Clash client. A key area for direct rule customization is the cfw-bypass list, which specifies domains and IP ranges that should bypass the system proxy in Clash for Windows.
# Source: Clash/GeneralClashConfig.yml:230-248
# 系统代理跳过列表 起作用的
cfw-bypass:
# 直连列表
# MyList
- "*.13th.tech"
- "*.423down.com"
- "*.bokecc.com"
# ... more domains
# CN域名直连(中国|公司|网络)
- "*.cn"
- "*.xn--fiqs8s"
- "*.xn--55qx5d"
- "*.xn--io0a7i"
# 中国国内常见域名关键词直连
- "*360buy*"
- "*alicdn*"
- "*alipay*"
# ... more keywords
This list is extensive and categorizes bypass rules for common Chinese domains, services, and CDNs to ensure they are accessed directly.
Sources: Clash/GeneralClashConfig.yml:230-844
Rule Set Providers
The Clash/Providers/ directory contains the generated .yaml files, which act as rule providers. These are organized into logical groups.
| Provider File | Purpose |
|---|---|
ProxyGFWlist.yaml | A comprehensive list of domains and IPs to be proxied, based on the GFW list. |
ProxyLite.yaml | A smaller, curated list of domains and IPs to be proxied. |
Ruleset/AI.yaml | Contains rules for common AI services like OpenAI, Gemini, and Claude. |
Ruleset/Developer.yaml | Rules for developer tools and sites like Docker, GitLab, and Stack Overflow. |
Ruleset/Scholar.yaml | Rules for academic websites and research platforms. |
Ruleset/Github.yaml | Specific rules for GitHub domains. |
Microsoft.yaml | Rules for various Microsoft services, including Office 365 and Azure. |
UnBan.yaml | A whitelist of domains that should not be blocked by ad-blocking rules. |
Sources: Clash/Providers/ProxyGFWlist.yaml, Clash/Providers/ProxyLite.yaml, Clash/Providers/Ruleset/AI.yaml, Clash/Providers/Ruleset/Developer.yaml, Clash/Providers/Ruleset/Scholar.yaml, Clash/Providers/Ruleset/Github.yaml, Clash/Providers/Microsoft.yaml, Clash/Providers/UnBan.yaml
An example from AI.yaml shows how rules are structured inside a provider file:
# Source: Clash/Providers/Ruleset/AI.yaml:1-10
payload:
# 内容：内容：AI平台-国外
# 数量：39条
- DOMAIN-KEYWORD,anthropic
- DOMAIN-KEYWORD,claude
- DOMAIN-KEYWORD,openai
- DOMAIN,ai.google.dev
- DOMAIN,api.githubcopilot.com
Sources: Clash/Providers/Ruleset/AI.yaml:1-10