Braulio2002/Monitor-de-cambios-en-superficie-de-ataque

# 🛡️ 高级攻击面变化监控器 (MACSA) ### *防御性暴露差异审计与合规检查器 (OWASP ASVS, NIST CSF 2.0 & CIS Controls v8)* ``` ███╗ ███╗ █████╗ ██████╗███████╗ █████╗ ████╗ ████║██╔══██╗██╔════╝██╔════╝██╔══██╗ ██╔████╔██║███████║██║ ███████╗███████║ ██║╚██╔╝██║██╔══██║██║ ╚════██║██╔══██║ ██║ ╚═╝ ██║██║ ██║╚██████╗███████║██║ ██║ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝ ╚═╝ ``` ## 📖 目录 1. [简介与目标](#-introducción-y-objetivos) 2. [与国际标准对齐 (NIST & OWASP & CIS)](#-alineación-con-estándares-internacionales-nist--owasp--cis) 3. [法律声明与安全防御扫描](#-advertencia-legal-y-escaneo-defensivo-seguro) 4. [Mermaid：组件架构与控制流](#-mermaid-arquitectura-de-componentes-y-flujo-de-control) 5. [项目物理结构](#-estructura-física-del-proyecto) 6. [安装与配置](#-instalación-y-aprovisionamiento) 7. [完整操作指南](#-guía-completa-de-operación) 8. [报告详情与映射 (多工作表 Excel)](#-detalle-y-mapeo-de-reportes-excel-multihoja) 9. [风险公式与加权评分](#-fórmula-de-riesgo-y-scoring-ponderado) 10. [集成至 DevSecOps (CI/CD Pipeline)](#-integración-en-devsecops-cicd-pipeline) 11. [生产环境容器 (Dockerfile)](#-contenedores-de-producción-dockerfile) 12. [可扩展性指南 (3分钟内添加规则)](#-guía-de-extensibilidad-añadir-reglas-en-3-minutos) 13. [故障排除 (Troubleshooting)](#-resolución-de-problemas-troubleshooting) 14. [测试套件与质量保证](#-suite-de-pruebas-y-aseguramiento) ## 📖 简介与目标 **高级攻击面变化监控器 (MACSA)** 是一款工业级的自动化防御性网络安全静态引擎。其主要目标是**对比组织外部暴露的两份授权快照** —— 即历史扫描（*baseline*）与当前扫描 —— 以检测端口、子域名、服务、HTTP 标头、TLS 配置和 API endpoint 中的关键变更。 该解决方案基于严格的 **Clean Architecture** 和 **SOLID** 原则设计，确保业务规则与基础设施库完全隔离。MACSA 可无缝集成至 **DevSecOps** 的 pipeline 中，允许 SOC 团队、网络安全分析师和系统管理员在每次部署或合规审查之前，以本地且确定性的方式审计其攻击面的演变。 ### 核心功能 - 检测**新开放的端口**或已关闭的历史端口（包括数据库、Docker API、SSH、RDP）。 - 发现**敏感子域名**（如 `admin`、`staging`、`backup`、`vpn` 等）及 IP 变更（*Subdomain Takeover* 风险）。 - 分析**暴露的服务**及关键组件的版本变更。 - 审计**安全标头**（HSTS、CSP、X-Frame-Options、cookies）。 - 验证 **SSL/TLS**（过期的证书、过时的 TLS 1.0/1.1 协议）。 - 监控在私有路由上失去身份验证的 **API endpoint**。 - 具备 `CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFO` 严重级别的 **0–100 量化评分**引擎。 - 生成适用于 SIEM/SOAR 的 **Excel（9个工作表）**、**PDF 执行摘要**和 **JSON** 格式的企业级报告。 ## 📋 与国际标准对齐 (NIST & OWASP & CIS) 该工具将扫描结果和审计内容原生映射到外部暴露管理中最相关的合规框架和安全最佳实践中： | 监控服务 | 控制参考 | 法规符合性目标 | 典型严重程度 | | :--- | :--- | :--- | :--- | | **`ports_diff_service.py`** | **CIS Control 12.3** | 检测暴露在互联网上的未经授权的网络服务（DB、RDP、Docker API）。 | **紧急 / 高危** | | **`subdomains_diff_service.py`** | **OWASP ASVS V14** | 识别 DNS 边界的未经授权扩展及暴露的管理子域名。 | **高危 / 中危** | | **`services_diff_service.py`** | **NIST CSF 2.0 (ID.AM)** | 清点并对比边界资产上的服务和版本。 | **中危** | | **`headers_diff_service.py`** | **OWASP Top 10 A05:2021** | 检测安全加固标头（HSTS、CSP、X-Frame-Options）的削弱。 | **高危 / 中危** | | **`ssl_tls_diff_service.py`** | **NIST SP 800-52 Rev. 2** | 验证证书有效期并禁用过时的 TLS 协议。 | **紧急 / 高危** | | **`endpoint_diff_service.py`** | **OWASP API Security Top 10** | 针对失去身份验证或授权控制的 endpoint 发出警报。 | **紧急** | | **`severity_classifier_service.py`** | **CVSS Qualitative** | 将发现的结果分类为操作严重性级别，以确定修复优先级。 | **可变** | | **`risk_score_calculator_service.py`** | **NIST CSF 2.0 (ID.RA)** | 计算加权量化风险，用于执行报告和暴露 KPI。 | **可变** | ## ⚠️ 法律声明与安全防御扫描 ### MACSA 安全与防御性操作规则： * **离线快照分析：** MACSA **不会**对网络目标执行**主动扫描**。它仅处理由授权工具（Nmap、内部扫描器、企业 ASM）预先导出的 JSON/CSV 文件。 * **无攻击性 payload：** 不执行漏洞利用、暴力破解、注入、自动下载，也不对分析的输入文件进行任何物理修改。 * **容错能力：** 如果快照文件损坏或缺失，它会在错误工作表中记录事件，并继续分析清单的其余部分。 * **演示合成数据：** 在首次启动时，它会在 `datos_entrada/` 中生成示例数据，以在不暴露真实资产的情况下验证流程。 * **输出加固：** 报告不包含任何凭据或机密；仅包含输入快照中已有的暴露元数据。 ## 🗺️ Mermaid：组件架构与控制流 MACSA 的设计遵循 **Clean Architecture** 模式并应用了 **控制反转**，使得逻辑核心（领域层和应用层）不依赖于框架或基础设施库： ``` graph TD subgraph Presentacion_Infraestructura [Presentación e Infraestructura - Adapters] CLI[app/presentation/cli.py] JsonReader[app/infrastructure/readers/json_snapshot_reader.py] CsvReader[app/infrastructure/readers/csv_snapshot_reader.py] ExcelExporter[app/infrastructure/exporters/excel_report_exporter.py] JsonExporter[app/infrastructure/exporters/json_report_exporter.py] PdfExporter[app/infrastructure/exporters/pdf_report_exporter.py] DirectoryManager[app/infrastructure/filesystem/directory_manager.py] end subgraph Aplicacion [Lógica de Aplicación - Casos de Uso y Servicios] UseCase[app/application/use_cases/monitor_attack_surface_changes_use_case.py] PortsDiff[app/application/services/ports_diff_service.py] SubdomainsDiff[app/application/services/subdomains_diff_service.py] ServicesDiff[app/application/services/services_diff_service.py] HeadersDiff[app/application/services/headers_diff_service.py] SslTlsDiff[app/application/services/ssl_tls_diff_service.py] EndpointDiff[app/application/services/endpoint_diff_service.py] ScoreCalc[app/application/services/risk_score_calculator_service.py] SeverityClass[app/application/services/severity_classifier_service.py] Recommendation[app/application/services/recommendation_service.py] ExecSummary[app/application/services/executive_summary_service.py] ReaderInterface[app/application/interfaces/snapshot_reader_interface.py] ExporterInterface[app/application/interfaces/report_exporter_interface.py] end subgraph Dominio [Capa de Dominio - Entidades y Value Objects] ChangeReport[app/domain/entities/change_report.py] DetectedChange[app/domain/entities/detected_change.py] ScanSnapshot[app/domain/entities/scan_snapshot.py] ExposedPort[app/domain/entities/exposed_port.py] AssetTypeVO[app/domain/value_objects/asset_type.py] SeverityVO[app/domain/value_objects/severity_level.py] RiskVO[app/domain/value_objects/risk_level.py] ChangeTypeVO[app/domain/value_objects/change_type.py] end CLI --> UseCase JsonReader -.->|Implementa| ReaderInterface CsvReader -.->|Implementa| ReaderInterface ExcelExporter -.->|Implementa| ExporterInterface JsonExporter -.->|Implementa| ExporterInterface PdfExporter -.->|Implementa| ExporterInterface DirectoryManager --> CLI UseCase --> ReaderInterface UseCase --> ExporterInterface UseCase --> PortsDiff UseCase --> SubdomainsDiff UseCase --> ServicesDiff UseCase --> HeadersDiff UseCase --> SslTlsDiff UseCase --> EndpointDiff UseCase --> ScoreCalc UseCase --> SeverityClass UseCase --> Recommendation UseCase --> ExecSummary UseCase --> ChangeReport ChangeReport --> DetectedChange DetectedChange --> AssetTypeVO DetectedChange --> SeverityVO DetectedChange --> RiskVO DetectedChange --> ChangeTypeVO ScanSnapshot --> ExposedPort ``` ## 🏗️ 项目物理结构 ``` Monitor de cambios en superficie de ataque/ │ ├── app/ │ ├── main.py # Punto de entrada: delega en la CLI. │ │ │ ├── config/ │ │ └── settings.py # Rutas, pesos de scoring y catálogos sensibles. │ │ │ ├── domain/ # Capa de Dominio (lógica pura, sin dependencias externas) │ │ ├── entities/ │ │ │ ├── scan_snapshot.py # Agregado raíz del inventario escaneado. │ │ │ ├── change_report.py # Reporte consolidado de la auditoría delta. │ │ │ ├── detected_change.py # Hallazgo individual con score y recomendación. │ │ │ ├── exposed_port.py # Puerto expuesto en un objetivo. │ │ │ ├── subdomain_asset.py # Activo de subdominio. │ │ │ ├── exposed_service.py # Servicio detectado en un host. │ │ │ ├── header_snapshot.py # Cabeceras HTTP de una URL. │ │ │ ├── ssl_tls_snapshot.py # Estado criptográfico de un dominio. │ │ │ └── exposed_endpoint.py # Endpoint de API monitorizado. │ │ │ │ │ ├── value_objects/ │ │ │ ├── asset_type.py # Enum: PORT, SUBDOMAIN, SERVICE, HEADER, SSL_TLS, ENDPOINT. │ │ │ ├── change_type.py # Enum: ADDED, REMOVED, MODIFIED, WEAKENED, IMPROVED. │ │ │ ├── severity_level.py # Enum: CRITICAL, HIGH, MEDIUM, LOW, INFO. │ │ │ └── risk_level.py # Enum: CRITICAL, HIGH, MEDIUM, LOW. │ │ │ │ │ └── exceptions/ │ │ └── domain_exceptions.py # Excepciones del dominio de seguridad. │ │ │ ├── application/ # Capa de Aplicación (orquestación y reglas de negocio) │ │ ├── use_cases/ │ │ │ └── monitor_attack_surface_changes_use_case.py # Orquestador central del flujo delta. │ │ │ │ │ ├── services/ │ │ │ ├── ports_diff_service.py # Diff de puertos abiertos/cerrados/modificados. │ │ │ ├── subdomains_diff_service.py # Diff de subdominios y cambios de IP. │ │ │ ├── services_diff_service.py # Diff de servicios y versiones. │ │ │ ├── headers_diff_service.py # Diff de cabeceras de seguridad HTTP. │ │ │ ├── ssl_tls_diff_service.py # Diff de certificados y protocolos TLS. │ │ │ ├── endpoint_diff_service.py # Diff de endpoints y autenticación. │ │ │ ├── snapshot_validator_service.py # Validación estructural de snapshots. │ │ │ ├── severity_classifier_service.py # Clasificador cualitativo de severidad. │ │ │ ├── risk_score_calculator_service.py # Calculador de score 0–100 y riesgo global. │ │ │ ├── recommendation_service.py # Generador de remediaciones contextualizadas. │ │ │ └── executive_summary_service.py # Resumen ejecutivo para CISO/Gerencia. │ │ │ │ │ └── interfaces/ │ │ ├── snapshot_reader_interface.py # Puerto de lectura de snapshots. │ │ └── report_exporter_interface.py # Puerto de exportación de reportes. │ │ │ ├── infrastructure/ # Adaptadores de entrada/salida │ │ ├── readers/ │ │ │ ├── json_snapshot_reader.py # Lector principal de snapshots JSON. │ │ │ └── csv_snapshot_reader.py # Lector alternativo CSV. │ │ ├── exporters/ │ │ │ ├── excel_report_exporter.py # Exportador Excel premium (9 hojas). │ │ │ ├── json_report_exporter.py # Exportador JSON para integraciones. │ │ │ └── pdf_report_exporter.py # Exportador PDF ejecutivo (ReportLab). │ │ └── filesystem/ │ │ └── directory_manager.py # Aprovisionamiento de datos_entrada/datos_salida. │ │ │ ├── presentation/ │ │ └── cli.py # Interfaz CLI con banner y panel de resultados. │ │ │ └── shared/ │ ├── constants.py # Puertos/servicios/subdominios sensibles y recomendaciones. │ ├── logger.py # Logging centralizado con colores. │ ├── filename_utils.py # Generación de nombres de reporte sin colisiones. │ ├── date_utils.py # Timestamps UTC / ISO 8601. │ └── normalization_utils.py # Normalización de cabeceras y cadenas. │ ├── tests/ │ ├── unit/ # 8 módulos de pruebas unitarias de servicios diff/scoring. │ └── integration/ │ └── test_monitor_attack_surface_changes_flow.py # Flujo E2E con datos sintéticos. │ ├── datos_entrada/ # Snapshots de entrada (generados o cargados manualmente) │ ├── escaneo_anterior/ # Baseline histórico │ └── escaneo_actual/ # Escaneo de comparación │ ├── datos_salida/ # Reportes generados (Excel, PDF, JSON) │ ├── requirements.txt # Dependencias: pandas, openpyxl, reportlab, pydantic, pytest, ruff. ├── pyproject.toml # Configuración pytest y ruff (line-length = 150). └── .gitignore ``` ## 🛠️ 安装与配置 ### 系统要求 * **Python 3.11 或更高版本**（兼容 3.12 和 3.13）。 * 依赖管理器 `pip`。 * 用于存放 JSON 快照和导出报告的磁盘空间。 ### 配置执行环境 1. **克隆或下载**仓库至您的工作目录。 2. **创建并激活隔离的虚拟环境：** * **Microsoft Windows (PowerShell):** python -m venv venv .\venv\Scripts\activate * **GNU/Linux / macOS:** python -m venv venv source venv/bin/activate 3. **安装依赖套件：** pip install -r requirements.txt 4. **(可选) 验证代码质量：** ruff check app tests ruff format app tests --check ## 🚀 完整操作指南 ### 1. 准备输入快照 MACSA 会在首次启动时自动配置 `datos_entrada/` 结构。请按以下方式组织文件： ``` datos_entrada/ ├── escaneo_anterior/ # Baseline (estado histórico autorizado) │ ├── ports.json │ ├── subdomains.json │ ├── services.json │ ├── headers.json │ ├── ssl_tls.json │ └── endpoints.json # Opcional └── escaneo_actual/ # Estado actual a contrastar ├── ports.json ├── subdomains.json ├── services.json ├── headers.json ├── ssl_tls.json └── endpoints.json # Opcional ``` 如果文件夹为空，系统将生成**真实的演示数据**，以便立即验证审计流程。 ### 2. 启动差异审计 从仓库根目录执行引擎： ``` python -m app.main ``` ### 3. 控制台输出 (交互式面板) CLI 界面将提供汇总指标及生成报告的路径： ``` ================================================================================ MONITOR AVANZADO DE CAMBIOS EN SUPERFICIE DE ATAQUE (v1.0.0) [Herramienta de Auditoría Defensiva y Monitoreo de Exposición] ================================================================================ ================================================================================ RESUMEN DE AUDITORÍA DE EXPOSICIÓN ================================================================================ Fecha de Ejecución: 2026-05-26T12:00:00Z Puntuación de Riesgo: 95.00/100 Nivel de Riesgo Global: CRITICAL -------------------------------------------------------------------------------- Total de Cambios: 12 [-] Críticos: 2 [-] Altos: 4 [-] Medios: 3 [-] Bajos: 2 [-] Informativos: 1 -------------------------------------------------------------------------------- Reportes generados correctamente en datos_salida/: [+] attack_surface_changes_report.json [+] attack_surface_changes_report.xlsx [+] attack_surface_changes_report.pdf ================================================================================ Proceso finalizado. ================================================================================ ``` ### 4. 输出文件 报告将保存在 `datos_salida/` 中，如果已存在先前版本，则会使用递增的命名方式： | 文件 | 描述 | | :--- | :--- | | `attack_surface_changes_report.xlsx` | 按严重程度进行颜色编码的企业级多工作表报告 | | `attack_surface_changes_report.pdf` | 用于向 CISO/管理层汇报的执行摘要 | | `attack_surface_changes_report.json` | 用于 SIEM、SOAR 或内部仪表板的结构化 payload | ## 📊 报告详情与映射 (多工作表 Excel) Microsoft Excel (`.xlsx`) 报告包含 **9 个高度结构化的工作表**，并使用 `openpyxl` 进行了企业级严重程度样式格式化： ``` [ attack_surface_changes_report.xlsx ] ├── 📈 1. Resumen --> KPIs globales, riesgo ponderado y fecha de generación. ├── 📋 2. Cambios Detectados --> Inventario maestro de todos los hallazgos delta. ├── 🔌 3. Puertos --> Detalle de puertos abiertos, cerrados o modificados. ├── 🌐 4. Subdominios --> Nuevos subdominios, cambios de IP y estado HTTP. ├── ⚙️ 5. Servicios --> Servicios expuestos y cambios de versión. ├── 🛡️ 6. Headers --> Cabeceras de seguridad añadidas, removidas o debilitadas. ├── 🔒 7. SSL_TLS --> Certificados, expiración y protocolos TLS obsoletos. ├── 💡 8. Recomendaciones --> Matriz priorizada de acciones de remediación. └── 🛑 9. Errores --> Incidencias de lectura/validación no bloqueantes. ``` ### 各工作表列说明 1. **Resumen (摘要):** `total_cambios`, `cambios_criticos`, `cambios_altos`, `cambios_medios`, `cambios_bajos`, `cambios_informativos`, `riesgo_general`, `fecha_generacion`。 2. **Cambios Detectados (检测到的变更):** `change_id`, `asset_type`, `change_type`, `asset_identifier`, `previous_value`, `current_value`, `severity`, `risk_score`, `risk_level`, `description`, `impact`, `recommendation`, `detected_at`。 3. **Puertos (端口):** `target`, `ip`, `port`, `previous_status`, `current_status`, `previous_service`, `current_service`, `severity`, `recommendation`。 4. **Subdominios (子域名):** `domain`, `subdomain`, `previous_ip`, `current_ip`, `previous_status`, `current_status`, `severity`, `recommendation`。 5. **Servicios (服务):** `host`, `port`, `previous_service`, `current_service`, `previous_version`, `current_version`, `severity`, `recommendation`。 6. **Headers (标头):** `url`, `header`, `previous_value`, `current_value`, `change_type`, `severity`, `recommendation`。 7. **SSL_TLS:** `domain`, `check_name`, `previous_value`, `current_value`, `change_type`, `severity`, `recommendation`。 8. **Recomendaciones (建议):** `prioridad`, `asset_type`, `asset_identifier`, `problema`, `recomendacion`。 9. **Errores (错误):** `archivo`, `tipo_error`, `mensaje_error`, `fecha`。 ## 📊 风险公式与加权评分 引擎利用在 `app/config/settings.py` (`RISK_WEIGHTS`) 中配置的参数化权重，针对检测到的每个变更计算一个 **0 到 100 的量化评分**： $$\text{Score}_{\text{cambio}} = f(\text{asset\_type}, \text{change\_type}, \text{details}) \in [0, 100]$$ $$\text{Riesgo}_{\text{global}} = \begin{cases} \max(\text{scores}) & \text{si } \max(\text{scores}) \geq 76 \\ \dfrac{1}{n}\sum_{i=1}^{n} \text{score}_i & \text{en caso contrario} \end{cases}$$ ### 风险定性映射 | 范围 | 级别 | 操作解释 | | :---: | :--- | :--- | | **0 – 20** | 🟢 **LOW** | 信息类变更或暴露减少（端口关闭、标头改进）。 | | **21 – 50** | 🟡 **MEDIUM** | 新的中等暴露资产或非关键性版本变更。 | | **51 – 75** | 🔶 **HIGH** | 敏感服务暴露、HSTS/CSP 削弱或管理子域名暴露。 | | **76 – 100** | 🛑 **CRITICAL** | 公开的数据库、Docker API、过期证书或 API 身份验证失效。 | ### 默认配置权重示例 | 场景 | 权重 | | :--- | :---: | | Docker API 暴露 (`2375`) | **100** | | 数据库暴露 (MySQL, PostgreSQL, Redis, MongoDB) | **95** | | 无身份验证的私有 endpoint | **95** | | SSL/TLS 证书过期 | **95** | | RDP 暴露 (`3389`) | **85** | | 新增敏感服务 (SSH、Jenkins、Grafana…) | **80** | | 启用 TLS 1.0 协议 | **75** | | HSTS 被移除 | **70** | | SSH 暴露 (`22`) | **70** | | CSP 削弱 (`unsafe-inline`) | **60** | | 端口关闭 / 安全性提升 | **0** | ## 🤖 集成至 DevSecOps (CI/CD Pipeline) 通过添加 `.github/workflows/attack-surface-monitor.yml`，在每次流水线执行中自动验证攻击面的变化： ``` name: Attack Surface Change Monitor (MACSA) on: push: branches: [ main, develop ] pull_request: branches: [ main ] schedule: - cron: '0 6 * * 1' # Auditoría semanal los lunes a las 06:00 UTC jobs: exposure-delta-audit: runs-on: ubuntu-latest steps: - name: Checkout Code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.11' cache: 'pip' - name: Install Dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt - name: Run Quality Test Suite (Pytest) run: python -m pytest -q - name: Run Lint (Ruff) run: ruff check app tests - name: Run MACSA Exposure Delta Audit run: python -m app.main - name: Upload Security Reports uses: actions/upload-artifact@v4 with: name: attack-surface-reports path: | datos_salida/attack_surface_changes_report*.xlsx datos_salida/attack_surface_changes_report*.json datos_salida/attack_surface_changes_report*.pdf ``` ## 🐳 生产环境容器 为了实现独立且纯净的企业级部署，请使用以下优化的清单打包该工具： ``` # 构建层 FROM python:3.11-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir --user -r requirements.txt # 安全执行层 FROM python:3.11-slim AS runner WORKDIR /app RUN groupadd -g 10001 secops && \ useradd -u 10001 -g secops -m -s /bin/bash secops COPY --from=builder /root/.local /home/secops/.local COPY --chown=secops:secops app/ ./app/ COPY --chown=secops:secops pyproject.toml . ENV PATH=/home/secops/.local/bin:$PATH ENV PYTHONUNBUFFERED=1 RUN mkdir -p datos_entrada/escaneo_anterior datos_entrada/escaneo_actual datos_salida && \ chown -R secops:secops datos_entrada datos_salida USER secops VOLUME [ "/app/datos_entrada", "/app/datos_salida" ] ENTRYPOINT [ "python", "-m", "app.main" ] ``` **构建与执行：** ``` docker build -t macsa:latest . docker run --rm \ -v "$(pwd)/datos_entrada:/app/datos_entrada" \ -v "$(pwd)/datos_salida:/app/datos_salida" \ macsa:latest ``` ## ⚙️ 可扩展性指南 (3分钟内添加规则) 基于接口的设计允许您快速扩展带有新验证的引擎。示例：通过 endpoint 中的 URL 模式检测管理面板的暴露情况。 ### 1. 创建规则服务 创建 `app/application/services/admin_panel_exposure_service.py`： ``` from typing import List from app.domain.entities.detected_change import DetectedChange from app.domain.value_objects.asset_type import AssetType from app.domain.value_objects.change_type import ChangeType from app.domain.value_objects.severity_level import SeverityLevel class AdminPanelExposureService: ADMIN_PATHS = ("/admin", "/wp-admin", "/phpmyadmin", "/manager/html") def analyze_endpoint(self, endpoint_dict: dict) -> List[dict]: findings: List[dict] = [] url = str(endpoint_dict.get("url", "")).lower() if any(path in url for path in self.ADMIN_PATHS): findings.append( { "asset_type": AssetType.ENDPOINT, "change_type": ChangeType.ADDED, "asset_identifier": url, "description": f"Panel administrativo potencialmente expuesto: {url}", "details": endpoint_dict, } ) return findings ``` ### 2. 在用例中注册 将该服务注入到 `monitor_attack_surface_changes_use_case.py` 中，并在计算评分之前将其发现的结果累积到 `raw_changes` 中，重用现有的 `SeverityClassifierService`、`RiskScoreCalculatorService` 和 `RecommendationService`。 ### 3. 调整权重 (可选) 在 `app/config/settings.py` 的 `RISK_WEIGHTS` 中添加一个键： ``` "ADMIN_PANEL_EXPOSED": 85, ``` ## 🪵 故障排除 ### 1. Windows 终端中出现 `charmap` 编码错误 * **原因：** 传统的 CMD/PowerShell 控制台未使用 UTF-8，导致在打印特殊字符时失败。 * **解决方案：** chcp 65001 $OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::UTF8 ### 2. `ModuleNotFoundError: No module named 'app'` * **原因：** 从子目录执行脚本时，解释器无法解析根包。 * **解决方案：** 始终从仓库根目录执行： python -m app.main ### 3. 快照为空或未检测到变化 * **原因：** JSON 文件缺失、格式错误，或者在 `escaneo_anterior` 和 `escaneo_actual` 之间完全相同。 * **解决方案：** 检查输入结构，查阅 Excel 的 **Errores** 工作表，并验证两次扫描之间的标识符（`target`、`subdomain`、`url`）是否一致。 ### 4. 输入/输出路径不正确 * **原因：** `app/config/settings.py` 中的 `BASE_DIR` 指向了另一个环境的绝对路径。 * **解决方案：** 将 `BASE_DIR` 更新为项目的本地路径，或重构为基于 `Path(__file__).resolve().parents[2]` 的相对路径。 ### 5. 生成 PDF 或 Excel 失败 * **原因：** 未安装 `reportlab` 或 `openpyxl` 依赖，或者对 `datos_salida/` 没有足够的写入权限。 * **解决方案：** pip install -r requirements.txt 确认输出文件夹的写入权限。 ## 🧪 测试套件与质量保证 引擎包含 **18 个自动化测试**（单元测试和集成测试），通过 `pytest` 执行： ``` # 标准执行 pytest # 详细模式 pytest -v # 带覆盖率（需要安装 pytest-cov） pytest --cov=app --cov-report=term-missing ``` ### 覆盖模块 | 测试模块 | 验证范围 | | :--- | :--- | | `test_ports_diff_service.py` | 敏感端口差异对比与评分 | | `test_subdomains_diff_service.py` | 新增子域名与 IP 变更 | | `test_services_diff_service.py` | 暴露的服务及版本 | | `test_headers_diff_service.py` | 标头移除/削弱 | | `test_ssl_tls_diff_service.py` | 证书与 TLS 协议 | | `test_severity_classifier.py` | 定性分类 | | `test_risk_score_calculator.py` | 数值化风险计算 | | `test_recommendation_service.py` | 补救建议生成 | | `test_monitor_attack_surface_changes_flow.py` | 端到端 (E2E) 流程：读取 → diff → 导出 | ### 代码质量 ``` ruff check app tests # Lint estático ruff format app tests # Formateo automático ``` ## 📄 许可证与负责任的使用 本软件仅出于教育目的及授权的防御性审计进行分发。操作者有责任遵守当地的网络安全法律，并获得被分析资产所有者的明确同意。

MACSA v1.0.0 — 高级攻击面变化监控器
Clean Architecture · DevSecOps Ready · Zero Offensive Payloads

标签：DevSecOps, 上游代理, 实时处理, 密码管理, 持续监控, 请求拦截, 逆向工具