ipanalytics/BogonForge
GitHub: ipanalytics/BogonForge
一个基于 IANA 官方注册表、可重现的特殊用途 IP 和 ASN 策略编译器，用于防止下游系统对私有、文档等地址空间进行错误增强。
Stars: 1 | Forks: 0
# BogonForge
BogonForge 是一个可重现的编译器，用于 IANA/RFC 特殊用途 IP 和 ASN 策略。它将规范的注册表事实转化为带版本号的工件，供增强、GeoIP、信誉、路由、SIEM 和数据质量流水线在给某个地址或 ASN 赋予含义之前使用。
大多数 bogon 列表告诉你应该过滤什么。
BogonForge 告诉你的流水线一个地址被允许有什么含义。
它能防止文档、私有、环回、链路本地、保留和特殊用途地址空间被错误地定位地理信息、评分为信誉数据、映射到提供商或被当作外部基础设施。
## 概述
BogonForge 位于 IP 智能和网络数据流水线的前端。对于每个特殊用途前缀或 ASN，它保留了注册表事实，推导出特定于场景的策略，并发出具有来源信息的发布工件。
主要用例不是数据包过滤，而是防止无效的增强：
- 文档前缀进入威胁情报；
- 私有或共享地址空间获得 GeoIP 归属；
- 环回和链路本地地址被当作外部基础设施；
- 私有、保留或文档 ASN 成为提供商身份；
- CI 测试固件和示例因使用标准定义的测试范围而被拒绝。
BogonForge 提供了稳定的策略层，下游系统在继续 ASN、GeoIP、信誉或风险增强之前可以检查该层。
## 系统行为
```
IANA / RFC registries
|
v
normalized facts
|
v
policy profiles
|
v
release artifacts, configs, schemas, impact diff
```
事实和策略是故意分离的。事实来自 IANA/RFC 来源。策略是根据特定操作场景的配置文件推导出来的。
| 层 | 用途 | 示例 |
| --- | --- | --- |
| 事实 | 注册表派生的属性 | `source_valid`、`destination_valid`、`forwardable`、`globally_reachable`、`reserved_by_protocol`、`rfc` |
| 策略 | 流水线行为 | `exclude_from_geoip`、`exclude_from_reputation`、`exclude_from_provider_map`、`allow_in_examples` |
| 工件 | 机器可消费的输出 | JSONL、CSV、配置文件、nftables/ipset/nginx 配置、Schema、影响差异 |
## 特性
- 编译 IPv4 和 IPv6 IANA 特殊用途注册表
- 编译 IANA 特殊用途 AS 号
- 每条记录保留 RFC 来源信息
- 为 IP 和 ASN 记录输出 JSONL 和 CSV 数据集
- 生成 `data-policy`、`edge-drop`、`lab-allow` 和 `geoip-exclude` 配置文件
- 导出适用于边缘的 nftables、ipset 和 nginx 配置
- 提供从已编译工件进行本地 `inspect` 和 `explain` 查询
- 输出 `impact-diff.json` 用于下游重建决策
- 为生成的记录和配置文件输出生成 JSON Schema
- 从明确的上游注册表 URL 确定性构建
## 快速开始
```
git clone https://github.com/ipanalytics/bogonforge.git
cd bogonforge
go test ./...
go run ./cmd/bogonforge build --out release/current
go run ./cmd/bogonforge explain 100.64.1.1 --db release/current/bogonforge.jsonl.gz
```
示例输出：
```
IP: 100.64.1.1 -> 100.64.0.0/10
Class: shared-address-space (RFC6598, iana-ipv4-special-registry)
Name: Shared Address Space
Facts: globally_reachable=false forwardable=true source_valid=true destination_valid=true reserved_by_protocol=false
Policy: exclude_from_geoip, exclude_from_reputation, exclude_from_provider_map
```
## 安装说明
BogonForge 是一个 Go CLI。
```
go install https://github.com/ipanalytics/BogonForge/cmd/bogonforge@latest
```
本地开发：
```
go build ./cmd/bogonforge
./bogonforge build --out release/current
```
## 使用
构建发布版本：
```
bogonforge build --out release/current
```
检查地址：
```
bogonforge inspect 192.0.2.1 --db release/current/bogonforge.jsonl.gz
```
导出边缘丢弃的 nftables 集合：
```
bogonforge export \
--profile edge-drop \
--format nftables \
--db release/current/bogonforge.jsonl.gz
```
验证发布版本：
```
bogonforge validate release/current
```
比较两个发布版本：
```
bogonforge diff release/previous release/current
```
## 输出
构建会写入一个包含数据集、配置文件、配置、Schema、元数据和校验和的发布目录。
```
release/current/
├── bogonforge.jsonl.gz
├── bogonforge.csv.gz
├── bogonforge-asn.jsonl.gz
├── bogonforge-asn.csv.gz
├── profiles/
│ ├── data-policy.json
│ ├── edge-drop.txt
│ ├── lab-allow.txt
│ └── geoip-exclude.txt
├── configs/
│ ├── nftables-set.nft
│ ├── ipset.restore
│ └── nginx-deny.conf
├── schemas/
│ ├── special-ip.schema.json
│ ├── special-asn.schema.json
│ └── policy-profile.schema.json
├── metadata.json
├── impact-diff.json
├── quality-report.md
└── checksums.txt
```
| 工件 | 消费者 |
| --- | --- |
| `bogonforge.jsonl.gz` | 增强服务、批处理流水线、本地 explain 查询 |
| `bogonforge-asn.jsonl.gz` | ASN 归属、路由卫生、提供商身份检查 |
| `profiles/data-policy.json` | GeoIP、信誉、欺诈/风险、可观测性数据集 |
| `profiles/edge-drop.txt` | 防火墙、入站过滤器、边缘允许/拒绝逻辑 |
| `profiles/lab-allow.txt` | CI、测试固件、示例、文档检查 |
| `impact-diff.json` | 发布自动化和下游重建决策 |
## 数据格式
每条 IP 记录将注册表事实与派生策略分开：
```
{
"prefix": "192.0.2.0/24",
"family": "ipv4",
"class": "documentation",
"name": "Documentation (TEST-NET-1)",
"facts": {
"source": "iana-ipv4-special-registry",
"rfc": ["RFC5737"],
"globally_reachable": false,
"forwardable": false,
"source_valid": false,
"destination_valid": false,
"reserved_by_protocol": false,
"stability": "permanent",
"allocation_date": "2010-01",
"termination_date": "N/A"
},
"dataset_policy": [
"exclude_from_geoip",
"exclude_from_reputation",
"exclude_from_provider_map",
"allow_in_examples",
"warn_if_seen_on_public_edge"
]
}
```
ASN 记录使用相同的模式：
```
{
"asn_range": "64496-64511",
"class": "documentation",
"reason": "For documentation and sample code; reserved by [RFC5398]",
"facts": {
"source": "iana-as-numbers-special-registry",
"rfc": ["RFC5398"],
"stability": "permanent"
},
"dataset_policy": [
"exclude_from_public_asn_identity",
"allow_in_examples"
]
}
```
## 源注册表
BogonForge 默认使用官方 IANA CSV 注册表端点。
| 注册表 | 来源 |
| --- | --- |
| IPv4 特殊用途地址空间 | `https://www.iana.org/assignments/iana-ipv-special-registry/iana-ipv4-special-registry-1.csv` |
| IPv6 特殊用途地址空间 | `https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry-1.csv` |
| 特殊用途 AS 号 | `https://www.iana.org/assignments/iana-as-numbers-special-registry/special-purpose-as-numbers.csv` |
可以传递自定义源 URL 给 `build`，用于固定镜像或离线发布流水线：
```
bogonforge build \
--ipv4-url https://mirror.example.net/iana-ipv4-special-registry-1.csv \
--ipv6-url https://mirror.example.net/iana-ipv6-special-registry-1.csv \
--asn-url https://mirror.example.net/special-purpose-as-numbers.csv \
--out release/current
```
## 操作说明
特殊用途注册表变化缓慢。每周一次的稳定构建通常足以满足生产流水线。对于希望尽早了解注册表变化的组织，每日快照也是合理的。
推荐的流水线行为：
```
lookup address in BogonForge
if special-use:
attach explanation
apply dataset policy
stop incompatible enrichment
else:
continue ASN / GeoIP / reputation / risk enrichment
```
使用 `impact-diff.json` 决定在注册表或策略变化后哪些下游工件需要重建。
影响差异示例
```
{
"build_id": "20260524-143622Z",
"semantic_changes": 1,
"profile_impacts": {
"data-policy": ["192.0.2.0/24"],
"edge-drop": [],
"lab-allow": ["192.0.2.0/24"]
},
"downstream_rebuild_recommended": [
"GeoForge",
"Blackroute",
"ASNForge",
"PrefixLint",
"IntelMerge"
]
}
```
## 用例
- 从 GeoIP 数据集中排除特殊用途范围
- 防止文档和私有范围进入信誉系统
- 保护提供商映射免受保留/私有 ASN 身份的影响
- 从注册表支持的事实生成边缘丢弃配置
- 允许在示例和测试固件中使用标准定义的文档范围
- 向 SIEM 和可观测性事件添加可解释的特殊用途上下文
- 当影响策略的注册表事实发生变化时驱动下游重建
## 项目范围
BogonForge 涵盖 IANA/RFC 特殊用途 IP 前缀和特殊用途 ASN。它是一个基于注册表的稳定层，适用于数据和基础设施流水线。
不在范围内：
- 实时 BGP 可见性
- 威胁情报评分
- GeoIP 归属
- 替换 Team Cymru fullbogons
- 恶意分类
## 限制
- 当前的 explain 数据库是 JSONL gzip。MMDB 输出已列入发布目标，但此实现尚未输出。
- 配置工件以机械方式生成，应通过每个环境的正常审查路径集成。
- 策略配置文件有意保持保守且小巧；下游系统可以叠加更严格的本地策略。
## 目录结构
```
.
├── cmd/bogonforge/ # CLI entrypoint
├── internal/bogonforge/ # compiler, policy, artifacts, lookup, diff
├── schemas/ # JSON schemas copied into releases
├── site/ # repository visual assets
├── release/ # generated output, ignored by git
└── .github/workflows/ # CI
```
## 部署
对于计划构建，请在 CI 或受控发布作业中运行编译器，并将生成的 `release/current` 目录发布到对象存储、GitHub Releases 或内部制品仓库。
最小化的 GitHub Actions 结构：
```
name: release
on:
schedule:
- cron: "0 3 * * 1"
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: "1.22"
- run: go test ./...
- run: go run ./cmd/bogonforge build --out release/current
- run: go run ./cmd/bogonforge validate release/current
```
## 许可证
BogonForge 采用 [Apache License 2.0](./LICENSE) 许可证。
## 免责声明
BogonForge 编译公共注册表数据和派生策略工件，供基础设施和数据工程使用。操作人员仍负责在生产环境中应用之前验证生成的配置和策略。
标签：ASN, bogon列表, enrichment管道, EVTX分析, GeoIP, Go语言, IP信誉, IP地址管理, RFC合规, 可重现构建, 地址验证, 威胁情报, 开发者工具, 数据管道, 数据质量, 日志审计, 时序数据库, 版本化工件, 特殊用途地址, 程序破解, 编译器, 网络策略, 路由, 软件工程