ipanalytics/ASNforge
GitHub: ipanalytics/ASNforge
ASNForge 是一个确定性的 ASN 与前缀来源情报本地编译器，将公共注册表与 BGP 数据编译为可复现的 IP 富化制品以供路由分析和安全数据管道使用。
Stars: 1 | Forks: 0
# ASNForge
ASNForge 为 IP 富化、路由分析和安全数据管道构建可复现的 ASN 和前缀来源情报制品。它将公共注册表和路由输入编译为紧凑的 IP 到 ASN 的 MaxMind DB、规范化 ASN 表、前缀来源快照、构建元数据、校验和以及可直接发布的归档文件。
asnforge inspect-asn
asnforge stats
asnforge version
```
常用 flag：
| Flag | 默认值 | 描述 |
| --- | --- | --- |
| `--config` | `config/public-safe.yaml` | 构建配置 |
| `--out` | `release/current` | 发布输出目录 |
| `--cache` | `data/cache` | 源缓存目录 |
| `--build-id` | UTC 时间戳 | 显式构建标识符 |
| `--schema-version` | `asnforge.v0.1` | 制品 schema 版本 |
| `--private-asn-policy` | 配置值 | `flag`、`drop` 或 `keep` |
| `--moas-policy` | 配置值 | `mark_ambiguous`、`most_observed` 或 `lowest_asn` |
| `--mmdb` | `/asnforge.mmdb` | 用于构建或检查的 MMDB 路径 |
| `--skip-download` | `false` | 使用缓存/本地源文件 |
| `--strict` | `false` | 将质量警告视为构建失败 |
| `--format` | `text` | 支持的 `text` 或 `json` |
## 输出
成功的构建会写入一个完整的发布目录：
```
release/current/
├── asnforge.mmdb
├── asnforge.mmdb.gz
├── asnforge-asn.jsonl
├── asnforge-asn.jsonl.gz
├── asnforge-asn.csv
├── asnforge-asn.csv.gz
├── asnforge-prefixes.jsonl
├── asnforge-prefixes.jsonl.gz
├── asnforge-prefixes.csv
├── asnforge-prefixes.csv.gz
├── metadata.json
├── checksums.txt
├── quality-report.md
├── asnforge-diff.json
└── manifest.json
```
| 文件 | 描述 |
| --- | --- |
| `asnforge.mmdb` | 用于 IP -> ASN profile 查找的紧凑 MaxMind DB |
| `asnforge-asn.jsonl` | 规范 ASN profile 表 |
| `asnforge-asn.csv` | ASN profile 表的 CSV 格式 |
| `asnforge-prefixes.jsonl` | 规范前缀来源快照 |
| `asnforge-prefixes.csv` | 前缀来源状态的 CSV 格式 |
| `metadata.json` | 构建元数据、源哈希、制品哈希、摘要、质量结论 |
| `checksums.txt` | 发布制品的 SHA256 校验和 |
| `quality-report.md` | 人类可读的构建和质量报告 |
| `asnforge-diff.json` | 基线或跨版本发布的差异结构 |
| `manifest.json` | 机器可读的制品清单 |
## 数据格式
每个主要记录包含：
- `schema_version`
- `build_id`
这些字段使 join 操作变得明确，并防止意外混合不兼容的构建。
### ASN Profile
`asnforge-asn.jsonl` 和 `asnforge-asn.csv` 为每个 ASN 包含一行：
```
{
"schema_version": "asnforge.v0.1",
"build_id": "local-dev",
"asn": 15169,
"asn_name": "Google LLC",
"asn_org": "Google",
"asn_type": "cloud",
"asn_tags": ["cloud", "dns", "manual-override", "search"],
"registration_country": "US",
"rir": "arin",
"asn_confidence": 100
}
```
`registration_country` 是来自 RIR delegated 数据的注册表分配国家/地区。它不是用户、主机或服务的地理位置。
### 前缀来源
`asnforge-prefixes.jsonl` 和 `asnforge-prefixes.csv` 保留路由观察状态：
```
{
"prefix": "8.8.8.0/24",
"origin_asns": [15169],
"selected_origin_asn": 15169,
"moas": false,
"origin_policy": "most_observed",
"observation_count": 2,
"source_collectors": ["ris-rrc00", "routeviews2"],
"prefix_confidence": 90,
"rpki_state": "unknown"
}
```
### MMDB 记录
MMDB 以前缀为键，并针对本地 IP 富化进行了优化：
```
{
"schema_version": "asnforge.v0.1",
"build_id": "local-dev",
"asn": 15169,
"asn_name": "Google LLC",
"asn_org": "Google",
"asn_type": "cloud",
"asn_tags": ["cloud", "dns", "manual-override", "search"],
"registration_country": "US",
"rir": "arin",
"moas": false,
"asn_confidence": 100
}
```
详细的 MOAS 状态、来源数组、收集器观察结果和字段级的 provenance 属于前缀和 ASN 表。将这些字段排除在 MMDB 之外可以保留数据部分的去重，并使数据库保持紧凑。
## 操作说明
- 对于相同的输入、配置、schema 版本和构建 ID，构建是确定性的。
- ASN 行按数字 ASN 排序。
- 前缀行按 IP 系列、地址字节和前缀长度排序。
- CSV 列表字段使用分号分隔的稳定排序。
- `metadata.json` 记录源路径、URL、SHA256 哈希、大小、生成时间、制品哈希和质量摘要。
- `validate --strict` 专为 CI 和发布工作流而设计。
## 源配置文件
| 配置文件 | 用途 | 需要网络 |
| --- | --- | --- |
| `config/local-dev.yaml` | 确定性开发和 CI fixture 构建 | 否 |
| `config/public-safe.yaml` | 使用 RIR delegated 文件、bgp.tools 导出和静态 ipanalytics ASN 信号源的安全发布配置 | 是 |
| `config/research-caida.yaml` | 安全源加上可选的 CAIDA ASRank、AS2Org 和 AS 关系批量文件 | 是，加上操作者提供的 CAIDA 文件 |
public-safe 配置文件下载 `https://bgp.tools/table.jsonl` 作为生产前缀来源输入，下载 `https://bgp.tools/asns.csv` 作为 ASN 名称和源类别，并从 IP-Knowledge-Layer 和 ASN-Signal-Graph 下载静态原始 CSV 信号导出。`examples/testdata` 下的确定性 fixture 专门针对 `config/local-dev.yaml` 设定。
research CAIDA 配置文件是分开的，因为 CAIDA 数据集有其自身的可接受使用、引用和分发条款。CAIDA 字段被写入 ASN JSONL/CSV 制品中，并被故意排除在紧凑的 MMDB 之外。
默认的 CAIDA 研究输入：
| 数据集 | 文件 |
| --- | --- |
| AS2Org | `https://publicdata.caida.org/datasets/as-organizations/latest.as-org2info.txt.gz` |
| AS relationships | 从 `https://publicdata.caida.org/datasets/as-relationships/serial-2/` 解析出的最新 `*.as-rel2.txt.bz2` |
| ASRank | 操作者提供的 CSV 路径或 URL；不使用 ASRank API 爬取 |
该代码库包含一个每月/手动的 `release-caida` 工作，用于发布标记为 `research-caida-YYYYMMDD-HHMMSSZ` 的预发布。
默认情况下，v0.1 public-safe 配置文件不包含 CAIDA 数据。可选的 PeeringDB、CAIDA、RPKI 和原生 MRT 支持被追踪为后续的源配置文件和解析器扩展。
## 使用场景
- 在 SIEM、欺诈、滥用和流量分析系统中进行 IP 富化。
- 在数据仓库和流处理器中进行本地 ASN profile join。
- 用于路由分析和 MOAS 审查的前缀来源快照。
- 为内部安全数据管道提供可复现的发布制品。
- 在构建时验证第三方注册表和路由源的更改。
## 范围
ASNForge v0.1 专注于 pipeline 形态：解析器、规范化模型、确定性输出、紧凑的 MMDB 生成、元数据、验证和发布自动化。
分类是保守的。`asn_type` 是一种评分操作分类，而不是权威的注册事实。置信度描述了来源的一致性、完整性或观察强度；它不是风险评分。
## 局限性
- v0.1 中未实现原生 MRT 解析。
- 前缀来源输入是规范化的 CSV/TSV。
- RPKI 状态默认为 `unknown`。
- 没有可选的富化来源，ASN 分类故意保持稀疏。
- 实时路由数据因收集器和收集时间的不同而异。
## 目录结构
```
.
├── cmd/asnforge/ # CLI entry point
├── internal/asn/ # ASN models, classification, private/reserved policy
├── internal/bgp/ # Prefix-origin parser and aggregation
├── internal/build/ # Build pipeline, metadata, quality, diff
├── internal/config/ # Config loading and CLI options
├── internal/download/ # Source download, hashing, source state
├── internal/mmdb/ # MaxMind DB writer and inspector
├── internal/output/ # JSONL, CSV, gzip, checksums
├── internal/rir/ # RIR delegated parser
├── internal/smoke/ # Smoke test runner
├── config/ # Build profiles
├── schemas/ # JSON Schemas
├── examples/ # Overrides, smoke cases, deterministic testdata
├── docs/ # Data source and artifact documentation
└── .github/workflows/ # CI and release automation
```
## 部署
发布制品旨在通过 GitHub Releases 发布，而不是提交到代码库。
发布工作流会构建 CLI，运行配置好的 public-safe 构建，验证输出，计算校验和，创建发布 tag，并上传压缩的数据制品以及元数据：
```
./asnforge build --config config/public-safe.yaml --out release/current
./asnforge validate --out release/current --strict
```
对于内部部署，在 CI 中运行相同的命令，并将 `release/current/*` 发布到对象存储、包注册表或内部制品仓库。
## 文档
- [数据源](docs/DATA_SOURCES.md)
- [第三方数据](docs/THIRD_PARTY_DATA.md)
- [分类](docs/CLASSIFICATION.md)
- [MMDB 输出](docs/MMDB_OUTPUT.md)
- [发布制品](docs/RELEASE_ARTIFACTS.md)
- [置信度](docs/CONFIDENCE.md)
## 许可证
ASNForge 采用 [Apache License 2.0](LICENSE) 授权。
## 免责声明
ASNForge 汇总注册表和观察到的路由数据，用于防御、分析和操作目的。路由数据是观察性的，可能因收集器和收集时间的不同而有所差异。
标签：ASN, Docker 部署, EVTX分析, Go, IP情报, MaxMind DB, Ruby工具, 日志审计, 时序数据库, 网络运维, 路由分析