强大、高效、易用的Go语言访问控制列表库
保护您的应用免受未授权访问
|
|
|
|
使用Go模块安装go-acl库：
# 推荐使用Go Module (Go 1.18+)
go get -u github.com/cyberspacesec/acl-skills快速示例，展示基本的黑名单模式：
package main
import (
"fmt"
"github.com/cyberspacesec/acl-skills/pkg/acl"
"github.com/cyberspacesec/acl-skills/pkg/types"
)
func main() {
// 创建ACL管理器
manager := acl.NewManager()
// 配置域名黑名单
manager.SetDomainAcl([]string{
"malicious-site.com",
"phishing-example.org",
}, types.Blacklist, true) // true表示阻止子域名
// 配置IP黑名单（包含一些内网地址）
manager.SetIPAclWithDefaults(
[]string{"203.0.113.0/24"}, // 自定义IP范围
types.Blacklist,
[]ip.PredefinedSet{ip.PrivateNetworks}, // 预定义集合: 所有私有网络
false, // false表示黑名单，即阻止这些IP
)
// 检查域名
if perm, _ := manager.CheckDomain("api.malicious-site.com"); perm == types.Denied {
fmt.Println("恶意域名已被阻止!")
}
// 检查IP (SSRF防护)
if perm, _ := manager.CheckIP("10.0.0.1"); perm == types.Denied {
fmt.Println("内网IP访问被阻止，防止SSRF攻击!")
}
}graph TD
A[ACL Manager] --> B[Domain ACL]
A --> C[IP ACL]
B --> D[Domain Rules]
C --> E[IP Rules]
C --> F[Predefined Sets]
G[File Handlers] --> C
G --> B
- ACL Manager: 核心组件，同时管理域名和IP规则
- Domain ACL: 处理域名访问控制，支持子域名匹配
- IP ACL: 处理IP地址访问控制，支持CIDR格式
- Predefined Sets: 内置安全IP集合，如内网地址、云元数据等
- File Handlers: 文件操作工具，支持导入导出规则
// 创建域名白名单 (只允许特定域名及其子域名访问)
manager.SetDomainAcl([]string{
"example.com",
"trusted-partner.org",
}, types.Whitelist, true)
// 检查域名
permission, err := manager.CheckDomain("api.example.com")// 创建IP黑名单
manager.SetIPAcl([]string{
"192.168.1.100", // 单个IP
"10.0.0.0/8", // CIDR格式
"2001:db8::/32", // IPv6支持
}, types.Blacklist)
// 动态添加和移除IP
manager.AddIP("8.8.8.8", "8.8.4.4")
manager.RemoveIP("8.8.8.8")// 从文件加载IP规则
manager.SetIPAclFromFile("path/to/blacklist.txt", types.Blacklist)
// 保存当前规则到文件
manager.SaveIPAclToFile("path/to/saved_blacklist.txt", true)go-acl内置了多种预定义IP集合，用于常见的安全防护场景：
| 集合名称 | 描述 | 安全场景 |
|---|---|---|
ip.PrivateNetworks |
RFC1918中定义的内网地址 | 防止SSRF访问内网 |
ip.LoopbackNetworks |
本地回环地址 | 防止SSRF访问本地服务 |
ip.CloudMetadata |
云元数据服务地址 | 防止泄露云实例凭证 |
ip.LinkLocalNetworks |
链路本地地址 | 网络安全隔离 |
ip.DockerNetworks |
Docker默认网络 | 容器安全隔离 |
ip.PublicDNS |
公共DNS服务器 | DNS服务器白名单 |
// 安全增强配置 - 阻止访问所有内部网络
manager.SetIPAclWithDefaults(
[]string{},
types.Blacklist,
[]ip.PredefinedSet{
ip.PrivateNetworks,
ip.LoopbackNetworks,
ip.CloudMetadata,
ip.DockerNetworks,
},
false,
)我们提供了多个详细的示例，展示go-acl的各种使用场景：
| 示例 | 说明 | 链接 |
|---|---|---|
| 域名访问控制 | 演示域名黑白名单和子域名匹配 | 查看示例 |
| IP访问控制 | 演示IP黑白名单和CIDR格式 | 查看示例 |
| 文件操作 | 演示配置保存和加载 | 查看示例 |
| 预定义集合 | 演示使用内置IP集合实现安全增强 | 查看示例 |
| ACL管理器 | 演示同时管理域名和IP规则 | 查看示例 |
| 完整应用示例 | 集成所有功能的Web应用防护示例 | 查看示例 |
| 自定义ACL扩展 | 演示注册自定义 ACL 实现到 Manager | 查看示例 |
查看示例目录获取完整示例代码。
go-acl 通过 types.MutableACL 接口提供扩展点，支持接入自定义的访问控制实现：
// 自定义 ACL 只需实现 MutableACL 接口：
// Check(value string) (Permission, error)
// GetListType() ListType
// Add(rules ...string) error
// Remove(rules ...string) error
// GetRules() []string
manager := acl.NewManager()
manager.RegisterACL("token", myTokenACL) // 注册自定义 ACL
perm, _ := manager.CheckKind("token", "secret") // 统一入口检查
manager.AddRule("token", "new-token") // 统一入口增删规则内置的 KindDomain / KindIP 是预定义的注册键，与旧 API（SetDomainACL/CheckIP 等）完全兼容。详见 自定义ACL示例。
分层接口：
| 接口 | 能力 |
|---|---|
ACL |
仅 Check（最小契约，向后兼容） |
ListTypeACL |
+ GetListType |
MutableACL |
+ Add/Remove/GetRules（Manager 注册所需） |
go-acl 针对高并发场景做了优化，并配有完整的基准测试（go test -bench=. -benchmem ./...）：
| 场景 | 规模 | 延迟 | 说明 |
|---|---|---|---|
| IPACL.Check | 100 / 1000 / 10000 | ~75 ns/op | 前缀树，与规则数无关 |
| IPACL.Check（并发） | 10000 | ~45 ns/op | RWMutex 读写分离 |
| DomainACL.Check（精确） | 100 / 1000 / 10000 | ~70 ns/op | map O(1)，与规则数无关 |
| DomainACL.Check（含子域名） | 10000 | ~76 µs/op | 后缀线性匹配 |
| Manager.CheckIP / CheckDomain | 10000 | ~70-80 ns/op | 不同 kind 互不阻塞 |
- 零内存分配：Check 路径 0 allocs/op
- 并发安全：底层 ACL 内置
sync.RWMutex，Manager 仅用轻量锁守 map；查询不同 ACL 类型互不阻塞 - IP 匹配常数级：IPv4/IPv6 各一棵按位前缀树（
pkg/ip/trie.go），查询 O(32)/O(128)
CI 在每次推送时自动运行基准测试（benchmark job，不阻塞主流程）。
欢迎贡献代码、报告问题或提出建议！请参阅贡献指南了解更多信息。
该项目采用MIT许可证 - 有关详细信息，请查看LICENSE文件。