dabumana/ransomware-live-go
GitHub: dabumana/ransomware-live-go
Ransomware.live 威胁情报 API 的 Go 客户端，封装了勒索软件组织追踪、受害者查询、IoC 获取、谈判记录检索等全套接口，便于开发者将威胁情报集成到 Go 应用中。
Stars: 0 | Forks: 0
# Ransomware.live - Go Client
Ransomware.live API 的 Go 客户端。Ransomware.live 是一个全面的威胁情报源，用于追踪勒索软件组织、受害者、入侵指标（IoCs）、谈判聊天记录、勒索信等。
## 安装
```
go get github.com/dabumana/ransomware
```
如果发布，请替换为您实际的 module 路径。
### 快速开始
```
package main
import (
"fmt"
"log"
"github.com/dabumana/ransomware"
)
func main() {
client := ransomware.NewClient("YOUR_API_KEY")
// Get recent victims
victims, err := client.GetRecentVictims()
if err != nil {
log.Fatal(err)
}
for _, v := range victims {
fmt.Printf("%s - %s (%s)\n", v.Victim, v.Group, v.Country)
}
}
```
## 认证
所有 endpoint 都需要 X-API-KEY header。您必须从 ransomware.live/my 获取免费的 API key。
将其传递给 NewClient：
```
client := ransomware.NewClient("your-api-key")
```
速率限制：每个 key 每月 500,000 次请求。超出此配额的请求将返回 HTTP 429。
### 客户端配置
您可以使用可选的 Option 函数自定义客户端：
### Option 描述
* **WithHTTPClient(http.Client)** 使用自定义的 HTTP 客户端（例如，使用代理）。
* **WithBaseURL(string)** 覆盖 base URL（对测试很有用）。
示例：
```
customClient := &http.Client{Timeout: 30 * time.Second}
client := ransomware.NewClient(
"api-key",
ransomware.WithHTTPClient(customClient),
ransomware.WithBaseURL("https://custom-api.example.com"),
)
```
## API 方法
### 组织
|方法 | Endpoint |描述|
|-------|----------|-----------|
|ListGroups() ([]GroupSummary, error) | GET /groups | 返回所有受追踪的勒索软件组织及其受害者数量。|
|GetGroup(name string) (*GroupDetail, error) | GET /groups/{groupname} | 返回特定勒索软件组织的综合情报，包括描述、受害者、首次/最后发现时间、位置（Tor/明网 URL）、TTPs（MITRE ATT&CK）、漏洞（附带 CVSS 评分的 CVE）、工具、谈判/勒索信可用性。|
### 受害者
|方法 | Endpoint | 描述|
|-------|----------|------------|
|GetRecentVictims(order string) ([]Victim, error) | GET /victims/recent | 返回 100 个最近的活跃受害者，包含截图、infostealer 数据、新闻报道和 permalink。|
|ListVictims(filter VictimFilter) ([]Victim, error) | GET /victims/ | 返回符合所提供过滤器的受害者（至少需要一个过滤器）。|
|SearchVictims(q string, filter VictimFilter) ([]Victim, error) | GET /victims/search | 对受害者名称和网站域名进行全文搜索，支持可选的辅助过滤器。|
|GetVictim(victimID string) (*VictimDetail, error) | GET /victim/{victim_id} | 返回单个受害者的详细信息。victim_id 是 post_title@group_name 的 Base64 编码字符串（可从任何受害者列表中的 id 字段获取）。|
### 入侵指标
|方法 | Endpoint | 描述|
|-------|----------|------------|
|ListIOCGroups(iocType string) ([]IOCGroup, error) GET /iocs 返回所有拥有 IoC 的勒索软件组织，并附带 IoC 类型和数量的明细。使用 ?type= 过滤具有特定 IoC 类型（如 md5、ip、btc）的组织。
|GetGroupIOCs(group string, iocType string) (*GroupIOCs, error) GET /iocs/{group} 返回特定勒索软件组织的所有 IoC，按类型（如 md5、ip、domain）组织。使用 ?type= 仅检索一种 IoC 类型。
### 谈判聊天
|方法 | Endpoint | 描述|
|-------|----------|------------|
|ListNegotiationGroups() ([]NegotiationGroup, error) | GET /negotiations | 列出所有泄露了可用谈判聊天记录的勒索软件组织，并附带每个组织的聊天数量。|
|ListNegotiationChats(group string) ([]NegotiationChat, error) | GET /negotiations/{group} | 返回给定组织所有可用谈判聊天的元数据（聊天 ID、消息计数、初始勒索金额、协商金额、支付状态）。|
|GetNegotiationChat(group, chatID string) (*NegotiationChatDetail, error) | GET /negotiations/{group}/{chat_id} | 返回特定谈判聊天的完整消息线程和勒索元数据。|
### 勒索信
|方法 | Endpoint | 描述|
|-------|----------|------------|
|ListRansomNoteGroups() ([]RansomNoteGroup, error) | GET /ransomnotes | 列出所有至少存有一份勒索信的勒索软件组织，并附带每个组织的勒索信数量。|
|ListRansomNotes(group string) ([]string, error) | GET /ransomnotes/{group} | 返回某个组织的勒索信标识符列表（不带扩展名的文件名）。|
|GetRansomNote(group, noteName string) (*RansomNote, error) | GET /ransomnotes/{group}/{note_name} | 返回特定勒索信的完整文本内容（支持的格式：.txt、.html、.md）。|
### YARA 规则
|方法 | Endpoint | 描述|
|-------|----------|------------|
|ListYARAGroups() ([]YARAGroup, error) | GET /yara | 列出所有具有关联 YARA 检测规则的勒索软件组织，并附带每个组织的规则文件数量。|
|GetYARARules(group string) ([]YARARule, error) | GET /yara/{group} | 返回特定勒索软件组织的所有 YARA 规则（文件名 + 完整规则内容）。|
### 新闻 / 网络攻击记录
|方法 | Endpoint | 描述|
|-------|----------|------------|
|ListPressEntries(year, month, country string) ([]PressEntry, error) | GET /press/all | 返回所有受追踪的网络攻击新闻记录，如果受害者域名与已知受害者匹配，则会附带 HudsonRock infostealer 数据和勒索软件链接。结果按日期降序排列。|
|GetRecentPressEntries(country string) ([]PressEntry, error) | GET /press/recent | 返回 100 条最新的网络攻击新闻记录，包含 infostealer 数据和勒索软件链接。可选的国家/地区过滤器。|
### CSIRT 联系方式
|方法 | Endpoint | 描述|
|-------|----------|------------|
|GetCSIRTContacts(country string) ([]CSIRTContact, error) | GET /csirt/{country} | 返回指定国家/地区的所有 CSIRT/CERT 联系方式。接受 ISO 3166-1 alpha-2（如 FR）和 alpha-3（如 FRA）代码。|
### SEC 8-K 表格文件
|方法 | Endpoint | 描述|
|-------|----------|------------|
|GetSECFilings(ticker, cik, year, month string, item105, item801 bool) ([]SECFiling, error) | GET /8k | 返回与网络安全事件相关的 SEC 8-K 表格文件（Item 1.05 - 重大网络安全事件，自 2023 年 12 月起强制要求；Item 8.01 – 其他事件）。|
### 行业
|方法 | Endpoint | 描述|
|-------|----------|------------|
|ListSectors() ([]Sector, error) | GET /listsectors | 返回受害者数据库中所有唯一的行业/部门值，按字母顺序排序，并附带每个行业的受害者数量。|
### 统计数据
|方法 | Endpoint | 描述|
|-------|----------|------------|
|GetStats() (*Stats, error) | GET /stats | 返回高级统计数据：受害者总数、受追踪的勒索软件组织数量、新闻/网络攻击记录数量，以及最近发现的受害者时间戳。|
### 验证
|方法 | Endpoint | 描述|
|-------|----------|------------|
|ValidateKey() (*ValidationResponse, error) | GET /validate | 检查提供的 X-API-KEY header 是否有效，并返回关联的客户端标识符。|
### 数据类型
常见的日期和国家/地区字段
* 日期字段 – attackdate 是估计的攻击/发布日期；discovered 是 ransomware.live 首次观察到该列表的时间。
* 国家/地区代码 – 除非另有说明，否则使用 ISO 3166-1 alpha-2（两位字母，如 US、FR）。
### 过滤
#### VictimFilter
与 ListVictims 和 SearchVictims 一起使用：
|字段 | 类型 | 描述|
|------|------|------------|
|Group | string | 勒索软件组织名称，不区分大小写的精确匹配。
|Sector | string | 受害者行业/部门，不区分大小写的精确匹配（使用 ListSectors 获取有效值）。
|Country | string | ISO 3166-1 alpha-2 国家/地区代码，大写（如 US、FR）。
|Year | string | 4 位数字的年份（如 2024）。
|Month | string | 2 位数字的月份，需要同时指定 Year（如 03）。
|Date | string | 要过滤的日期字段："discovered"（默认）或 "attacked"。
|Order | string | 最近受害者的排序方式："discovered"（默认）或 "attacked"。
**注意**：ListVictims 至少需要设置一个过滤器。
### 错误处理
客户端返回标准的 Go errors。常见错误：
* HTTP 429 – 超出速率限制（500,000 次请求/月）。
* HTTP 401/403 – API key 无效或缺失。
* HTTP 404 – 找不到资源（例如，无效的组织名称、受害者 ID 或聊天 ID）。
* HTTP 400 – 参数无效（例如，缺少必填字段）。
### 示例
1. 列出所有组织
```
groups, err := client.ListGroups()
if err != nil {
log.Fatal(err)
}
for _, g := range groups {
fmt.Printf("%s: %d victims\n", g.Group, g.Victims)
}
```
2. 获取详细的组织情报
```
group, err := client.GetGroup("lockbit3")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Description: %s\n", group.Description)
for _, ttp := range group.TTPs {
fmt.Printf("TTP: %s\n", ttp)
}
for _, vuln := range group.Vulnerabilities {
fmt.Printf("CVE: %s (CVSS: %.1f)\n", vuln.ID, vuln.CVSS)
}
```
3. 获取最近的受害者
```
victims, err := client.GetRecentVictims("discovered")
if err != nil {
log.Fatal(err)
}
for _, v := range victims {
fmt.Printf("%s (%s) - %s\n", v.Victim, v.Group, v.Country)
}
```
4. 按组织和国家/地区过滤受害者
```
filter := ransomware.VictimFilter{
Group: "lockbit",
Country: "US",
}
victims, err := client.ListVictims(filter)
if err != nil {
log.Fatal(err)
}
```
5. 按关键字搜索受害者
```
victims, err := client.SearchVictims("hospital", ransomware.VictimFilter{Country: "FR"})
if err != nil {
log.Fatal(err)
}
```
6. 获取组织的 IoC
```
iocs, err := client.GetGroupIOCs("lockbit3", "ip")
if err != nil {
log.Fatal(err)
}
for _, ip := range iocs.IPs {
fmt.Println(ip)
}
```
7. 获取谈判聊天
```
chats, err := client.ListNegotiationChats("lockbit3")
if err != nil {
log.Fatal(err)
}
if len(chats) > 0 {
chat, err := client.GetNegotiationChat("lockbit3", chats[0].ID)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Initial ransom: %s, Paid: %t\n", chat.InitialRansom, chat.Paid)
}
```
8. 获取勒索信内容
```
notes, err := client.ListRansomNotes("lockbit3")
if err != nil {
log.Fatal(err)
}
if len(notes) > 0 {
note, err := client.GetRansomNote("lockbit3", notes[0])
if err != nil {
log.Fatal(err)
}
fmt.Printf("Format: %s\nContent: %s\n", note.Extension, note.Content)
}
```
9. 获取 YARA 规则
```
rules, err := client.GetYARARules("lockbit3")
if err != nil {
log.Fatal(err)
}
for _, rule := range rules {
fmt.Printf("Rule: %s\n%s\n", rule.Filename, rule.Content)
}
```
10. 获取 SEC 8-K 文件
```
filings, err := client.GetSECFilings("MSFT", "", "2025", "", true, true)
if err != nil {
log.Fatal(err)
}
for _, f := range filings {
fmt.Printf("Filing: %s\n", f.Title)
}
```
11. 验证 API Key
```
resp, err := client.ValidateKey()
if err != nil {
log.Fatal(err)
}
fmt.Printf("Valid key for client: %s\n", resp.ClientID)
```
## 重要说明
* 认证 – 所有 endpoint 都需要 X-API-KEY header。从 ransomware.live/my 获取免费 key。
* 速率限制 – 每个 key 每月 500,000 次请求。
* 日期字段 – attackdate 是估计的攻击/发布日期；discovered 是 ransomware.live 首次观察到该列表的时间。
* 国家/地区代码 – 除非另有说明，否则使用 ISO 3166-1 alpha-2（两位字母，如 US、FR）。
* 分页 – API 不会为所有 endpoint 暴露显式的分页。/victims/recent endpoint 始终返回 100 条最新记录。对于历史数据，请使用带有日期过滤器的 /victims/ endpoint。
* IoC Endpoints – IoC endpoint 不受速率限制，但需遵循合理使用原则。
标签：API客户端, EVTX分析, Go, Ruby工具, 勒索软件, 威胁情报, 开发者工具, 日志审计