notfixingit3/echostate
GitHub: notfixingit3/echostate
EchoState 是一个被动侦察平台，通过并发采集多维度网络情报并永久保存扫描快照，帮助安全团队追踪目标资产随时间的变化。
Stars: 1 | Forks: 0
# EchoState
EchoState 是一个被动侦察平台：由 Go API 和 Next.js Web UI 组成，用于扫描主机、追踪随时间的变化以及下载 PDF 报告。
只需输入主机名、IP 或 URL，它就能并发收集 WHOIS、BGP/ASN、DNS、TLS 证书、traceroute、证书透明度和网页情报。快照永不会被删除——重新扫描会突出显示差异。提交者的 IP 会通过 [pWhois](https://pwhois.org/) 进行异步丰富。
## 功能
- **被动侦察** — WHOIS、Team Cymru ASN/BGP（RIPEstat 劫持风险启发式分析、AS-path 丰富、PeeringDB IX 数据）、DNS、TLS + JARM、crt.sh 子域名发现、多视角 traceroute（本地 + HackerTarget）、favicon MMH3、robots/sitemap 爬取、云存储桶提示、来自最终页面加载的 HTTP 安全标头和完整响应标头、技术栈指纹识别、headless Chrome 网页抓取以及 JPEG 屏幕截图缩略图。
- **Web UI** — 扫描表单、带有标签和重新扫描功能的目标详情、情报选项卡（WHOIS、ASN、DNS、TLS、Web、Favicon、爬取、存储、CT、Traceroute、屏幕截图、提交者）、快照浏览器、原始差异并排对比、设置和报告下载。默认浅色模式；页脚显示版本号。
- **历史追踪** — 快照永久保存；相同的重新扫描会更新 `last_seen`。字段级别的 `change_details`（严重性、类型、摘要）可突出显示 TLS 过期、新增 CT 子域名、DNS 变动等。
- **异步扫描** — `POST /api/scan` 将任务加入队列（`202`）；轮询 `GET /api/scans/:id` 获取状态和生成的快照。
- **定时重新扫描** — 后台调度程序按可配置的间隔对过期目标进行重新扫描。
- **PDF 报告** — 异步 worker 通过 headless Chrome 将 HTML 渲染为 PDF。
- **IP 丰富** — pWhois worker 用于丰富提交者 IP（组织、ASN、地理位置）。
- **通知** — Slack、Discord、MS Teams webhooks 和 Pushover 移动警报，带有结构化的变更 payload 和警报规则过滤。
- **设置** — DNS 解析器、pWhois 服务器、速率限制、扫描并发/超时、调度程序、保留策略、警报规则（带有针对每个 webhook 的过滤器）以及可选的 Shodan/Censys/HIBP/RiskIQ API 密钥。
- **可选 API 密钥** — 设置 `ECHOSTATE_API_KEY`（或在设置中配置）以保护写入端点（`scan`、`reports`、`webhooks`、`settings`）。
- **Neo4j 图谱** — 扫描时同步关系，外加交互式 `/graph` UI，提供 infra、CT、DNS、cert SAN、BGP、traceroute 和 peering 视图；路由差异、共享跳数和 infra 集群。
- **容器化** — Docker Compose：API、前端、PostgreSQL、browserless Chrome、Neo4j。
## 快速开始
```
cp .env.example .env
docker compose up --build
```
| 服务 | URL |
| --------- | --------------------------- |
| Web UI | http://localhost:3001 |
| API | http://localhost:8080 |
| Browser | ws://localhost:3000/ |
| Neo4j | bolt://localhost:7687 |
UI 将 `/api` 代理到 Docker 内部的 Go 后端——在本地使用时无需配置 CORS。
## API
### 健康检查
```
curl http://localhost:8080/health
# {"status":"ok","env":"development","version":"0.0.1-beta.13"}
```
### 扫描目标
```
# 加入扫描队列 (202 Accepted)
curl -X POST http://localhost:8080/api/scan \
-H "Content-Type: application/json" \
-d '{"host":"example.com"}'
# {"id":"
","status":"pending",...}
# 轮询直到完成
curl http://localhost:8080/api/scans/
```
当 `status` 为 `completed` 时，响应将包含带有 `raw_data`（`whois`、`asn`、`dns`、`tls`、`web`、`ct`、`traceroute`、`screenshot`、`favicon`、`crawl`、`storage`、`errors`）的快照以及与上一个快照对比的 `change_details`。
如果设置了 `ECHOSTATE_API_KEY`，请在写入请求时传递 `Authorization: Bearer ` 或 `X-API-Key: `。
重新扫描目标使用相同的端点——没有单独的重新扫描 API。
### 浏览与管理
| 端点 | 描述 |
| -------- | ----------- |
| `GET /api/targets` | 分页目标（`page`、`limit`、`q`） |
| `GET /api/targets/:id` | 目标详情 + 最新快照 |
| `PUT /api/targets/:id/tags` | 更新目标标签 |
| `GET /api/targets/:id/snapshots` | 某个目标的快照 |
| `GET /api/targets/:id/screenshots` | 屏幕截图时间线（base64 JPEG 缩略图） |
| `GET /api/snapshots` | 所有快照（`target_id` 过滤器） |
| `GET /api/snapshots/:id` | 包含 pWhois 数据的完整快照 |
| `GET /api/snapshots/:id/diff` | 与上一个快照对比的原始 JSON 差异 |
| `GET /api/snapshots/:id/report` | 为快照排队或获取报告 |
| `GET /api/reports` | 报告列表（`status`、`snapshot_id`） |
| `POST /api/reports` | 将 PDF 加入队列（`{"snapshot_id":"..."}`） |
| `GET /api/reports/:id/download` | 下载已完成的 PDF |
| `GET/POST/PUT/DELETE /api/webhooks` | Webhook 管理 |
| `GET /api/scans/:id` | 异步扫描任务状态（完成时包含快照） |
| `GET/PUT /api/settings` | 系统设置（DNS、pWhois、速率限制、调度程序、保留策略、警报规则、API 密钥） |
| `GET /api/graph` | 基础设施图谱（可选 `?target_id=`；`?view=` = `infra`、`ct`、`dns`、`cert`、`bgp`、`traceroute`、`peering`） |
## 开发
### 要求
- Go 1.26+
- Node.js 20+（前端）
- PostgreSQL 16+
- browserless/chrome 或其他 CDP WebSocket 端点
- Neo4j 5+（可选；已包含在 Compose 中）
### 后端
```
cp .env.example .env
docker compose up db browser neo4j -d # or point env vars yourself
go run ./main.go
```
### 前端
```
cd frontend
npm install
cp .env.local.example .env.local # NEXT_PUBLIC_API_URL=http://localhost:8080
npm run dev
```
### 测试
```
# Backend (排除 frontend/node_modules Go shim)
go test $(go list ./... | grep -v '/frontend/')
# Frontend
cd frontend && npm run typecheck && npm run build
# E2E (需要完整的 docker compose stack)
cd frontend && npx playwright test
```
## 架构
```
echostate/
├── main.go # Entry point, workers, HTTP server
├── internal/
│ ├── config/ # Environment + runtime settings
│ ├── db/ # PostgreSQL migrations + Neo4j graph sync
│ ├── handlers/ # Gin routes (scan, browse, graph, reports, settings)
│ ├── middleware/ # CORS, rate limiting
│ ├── models/ # Domain types
│ ├── pwhois/ # Async IP enrichment worker
│ ├── reports/ # Async PDF worker
│ ├── scanner/ # WHOIS, ASN, DNS, TLS, CT, traceroute, favicon, crawl, storage, web, screenshot gatherers
│ ├── version/ # Build-time version injection
│ ├── webhooks/ # Snapshot notification dispatcher (Slack, Discord, Teams, Pushover)
│ └── pdf/ # Report HTML renderer
└── frontend/ # Next.js static export + nginx
```
## 发布
带有标签的发布（`v*`）会触发：
- **GitHub Release** — Linux 和 macOS 二进制文件（amd64 + arm64）
- **GHCR 镜像** — `ghcr.io/notfixingit3/echostate`（API）和 `ghcr.io/notfixingit3/echostate-frontend`
包含 `beta`、`alpha` 或 `rc` 的预发布标签将被标记为 GitHub 预发布。
在打标签之前，请更新根目录下的 `VERSION` 文件并运行 `./scripts/sync-version.sh`。对于本地 Docker 构建，请在 `.env` 中设置 `ECHOSTATE_VERSION` 以使其匹配。
## 许可证
[MIT](LICENSE)标签：EVTX分析, GitHub, Go语言, 侦察工具, 威胁情报, 安全合规, 实时处理, 开发者工具, 日志审计, 测试用例, 程序破解, 网络代理, 请求拦截