# ASN Karma
ASN Karma 是一个使用 Go 编写的 pipeline，旨在基于观察到的
BlackRoute 证据构建 ASN 级别的风险数据集。它按自治系统聚合恶意的 IP/CIDR 记录，使用可审计的规则集对滥用风险进行评分，并为安全分析、欺诈/风险丰富、流量策略和网络运营生成发布制品。
## 最新版本
计划的构建任务会定期发布最新的数据集制品。以下链接指向最新的 GitHub Release 资产。
_最近一次数据集构建：`2026-06-16T10:00:37Z`_
[打开最新的 GitHub release](https://github.com/ipanalytics/ASN-Karma/releases/latest)
| 制品 | 下载 | 描述 |
| --- | --- | --- |
| `index.json` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/index.json) | 机器可读的发布清单 |
| `asn-risk.jsonl` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/asn-risk.jsonl) | 主要的 JSONL 风险数据集 |
| `asn-changes.jsonl` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/asn-changes.jsonl) | 自上次构建以来的 ASN delta feed |
| `asn-summary.csv` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/asn-summary.csv) | 用于审查和报告的 CSV 摘要 |
| `asn-evidence-table.md` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/asn-evidence-table.md) | ASN 证据计数排名前列的 Markdown 表格 |
| `asn-profiles.tar.gz` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/asn-profiles.tar.gz) | 各个 ASN 的 JSON 配置文件 |
| `source-impact.csv` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/source-impact.csv) | 来源贡献明细 |
| `country-risk.csv` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/country-risk.csv) | 国家/地区级别的运营汇总 |
| `high-risk-asn-critical.txt` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/high-risk-asn-critical.txt) | 严重级别的 ASN 层级 |
| `high-risk-asn-high.txt` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/high-risk-asn-high.txt) | 高级别的 ASN 层级 |
| `high-risk-asn-watch.txt` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/high-risk-asn-watch.txt) | 观察级别的 ASN 层级 |
| `high-risk-asn-prefixes-critical.txt` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/high-risk-asn-prefixes-critical.txt) | 衍生的严重 ASN 宣告前缀 |
| `high-risk-asn-prefixes-high.txt` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/high-risk-asn-prefixes-high.txt) | 衍生的高级别 ASN 宣告前缀 |
| `high-risk-asn-prefixes-watch.txt` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/high-risk-asn-prefixes-watch.txt) | 衍生的观察级别 ASN 宣告前缀 |
| `report.md` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/report.md) | Markdown 数据集报告 |
| `release-notes.md` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/release-notes.md) | 发布摘要及 ASN 排名前列的表格 |
| `run_stats.json` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/run_stats.json) | 构建元数据和层级计数 |
| `checksums.txt` | [下载](https://github.com/ipanalytics/ASN-Karma/releases/latest/download/checksums.txt) | 发布制品的 SHA256 校验和 |
## 概述
ASN Karma 使用
BlackRoute JSONL 记录，并生成专为实现运营用途而设计的 ASN 风险层。其输出具备刻意的可解释性：每条 ASN 记录都包含评分、层级、观察到的记录计数、来源多样性、主要威胁标签和构建元数据。
本项目将 ASN 扩展视为衍生情报。来源证据仅来自观察到的 IP/CIDR 记录；生成的 ASN 前缀列表是输出制品，不会作为反馈回流到证据流中。
## 系统行为
```
BlackRoute JSONL
-> parse observed IP/CIDR evidence
-> enrich records without ASN via Team Cymru bulk whois
-> aggregate records by ASN
-> compute source diversity and threat label distribution
-> apply scoring policy from configs/scoring.json
-> write JSONL, CSV, TXT tiers, and run statistics
```
| 阶段 | 职责 | 当前实现 |
| --- | --- | --- |
| 接收 | 读取 BlackRoute 样式的 JSONL，支持容错的字段映射 | `internal/blackroute` |
| 丰富映射 | 将观察到的 IP/CIDR 记录映射到 ASN、国家/地区和路由前缀 | `internal/enrich` |
| 数据建模 | 规范化观察到的记录并按 ASN 聚合 | `internal/model` |
| 评分 | 应用确定性的评分和层级策略 | `internal/scoring` |
| 输出 | 为机器和操作员生成发布制品 | `internal/output` |
| 自动化 | 通过 GitHub Actions 构建和发布制品 | `.github/workflows/build.yml` |
## 功能
- Go CLI，无运行时服务依赖。
- 为缺乏 ASN 元数据的上游记录提供 Team Cymru 批量 whois 丰富映射。
- 基于本地配置的确定性 ASN 评分。
- 面向下游数据 pipeline 的 JSONL 主要输出。
- 面向分析师工作流的 CSV 摘要。
- 用于基础设施策略集成的文本层级文件。
- 用于持久性和趋势分析的 7/30/90 天历史信号。
- 附带风险评分的置信度评分。
- 每个 ASN 的配置文件归档以及衍生的宣告前缀制品。
- 发布制品的 SHA256 校验和。
- 用于计划内数据集构建的 GitHub Actions 工作流。
- 风险记录中包含明确的 `expanded_prefixes_are_evidence: false` 字段。
- 在 `data/blackroute.example.jsonl` 下提供本地冒烟测试装置。
## 快速开始
```
go test ./...
go run ./cmd/asn-karma \
-input data/blackroute.example.jsonl \
-out release \
-readme README.md
```
该命令将发布制品写入 `release/` 目录。
```
release/
index.json
asn-risk.jsonl
asn-changes.jsonl
asn-summary.csv
asn-evidence-table.md
asn-profiles.tar.gz
source-impact.csv
country-risk.csv
high-risk-asn-critical.txt
high-risk-asn-high.txt
high-risk-asn-watch.txt
high-risk-asn-prefixes-critical.txt
high-risk-asn-prefixes-high.txt
high-risk-asn-prefixes-watch.txt
report.md
release-notes.md
run_stats.json
checksums.txt
```
## 安装
### 从源码构建
```
git clone https://github.com/ipanalytics/ASN-Karma.git
cd ASN-Karma
go build -o bin/asn-karma ./cmd/asn-karma
```
### 环境要求
| 组件 | 版本 |
| --- | --- |
| Go | 1.22 或更高版本 |
| 输入数据集 | BlackRoute JSONL |
| 运行环境 | Linux、macOS 或容器化的 CI 环境 |
## 使用说明
针对本地的
BlackRoute 导出文件运行：
```
asn-karma \
-input data/blackroute.jsonl \
-config configs/scoring.json \
-out release
```
ASN 丰富映射默认已启用。如果要对已经包含 ASN 字段的数据进行离线解析器测试：
```
asn-karma \
-input data/blackroute.example.jsonl \
-out release \
-asn-enrich=false
```
使用固定的构建时间戳以生成可复现的测试输出：
```
asn-karma \
-input data/blackroute.example.jsonl \
-out /tmp/asn-karma-release \
-built-at 2026-06-15T00:00:00Z
```
直接使用 Go 运行：
```
go run ./cmd/asn-karma -input data/blackroute.jsonl -out release
```
## 输出制品
| 制品 | 格式 | 用途 |
| --- | --- | --- |
| `index.json` | JSON | 机器可读的发布清单，包含大小和 SHA256 哈希值 |
| `asn-risk.jsonl` | JSONL | 主要的机器可读 ASN 风险数据集 |
| `asn-changes.jsonl` | JSONL | 自上次构建以来的 delta feed |
| `asn-summary.csv` | CSV | 简洁的审查和报告表 |
| `asn-evidence-table.md` | Markdown | 供 README 和 release notes 使用的 ASN 证据排名前列的表格 |
| `asn-profiles.tar.gz` | tar.gz | 每个 ASN 的 JSON 配置文件，包含风险、历史、置信度和衍生前缀 |
| `source-impact.csv` | CSV | 来源贡献和 ASN 影响摘要 |
| `country-risk.csv` | CSV | 国家/地区级别的运营汇总 |
| `high-risk-asn-critical.txt` | TXT | 严格执行层级 |
| `high-risk-asn-high.txt` | TXT | 挑战或速率限制层级 |
| `high-risk-asn-watch.txt` | TXT | 丰富映射和日志记录层级 |
| `high-risk-asn-prefixes-critical.txt` | TXT | 衍生的严重 ASN 层级的宣告前缀 |
| `high-risk-asn-prefixes-high.txt` | TXT | 衍生的高 ASN 层级的宣告前缀 |
| `high-risk-asn-prefixes-watch.txt` | TXT | 衍生的观察 ASN 层级的宣告前缀 |
| `report.md` | Markdown | 包含 delta、国家/地区和来源影响的渲染版发布报告 |
| `release-notes.md` | Markdown | 包含运行摘要和 ASN 排名前列表格的 GitHub Release 正文 |
| `run_stats.json` | JSON | 构建元数据和层级计数 |
| `checksums.txt` | TXT | 发布制品的 SHA256 校验和 |
## 最新 ASN 证据
计划的构建任务会根据当前数据集更新此表。`Evidence` 是指在当前构建窗口期内，为该 ASN 聚合的观察到的
BlackRoute 记录数量。当上游记录或丰富映射数据中存在国家/地区信息时，将自动填充。
_最近更新：`2026-06-16T10:00:37Z`_
| ASN | 名称 | 国家/地区 | 证据 | 来源 | 评分 | 层级 | 审查 |
| --- | --- | --- | ---: | ---: | ---: | --- | --- |
| AS16509 | AMAZON-02 - Amazon.com, Inc., US | US | 360959 | 34 | 65 | `watch` | true |
| AS14061 | DIGITALOCEAN-ASN - DigitalOcean, LLC, US | US | 169742 | 34 | 65 | `watch` | true |
| AS174 | COGENT-174 - Cogent Communications, LLC, US | US | 96454 | 23 | 65 | `watch` | true |
| AS14618 | AMAZON-AES - Amazon.com, Inc., US | US | 85728 | 32 | 65 | `watch` | true |
| AS4134 | CHINANET-BACKBONE - No.31,Jin-rong Street, CN | CN | 78169 | 32 | 65 | `watch` | true |
| AS37963 | ALIBABA-CN-NET - Hangzhou Alibaba Advertising Co.,Ltd., CN | CN | 57004 | 25 | 65 | `watch` | true |
| AS396982 | GOOGLE-CLOUD-PLATFORM - Google LLC, US | US | 51545 | 33 | 65 | `watch` | true |
| AS8075 | MICROSOFT-CORP-MSN-AS-BLOCK - Microsoft Corporation, US | US | 47084 | 32 | 65 | `watch` | true |
| AS20011 | Dimension Data - Dimension Data, ZA | ZA | 43901 | 12 | 65 | `watch` | true |
| AS4837 | CHINA169-Backbone - CHINA UNICOM China169 Backbone, CN | CN | 41447 | 31 | 65 | `watch` | true |
| AS45102 | ALIBABA-CN-NET - Alibaba (US) Technology Co., Ltd., CN | US | 38236 | 31 | 65 | `watch` | true |
| AS16276 | OVH - OVH SAS, FR | FR | 37021 | 32 | 65 | `watch` | true |
| AS31898 | ORACLE-BMC-31898 - Oracle Corporation, US | US | 29913 | 29 | 65 | `watch` | true |
| AS36352 | AS-COLOCROSSING - HostPapa, US | US | 29491 | 30 | 65 | `watch` | true |
| AS24940 | HETZNER-AS - Hetzner Online GmbH, DE | DE | 23170 | 30 | 65 | `watch` | true |
| AS132203 | TENCENT-NET-AP-CN - Tencent Building, Kejizhongyi Avenue, CN | SG | 20518 | 24 | 65 | `watch` | true |
| AS20473 | AS-VULTR - The Constant Company, LLC, US | US | 18902 | 24 | 65 | `watch` | true |
| AS212238 | CDNEXT - Datacamp Limited, GB | GB | 17784 | 27 | 65 | `watch` | true |
| AS45090 | TENCENT-NET-AP - Shenzhen Tencent Computer Systems Company Limited, CN | CN | 16741 | 28 | 65 | `watch` | true |
| AS203020 | HostRoyale - HostRoyale Technologies Pvt Ltd, IN | US | 15868 | 18 | 85 | `high` | false |
| AS3257 | GTT-BACKBONE - GTT Communications Inc., US | US | 13207 | 13 | 65 | `watch` | true |
| AS12389 | ROSTELECOM-AS - PJSC Rostelecom, RU | RU | 12760 | 25 | 65 | `watch` | true |
| AS51167 | CONTABO - Contabo GmbH, DE | DE | 12567 | 29 | 65 | `watch` | true |
| AS63949 | AKAMAI-LINODE-AP - Akamai Connected Cloud, SG | US | 12488 | 27 | 65 | `watch` | true |
| AS9829 | BSNL-NIB - National Backbone, IN | IN | 11507 | 23 | 65 | `watch` | true |
### 风险记录
当 ASN 记录可用时，`asn-risk.jsonl` 会为每个 ASN 包含一个 JSON 对象：
```
{
"asn": 64500,
"asn_name": "Example Hosting",
"country": "US",
"risk_score": 39,
"risk_level": "low",
"confidence_score": 40,
"confidence": "low",
"recommended_action": "no_action",
"observed_records": 2,
"unique_observed_cidrs": 2,
"source_count": 2,
"source_diversity": 2,
"top_threat_labels": {
"c2_ioc": 1,
"malware_host_active": 1,
"network_scan_or_abuse": 1
},
"evidence_window_days": 30,
"persistence_days_30d": 1,
"active_days_7d": 1,
"active_days_30d": 1,
"active_days_90d": 1,
"first_seen": "2026-06-15",
"last_seen": "2026-06-15",
"trend": "new",
"evidence_delta_1d": 2,
"expanded_prefix_count": 0,
"expanded_prefixes_are_evidence": false,
"large_cloud": false,
"watchlist": false,
"built_at": "2026-06-15T00:00:00Z"
}
```
如果构建过程被明确允许在 ASN 记录为零的情况下完成，`asn-risk.jsonl` 将包含一个单一的 `build_status` JSON 对象，解释未生成任何 ASN 记录的原因。计划的生产构建不使用 `-allow-empty`；空的 ASN 数据集会在发布前失败。
## 数据契约
Schema 保存于 `docs/schema/` 目录下：
| Schema | 覆盖范围 |
| --- | --- |
| `docs/schema/asn-risk.schema.json` | `asn-risk.jsonl` 记录 |
| `docs/schema/asn-changes.schema.json` | `asn-changes.jsonl` 记录 |
| `docs/schema/index.schema.json` | `index.json` 发布清单 |
| `docs/schema/run-stats.schema.json` | `run_stats.json` |
## 集成示例
操作示例位于 `examples/` 目录下：
| 文件 | 目标 |
| --- | --- |
| `examples/cloudflare-waf.md` | Cloudflare WAF ASN 策略 |
| `examples/nginx-map.md` | NGINX 丰富映射模式 |
| `examples/opnsense-alias.md` | OPNsense 防火墙别名 |
| `examples/splunk-lookup.md` | Splunk CSV 查找 |
| `examples/clickhouse-ingest.sql` | ClickHouse JSONL 摄取 |
## 评分策略
评分在 `configs/scoring.json` 中配置。
| 信号 | 作用 |
| --- | --- |
| 来源多样性 | 奖励跨信息源的交叉验证 |
| 威胁严重性 | 对 C2、恶意软件托管、垃圾邮件和扫描等标签进行权重计算 |
| 近期活动 | 捕获在构建窗口期内观察到的数量 |
| 滥用密度代理 | 为较小但高度集中的滥用面赋予权重 |
| 网络犯罪前缀奖励 | 对严重的基础设施标签增加权重 |
| 大型云惩罚 | 减少对广泛提供商的过度分类 |
| 允许列表惩罚 | 在适当情况下抑制已知的基础设施 |
| 观察列表标记 | 添加上下文，而不会将上下文转化为证据 |
风险层级分为 `critical`、`high`、`watch` 或 `low`。
## 运维说明
- 将 `asn-risk.jsonl` 视为权威制品。
- 仅在本地验证后才将 TXT 层级文件用作策略输入。
- 保持评分更改是可审查的；策略漂移应体现在配置差异中。
- 不要将衍生的 ASN 前缀扩展反馈回源证据。
- 使用 `checksums.txt` 验证下载的制品。
- 标记为 `review_required=true` 的 ASN 属于大型云、骨干网、CDN 或主要托管网络；除非本地遥测数据支持执行，否则它们将被限制在审查/观察策略内。
- 大型云和 CDN 网络在生产策略中需要具备提供商感知的处理方式。
- 在上游 BlackRoute 发布完成后，按计划运行构建。
## 项目范围
ASN Karma 专注于 ASN 级别的聚合、评分和制品生成。其设计初衷是作为原始 IP 信誉源与下游执行、丰富映射或分析系统之间的桥梁。
计划的扩展点包括：
- 可选的发布签名。
- GitHub Pages 数据集索引。
## 用例
- 使用 ASN 风险上下文丰富 SIEM、SOAR 和数据湖事件。
- 利用保守的 ASN 层级为 WAF、CDN 和边缘策略提供输入。
- 追踪托管提供商和网络运营商中的滥用集中度。
- 为欺诈和风险 pipeline 提供基础设施级特征支持。
- 为安全运营构建每日 ASN 风险报告。
## 局限性
ASN 级别的评分在设计上较为粗略。在采取执行措施之前，应将其与本地遥测、资产上下文、客户影响分析以及特定于提供商的知识相结合。
Team Cymru 丰富映射使用当前的 BGP 归属数据。对于历史分析，请针对已经包含符合时间段的 ASN 元数据的输入数据运行评分程序。
## 目录结构
```
.
├── cmd/asn-karma/ # CLI entrypoint
├── configs/ # scoring and policy configuration
├── data/ # local fixtures and input data
├── data/history/ # persisted daily ASN history state
├── docs/schema/ # JSON schema contracts
├── examples/ # integration examples
├── internal/blackroute/ # BlackRoute JSONL ingest
├── internal/enrich/ # ASN enrichment adapters
├── internal/model/ # normalized records and aggregation
├── internal/output/ # release artifact writers
├── internal/scoring/ # scoring policy implementation
├── release/ # generated artifacts
├── site/ # README and documentation assets
└── .github/workflows/ # scheduled build automation
```
## 部署
本仓库包含一个计划的 GitHub Actions 工作流：
```
on:
schedule:
- cron: "47 4 * * *"
workflow_dispatch:
```
该工作流会测试 Go 代码，下载最新的 BlackRoute JSONL release，构建 ASN Karma 制品，更新 README 证据表，并将生成的文件作为 GitHub release 发布。
对于自托管部署，可以通过 cron、systemd 定时器、Kubernetes CronJobs 或现有的数据编排系统运行此 CLI。该过程是面向批处理的，并为每次运行写入不可变的输出文件。
Kubernetes CronJob 命令示例
```
command:
- /usr/local/bin/asn-karma
- -input
- /data/blackroute.jsonl
- -config
- /config/scoring.json
- -out
- /release
```
## 许可证
MIT 许可证。
## 免责声明
ASN Karma 提供源自公开滥用证据的基础设施风险信号。运营人员有责任在执行前应用本地策略、验证和影响控制措施。