chillyka0x1/periscan

# Periscan [](https://github.com/chillyka0x1/periscan/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) **一款懂你应用的家庭实验室（homelab）暴露检测工具。** 像 Nmap 和 Nuclei 这样的工具能告诉你*端口和 CVE*——但无法告诉你是否 意外地将你的 **Proxmox**、你的 **code-server** 或你的 **Nginx Proxy Manager 管理面板**暴露在了公网上。Periscan 可以从外部检查你的域名， 识别常见的自托管应用，并用通俗易懂的语言告诉你**什么是危险的以及该如何处理**。  ## 功能介绍 - 通过**证书透明度日志 (crt.sh)** 以及自托管关键词字典发现子域名 - 通过**公共 DNS (DoH)** 进行解析 → 提供真正的**外部视角**，而不是你的内部 split-horizon 视图 - 针对每个主机：**是否可公开访问？** HTTP 状态，**TLS 证书是否有效或过期？** - **指纹识别约 60 种自托管应用** —— 包括 Proxmox、OPNsense、pfSense、Portainer、NPM、 Pi-hole、code-server、n8n、Grafana、Gitea、Vaultwarden、Immich、Jellyfin、Nextcloud、 TrueNAS、Synology 等等 - **主动未经身份验证检查：** 区分*“仅可见登录页面”*（受保护） 与*“数据或设置确实已暴露”* —— 一个开放的安装向导意味着账户可能会被接管 - **风险报告**（从 CRITICAL 到 INFO）以 **CLI 输出**或**Web 仪表板**（深色模式）呈现 ## 安装说明 ``` pip install . ``` 这会安装两个命令： ``` periscan your-domain.tld # CLI scan in the terminal periscan-web # web UI, opens http://127.0.0.1:8000 ``` 多个域名：`periscan a.tld b.tld` 或 `periscan --config domains.txt`（每行一个）。 **CLI 选项：** `--no-crt` · `--local-dns` · `--no-ports` · `--timeout` · `--workers` · `--config FILE` · `--json/--html/--svg FILE` 检测到的应用版本会被标记上“检查 CVE”的提示。 ### 监控 —— 检测变更并发出警报 ``` # 自上次扫描以来有什么变化？ periscan your-domain.tld --diff # 每小时扫描一次，当有新内容暴露时向 Discord 发送警报 periscan your-domain.tld --watch 3600 --discord ``` Periscan 将每次扫描的快照存储在 `~/.periscan` 中，并报告**新增、变更和 消失的**暴露情况 —— 这对于作为 cron job 或长期运行的服务非常有用。 通过 `--discord ` 或 `--webhook `（JSON POST）发送警报。使用 `--alert-min` 设置严重程度阈值。 ### Docker ``` # prebuilt image docker run --rm -p 8000:8000 ghcr.io/chillyka0x1/periscan # 或者自己构建 docker build -t periscan . docker run --rm -p 8000:8000 periscan # 或者使用 compose docker compose up --build ``` 然后打开 http://localhost:8000 ## 隐私说明 完全**在本地运行**。无需账户，无遥测，**不会向作者**或任何 云服务发送数据。代码是开源的 —— 你可以自行验证。 仅有的外部网络连接包括： | 目标 | 原因 | 禁用方式 | |---|---|---| | **crt.sh** | 从证书透明度日志获取子域名 | `--no-crt` | | **公共 DoH 解析器** (Cloudflare, Google) | 用于“从外部”进行解析 | `--local-dns` | | **你正在扫描的域名或 IP** | 实际的扫描过程 | — | 你的扫描结果**不会发送到任何地方**。User agent 会如实标明该工具的身份。 ## 道德与合法性 **仅扫描你拥有**或获得明确书面授权测试的主机。在你无法控制的系统上执行 主动端口和 endpoint 检查，在你的司法管辖区可能属于违法行为。 ## 路线图 - [x] 带有 DoH 外部视角的 CLI - [x] 约 60 种应用的指纹数据库以及主动未经身份验证检查 - [x] Web 仪表板（深色/浅色主题），支持 pip 和 Docker 安装 - [x] 直接端口检查，即使在没有反向代理的情况下也能进行 - [x] 监控：循环扫描、随时间变化的差异比对、Discord/webhook 警报 - [x] IPv6/AAAA 回退、多域名扫描、身份验证标记 - [x] 测试和 CI (GitHub Actions) - [ ] 根据检测到的版本进行 CVE 匹配，支持为多个域名配置配置文件 - [ ] Logo/favicon，完善浅色主题 - [ ] 托管版本 —— 从你的网络外部进行扫描，持续监控 ## 当前状态 基于真实的 homelab 环境开发（Proxmox / OPNsense / NPM / Pi-hole）。在**首次运行时，它发现 了一个意外暴露的 Proxmox 和 OPNsense** —— 这正是我开发它的原因：我想 验证我的网络隔离策略，而不是仅仅盲目假设它是安全的。 欢迎提供反馈和提交 Issue。

标签：Python, Web安全, 动态插桩, 实时处理, 密码管理, 无后门, 蓝队分析, 请求拦截, 资产测绘, 逆向工具, 风险报告