feat(honeypot): 蜜罐安全状况周期汇总(周报/月报 + 地图 + 邮件)

以周/月为单位汇总蜜罐命中,把来源 IP 通过公共服务查地理位置,画到地图上,
生成 HTML 报告并发邮件。同时补齐 ipinfo 无法回答「这个 IP 在哪儿」的问题。

新增 IP 地理定位层 internal/security/geoip:
- 与 internal/security/ipinfo 正交。ipinfo 走 cdncheck 离线指纹,只认云厂商/CDN/WAF,
  答的是「是不是代理」;肉鸡(家宽、企业宽带、移动网络)必然被判为
  「未识别(普通网络)」,所以「在哪儿」必须另建一套。
- ip-api.com 批量打底(100 个/请求、1.4s 节流)+ 腾讯位置服务精修国内
  (一 IP 一请求,只精修命中数最高的前 N 个,受 ip_geo_tencent_key 控制)。
- Result{Geo, Unresolved, Requests, Failures} 三态。服务明确回答「没有这个地址」
  才允许写失败缓存;请求超时/限流/5xx 一律不写 —— 否则一次抖动会把整批 IP
  钉成「查不到」三天,此后每份报告的定位覆盖率都莫名变成 0。
- addrs 按调用方给的顺序构建(不是 map 遍历):腾讯精修只取前 N 个,乱序会让
  每次运行精修到不同 IP,配额花在长尾上。

报告生成 internal/security/report:
- period:PreviousWeek / PreviousMonth,窗口一律 [start, end) 左闭右开,
  相邻两期不重叠也不漏边界整点;period_key(week:2026-W44)做幂等。
- aggregate:按 shared.LimitKey 合并(IPv4 精确 / IPv6 折 /64);国家、城市、
  路径、每日趋势;显式统计未定位命中数(覆盖率 60% 的图看起来和 100% 一样)。
- mapdraw:自绘等距圆柱投影气泡图。零海岸线零国界 —— 国界/台湾/南海诸岛绘制
  必须符合国家标准,自绘极易画错,真实底图交给腾讯。经纬网 + 度数刻度 +
  标签防重叠(同一都市圈两城市坐标差 0.01°,曾把「AU 55」和「AU 30」叠成
  看起来像 AU 305 的假数字)。
- html:自包含报告页,内嵌 SVG + 腾讯交互地图(无 key 时给申请指引,
  代码里不预置任何 key)。
- countryname:港澳台统一显示「中国香港/中国澳门/中国台湾」,常见国家用中文名。

存储与调度:
- ip_geo_cache(主键 = LimitKey,成功 TTL 90 天 / 明确无数据 TTL 3 天)
- security_report_logs(period_key 唯一索引 → 重启、错过时间窗都能正确补发,
  失败重试上限 5 次后停止)
- honeypot report --period week|month [--to] [--dir] [--no-email]
- web 启动时按配置挂 30 分钟一轮的调度器(与保留期清理共用停止信号,
  defer 移出 if 外,避免「清理关掉、报告开着」时 goroutine 泄漏)

配置([security]):ip_geo_provider=auto|ipapi|tencent|none、ip_geo_tencent_key、
honeypot_report_enabled / _weekly / _monthly / _email / _dir。

顺带修复:
- route/honeypot_test.go 的 captureStore 缺 AggregateSources/AggregatePaths/
  TimestampsBetween,整个 route 包编译不过。
