dev-ugurkontel/surface-audit

# surface-audit [](https://github.com/dev-ugurkontel/surface-audit/actions/workflows/ci.yml) [](https://pypi.org/project/surface-audit/) [](https://pypistats.org/packages/surface-audit) [](https://pypi.org/project/surface-audit/) [](LICENSE) [](https://mypy.readthedocs.io/) [](https://github.com/astral-sh/ruff) 确定性 **安全冒烟测试**，用于暂存环境、预览环境以及 预部署的 Web 应用。 `surface-audit` 向 **已知 URL** 发送一组小型、有约束的安全探测，并将结果转化为 CI 友好的发现结果、SARIF、Markdown、HTML 和 JSON 报告。它专为希望在上线 **之前** 捕获头部、TLS、重定向、Cookie、CORS、暴露文件及其他表面级错误的团队设计。 ## 为何团队使用它 - **默认安全** — 针对已知 URL 进行有约束的检查，而非爬虫或攻击框架。 - **回归导向** — 基线抑制和报告差异帮助回答“哪里变差了”，而不仅仅是“存在什么”。 - **CI 原生** — `--fail-on`、SARIF、Markdown、HTML 和 JSON 均可无缝融入拉取请求、代码扫描和发布门禁。 - **LLM 安全的 MCP 支持** — 可选的 MCP 服务器仅暴露主机白名单接口。 - **可扩展** — 检查和渲染器可通过入口点插拔。 - **供应链感知** — PyPI 可信发布、Sigstore 签名、GitHub 发布和 CycloneDX SBOM 已内置到发布流程中。 ## 何时使用它 - 你有一个暂存、预览或预生产 URL - 你希望在 CI 中设置确定性的安全门禁 - 你关心两次部署之间的安全回归 - 你需要 SARIF、仪表板或 PR 注释用的机器可读输出 ## 何时改用其他工具 - 你需要完整爬取或蜘蛛式扫描 - 你需要认证扫描流程 - 你需要漏洞确认或广泛的模板语料库 这种定位是经过深思熟虑的：`surface-audit` 最适合作为 **预部署安全冒烟测试**，而非完整的 DAST 平台。 ## 快速开始 ``` pipx install surface-audit surface-audit scan https://preview.example.com \ --scope-host preview.example.com \ --fail-on HIGH ``` 详细安装说明： [`docs/INSTALL.md`](docs/INSTALL.md)。 ## 分发选项 - **PyPI** — 当你希望在 `pipx`、虚拟环境或你自己的 Python 工具链中使用 CLI 时最佳。 - **GHCR** — 当你的 CI 更偏好预构建容器镜像而非运行时安装 Python 依赖时最佳。 - **GitHub Action** — 当预览环境工作流已存在于 GitHub Actions 中且你希望集成路径最短时最佳。 注重容器的团队可使用发布版本中提供的公开 GHCR 镜像： ``` docker run --rm ghcr.io/dev-ugurkontel/surface-audit:latest \ scan https://preview.example.com --fail-on HIGH ``` 对稳定主线路使用 GitHub Action `@v1` 标签，或在需要完全可重现的工作流时固定具体动作版本如 `@v1.0.2`。标记版本也会发布 GitHub Release 构件、CycloneDX SBOM 和 Sigstore 签名。 更多端到端模式： [`docs/RECIPES.md`](docs/RECIPES.md)。 ## 安全回归差异 ``` # 仅捕获一次基线 surface-audit scan https://preview.example.com \ --output reports/baseline.json \ --format json # 仅对新引入的 HIGH+ 发现问题进行拦截 surface-audit scan https://preview.example.com \ --baseline reports/baseline.json \ --fail-on HIGH # 或显式对比两个报告 surface-audit diff reports/before.json reports/after.json \ --output reports/diff.json \ --fail-on-new ``` ## GitHub Action 该仓库在根目录提供一个 Action，可直接在预览环境工作流中运行扫描，无需手动安装步骤： ``` - name: Run surface-audit uses: dev-ugurkontel/surface-audit@v1 with: target: ${{ steps.preview.outputs.url }} scope-hosts: preview.example.com output: reports/surface-audit.sarif format: sarif fail-on: HIGH - name: Upload SARIF uses: github/codeql-action/upload-sarif@v4 with: sarif_file: reports/surface-audit.sarif ``` 更多端到端模式： [`docs/RECIPES.md`](docs/RECIPES.md)。 ## 示例输出 ``` Target: https://preview.example.com/ Summary: HIGH 1 MEDIUM 2 LOW 1 HIGH security-headers Missing Content-Security-Policy header MEDIUM auth-cookies Cookie 'sessionid' missing SameSite MEDIUM security-txt Missing /.well-known/security.txt LOW directory-listing Auto-generated index page exposed ``` ## 内置检查 | 检查 ID | OWASP | 摘要 | | ------------------------ | ----- | ------------------------------------------------------------ | | `security-headers` | A05 | 缺失或配置薄弱的 HSTS / CSP / XFO / Referrer / Permissions | | `ssl-tls` | A02 | 弱密码套件或过时的 TLS 版本 | | `https-redirect` | A02 | 明文 HTTP 未重定向到 HTTPS | | `cross-origin-isolation` | A05 | 缺失 COOP / COEP / CORP 隔离头 | | `xss-reflection` | A03 | 查询字符串输入未经输出编码直接反射 | | `sql-injection` | A03 | 数据库错误消息在元字符输入时泄露 | | `csrf` | A01 | 缺少可识别抗 CSRF 令牌的修改 HTML 表单 | | `auth-cookies` | A07 | 缺少 `Secure` / `HttpOnly` / `SameSite` 的 Cookie | | `open-redirect` | A01 | 允许指向外部站点的 30x 重定向查询参数 | | `misconfiguration` | A05 | 已知暴露路径（`.env`、`.git`、管理控制台） | | `directory-listing` | A05 | 自动生成的目录索引页 | | `cors` | A05 | 允许凭据的通配符 CORS 反射 | | `security-txt` | A09 | 缺失 `/.well-known/security.txt`（RFC 9116） | 运行 `surface-audit list-checks` 可查看环境中已注册的内容（包括任何第三方插件）。 ## 使用方法 ``` # 保存 JSON 报告并在发现 HIGH+ 问题时使 CI 失败 surface-audit scan https://example.com \ --output reports/example.json --format json --fail-on HIGH # 输出 SARIF 以用于 GitHub Advanced Security surface-audit scan https://example.com \ --output reports/example.sarif --format sarif # 仅运行部分检查 surface-audit scan https://example.com \ --enable security-headers --enable ssl-tls ``` 完整的 CLI 和库参考： [`docs/USAGE.md`](docs/USAGE.md)。 ## MCP 集成 ``` pip install "surface-audit[mcp]" surface-audit mcp-serve --allow-host staging.example.com ``` 这会将 `scan`、`list_checks`、`list_formats` 和 `render_report` 工具暴露给本地 MCP 客户端，同时保持扫描受主机白名单约束。 ## 项目站点 项目站点重点介绍冒烟测试流程、GitHub Action、示例构件和核心采用模式： - [项目落地页](https://dev-ugurkontel.github.io/surface-audit/) - [控制台示例](https://dev-ugurkontel.github.io/surface-audit/samples/preview-report.console.txt) - [HTML 示例](https://dev-ugurkontel.github.io/surface-audit/samples/preview-report.html) - [SARIF 示例](https://dev-ugurkontel.github.io/surface-audit/samples/preview-report.sarif.json) 使用 [PyPI 统计](https://pypistats.org/packages/surface-audit) 可查看下载趋势。 ## 库示例 ``` import asyncio from surface_audit import Scanner, ScannerConfig async def main() -> None: report = await Scanner( "https://example.com", config=ScannerConfig(max_concurrency=4, timeout=5.0), ).run() for finding in report.findings: print(finding.severity.value, finding.check_id, finding.title) asyncio.run(main()) ``` ## 扩展它 任何在 `surface_audit.checks` 下提供入口点的包都会添加一个检查。第三方检查的启动模板位于： [`examples/plugin-template`](examples/plugin-template) ``` # your-plugin/pyproject.toml [project.entry-points."surface_audit.checks"] cors_wildcard = "my_checks.cors:PermissiveCORSCheck" ``` 有关分层、SOLID 评分卡和设计模式的详细信息，请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。 ## 文档 - [`docs/INSTALL.md`](docs/INSTALL.md) — 每平台安装 - [`docs/USAGE.md`](docs/USAGE.md) — CLI、库及 CI 示例 - [`docs/RECIPES.md`](docs/RECIPES.md) — 预览、SARIF、基线、MCP 及 Action 示例 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 分层和扩展点 - [`docs/SCHEMA.md`](docs/SCHEMA.md) — JSON 报告契约 - [`examples/plugin-template`](examples/plugin-template) — 第三方检查启动模板 - [`SUPPORT.md`](SUPPORT.md) — 问题提问与正确报告方式 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — 开发流程 - [`SECURITY.md`](SECURITY.md) — 漏洞披露 - [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — 社区规范 ## 开发 ``` make install # set up .venv with dev extras make all # ruff + mypy + bandit + pytest ``` CI 在每次推送时对 Python 3.10 – 3.13 运行测试 — 详见 [`.github/workflows/ci.yml`](https://img.shields.io/pypi/dm/surface-audit.svg)。 ## 许可证 [Apache License 2.0](LICENSE) — 版权所有 © 2026 Uğur Kontel。参见 [`NOTICE`](NOTICE) 了解再分发所需的署名要求。 `surface-audit` 是一个来自 [Fillbyte](https://fillbyte.com) 的开源项目。

标签：Cookie 安全, CORS 检查, CycloneDX SBOM, GitHub Releases, HTML 报告, HTTP 头部检查, JSON 报告, LNA, Markdown 报告, MCP 服务器, mypy, PyPI, Python 安全工具, Ruff, SARIF, Sigstore, TLS 检查, Trusted Publishing, URL 检测, Web 安全, 上线前检查, 安全合规, 安全回归检测, 安全测试, 开源安全工具, 开源框架, 扩展插件, 持续集成, 攻击性安全, 文件暴露检测, 烟雾测试, 确定性测试, 网络代理, 请求拦截, 逆向工具, 逆向工程平台, 重定向检测, 预发布环境