Miguel-DevOps/passive-sentry

## 当前状态 - 运行时基线：Python 3.14+ - 包管理器：uv 及确定性 lockfile (uv.lock) - 安全模型：100% 纯被动收集 - OWASP 范围：映射 A01-A10 的被动启发式检测 - 最新验证：2026-04-06 - 测试结果：40/40 通过 已验证的命令： ``` uv run --python 3.14 pytest -q ``` ## 核心功能 - 通过 CLI 进行单域名审计 - 多域名批处理 - 规范的 OWASP A01-A10 模块编排 - 确定性风险评分和发现结果标准化 - JSON 报告生成 - PDF 报告生成（延迟加载，生成时需要原生依赖） - 用于结果探索的 Streamlit dashboard - Docker 和 Docker Compose 工作流 ## 日志和输出行为 PassiveSentry 运行干净且噪音极低： - **预期的 404（已抑制）**：可选资源（robots.txt、sitemap.xml、security.txt 等）的 HTTP 404 响应将在 DEBUG 级别记录，以避免警告刷屏。 - **外部库日志已抑制**：第三方库（fontTools、Pillow、urllib3 等）已被静音，以保持输出专注于 PassiveSentry 的结果。 - **详细模式**（`--verbose`）：如果需要排查问题，请传递此标志以启用 DEBUG 日志记录。 ## 纯被动强制执行 PassiveSentry 被设计为非侵入式： - 无漏洞利用 - 无暴力破解 - 无模糊测试 - 无主动 payload 注入 - 无经过身份验证的内部应用测试 HTTP 收集被限制为安全方法（GET/HEAD/OPTIONS）。结果基于公开可见的工件。 ## OWASP 覆盖范围 (Top 10:2025) 在 [src/passivesentry/modules/owasp_top10_2025.py](src/passivesentry/modules/owasp_top10_2025.py) 中实现： - A01 失效的访问控制 - A02 安全配置错误 - A03 软件和供应链漏洞 - A04 加密失败 - A05 注入 - A06 安全设计缺陷 - A07 身份认证失败 - A08 软件和数据完整性失败 - A09 安全日志记录和监控失败 - A10 异常情况处理不当 覆盖范围说明： - 所有类别均已包含并在完整审计中执行。 - 深度被刻意限制为被动；某些类别仅提供指标级别的置信度。 - A09 是基于外部可见的 DNS 和相关遥测数据建模的，因此应将其视为间接证据。 ## 确定性报告模型 规范的数据真实来源： - 字段：risk_analysis.normalized_findings - 生成者：[src/passivesentry/reporting/risk_scoring.py](src/passivesentry/reporting/risk_scoring.py) 标准化保证： - 按 category + text 去重 - 重复项取最高严重性 - 稳定的排序顺序以实现可重现的输出 - 对历史发现变体使用标准化的英文表述 ## 输出路径和域名处理保证 单次和批处理工作流的默认输出目录现在均为 results。 单域名审计输出： - results 目录中的 JSON 报告 - 可选的摘要文本 - 可选的 PDF 批处理输出： - 每个输入域名一个子目录 - 每个域名对应 audit_results.json - 可选的针对单个域机的技术和执行 PDF - 根输出目录中的批处理 JSON 摘要和执行日志 域名处理保证： - 输入文件中的每个非空、非注释行都会被处理。 - 批处理摘要包括 total_domains、succeeded、failed 以及每个域名的状态。 - 无效域名将被计为已处理的失败项（不会被静默跳过）。 ## 环境要求 - Python >= 3.14 - uv 作为受支持的解析器和运行器 - 提交 uv.lock 以实现可重现的安装 - Docker（可选） ### PDF 生成的原生要求 PDF 输出依赖于 WeasyPrint 原生库。在 Debian/Ubuntu 环境中，请安装： ``` sudo apt-get update sudo apt-get install -y libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 libffi8 shared-mime-info fonts-dejavu ``` 如果这些库不可用，请在没有 PDF 工件的情况下运行批处理模式： ``` uv run --python 3.14 passivesentry batch --input domains.txt --no-pdf --no-summary ``` 批处理运行时行为： - 在启动时，批处理模式会检查 PDF 运时功能。 - 该检查是静默的，不会直接导入 WeasyPrint（以避免启动噪音）。 - 如果缺少依赖项，警告中将包含确切缺失的组件。 - 如果缺少 WeasyPrint 原生依赖项，将自动禁用 PDF 工件。 - 域名处理将继续以仅 JSON 模式进行，而不是导致批处理失败。 - 会记录一条警告，以便运维人员稍后可以启用 PDF 支持，而不会丢失执行覆盖率。 ## 站点质量指标 除了 OWASP Top 10:2025 漏洞评估外，PassiveSentry 还会评估反映运营成熟度和安全意识实践的**站点质量指标**： - `robots.txt` - 爬虫指令（SEO、公开/私有内容处理） - `sitemap.xml` - 站点结构声明（可爬取性） - `security.txt` - 漏洞披露政策（兼容 RFC 9110） - `llms.txt` - LLM/AI 训练指令（数据治理） - `ai.json` - AI 机器人行为配置（新兴标准） - `dnt-policy.txt` - 请勿追踪政策（隐私） ### 它们在报告中的体现方式 **执行摘要 PDF：** - 简明的存在/缺失列表 - 针对每个指标的高层级建议 **完整技术报告 PDF：** - 详细的逐域名评估 - 对于每个**存在**的指标：URL、大小和针对性指导 - 对于每个**缺失**的指标：目的、实施步骤和优先级排序 - 指导修复顺序的优先级重点列表 **JSON 输出（`audit_results.json`）：** ``` "site_quality_indicators": { "present": { "sitemap.xml (site structure)": { "url": "https://example.com/sitemap.xml", "status_code": 200, "size_bytes": 1524 } }, "absent": [ "robots.txt (crawler directives)", "security.txt (security policy)" ] } ``` ### 自定义 站点质量指标可以根据您组织的标准进行**完全自定义**： - 添加/删除要检查的资源（例如，行业合规文件、自定义 endpoint） - 修改每个指标的建议文本 - 调整优先级排序 - 添加合规框架映射 有关以下内容的详细说明，请参阅 [`docs/customizing_reports.md`](docs/customizing_reports.md)： - 在哪里编辑模板 - 如何添加自定义资源或字段 - 映射到您组织的合规标准 - 自动化和 CI/CD 集成示例 ## 安装 安装锁定的运行时依赖： ``` uv sync --frozen ``` 安装开发依赖： ``` uv sync --dev ``` 依赖项更改后刷新 lockfile： ``` uv lock --python 3.14 ``` ## CLI 用法 帮助： ``` uv run --python 3.14 passivesentry --help ``` 完整审计（A01-A10）： ``` uv run --python 3.14 passivesentry audit example.com ``` 范围审计： ``` uv run --python 3.14 passivesentry audit example.com -m security_misconfiguration -m cryptographic_failures ``` 批处理（默认输出为 results）： ``` uv run --python 3.14 passivesentry batch --input domains.txt ``` 带有明确输出的批处理： ``` uv run --python 3.14 passivesentry batch --input domains.txt --output results ``` ## Streamlit 仪表盘 运行： ``` streamlit run scripts/streamlit_dashboard.py ``` 默认的 dashboard 输入目录为 results。 ## Docker 构建镜像： ``` docker build -t passivesentry:latest . ``` 运行单次审计： ``` docker run --rm passivesentry:latest passivesentry audit example.com ``` 运行批处理并将输出持久化到 results： ``` docker run --rm \ -v $(pwd)/results:/app/results \ -v $(pwd)/domains.txt:/app/domains.txt:ro \ passivesentry:latest \ passivesentry batch --input domains.txt --output results ``` 运行 dashboard： ``` docker run --rm -p 8501:8501 \ -v $(pwd)/results:/app/results \ passivesentry:latest \ streamlit run scripts/streamlit_dashboard.py --server.address=0.0.0.0 --server.port=8501 ``` Compose： ``` docker compose up --build ``` ## 测试 完整套件： ``` uv run --python 3.14 pytest -q ``` 批处理和输出行为检查： ``` uv run --python 3.14 pytest -q tests/e2e/test_batch_cli.py tests/unit/test_batch_processing.py ``` ## 仓库结构 ``` src/passivesentry/ core.py cli.py batch.py modules/ owasp_top10_2025.py security_misconfiguration.py software_supply_chain.py cryptographic_failures.py security_logging.py reporting/ risk_scoring.py json_reporter.py pdf_reporter.py templates/ executive_summary.html full_technical_report.html scripts/ batch_processing.py streamlit_dashboard.py tests/ unit/ e2e/ docs/ ``` ## 文档 - [docs/architecture.md](docs/architecture.md) - [docs/technical_decisions.md](docs/technical_decisions.md) - [docs/owasp_coverage.md](docs/owasp_coverage.md) ## 所有权与联系 PassiveSentry 的核心代码和模块是专有的。如需商业访问权限，请联系 [miguel@developmi.com](mailto:miguel@developmi.com)。 作者：Miguel Lozano | Developmi - GitHub: [Miguel-DevOps](https://github.com/Miguel-DevOps) - 网站: [developmi.com](https://developmi.com/) - LinkedIn: [Miguel DevOps](https://www.linkedin.com/in/miguel-dev-ops/)

标签：GitHub, OWASP标准, Python, Snort++, Streamlit, 安全审计, 实时处理, 开源情报, 无后门, 被动扫描, 访问控制, 风险评估