wolffcatskyy/crowdsec-blocklist-import

# crowdsec-blocklist-import **将 28+ 威胁情报源导入 CrowdSec，支持自动去重、规范化处理和实时同步。** [](https://github.com/wolffcatskyy/crowdsec-blocklist-import/stargazers) [](https://github.com/wolffcatskyy/crowdsec-blocklist-import/actions/workflows/ci.yml) [](https://github.com/wolffcatskyy/crowdsec-blocklist-import/releases/latest) [](LICENSE) [](https://www.python.org/) [](https://github.com/wolffcatskyy/crowdsec-blocklist-import/pkgs/container/crowdsec-blocklist-import) [](https://github.com/wolffcatskyy/awesome-crowdsec) ``` Threat Feeds (28+) crowdsec-blocklist-import CrowdSec LAPI ┌──────────────────┐ ┌────────────────────────┐ ┌──────────────┐ │ IPsum │───────>│ Fetch & Normalize │ │ │ │ Spamhaus DROP │───────>│ Deduplicate vs LAPI │───────>│ Decisions │──> Bouncers │ Firehol L1/L2/L3 │───────>│ Batch Import │ │ Database │ (fw, CDN, │ Abuse.ch Feodo │───────>│ Allowlist Filtering │ │ │ nginx...) │ 24 more feeds... │───────>│ Webhook + Metrics │ └──────────────┘ └──────────────────┘ └────────────────────────┘ ``` **目录：** [为什么选择此工具](#why-ip-freshness-matters) | [功能特性](#core-features) | [快速开始](#quickstart) | [安装说明](#installation) | [配置选项](#configuration) | [阻止列表](#supported-blocklists) | [CLI 用法](#cli-usage) | [进阶用法](#advanced-usage) | [监控](#monitoring) | [故障排除](#troubleshooting) | [贡献指南](#contributing) ## IP 时效性为何如此重要 大多数阻止列表工具都存在一个致命缺陷：**陈旧性**。它们按计划获取阻止列表，将其缓存，并执行已过时的条目长达数天或数周。届时，威胁行为者早已转移到新的基础设施，但你的防火墙仍在封锁数周前被入侵的地址。 **crowdsec-blocklist-import 解决了这个问题：** - **新 IP 即时生效** -- 来自 28+ 源的新威胁在几分钟内（而非几天）到达你的网络 - **过期威胁立即移除** -- 已恢复的 IP 会自动从列表中剔除，而不会保留数周 - **无 Cron 延迟** -- 通过内置调度器每小时运行一次或按需运行 - **无陈旧漂移** -- 每次同步都是完全刷新；没有孤立的条目残留 这就是被动安全（等待警报）与**主动威胁情报**（领先于攻击者）之间的区别。 ## 核心功能 - **去重引擎** -- 检测已在 CrowdSec 中的 IP，消除冗余处理和 API 调用 - **规范化层** -- 跨所有源剔除注释、验证 CIDR 块、移除重复项并强制执行一致的格式 - **实时同步** -- 无缓存，无延迟。每次导入都是使用实时威胁数据的完全刷新 - **28+ 威胁源** -- IPsum、Spamhaus、Blocklist.de、Firehol、Abuse.ch、Emerging Threats、Binary Defense、DShield、Talos、Tor 节点、扫描器 IP 等 - **单源控制** -- 通过环境变量启用或禁用单个阻止列表 - **允许列表支持** -- 三层系统：静态 IP 列表、CIDR 范围和特定提供商的例外（GitHub IP） - **内置调度器** -- 具有 `INTERVAL=3600` 的长期运行守护进程模式。支持优雅的 SIGTERM/SIGINT 关闭 - **Webhook 通知** -- 将导入结果推送到 Discord、Slack 或任何通用 webhook 端点 - **AbuseIPDB 集成** -- 公共镜像（无需密钥）加上可选的直接 API，以获得更高的速率限制和更新的数据 - **Prometheus 指标** -- 推送到 Pushgateway 以监控导入、去重率和源健康状况 - **Grafana 仪表板** -- 预构建的[仪表板](grafana-dashboard.json)，用于可视化导入指标 - **Docker Secrets** -- 所有凭证变量都支持 `_FILE` 后缀，用于挂载密钥文件 - **合并警报** -- 可选择将每次运行的所有 IP 批量合并为单个警报，以节省 CrowdSec 警报配额 ## 快速开始 ### 1. 前置条件 你需要运行 CrowdSec 并具有 LAPI 凭证： ``` # 创建 machine 凭证 (用于写入 decisions) cscli machines add blocklist-import --password 'SecurePassword123' # 创建 bouncer 密钥 (用于读取现有 decisions) cscli bouncers add blocklist-import -o raw # 保存输出 —— 稍后您会用到它 ``` ### 2. Docker Compose（推荐） ``` services: blocklist-import: image: ghcr.io/wolffcatskyy/crowdsec-blocklist-import:latest restart: unless-stopped networks: - crowdsec environment: - CROWDSEC_LAPI_URL=http://crowdsec:8080 - CROWDSEC_LAPI_KEY=YOUR_BOUNCER_KEY - CROWDSEC_MACHINE_ID=blocklist-import - CROWDSEC_MACHINE_PASSWORD=SecurePassword123 - DECISION_DURATION=24h - INTERVAL=3600 # Run every hour (built-in scheduler) - LOG_LEVEL=INFO networks: crowdsec: external: true ``` ``` docker compose up -d ``` 设置 `INTERVAL=3600` 后，容器将作为长期运行的守护进程运行，并每小时重复一次。不需要 cron 或 systemd 计时器。设置 `INTERVAL=0`（默认值）则仅运行一次。 ### 3. 单次运行模式（Cron/计时器） 如果你更喜欢外部调度，请省略 `INTERVAL` 并使用 `restart: "no"`： ``` # 每天凌晨 4 点 0 4 * * * docker compose -f /path/to/compose.yml up --abort-on-container-exit ``` ## 安装说明 ### Docker（推荐） ``` docker run --rm --network crowdsec \ -e CROWDSEC_LAPI_URL=http://crowdsec:8080 \ -e CROWDSEC_LAPI_KEY=YOUR_KEY \ -e CROWDSEC_MACHINE_ID=blocklist-import \ -e CROWDSEC_MACHINE_PASSWORD=YourPassword \ ghcr.io/wolffcatskyy/crowdsec-blocklist-import:latest ``` ### Homebrew（macOS/Linux） ``` brew tap wolffcatskyy/crowdsec brew install crowdsec-blocklist-import ``` ### pip（Python 3.9+） ``` pip install git+https://github.com/wolffcatskyy/crowdsec-blocklist-import.git cp .env.example .env # 使用您的凭证编辑 .env crowdsec-blocklist-import ``` ### 从源码安装 ``` git clone https://github.com/wolffcatskyy/crowdsec-blocklist-import.git cd crowdsec-blocklist-import pip install -r requirements.txt cp .env.example .env # 使用您的凭证编辑 .env python blocklist_import.py ``` ### 本地构建 Docker 镜像 ``` git clone https://github.com/wolffcatskyy/crowdsec-blocklist-import.git cd crowdsec-blocklist-import docker build -t crowdsec-blocklist-import . docker run --rm --network crowdsec -e ... crowdsec-blocklist-import ``` 有关详细的配置选项，请参阅[配置参考](docs/config-reference.md)。 ## 配置选项 ### 最小设置 使用你的 CrowdSec 凭证编辑 `.env`： ``` CROWDSEC_LAPI_URL=http://crowdsec:8080 CROWDSEC_LAPI_KEY=your_bouncer_key CROWDSEC_MACHINE_ID=blocklist-import CROWDSEC_MACHINE_PASSWORD=your_password DECISION_DURATION=24h ``` 所有凭证变量都通过 `_FILE` 后缀支持 Docker Secrets（例如 `CROWDSEC_LAPI_KEY_FILE=/run/secrets/lapi_key`）。 ### 常用设置 | 变量 | 默认值 | 用途 | |----------|---------|---------| | `DECISION_DURATION` | `24h` | 导入的决策持续时间 | | `BATCH_SIZE` | `1000` | 每批 IP 数量（内存与速度的权衡） | | `DECISION_TYPE` | `ban` | 决策类型（`ban`、`captcha`、`throttle`） | | `LOG_LEVEL` | `INFO` | `DEBUG`、`INFO`、`WARN`、`ERROR` | | `DRY_RUN` | `false` | 预览而不导入 | | `INTERVAL` | `0` | 守护进程模式：运行间隔秒数（0 = 单次运行） | | `CONSOLIDATE_ALERTS` | `false` | 将所有 IP 批量合并为每次运行一个警报（节省警报配额） | ### 通知设置 | 变量 | 默认值 | 用途 | |----------|---------|---------| | `WEBHOOK_URL` | *(无)* | 导入通知的 Webhook URL | | `WEBHOOK_TYPE` | `generic` | Webhook 格式：`generic`、`discord`、`slack` | ### AbuseIPDB `ENABLE_ABUSE_IPDB=true` 获取由 [@borestad](https://github.com/borestad/blocklist-abuseipdb) 维护的**公共镜像** —— 无需 API 密钥。 要获得更高的速率限制和更新的数据，你可以选择配置**直接 API 密钥**： | 变量 | 默认值 | 用途 | |----------|---------|---------| | `ABUSEIPDB_API_KEY` | *(无)* | 可选：用于更高速率限制的直接 API 密钥 | | `ABUSEIPDB_API_KEY_FILE` | *(无)* | 可选：API 密钥文件路径 | | `ABUSEIPDB_MIN_CONFIDENCE` | `90` | 最小置信度分数 (1-100) | | `ABUSEIPDB_LIMIT` | `10000` | 每次直接 API 查询获取的最大 IP 数 | 在 [abuseipdb.com](https://www.abuseipdb.com/) 获取免费 API 密钥。免费层每天允许 5 次黑名单检查。 ### 选择性阻止列表 默认情况下，所有阻止列表均已启用。禁用你不需要的源： ``` ENABLE_IPSUM=true # Aggregated threats (recommended) ENABLE_SPAMHAUS=true # Spamhaus DROP ENABLE_TOR=false # Tor exit nodes (may cause false positives) ENABLE_SCANNERS=false # Shodan/Censys scanners ``` 有关 `ENABLE_*` 变量的完整列表，请参阅[配置参考](docs/config-reference.md)。 ### 允许列表 保护受信任的 IP 免被阻止： ``` # 以逗号分隔的 IP 和/或 CIDR 范围 ALLOWLIST="1.2.3.4,5.6.7.8,192.168.0.0/16,10.0.0.0/8" # 自动获取 GitHub IP 范围 (git, web, api, hooks, actions) ALLOWLIST_GITHUB=true ``` ## 支持的阻止列表 crowdsec-blocklist-import 从 28+ 威胁情报源拉取数据： | 来源 | 用途 | 类型 | |--------|---------|------| | **IPsum** | 聚合威胁情报（出现在 3+ 阻止列表上的 IP） | 聚合 | | **Spamhaus DROP** | 已知被劫持的网络 | 网络块 | | **Blocklist.de** | SSH、Web、邮件攻击（所有类别） | 攻击向量 | | **Firehol Level 1/2/3** | 恶意软件、C2、受损主机 | 恶意软件 | | **Abuse.ch** | Feodo（银行木马）、SSL 黑名单、URLhaus | 恶意软件 | | **Emerging Threats** | 受损 IP 检测 | 威胁 | | **Binary Defense** | 恶意软件、DoS、僵尸网络 IP | 恶意软件 | | **Bruteforce Blocker** | SSH/RDP 暴力破解攻击 | 攻击 | | **DShield** | 热门攻击 IP (Internet Storm Center) | 威胁 | | **CI Army** | 声誉不佳的主机 | 威胁 | | **AbuseIPDB** | 已报告的恶意 IP（公共镜像；可选直接 API） | 威胁 | | **Cybercrime Tracker** | 网络犯罪基础设施 | 恶意软件 | | **Monty Security C2** | 命令控制服务器 | 恶意软件 | | **VX Vault** | 恶意软件托管 IP | 恶意软件 | | **Botvrij** | 僵尸网络 C2 服务器 | 恶意软件 | | **GreenSnow** | 攻击者 IP | 威胁 | | **StopForumSpam** | 论坛垃圾邮件来源 | 垃圾邮件 | | **Tor Exit Nodes** | Tor 网络出口点 | 隐私 | | **Scanner IPs** | Shodan、Censys、互联网扫描器 | 扫描器 | 有关包含 URL 和威胁类型的完整列表，请参阅[示例](docs/examples.md)。 ## CLI 用法 ``` python blocklist_import.py [options] Options: -h, --help Show help -v, --version Show version and exit -n, --dry-run Preview without importing -d, --debug Enable debug logging --setup Launch interactive setup wizard --lapi-url URL Override LAPI URL --lapi-key KEY Override LAPI key --duration DURATION Override decision duration --batch-size SIZE Override batch size --list-sources List all available blocklist sources --validate Validate configuration and exit --pushgateway-url URL Override Prometheus Pushgateway URL --no-metrics Disable Prometheus metrics for this run --interval SECONDS Daemon mode: repeat every N seconds --webhook-url URL Webhook URL for notifications --webhook-type TYPE Webhook format: generic, discord, slack ``` ### 示例 ``` # 启动交互式设置向导 python blocklist_import.py --setup # Dry-run 以查看将要导入的内容 python blocklist_import.py --dry-run # 列出所有可用来源 python blocklist_import.py --list-sources # 使用自定义持续时间和 batch size 进行导入 python blocklist_import.py --duration 48h --batch-size 500 # 验证配置而不运行 python blocklist_import.py --validate ``` ## 进阶用法 ### 守护进程模式（内置调度器） 作为长期运行的服务运行，而不是使用 cron： ``` INTERVAL=3600 # Run every hour RUN_ON_START=false # Skip the first run and wait for the interval ``` 该守护进程优雅地处理 SIGTERM/SIGINT —— 它会完成当前运行，然后退出。这使其通过 `restart: unless-stopped` 与 Docker 兼容。 ### Webhook 通知 在每次导入运行后获取通知： ``` # Discord WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK WEBHOOK_TYPE=discord # Slack WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL WEBHOOK_TYPE=slack # Generic JSON POST WEBHOOK_URL=https://your-endpoint.example.com/webhook WEBHOOK_TYPE=generic ``` ### AbuseIPDB 直接 API 默认情况下，`ENABLE_ABUSE_IPDB=true` 获取**公共镜像**（无需 API 密钥）。要使用直接 API 以获得更高的速率限制和更新的数据： ``` ABUSEIPDB_API_KEY=your_api_key_here # 或 ABUSEIPDB_API_KEY_FILE=your_api_key_file_path_here ABUSEIPDB_MIN_CONFIDENCE=90 # Only IPs with 90%+ confidence ABUSEIPDB_LIMIT=10000 # Max IPs to fetch ``` 在 [abuseipdb.com](https://www.abuseipdb.com/) 获取免费 API 密钥。免费层每天允许 5 次黑名单检查。 ### Docker Secrets 所有凭证变量都支持 `_FILE` 后缀以用于 Docker Secrets： ``` services: blocklist-import: image: ghcr.io/wolffcatskyy/crowdsec-blocklist-import:latest environment: - CROWDSEC_LAPI_KEY_FILE=/run/secrets/lapi_key - CROWDSEC_MACHINE_PASSWORD_FILE=/run/secrets/machine_password secrets: - lapi_key - machine_password secrets: lapi_key: file: ./secrets/lapi_key.txt machine_password: file: ./secrets/machine_password.txt ``` ### 使用自定义配置的 Docker 挂载你的 `.env` 文件： ``` docker run --rm \ --network crowdsec \ -v /path/to/.env:/app/.env:ro \ ghcr.io/wolffcatskyy/crowdsec-blocklist-import:latest ``` ### 使用 Systemd 计时器调度

