Prepare Attack Surface Mapper for public release

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Report a reproducible problem without sharing sensitive target data
+title: "[bug] "
+labels: bug
+---
+
+## Summary
+
+<!-- Describe the observable problem. Do not include credentials, live target names or raw scan output. -->
+
+## Reproduction
+
+- Version or commit:
+- Profile:
+- Operating system:
+- Python version:
+- External tools and versions:
+
+## Expected behaviour
+
+## Actual behaviour
+
+## Evidence
+
+Use a sanitised fixture or minimal reproduction. Remove tokens, cookies, hostnames, IPs and personal data.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest a focused improvement
+title: "[feature] "
+labels: enhancement
+---
+
+## Problem
+
+What authorised testing or review workflow is currently difficult?
+
+## Proposed change
+
+Describe the smallest useful change.
+
+## Trade-offs
+
+Explain expected effects on noise, coverage, runtime, output compatibility and safety.

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## Summary
+
+<!-- What problem does this change solve? -->
+
+## Scope
+
+- [ ] Collector or external-tool integration
+- [ ] Validator or detection logic
+- [ ] Correlation, scoring or false-positive handling
+- [ ] Reporting or output contract
+- [ ] Documentation or tooling
+
+## Verification
+
+- [ ] `python -m compileall -q main.py src`
+- [ ] `python -m pytest -q`
+- [ ] Relevant controlled lab validation completed
+- [ ] No credentials, private keys, raw engagement reports or personal data added
+
+## Operational impact
+
+<!-- Describe noise, coverage, compatibility and authorised-use implications. -->

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install project and test dependencies
+        run: python -m pip install -e ".[dev]"
+      - name: Compile source
+        run: python -m compileall -q main.py src
+      - name: Run tests
+        run: python -m pytest -q
+
+      - name: Build package metadata
+        run: python -m pip wheel --no-deps --wheel-dir dist .

.github/workflows/security.yml

@@ -0,0 +1,31 @@
+name: Dependency security
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "17 5 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-audit:
+    name: Audit Python dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install project dependencies
+        run: python -m pip install -e .
+
+      - name: Run pip-audit
+        uses: pypa/gh-action-pip-audit@v1.1.0
+        with:
+          inputs: .

.gitignore

@@ -15,6 +15,7 @@ env/
 
 # Local execution outputs
 scans/
+reviews/
 *.log
 
 # Tooling and local state

CHANGELOG.md

