主机列表编译器
这是一个简单的工具,可以更容易编译 主机块列表 与AdGuard Home或任何其他AdGuard产品兼容 DNS 过滤。 。 。 .
关于储存库的说明: 积极发展发生在私人 辅助软件Limited/filters-hostlist-编译器 寄存器; 此公开 守护小组/主机编制器 寄存器是一个只读的镜像,从中自动更新.
使用量
首先,安装 hostlist-compiler数字 :
npm i -g @adguard/hostlist-compiler
之后你有两个选择.
快速主机转换
转换和压缩 a /etc/hosts- 语法块列表到 守护语法。 。 。 .
hostlist-compiler -i hosts.txt -i hosts2.txt -o output.txt
从多个来源建立可配置的块列表
准备列表配置( 更多信息 ) 下级)并运行编译器:
hostlist-compiler -c configuration.json -o output.txt
所有命令行选项
Usage: hostlist-compiler [options]
Options:
--config, -c Path to the compiler configuration file [string]
--input, -i URL (or path to a file) to convert to an AdGuard-syntax
blocklist. Can be specified multiple times. [array]
--input-type, -t Type of the input file (/etc/hosts, adguard) [string]
--output, -o Path to the output file [string] [required]
--verbose, -v Run with verbose logging [boolean]
--version Show version number [boolean]
-h, --help Show help [boolean]
Examples:
hostlist-compiler -c config.json -o compile a blocklist and write the
output.txt output to output.txt
hostlist-compiler -i compile a blocklist from the URL and
https://example.org/hosts.txt -o write the output to output.txt
output.txt
配置
配置定义您的过滤列表源, 以及应用到源上的转换 .
以下是此配置的一个例子:
{
"name": "List name",
"description": "List description",
"homepage": "https://example.org/",
"license": "GPLv3",
"version": "1.0.0.0",
"sources": [
{
"name": "Local rules",
"source": "rules.txt",
"type": "adblock",
"transformations": ["RemoveComments", "Compress"],
"exclusions": ["excluded rule 1"],
"exclusions_sources": ["exclusions.txt"],
"inclusions": ["*"],
"inclusions_sources": ["inclusions.txt"]
},
{
"name": "Remote rules",
"source": "https://example.org/rules",
"type": "hosts",
"exclusions": ["excluded rule 1"]
}
],
"transformations": ["Deduplicate", "Compress"],
"exclusions": ["excluded rule 1", "excluded rule 2"],
"exclusions_sources": ["global_exclusions.txt"],
"inclusions": ["*"],
"inclusions_sources": ["global_inclusions.txt"]
}
name- (强制性)名单名称.description- (可选)列表描述.homepage- (可选)列表主页的 URL .license- (可选)过滤列表许可证.version- (可选)过滤器列表版本.sources- 列表来源的(强制性)数组..source- 来源的(强制性)路径或URL。 它可以是传统的过滤列表或主机文件..name-(可选)来源名称..type- 来源的(可选)类型。 这可能是adblock用于块状列表或hosts用于/etc/hosts样式列表。 如未指明,adblock假设..transformations- (可选)适用于源规则的转换列表。 默认, 无变换 适用。 更多地了解可能的转变 这里。 。 。 ..exclusions- (可选的)规则列表(或通配符)以排除来源..exclusions_sources- (可选的)包含排除内容的文件列表..inclusions- (可选)包含来自源代码的通配符列表. 所有与这些通配符不相匹配的规则都不会包含在内..inclusions_sources- (可选)包含内容的文件列表.
transformations- (可选)适用于最终规则清单的转换列表。 默认, 无变换 适用。 更多地了解可能的转变 这里。 。 。 .exclusions- (可选的)规则列表(或通配符)以排除来源.exclusions_sources- (可选的)包含排除内容的文件列表..inclusions- (可选)包含来自源代码的通配符列表. 所有与这些通配符不相匹配的规则都不会包含在内..inclusions_sources- (可选)包含内容的文件列表.
以下是一个最小配置的例子:
{
"name": "test list",
"sources": [
{
"source": "rules.txt"
}
]
}
不适用和列入规则
请注意,排除或纳入规则可能是一种平庸的字符串、通配符或正则表达式.
plainstring- 所有包含plainstring将会符合规则*.plainstring- 每条规则都符合通配符规则/regex/– 符合此正则表达式的规则, 都会符合规则 。 默认情况下,正则表达式为对大小写不敏感.! comment- 评论将被忽略.
[大 确保排除列表中的规则与过滤列表中的规则格式相匹配. 为保持统一格式,请添加
Compress转换为转换/etc/hosts用于阻塞语法的规则. 如果有多个不同格式的列表,则这样做特别有用.
以下是一个例子:
HOSTS语法规则 : /hosts.txt
0.0.0.0 ads.example.com
0.0.0.0 tracking.example1.com
0.0.0.0 example.com
街区语法中的排除规则: /exclusions.txt
||example.com^
最后列表的配置 :
{
"name": "List name",
"description": "List description",
"sources": [
{
"name": "HOSTS rules",
"source": "hosts.txt",
"type": "hosts",
"transformations": ["Compress"]
}
],
"transformations": ["Deduplicate", "Compress"],
"exclusions_sources": ["exclusions.txt"]
}
最后过滤输出 /hosts.txt 应用后 Compress 变革和排斥:
||ads.example.com^
||tracking.example1.com^
现在最后一个规则 ||example.com^ 将正确匹配排除名单中的规则,并被排除在外.
命令行
命令行参数.
Usage: hostlist-compiler [options]
Options:
--version Show version number [boolean]
--config, -c Path to the compiler configuration file [string] [required]
--output, -o Path to the output file [string] [required]
--verbose, -v Run with verbose logging [boolean]
-h, --help Show help [boolean]
Examples:
hostlist-compiler -c config.json -o compile a blocklist and write the
output.txt output to output.txt
API 密码
安装 : npm i @adguard/hostlist-compiler 或者说 yarn add @adguard/hostlist-compiler
JavaScript 示例 :
const compile = require("@adguard/hostlist-compiler");
;(async () => {
// Compile filters
const result = await compile({
name: 'Your Hostlist',
sources: [
{
type: 'adblock',
source: 'https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt', // or local file
transformations: ['RemoveComments', 'Validate'],
},
],
transformations: ['Deduplicate'],
});
// Write to file
writeFileSync('your-hostlist.txt', result.join('\n'));
})();
类型脚本示例 :
import compile from '@adguard/hostlist-compiler';
import { writeFileSync } from 'fs';
;(async () => {
// Compile filters
const result = await compile({
name: 'Your Hostlist',
sources: [
{
type: 'adblock',
source: 'https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt',
transformations: ['RemoveComments', 'Validate'],
},
],
transformations: ['Deduplicate'],
});
// Write to file
writeFileSync('your-hostlist.txt', result.join('\n'));
})();
或:
import HostlistCompiler, { IConfiguration as HostlistCompilerConfiguration } from '@adguard/hostlist-compiler';
import { writeFileSync } from 'fs';
;(async () => {
// Configuration
const config: HostlistCompilerConfiguration = {
name: 'Your Hostlist',
sources: [
{
type: 'adblock',
source: 'https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt',
transformations: ['RemoveComments', 'Validate'],
},
],
transformations: ['Deduplicate'],
};
// Compile filters
const result = await HostlistCompiler(config);
// Write to file
writeFileSync('your-hostlist.txt', result.join('\n'));
})();
转换
以下列出可用的全部变换列表:
ConvertToAsciiTrimLinesRemoveCommentsCompressRemoveModifiersInvertAllowValidateValidateAllowIpValidateAllowPublicSuffixValidateAllowIpAndPublicSuffixDeduplicateRemoveEmptyLinesInsertFinalNewLine
请注意,这些转变总是按此处所指明的顺序进行.
转换到Ascii
这个转换将所有非 ASCII 字符转换为它们的 ASCII 等同. 总是先做.
示例
原名单:
||*.рус^
||*.कॉम^
||*.セール^
接下来,我们实施这一转变后
||*.xn--p1acf^
||*.xn--11b4c3d^
||*.xn--1qqw23a^
三角线
这是一个非常简单的转换,它去除了前导和后导的空间/tab.
示例
原名单:
rule1
rule2
rule3
rule4
接下来,我们实施这一转变后
rule1
rule2
rule3
rule4
删除注释
这是一个非常简单的转换,它简单地删除了注释(例如,所有规则从 ! 或者说 #) (中文(简体) ).
压缩
[大 此转换转换
hosts列表为adblock列表.
这就是它的作用:
- 它将所有的规则转换为"块"式的规则. 比如说,
0.0.0.0 example.org将转换为||example.org^。 。 。 . - 它抛弃了现在由于其他现有规则而多余的规则. 比如说,
||example.org块example.org和所有它都是子域, 因此附加规则 对于子域现在冗余.
删除修改器
默认, 守护之家 将忽略不支持的修改符的规则,这里列出的所有修改符都是不支持的. 然而,带有这些修饰符的规则对于DNS级阻塞很可能是好的,所以在从传统的过滤器列表中导入规则时,你可能会想将其删除.
以下列出将删除的修饰符:
$third-party财务报告和审定财务报表$3p修改$document财务报告和审定财务报表$doc修改$all修改$popup修改$network修改
[叹息] 盲目清除
$third-party从传统的广告封锁规则 导致很多虚假阳性.这正是为什么有 排除规则的选择 - 你可能需要使用它.
反转Allow
这种转换将阻塞规则转换为"允许"规则. 注意,它对/etc/hosts规则没有任何作用(除非它们以前通过不同的转换转换转换为adblock-tyle语法,例如: 压缩) (中文(简体) ).
关于这种转变,有两个重要的说明:
- 它维持了原有的规则秩序.
- 它忽略了评论,空行,/etc/host规则和已存在的"允许"规则.
示例
原名单:
! comment 1
rule1
# comment 2
192.168.11.11 test.local
@@rule2
接下来,我们实施这一转变后
! comment 1
@@rule1
# comment 2
192.168.11.11 test.local
@@rule2
校验
如果你把一个过滤列表 用于传统的广告屏蔽器作为源头,这个转换就非常关键.
它将危险或不相容的规则从清单中删除.
这就是它的作用:
- 丢弃特定域规则(如.
||example.org^$domain=example.com) (中文(简体) ). 你不想让特定领域的规则在全球运作. - 以不支持的修饰符丢弃规则. 点击这里 以便更多地了解支持哪些修饰者.
- 抛弃那些太短的规则.
- 丢弃IP地址. 如果您需要保留 IP 地址, 请使用 校验 AllowIp 换句话说.
被拒绝的 IP 模式
下列IP模式被所有验证转换所拒绝(Validate, (中文(简体) ), ValidateAllowIp, (中文(简体) ), ValidateAllowPublicSuffix, (中文(简体) ), ValidateAllowIpAndPublicSuffix它们要么不安全,要么含糊不清:
-
||192.168.1^- 3-ott 与^- 没用 -
192.168.1- 模棱两可:192.168.11, (中文(简体) ),192.168.111等 (中文(简体) ). -
1.2.或者说1.2.*- 宽度太高(1至2octets),取而代之的是正则克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 -
删除阻碍整个顶级域( TLD) 的规则
||*.org^,除非它们有特定的限制性修改语,例如:$denyallow, (中文(简体) ),$badfilter,或$client。 。 。 . 实例:||*.org^- 这条规则将被删除||*.org^$denyallow=example.com- 这条规则会被保留 因为它有一个限制修改符 如果必须保存这些规则,请使用 验证 Allow 公共后缀 或者说 验证 AllowIpAnd Public 后缀。 。 。 .
如果在无效规则之前有评论,也将被删除.
校验 AllowIp
此转换延伸 校验 以允许列表中的 IP 地址。 还有 使IP规则正常化 以 Adblock 样式改为安全格式 ||ip^。 。 。 .
IP 规则正常化
1.2.3.4→||1.2.3.4^(添加两个分隔符)1.2.3.4^→||1.2.3.4^(添加左锚)|1.2.3.4→||1.2.3.4^(替换)|与||,添加^(中文(简体) )|1.2.3.4^→||1.2.3.4^(替换)|与||(中文(简体) )||1.2.3.4→||1.2.3.4^(添加右分隔符)||1.2.3.4^~ (没有变化,已经可以了)192.168.1.→||192.168.1.(3-octet子网通配符)192.168.1.*→||192.168.1.*(3-octet子网通配符)
修饰者喜欢 $important, (中文(简体) ), $client, (中文(简体) ), $denyallow, (中文(简体) ), $badfilter 在正常化期间予以保留.
说明: 无效的 IP 模式只被基数拒绝 校验 逻辑——正常化只将有效模式转换为犬形,其他一切通过不变. 见 被拒绝的 IP 模式 详细情况.
验证 Allow 公共后缀
这种转变完全重复了 校验,但留下了与整个公共后缀相匹配的规则(例如. ||hl.cn^, (中文(简体) ), ||org^在列表中.
它仍然会过滤出无效的语法规则和不支持的修饰者,但不会拒绝公共后缀规则,除非规则本身是错的.
说明: 组合任意
Validate, (中文(简体) ),ValidateAllowIp, (中文(简体) ),ValidateAllowPublicSuffix,以及ValidateAllowIpAndPublicSuffix在一个变换列表中不允许并将导致出错。 每一个在上一个已过滤的输出上运行自己的验证器,所以允许-modes变得默默无效.
重要内容: 验证转换也不能同时用于源一级和上一级. 例如,如果一个源使用
ValidateAllowPublicSuffix并使用顶级配置Validate,编译器将丢出一个错误。 这是因为高层Validate将取代源级验证,生成ValidateAllowPublicSuffix无效。 仅在一个级别使用验证转换.
验证 AllowIpAnd Public 后缀
这种转变结合了 校验 AllowIp 财务报告和审定财务报表 验证 Allow 公共后缀. 它既允许IP地址,也允许列表中的公共后缀规则.
喜欢 ValidateAllowIp,它将不完整的IP规则与安全格式正常化 ||ip^ 在验证之前。 见 IP 规则正常化 详细情况.
喜欢 ValidateAllowPublicSuffix,它保持了与整个公共后缀相匹配的规则(例如. ||hl.cn^, (中文(简体) ), ||org^) (中文(简体) ).
重复
此转换只是从指定的源中去除重复.
关于这种转变,有两个重要的说明:
- 它维持了原有的规则秩序.
- 它忽略了评论。 但是,如果评论在删除的规则之前,评论也将被删除.
例如:
! rule1 comment 1
rule1
! rule1 comment 2
rule1
变身后剩下的是:
! rule1 comment 2
rule1
删除线
这是一个非常简单的转换,可以去除空行.
示例
原名单:
rule1
rule2
rule3
接下来,我们实施这一转变后
rule1
rule2
rule3
插入最后新线
这是一个非常简单的转换,它插入了最后的新行.
示例
原名单:
rule1
rule2
rule3
接下来,我们实施这一转变后
rule1
rule2
rule3
RemoveEmptyLines 由于执行命令,不删除此空行.