sanks205/getobserver

# Observer **找出问题所在——并为您提供修复方案。** *代码、依赖项、配置和基础设施——一次扫描，一份报告。离线运行，单一二进制文件，无需账号。*     ## ⬇️ 获取 Observer 下载适合您操作系统的单一二进制文件——无需 runtime，无需依赖项，无需账号： | Windows | macOS (Apple Silicon) | macOS (Intel) | Linux | |:---:|:---:|:---:|:---:| | [**下载**](https://github.com/sanks205/getobserver/releases/latest/download/observer_windows_amd64.exe) | [**下载**](https://github.com/sanks205/getobserver/releases/latest/download/observer_darwin_arm64) | [**下载**](https://github.com/sanks205/getobserver/releases/latest/download/observer_darwin_amd64) | [**下载**](https://github.com/sanks205/getobserver/releases/latest/download/observer_linux_amd64) | _{更喜欢使用包管理器？Scoop · Homebrew · `go install` —— 请参阅[安装说明](#installation)。在 macOS/Linux 上：`chmod +x observer_*`。} 然后将其指向任何项目： ``` observer analyze . --out report.html ``` 您将获得**一个独立的 `report.html`** —— 分组的问题发现、符合标准的安全评级 (A–E)，以及针对每个问题的建议修复方案。完全离线；在浏览器中打开它或打印为 PDF。 目标：帮助开发者快速识别生产环境问题，而无需手动搜索庞大的代码库和服务器日志。 该 CLI 二进制文件名为 **`observer`**。 ## 演示  将其指向任何代码库，即可获得一份独立的 HTML 报告——无需服务器、无需账号、无需 instrumentation： ``` observer analyze ./examples/php-demo --ai --out report.html ``` Observer 会检测技术栈，标记安全 / runtime / 依赖项问题及其严重程度和建议修复方案，对项目的**安全性 (Security)** 和**代码健康度 (Code Health)** 进行评分 (A–F)，并生成一个可共享的 `report.html`，您可以将其打开或打印为 PDF。 ## Observer 的对比 Observer 并不打算取代 SonarQube 或 Sentry——它是一种不同*类型*的工具：一个零配置、离线的快照，将代码、依赖项、runtime 和日志统一在一份报告中。客观对比如下： | | **Observer** | SonarQube / Semgrep | Snyk | Sentry | |---|---|---|---|---| | **配置** | 单一二进制文件，离线，无需账号 | Server/CI 或云端账号 | 云端账号 | Instrument 应用 + 账号 | | **覆盖范围** | 代码 + 依赖项 + runtime + 日志 + **基础设施/配置**，均在**一份报告**中 | 代码 | 依赖项 + 代码 | Runtime 错误 | | **静态分析深度** | 核心规则 + 可选 Semgrep | **更深**（支持多种语言） | 良好 | — | | **支持离线/无需注册** | ✅（可强制执行——`--assert-offline`） | — | — | — | | **定价** | 免费 + 一次性 Pro 版 | 订阅制 | 按开发者订阅 | 按使用量 + 按贡献者 | | **最适用于** | 审计、交接、SMB、离线扫描 | 持续的团队质量把控 | 依赖项繁重的团队 | 实时生产环境监控 | **使用 Observer 的场景** 当您需要进行一次性审计、遗留/客户交接、物理隔离 (air-gapped) 扫描，或无需搭建服务器或支付按席位费用即可获得统一的健康快照时。**选择其他工具的场景** 当您需要大规模的深度持续静态分析 (SonarQube/Semgrep) 或全天候的生产环境监控 (Sentry/Datadog) 时——许多团队会同时愉快地使用两者。 ## 限制 AI 生成的代码 现在 AI 编写了大量代码——而且它推送的问题正是 Observer 已经捕获的那些（硬编码的 secret、注入、脆弱的加密、有风险的依赖项），其比例甚至高于手写代码。Observer 是**这些变更的离线安全网**：无需重新扫描整个项目，只需扫描更改的部分。 ``` # 仅扫描你（或你的 AI 助手）刚刚更改的内容，对比上一次 commit observer analyze . --diff # PR review — 仅扫描该 branch 自 main fork 以来新增的行 observer analyze . --diff-base main --fail-on High # Pre-commit gate — 如果 staged changes 新增了 High 严重级别的 finding，则阻止 commit observer install-hook # one-time; bypass a commit with `git commit --no-verify` ``` 在任何扫描中添加 `--attest attestation.json` 以生成机器可读的记录——*“由 Observer 扫描，0 个高危，PASS”*——以附加到 PR 或保留用于审计跟踪。它是同样的离线二进制文件：您的代码永远不会离开您的机器，也无需账号。*(Observer Pro 可以对证明进行加密签名，以提供防篡改的证据。)* ## 隐私与物理隔离 (air-gapped) 使用 Observer 默认**完全离线运行**——关于您代码的任何信息都永远不会离开您的机器。没有账号，没有 telemetry，没有 phone-home。唯一涉及网络的功能都是明确选择启用的：`--cve` (OSV.dev 依赖项查找)，`--ai` *配合* `OPENAI_API_KEY` 使用，以及 `--email` / `--slack` / `--teams` / `--webhook` 通知器。如果不开启它们，扫描将完全在本地进行。 对于受监管、物理隔离 (air-gapped) 或客户机密的工作，您可以将此保证变为**可强制执行的**： ``` observer analyze ./my-project --assert-offline ``` 如果传入了任何需要联网的 flag，`--assert-offline` 将拒绝运行，并取消设置 `OPENAI_API_KEY`，以便 AI 层保持在其本地启发式算法上。它会打印出 `Offline mode: no network I/O.`，这样您就可以在审计中将其作为证据。非常适合金融、医疗保健、政府/国防或在 NDA 下审计客户代码——代码保留在原地，并且您可以证明这一点。 ## 架构 该产品围绕一个单一的**诊断核心引擎 (Diagnostic Core Engine)** 构建，每个接口（目前是 CLI；以后会有 API 和企业级 agent）都重用它。 ``` Interfaces CLI · API · Enterprise agent | v Diagnostic Core Engine | v ┌─────────────────────────────────────────────┐ │ Modules │ │ technology detector · static scanner │ │ runtime analyzer · log analyzer │ │ dependency analyzer · AI analyzer │ │ report generator │ └─────────────────────────────────────────────┘ ``` ### 仓库布局 ``` ai-production-debugging-assistant/ ├── cmd/cli/ # `observer` CLI entry point ├── internal/ │ ├── scanner/ # Phase 1 — folder scan, file counts, categories │ ├── detector/ # Phase 2 — language/framework/db/infra detection │ ├── analyzer/ # Phase 3 — static code analysis │ ├── logger/ # Phase 5 — log analysis │ ├── reporter/ # Phase 7 — HTML report generation │ ├── runtime/ # Phase 4 — ingest observer-agent runtime events │ ├── ai/ # Phase 6 — provider-agnostic AI abstraction │ └── storage/ # PostgreSQL persistence (SaaS/enterprise) ├── observer-agent/ # Phase 4 — drop-in PHP runtime error collector ├── api/ # HTTP API (Gin/Fiber) — later phase ├── web-report/ # static report assets / future React dashboard ├── docker/ # Dockerfile + compose assets ├── docs/ # documentation ├── examples/ # demo projects with intentional issues │ └── php-demo/ ├── tests/ # integration tests └── README.md ``` ## 安装说明 ### 下载预构建的二进制文件（推荐） Observer 以**单一独立可执行文件**的形式发布——无需 runtime，无依赖项，不需要在您的系统上安装任何东西。从 [Releases](https://github.com/sanks205/getobserver/releases) 页面下载适用于您操作系统的二进制文件并运行它： | OS | 文件 | |---|---| | Windows | `observer_windows_amd64.exe` | | macOS (Apple Silicon) | `observer_darwin_arm64` | | macOS (Intel) | `observer_darwin_amd64` | | Linux | `observer_linux_amd64` / `observer_linux_arm64` | 在 macOS/Linux 上，使其具有可执行权限：`chmod +x observer_*`（可选地重命名为 `observer`）。 二进制文件目前**未签名**——请根据 [release](https://github.com/sanks205/getobserver/releases) 上的 `SHA256SUMS.txt` 验证您的下载。（签名/公证的构建版本已列入路线图。） ### 通过包管理器安装 **Windows — [Scoop](https://scoop.sh)：** ``` scoop install https://raw.githubusercontent.com/sanks205/getobserver/main/packaging/scoop/observer.json ``` **macOS / Linux — [Homebrew](https://brew.sh)：** ``` brew install https://raw.githubusercontent.com/sanks205/getobserver/main/packaging/homebrew/observer.rb ``` 这两种方式都会将 `observer` 命令安装到您的 PATH 中，并验证下载的 SHA-256。 ### 从源码构建 需要 [Go 1.26+](https://go.dev/dl/)。 ``` git clone https://github.com/sanks205/getobserver.git cd getobserver go build -o observer ./cmd/cli ``` 在 Windows 上，输出文件为 `observer.exe`。要交叉编译所有平台的 release 二进制文件：`pwsh scripts/build-release.ps1`（或 `./scripts/build-release.sh`）。 ## 使用方法 ``` # 扫描项目并生成 report.html observer analyze ./examples/php-demo # 选择自定义输出路径 observer analyze ./examples/php-demo --out booking-report.html # 包含 observer-agent 捕获的 runtime error（见 observer-agent/） observer analyze ./examples/php-demo --runtime /tmp/observer-runtime.jsonl # 在报告中包含 application log 分析 observer analyze ./examples/php-demo --logs ./examples/php-demo/logs # 或者单独分析 log（打印摘要） observer analyze-log ./examples/php-demo/logs # 启动本地 web dashboard（此后无需命令行）： observer serve # open http://127.0.0.1:7777 — paste a folder, click Scan # 过往的扫描、stack、issue 计数以及“自上次扫描以来的新增项”会显示在一个页面上。 # 打开任意 report 并使用浏览器的打印 → 另存为 PDF。 # 添加针对 finding 的 AI 解释（root cause / impact / fix） observer analyze ./examples/php-demo --ai # 选择报告内容：仅部分 category 和/或最低 severity observer analyze ./examples/php-demo --categories "Security,Database" --min-severity High # 扫描 dependencies 以查找已知漏洞（OSV.dev；需要网络） observer analyze ./my-project --cve # Air-gapped / 受限环境：保证无网络 I/O — 拒绝 --cve/--email/--slack/ # --teams/--webhook 并强制 AI 使用 local heuristic。打印“Offline mode: no network I/O.” observer analyze ./my-project --assert-offline # 如果安装了 Semgrep，则进行更深入的多语言检测（若未安装则自动跳过） observer analyze ./my-project --semgrep # 自动检测并融入你已有的其他 engine（若不存在则各自自动跳过）： observer analyze ./my-project --phpstan --bandit --gosec --eslint # CI：生成 SARIF 并在 High+ finding 时使构建失败（见 docs/CI.md） observer analyze . --sarif observer.sarif --fail-on High # 将 finding 导出到其他工具 / 电子表格 observer analyze . --json findings.json --csv findings.csv # 扫描完成后通知 channel（Slack / Teams / 通用 webhook） observer analyze . --slack "$SLACK_WEBHOOK" # or --teams / --webhook # 在现有 codebase 上采用：记录 baseline，然后仅报告新 issue observer analyze . --write-baseline .observer-baseline.json observer analyze . --baseline .observer-baseline.json --fail-on Medium # 仅扫描更改部分（AI 安全网）— 对比 HEAD、base branch 或 staged changes observer analyze . --diff --fail-on High observer analyze . --diff-base main --fail-on High observer analyze . --diff-staged --out "" --attest attestation.json # 安装一个 git pre-commit hook 来拦截 staged changes（绕过：git commit --no-verify） observer install-hook # 通过电子邮件发送 report（通过 env vars 配置 SMTP；见下文） observer analyze ./examples/php-demo --email "dev@example.com,lead@example.com" ``` ### 邮件配置（阶段 8） `--email` 会附加 HTML 报告并通过 SMTP 发送摘要。使用环境变量进行配置： | 变量 | 用途 | 默认值 | |---|---|---| | `SMTP_HOST` | SMTP server host | _(发送邮件必填)_ | | `SMTP_PORT` | 端口 (587 STARTTLS, 465 implicit TLS, 25) | `587` | | `SMTP_USER` / `SMTP_PASS` | 凭证（如果是 open relay 则省略） | _(无)_ | | `SMTP_FROM` | 发件人地址 | `SMTP_USER` | | `OBSERVER_SMTP_DRYRUN` | 设置为 `1` 以生成 `.eml` 文件而不是发送（不需要服务器） | _(关闭)_ | ``` # 在没有邮件服务器的情况下离线验证组成： OBSERVER_SMTP_DRYRUN=1 SMTP_FROM=observer@example.com \ observer analyze ./examples/php-demo --email dev@example.com # -> 将 report.html.eml 写入 report 旁边 ``` ### AI 配置 `--ai` flag 用于解释发现的问题。它是**与提供商无关的**，并且可以离线工作： - **未设置 key** → 本地启发式算法，仅重述发现的问题（从不捏造）。 - **设置了 `OPENAI_API_KEY`** → 使用 OpenAI；出现任何错误时回退到本地。 | 变量 | 用途 | 默认值 | |---|---|---| | `OPENAI_API_KEY` | 启用 OpenAI 提供商 | _(未设置 → 本地模式)_ | | `OPENAI_MODEL` | 模型 ID | `gpt-4o-mini` | | `OPENAI_BASE_URL` | 覆盖 API endpoint（用于代理/测试） | OpenAI | | `OBSERVER_AI_PROVIDER` | 设置为 `local` 以即使在拥有 key 时也强制使用离线模式 | _(自动)_ | ``` # 版本 / 帮助 observer version observer help ``` ### 输出示例 ``` Scanning ./examples/php-demo ... Project: php-demo Language: PHP Framework: CodeIgniter 3 3.1.11 [High] Database: MySQL [High] Files: 6 Directories: 4 Code structure: Controllers: 1 Models: 1 Services: 1 Config: 2 Report written to .../report.html ``` 它还会生成一个独立的 **`report.html`**，其中包含技术概述、检测到的信号、代码结构和文件类型明细。 ## 路线图 | 阶段 | 范围 | 状态 | |------:|-------|--------| | 1 | 核心 CLI —— 扫描项目，生成 HTML 报告 | ✅ 完成 | | 2 | 技术检测（框架 / DB / 基础设施） | ✅ 完成 | | 3 | 静态代码分析（安全与性能问题） | ✅ 完成 | | 4 | Runtime 错误收集 (`observer-agent`) | ✅ 完成 | | 5 | 日志分析器 (`observer analyze-log`) | ✅ 完成 | | 6 | AI 分析模块 (OpenAI + 可插拔提供商) | ✅ 完成 | | 7 | 专业的多区块 HTML 报告 | ✅ 完成 | | 8 | 邮件报告 (SMTP) | ✅ 完成 | | 9 | 打包与分发 —— 跨平台单一二进制构建 | ✅ 完成 | | 10 | GitHub 质量 (README、徽章、下载/构建、贡献) | ✅ 完成 | | 11 | `observer serve` —— 本地 Web dashboard（多项目、历史记录、差异对比） | ✅ 完成 | | 12 | 依赖项 CVE 扫描 (OSV.dev —— PHP/npm/PyPI/Go) | ✅ 完成 | | 12+ | 可选引擎包装器 —— Semgrep / PHPStan / Bandit / gosec / ESLint ✅（自动检测） | ✅ 完成 | | 13 | CI 与团队工作流（SARIF、质量门禁、基线、GitHub 工作流） | ✅ 完成 | | 14 | 变更代码扫描 —— `--diff` 门禁 + 证明 + pre-commit hook（AI 代码安全网） | ✅ 完成 | | 15 | 桌面应用程序 (Pro) 和托管云 (团队版)、多语言 agent | ⏳ 计划中 | 有关产品愿景、版本和定位，请参阅 **[PRODUCT.md](PRODUCT.md)**。 ## Observer Pro CLI 和本地 dashboard **永久免费**。**Observer Pro** 增加了可选的付费功能——一次性购买，通过许可证密钥激活，激活后完全离线： - **品牌化 PDF 报告** —— 适合交付给客户的 PDF，带有您的标志和品牌 —— [$39](https://observerly1.gumroad.com/l/observer-pdf) - **计划/自动扫描** —— 按计划重新扫描，出现新问题时发出警报 —— [$29](https://observerly1.gumroad.com/l/observer-schedule) - **高级规则包** —— 更深度的框架安全规则：Laravel · CodeIgniter · WordPress · Symfony · Django · Rails · Spring · Express —— [$49](https://observerly1.gumroad.com/l/observer-rules-php) 或者以 **[All-Access bundle —— $89](https://observerly1.gumroad.com/l/observer-pro)** 获取所有内容。 通过 `observer pro activate ` 激活。 ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。欢迎提交 Issues 和 PR。 ## 许可证 [MIT](LICENSE)

标签：EVTX分析, Go, Petitpotam, Ruby工具, SOC Prime, 发包工具, 多模态安全, 开发工具, 日志审计, 错误基检测, 静态代码分析