@@ -1,4 +1,76 @@
-# attack_surface_mapper_project_v10.11
+# Attack Surface Mapper
+
+## v10.22.10 public-release hardening
+
+- Reworks the README around the actual pipeline, profile trade-offs, output contract and responsible-use boundary.
+- Adds architecture documentation, contribution guidance, code of conduct and GitHub issue/PR templates.
+- Adds MIT licensing and package metadata for a more reproducible public release.
+- Adds a scheduled dependency-audit workflow and a package build gate to CI.
+- Runs the dependency audit on pushes as well as pull requests, schedules and manual dispatches.
+- Documents the local-first system boundary and the checks required before publishing scan tooling.
+
+## v10.22.9 quality hardening
+
+- Repairs corrupted UTF-8 text in API/auth validation evidence so generated Spanish reports remain readable and professional.
+- Adds a minimal GitHub Actions quality gate for source compilation and the full pytest suite.
+- Adds a regression test that rejects mojibake markers in Python source files.
+- Aligns the package name, version and description with the public project identity.
+- Repairs legacy changelog encoding so the project history is readable.
+
+## v10.22.8 polish
+
+- Añade un exportador independiente de Elasticsearch (`scripts/export_elasticsearch_bundle.py`) que empaqueta findings, summaries y run manifest desde un run ya generado sin tocar el pipeline principal.
+- Genera mappings estables, NDJSON `_bulk` y helpers de ingesta para las tres vías pedidas por el tutor: manual/Kibana Dev Tools, `curl` y Python.
+- Reutiliza el contrato actual del hallazgo (`finding_id`, `correlation_id`, `priority_score`, `finding_role`, `validated`, `validation_basis`, etc.) y evita exportar `raw` completo para mantener los índices más estables.
+
+- Introduce un scoring estructurado (`scoring_version`, `priority_score`) basado en severidad, confianza, rol del hallazgo y base de validación, manteniendo la salida `low/medium/high/critical` pero haciéndola más estable y auditable.
+- Expone el score numérico y su razón en reportes, CSV, agregados y matriz de revisión para facilitar comparativas futuras e ingest estructurado.
+- Ajusta `comparison.json` para detectar cambios en `priority_score` aunque la etiqueta de prioridad no cambie, mejorando el seguimiento fino entre runs.
+
+- Introduce una capa de validación explícita en el modelo de hallazgo con `finding_role`, `validated` y `validation_basis`, separando mejor descubrimiento, candidatos y evidencia validada.
+- Propaga esa semántica a `report.summary.json`, `aggregate_summary.json`, `comparison.json` y la matriz de revisión para dejar el output estructurado más estable y más honesto.
+- Mantiene compatibilidad con hallazgos previos o JSON legacy: reporting, agregado y comparación infieren el rol de validación cuando el campo nuevo todavía no existe.
+- Amplía el golden set y la exportación de revisión con `finding_role`, `validated` y `validation_basis` para afinar falsos positivos con una semántica más clara.
+
+- Conserva el `debug_http_trace` de browser discovery y validación pasiva en una misma ejecución para facilitar análisis de ruido y troubleshooting.
+- Ajusta el resumen ejecutivo para que la nota sobre hallazgos altos/críticos confirmados dependa de los datos reales del run.
+- Amplía el `summary-json` con campos ya existentes del modelo (`kind`, `confidence`, `asset_host`, `asset_port`, `source_count`, `evidence_summary`) para mantener el output más preparado para consumo estructurado futuro.
+- Alinea la documentación con el comportamiento real de targets CLI + YAML: se combinan y deduplican, no se sobrescriben.
+- Separa `asset_host` estable de `asset_host_resolved` para que los outputs humanos y estructurados no cambien de hostname a IP según el punto del pipeline.
+- Añade identificadores deterministas por hallazgo y correlación para facilitar ingest futura en sistemas de indexación.
+- Reutiliza una única baseline probe compartida entre validadores HTTP durante la validación pasiva, reduciendo requests redundantes.
+- Documenta una validación repetible con Juice Shop para contrastar perfiles pasivos.
+- Añade `scripts/validate_labs.ps1` para repetir validaciones de laboratorio con Juice Shop y DVWA desde Windows/PowerShell.
+- Estabiliza `report.summary.json`, `aggregate_summary.json` y `run_manifest.json` con secciones y claves más predecibles para futuro consumo estructurado.
+- Endurece `scripts/validate_labs.ps1` para validar artefactos generados, IDs estables y un mínimo configurable de hallazgos.
+- Reduce falsos positivos de `APIValidator` descartando pantallas de login servidas desde rutas como `/swagger` o `/graphql`.
+- Enriquece `comparison.json` y la sección de comparativa en reportes con promociones, regresiones y cambios de confianza/verificación.
+- Alinea mejor `verification_status`, `needs_manual_validation` y prioridad para que un hallazgo `confirmed` no siga marcado como revisión manual por inercia de categoría.
+- Añade una matriz de revisión exportable (`reviews/lab_findings_review.csv`) para etiquetar hallazgos de labs como `verdadero`, `falso` o `dudoso` durante el afinado de falsos positivos.
+- Ajusta la priorización de correlación para dar más peso a evidencia `confirmed` y evita que la mera multiplicidad de fuentes infle hallazgos todavía `likely`.
+
+- Permite validar `passive-recon-enum` dentro del flujo repetible de labs con un override local (`config/examples/lab-passive-recon-enum.yml`) que desactiva Nuclei y mantiene el perfil comparable en Docker.
+- Evita que headers confirmados de severidad media, como CSP ausente, escalen a prioridad `high` solo por estar confirmados; la prioridad se reserva mejor para evidencia aplicativa o impacto más claro.
+- Endurece `APIValidator`, `PanelsValidator` y `SensitiveFilesValidator` contra superficies de login servidas desde rutas de docs, respuestas HTML que simulan ficheros y respuestas GraphQL demasiado débiles o indistinguibles del fallback.
+- Reordena `top_findings` y el agregado para que hallazgos confirmados de aplicación queden por delante de inventario, fingerprints y headers higiénicos cuando comparten prioridad similar.
+
+- Acota mejor la prioridad de documentación y superficies API: `Swagger UI Exposed` deja de escalar a `critical`, `GraphQL Endpoint Accessible Without Authentication` se mantiene en `medium` cuando sigue en `likely`, y el inventario `Multiple API Endpoints Exposed` no compite como si fuese una confirmación de impacto.
+- Ajusta la matriz de revisión para que headers de higiene y superficies de inventario API queden en `revisar` o `descubrimiento`, evitando priorizar por defecto hallazgos que todavía son de contexto o endurecimiento.
+- Separa mejor el reporting entre riesgo de aplicación, higiene/endurecimiento y descubrimiento: `report.summary.json` expone listas dedicadas (`top_risk_findings`, `top_hygiene_findings`, `top_discovery_findings`) y el markdown mueve headers/TLS a una sección propia para que no compitan visualmente con acceso indebido real.
+- Ajusta `AuthValidator` para que rutas de superficie API como `/graphql`, `/swagger` o `/api-docs` no se expresen por defecto como fallo de autorización: ahora se reportan como `api` (`GraphQL Surface Exposed`, `Swagger UI Exposed`, etc.) y se acotan a `likely/medium` salvo evidencia más fuerte.
+- Filtra `top_risk_findings` para dejar fuera señales de baja prioridad como CORS amplio `likely` cuando ya existen hallazgos medios/altos más accionables, manteniendo el summary centrado en lo que primero merece revisión.
+
+## v10.22.6 false-positive tuning
+
+- Alinea `--profile passive-stealth`, `--profile passive-recon-safe` y `--profile active-aggressive` con la semántica de los YAML para evitar que la CLI ejecute Nuclei, Nmap o probes hardcoded cuando no toca.
+- El manifest de ejecución ya registra el perfil usado por CLI, no solo el definido en YAML.
+- Evita correlacionar hallazgos heterogéneos solo porque comparten rutas como `/login`: headers, fingerprints y formularios ya no se fusionan en un falso hallazgo de mayor prioridad.
+- Reduce ruido en headers: checks de CSP/X-Frame/Referrer se aplican solo a documentos de navegador, y cabeceras de bajo impacto quedan con prioridad baja.
+- Ajusta CORS: `Access-Control-Allow-Origin: *` sin credenciales se clasifica como señal low/likely, no como hallazgo confirmado de mayor impacto.
+- Trata `/login` como superficie de descubrimiento, no como panel expuesto.
+- Endurece detección de ficheros sensibles: `.zip` y `.DS_Store` requieren firma real, no solo `Content-Type`.
+- Reduce ruido de cookies: se ignoran cookies no relacionadas con sesión/auth y no se exige `HttpOnly` en cookies CSRF/XSRF.
+- Validado contra Docker local con OWASP Juice Shop y DVWA en perfiles `passive-stealth` y `passive-recon-safe`.
 
 Versión 10.10 del proyecto: mantiene el pipeline de **Nuclei + validaciones propias + correlación + reporting**, conserva **descubrimiento opcional con Nmap** y mejora el crawling con **Scrapling + fallback a requests**, además de promover formularios y pistas de endpoints descubiertos a nuevas validaciones.
 