- templates/render_test.go 的 mockLoggedUser 缺 TelegramChatID,3 个渲染测试失败。
This commit is contained in:
tamakyi
2026-10-30 16:40:44 +08:00
parent 08bbd17751
commit d690355cdc
33 changed files with 5198 additions and 1 deletions
+115
View File
@@ -0,0 +1,115 @@
// Copyright 2026 tamakyi. All rights reserved.
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file.
// Package report 生成周期性安全状况汇总(周报 / 月报)。
//
// 它回答的问题与蜜罐告警不同:告警是「刚刚有人在你门口试钥匙」,报告是
// 「这一周一共有多少人在试、从哪些国家来、哪几个网段最执着、我们在拦什么」。
//
// 产物分三份,各有各的用途:
// - 邮件正文里的 PNG 气泡地图:邮件客户端不执行 JS、多数还会剥离内联 SVG,
// 只有位图能保证「打开就看得到」;
// - 附件 HTML:完整报告(排行表 + 内联 SVG 地图),离线可看;
// - 附件 HTML 里的腾讯地图:配了 key 才有,可缩放、可点开看明细。
//
// ⚠️ 地图的合规边界:本包自己画的地图**只画经纬网与气泡,不画任何国界**。
// 国界、台湾、南海诸岛的绘制必须符合国家标准,自绘底图极容易画错,
// 所以自绘图一律不含政治边界;需要真实底图时用腾讯地图(底图由持牌厂商提供)。
package report
import (
"fmt"
"time"
)
// 周期类型。
const (
KindWeek = "week"
KindMonth = "month"
)
// Period 一个报告周期,时间窗口为 [Start, End)。
//
// 左闭右开是刻意的:相邻两期既不能重叠(同一条记录算两次),也不能漏掉
// 恰好落在边界整点上的记录。
type Period struct {
Kind string
Key string
Start time.Time
End time.Time
}
// Label 返回人类可读的窗口描述,如 "2026-10-19 ~ 2026-10-25"。
func (p Period) Label() string {
// End 是开区间端点,展示时退一秒落回周期内的最后一天,避免出现
// 「10-19 ~ 10-26」这种让人以为多算了一天的区间。
last := p.End.Add(-time.Second)
if p.Kind == KindMonth {
return p.Start.Format("2006-01")
}
return fmt.Sprintf("%s ~ %s", p.Start.Format("2006-01-02"), last.Format("2006-01-02"))
}
// Title 返回报告标题用的中文描述。
func (p Period) Title() string {
if p.Kind == KindMonth {
return p.Start.Format("2006 年 1 月") + "安全状况月报"
}
_, week := p.End.Add(-time.Second).ISOWeek()
return fmt.Sprintf("%s 第 %d 周安全状况周报", p.Start.Format("2006 年 1 月"), week)
}
// Filename 返回报告文件名(不含扩展名)。
func (p Period) Filename() string {
if p.Kind == KindMonth {
return "security-month-" + p.Start.Format("2006-01")
}
return "security-week-" + p.Start.Format("2006-01-02")
}
// startOfWeek 返回 t 所在周的周一 00:00(本地时区)。
func startOfWeek(t time.Time) time.Time {
wd := int(t.Weekday()) // Sunday=0 … Saturday=6
if wd == 0 {
wd = 7
}
y, m, d := t.Date()
return time.Date(y, m, d, 0, 0, 0, 0, t.Location()).AddDate(0, 0, -(wd - 1))
}
// startOfMonth 返回 t 所在月的 1 日 00:00。
func startOfMonth(t time.Time) time.Time {
y, m, _ := t.Date()
return time.Date(y, m, 1, 0, 0, 0, 0, t.Location())
}
// PreviousWeek 返回 now 之前的**完整**一周。
//
// 口径是「最近一个已结束的自然周(周一起算)」:在周一凌晨跑,拿到的是上周;
// 在周三跑(补发),拿到的仍然是上周而不是「本周至今」——
// 报告必须覆盖完整周期,否则两次运行之间数字对不上。
func PreviousWeek(now time.Time) Period {
end := startOfWeek(now)
start := end.AddDate(0, 0, -7)
// 用周期内最后一天算 ISO 周号:直接用 end 会被算成下一周。
y, w := end.Add(-time.Second).ISOWeek()
return Period{
Kind: KindWeek,
Key: fmt.Sprintf("week:%04d-W%02d", y, w),
Start: start,
End: end,
}
}
// PreviousMonth 返回 now 之前的完整一个自然月。
func PreviousMonth(now time.Time) Period {
end := startOfMonth(now)
start := end.AddDate(0, -1, 0)
return Period{
Kind: KindMonth,
Key: "month:" + start.Format("2006-01"),
Start: start,
End: end,
}
}