{"id":28237033,"url":"https://github.com/cyberspacesec/go-acl","last_synced_at":"2025-09-08T14:38:11.483Z","repository":{"id":284195443,"uuid":"953994069","full_name":"cyberspacesec/go-acl","owner":"cyberspacesec","description":"golang版本的ACL SDK","archived":false,"fork":false,"pushed_at":"2025-03-24T17:16:45.000Z","size":98,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-27T21:27:26.519Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyberspacesec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-24T12:01:38.000Z","updated_at":"2025-03-24T17:16:48.000Z","dependencies_parsed_at":"2025-03-24T17:41:44.515Z","dependency_job_id":null,"html_url":"https://github.com/cyberspacesec/go-acl","commit_stats":null,"previous_names":["cyberspacesec/go-acl"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cyberspacesec/go-acl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberspacesec%2Fgo-acl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberspacesec%2Fgo-acl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberspacesec%2Fgo-acl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberspacesec%2Fgo-acl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyberspacesec","download_url":"https://codeload.github.com/cyberspacesec/go-acl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyberspacesec%2Fgo-acl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274199736,"owners_count":25239903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-19T00:17:17.535Z","updated_at":"2025-09-08T14:38:11.428Z","avatar_url":"https://github.com/cyberspacesec.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔒 go-acl\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.18+-00ADD8?style=for-the-badge\u0026logo=go\u0026logoColor=white\" alt=\"Go版本\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge\" alt=\"许可证\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Coverage-96.7%25-success?style=for-the-badge\" alt=\"测试覆盖率\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/workflow/status/cyberspacesec/go-acl/Go%20Tests?style=for-the-badge\u0026logo=github\u0026label=tests\" alt=\"测试状态\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/workflow/status/cyberspacesec/go-acl/Go%20Tests?style=for-the-badge\u0026logo=github\u0026label=examples\u0026event=workflow_run\" alt=\"示例测试\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003e强大、高效、易用的Go语言访问控制列表库\u003c/b\u003e\u003cbr\u003e\n  \u003csub\u003e保护您的应用免受未授权访问\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cyberspacesec/go-acl/assets/go-acl-banner.png\" alt=\"go-acl横幅\" width=\"700\"\u003e\n\u003c/p\u003e\n\n---\n\n## 📋 目录\n\n- [🚀 特性](#-特性)\n- [⚙️ 安装](#️-安装)\n- [🔧 快速开始](#-快速开始)\n- [🎯 主要组件](#-主要组件)\n- [📘 详细用法](#-详细用法)\n- [🧪 预定义IP集合](#-预定义ip集合)\n- [🔍 示例](#-示例)\n- [📊 性能](#-性能)\n- [👥 贡献](#-贡献)\n- [📜 许可证](#-许可证)\n\n## 🚀 特性\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003e🌐 域名访问控制\u003c/h3\u003e\n      \u003cul\u003e\n        \u003cli\u003e支持黑白名单机制\u003c/li\u003e\n        \u003cli\u003e智能子域名匹配\u003c/li\u003e\n        \u003cli\u003e域名规范化处理\u003c/li\u003e\n        \u003cli\u003e支持国际化域名(IDN)\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003e🖥️ IP访问控制\u003c/h3\u003e\n      \u003cul\u003e\n        \u003cli\u003e支持单个IP和CIDR格式\u003c/li\u003e\n        \u003cli\u003e同时支持IPv4和IPv6\u003c/li\u003e\n        \u003cli\u003e内置常见IP集合\u003c/li\u003e\n        \u003cli\u003eSSRF防护机制\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003ch3\u003e🔄 动态规则管理\u003c/h3\u003e\n      \u003cul\u003e\n        \u003cli\u003e运行时添加/移除规则\u003c/li\u003e\n        \u003cli\u003e规则存储与加载\u003c/li\u003e\n        \u003cli\u003e线程安全操作\u003c/li\u003e\n        \u003cli\u003e灵活的API设计\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003ch3\u003e⚡ 高性能设计\u003c/h3\u003e\n      \u003cul\u003e\n        \u003cli\u003e优化的匹配算法\u003c/li\u003e\n        \u003cli\u003e低内存占用\u003c/li\u003e\n        \u003cli\u003e无外部依赖\u003c/li\u003e\n        \u003cli\u003e完善的测试覆盖\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## ⚙️ 安装\n\n使用Go模块安装go-acl库：\n\n```bash\n# 推荐使用Go Module (Go 1.18+)\ngo get -u github.com/cyberspacesec/go-acl\n```\n\n## 🔧 快速开始\n\n快速示例，展示基本的黑名单模式：\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/cyberspacesec/go-acl/pkg/acl\"\n    \"github.com/cyberspacesec/go-acl/pkg/types\"\n)\n\nfunc main() {\n    // 创建ACL管理器\n    manager := acl.NewManager()\n    \n    // 配置域名黑名单\n    manager.SetDomainAcl([]string{\n        \"malicious-site.com\",\n        \"phishing-example.org\",\n    }, types.Blacklist, true) // true表示阻止子域名\n    \n    // 配置IP黑名单（包含一些内网地址）\n    manager.SetIPAclWithDefaults(\n        []string{\"203.0.113.0/24\"}, // 自定义IP范围\n        types.Blacklist,\n        []ip.PredefinedSet{ip.PrivateNetworks}, // 预定义集合: 所有私有网络\n        false, // false表示黑名单，即阻止这些IP\n    )\n    \n    // 检查域名\n    if perm, _ := manager.CheckDomain(\"api.malicious-site.com\"); perm == types.Denied {\n        fmt.Println(\"恶意域名已被阻止!\")\n    }\n    \n    // 检查IP (SSRF防护)\n    if perm, _ := manager.CheckIP(\"10.0.0.1\"); perm == types.Denied {\n        fmt.Println(\"内网IP访问被阻止，防止SSRF攻击!\")\n    }\n}\n```\n\n## 🎯 主要组件\n\n```mermaid\ngraph TD\n    A[ACL Manager] --\u003e B[Domain ACL]\n    A --\u003e C[IP ACL]\n    B --\u003e D[Domain Rules]\n    C --\u003e E[IP Rules]\n    C --\u003e F[Predefined Sets]\n    G[File Handlers] --\u003e C\n    G --\u003e B\n```\n\n- **ACL Manager**: 核心组件，同时管理域名和IP规则\n- **Domain ACL**: 处理域名访问控制，支持子域名匹配\n- **IP ACL**: 处理IP地址访问控制，支持CIDR格式\n- **Predefined Sets**: 内置安全IP集合，如内网地址、云元数据等\n- **File Handlers**: 文件操作工具，支持导入导出规则\n\n## 📘 详细用法\n\n### 域名控制\n\n```go\n// 创建域名白名单 (只允许特定域名及其子域名访问)\nmanager.SetDomainAcl([]string{\n    \"example.com\",\n    \"trusted-partner.org\",\n}, types.Whitelist, true)\n\n// 检查域名\npermission, err := manager.CheckDomain(\"api.example.com\")\n```\n\n### IP控制\n\n```go\n// 创建IP黑名单\nmanager.SetIPAcl([]string{\n    \"192.168.1.100\",  // 单个IP\n    \"10.0.0.0/8\",     // CIDR格式\n    \"2001:db8::/32\",  // IPv6支持\n}, types.Blacklist)\n\n// 动态添加和移除IP\nmanager.AddIP(\"8.8.8.8\", \"8.8.4.4\")\nmanager.RemoveIP(\"8.8.8.8\")\n```\n\n### 文件导入导出\n\n```go\n// 从文件加载IP规则\nmanager.SetIPAclFromFile(\"path/to/blacklist.txt\", types.Blacklist)\n\n// 保存当前规则到文件\nmanager.SaveIPAclToFile(\"path/to/saved_blacklist.txt\", true)\n```\n\n## 🧪 预定义IP集合\n\ngo-acl内置了多种预定义IP集合，用于常见的安全防护场景：\n\n| 集合名称 | 描述 | 安全场景 |\n|---------|------|--------|\n| `ip.PrivateNetworks` | RFC1918中定义的内网地址 | 防止SSRF访问内网 |\n| `ip.LoopbackNetworks` | 本地回环地址 | 防止SSRF访问本地服务 |\n| `ip.CloudMetadata` | 云元数据服务地址 | 防止泄露云实例凭证 |\n| `ip.LinkLocalNetworks` | 链路本地地址 | 网络安全隔离 |\n| `ip.DockerNetworks` | Docker默认网络 | 容器安全隔离 |\n| `ip.PublicDNS` | 公共DNS服务器 | DNS服务器白名单 |\n\n### 使用预定义集合\n\n```go\n// 安全增强配置 - 阻止访问所有内部网络\nmanager.SetIPAclWithDefaults(\n    []string{},\n    types.Blacklist,\n    []ip.PredefinedSet{\n        ip.PrivateNetworks,\n        ip.LoopbackNetworks,\n        ip.CloudMetadata,\n        ip.DockerNetworks,\n    },\n    false,\n)\n```\n\n## 🔍 示例\n\n我们提供了多个详细的示例，展示go-acl的各种使用场景：\n\n| 示例 | 说明 | 链接 |\n|------|------|------|\n| **域名访问控制** | 演示域名黑白名单和子域名匹配 | [查看示例](examples/01_domain_acl/) |\n| **IP访问控制** | 演示IP黑白名单和CIDR格式 | [查看示例](examples/02_ip_acl/) |\n| **文件操作** | 演示配置保存和加载 | [查看示例](examples/03_file_operations/) |\n| **预定义集合** | 演示使用内置IP集合实现安全增强 | [查看示例](examples/04_predefined_sets/) |\n| **ACL管理器** | 演示同时管理域名和IP规则 | [查看示例](examples/05_acl_manager/) |\n| **完整应用示例** | 集成所有功能的Web应用防护示例 | [查看示例](examples/06_complete_example/) |\n\n查看[示例目录](examples/)获取完整示例代码。\n\n## 📊 性能\n\ngo-acl库经过优化，具有出色的性能表现：\n\n- **低内存占用**: 10万条规则仅占用约5MB内存\n- **快速匹配**: 单次规则匹配平均耗时\u003c1µs\n- **线性扩展**: 性能与规则数量成线性关系\n- **并发安全**: 支持高并发环境下的规则检查\n\n## 👥 贡献\n\n欢迎贡献代码、报告问题或提出建议！请参阅[贡献指南](CONTRIBUTING.md)了解更多信息。\n\n## 📜 许可证\n\n该项目采用MIT许可证 - 有关详细信息，请查看[LICENSE](LICENSE)文件。","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberspacesec%2Fgo-acl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyberspacesec%2Fgo-acl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberspacesec%2Fgo-acl/lists"}