@@ -123,7 +195,7 @@ python main.py --config config/examples/config.example.yml
 
 ### Generales
 
-- `--profile {quick,normal,deep,passive,active}`
+- `--profile {quick,normal,deep,passive,active,active-aggressive,passive-stealth,passive-recon-safe,passive-recon-enum}`
 - `--workers 4`
 - `--output-root scans`
 - `--run-name nombre_scan`

CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+Participants are expected to be respectful, constructive and professional. Security discussions must remain focused on authorised testing, reproducible evidence and responsible disclosure.
+
+Harassment, personal attacks, discrimination, doxxing, publication of private data and requests to attack systems without permission are not acceptable.
+
+Project maintainers may remove content or restrict participation when these expectations are not met.

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for helping improve Attack Surface Mapper.
+
+## Before opening a change
+
+- Work only with targets and datasets you are authorised to use.
+- Keep changes focused and explain the operational or reporting impact.
+- Add regression coverage for parser, validator, correlation or output changes.
+- Do not commit credentials, private keys, raw reports from real engagements or personal data.
+
+## Local checks
+
+```bash
+python -m compileall -q main.py src
+python -m pytest -q
+python -m pip wheel --no-deps --wheel-dir dist .
+```
+
+For changes to profiles or lab behaviour, also run the relevant controlled lab validation and update the documentation and changelog.
+
+## Pull requests
+
+Describe:
+
+- the problem and intended behaviour;
+- the affected pipeline stages or output fields;
+- tests and lab checks executed;
+- any compatibility or noise/coverage trade-off.
+
+Avoid including live target names, sensitive evidence or operational credentials in commits and pull requests.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Vacaro Goytia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.