Systemd 服务和计时器单元文件

创建 `/etc/systemd/system/blocklist-import.service`： ``` [Unit] Description=CrowdSec Blocklist Import After=docker.service Requires=docker.service [Service] Type=oneshot ExecStart=docker compose -f /opt/compose/blocklist-import.yml up --abort-on-container-exit StandardOutput=journal StandardError=journal ``` 创建 `/etc/systemd/system/blocklist-import.timer`： ``` [Unit] Description=CrowdSec Blocklist Import Timer Requires=blocklist-import.service [Timer] OnBootSec=5min OnUnitActiveSec=1h AccuracySec=1min [Install] WantedBy=timers.target ``` 启用： ``` systemctl daemon-reload systemctl enable --now blocklist-import.timer ```

有关更多示例，请参阅[进阶用法](docs/examples.md)。 ## 监控 ### Prometheus 指标 将指标推送到 Prometheus Pushgateway： ``` METRICS_PUSHGATEWAY_URL=http://prometheus:9091 ``` 跟踪的指标： - 每个源导入的 IP 总数 - 跳过的重复条目 - 每个源的导入失败数 - 每次运行的导入持续时间 ### Grafana 仪表板 [`grafana-dashboard.json`](grafana-dashboard.json) 中包含预构建的 Grafana 仪表板。将其导入 Grafana 以随时间可视化导入活动、去重率和源健康状况。 ## CrowdSec UniFi 生态系统的一部分 crowdsec-blocklist-import 适用于任何 CrowdSec 设置。它也与下面特定于 UniFi 的项目完美搭配，以便在 UniFi 硬件上实现完整的检测 → 决策 → 执行堆栈： | 项目 | 描述 | |---------|-------------| | [crowdsec-unifi-suite](https://github.com/wolffcatskyy/crowdsec-unifi-suite) | 完整堆栈的一键安装程序 | | [crowdsec-unifi-bouncer](https://github.com/wolffcatskyy/crowdsec-unifi-bouncer) | 在 UniFi 防火墙上执行 CrowdSec 决策 | | [crowdsec-unifi-parser](https://github.com/wolffcatskyy/crowdsec-unifi-parser) | 为 CrowdSec 解析 UniFi 防火墙日志 | ## 故障排除 ### CrowdSec 连接失败 ``` # 验证 LAPI 是否可达 curl http://crowdsec:8080/health # 如果使用 Docker，请确保容器共享一个网络 docker network inspect crowdsec ``` ### 认证错误 ``` # 测试 bouncer 密钥 curl -H "X-Api-Key: YOUR_KEY" http://crowdsec:8080/decisions # 测试 machine 登录 curl -X POST http://crowdsec:8080/watchers/login \ -H "Content-Type: application/json" \ -d '{"machine_id":"blocklist-import","password":"YourPassword"}' ``` ### 未导入 IP ``` docker logs blocklist-import # Docker logs python blocklist_import.py --debug # Detailed output ``` 常见原因- 所有阻止列表均已禁用（检查 `ENABLE_*` 变量） - CrowdSec 已包含所有 IP（检查日志中的去重计数） - 网络连接问题（检查 `curl https://example.com`） ### 内存问题 ``` BATCH_SIZE=100 # Reduce from default 1000 ENABLE_IPSUM=false # IPsum is the largest feed ``` 有关更多故障排除，请参阅 [FAQ](docs/faq.md)。 ## 技术细节 | 属性 | 值 | |-----------|-------| | **语言** | Python 3.9+ | | **架构** | 单文件，约 650 行生产代码 | | **依赖项** | `requests`、`python-dotenv`（+ 可选 `prometheus-client`） | | **内存** | ~50-100 MB 流式处理（300k+ IP） | | **速度** | 500-1000 IP/秒，具体取决于网络和 LAPI | | **Docker 镜像** | `ghcr.io/wolffcatskyy/crowdsec-blocklist-import:latest` (~150 MB) | | **认证** | CrowdSec LAPI 机器凭证 (JWT) + bouncer 密钥 | ## 贡献指南 我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 - **报告错误：** [GitHub Issues](https://github.com/wolffcatskyy/crowdsec-blocklist-import/issues) - **建议功能：** [GitHub Discussions](https://github.com/wolffcatskyy/crowdsec-blocklist-import/discussions) - **更新日志：** [CHANGELOG.md](CHANGELOG.md) - **路线图：** [ROADMAP.md](ROADMAP.md) ## 许可证 MIT 许可证 —— 详情请参阅 [LICENSE](LICENSE)。 ## 鸣谢 **由** [wolffcatskyy](https://github.com/wolffcatskyy) **维护**。在 Claude AI 的协助下开发。 **贡献者：** [gaelj](https://github.com/gaelj) **特别感谢：** - [CrowdSec](https://www.crowdsec.net/) 提供威胁检测平台 - 维护公开威胁源的安全社区 - [Awesome CrowdSec](https://github.com/wolffcatskyy/awesome-crowdsec) 社区

安全公告

这是在 [wolffcatskyy/crowdsec-blocklist-import](https://github.com/wolffcatskyy/crowdsec-blocklist-import) 维护的官方 CrowdSec 阻止列表导入工具。如果你是从其他来源或不同的 GitHub 用户处下载的，则可能正在使用冒充仓库。请务必验证你使用的是官方来源。

标签：CrowdSec, DevSecOps, Docker容器, IP封锁, IP黑名单, PB级数据处理, Python, Sysadmin, WAF, 上游代理, 入侵防御, 反垃圾邮件, 威胁情报, 安全运维, 开发者工具, 恶意IP检测, 攻击面发现, 数据聚合, 无后门, 网络安全, 自定义请求头, 请求拦截, 逆向工具, 防火墙, 隐私保护