ensmcp 0.1.0__tar.gz

ensmcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,116 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Least privilege by default. Neither job writes anything back to the repo,
+# so a read-only GITHUB_TOKEN is enough. Without this block the token
+# inherits the repository/organisation default, which on older repos is
+# read/write - and both jobs run third-party code (pip install executes
+# package build hooks, patchright downloads browser binaries), so a
+# compromised dependency would otherwise get a token that can push.
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality & security gates
+    runs-on: ubuntu-latest
+    steps:
+      # Actions are pinned to an immutable commit SHA, not a tag: tags are
+      # mutable, so @v4 silently follows whatever the action owner (or anyone
+      # who compromises their account) later points it at. The trailing
+      # comment keeps the human-readable version visible.
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          # Do not leave the token in .git/config for later steps to read.
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.14"
+          cache: pip
+      # Install from the PEP 751 lock, not by re-resolving pyproject.toml: every
+      # package is pinned to an exact version and verified against the sha256 in
+      # pylock.toml, so a tampered or yanked-and-replaced release cannot slip
+      # into CI. The local package goes in separately with --no-deps so it does
+      # not drag an unlocked resolution back in.
+      - run: pip install -r pylock.toml
+      - run: pip install -e . --no-deps
+      - run: black --check .
+      - run: ruff check .
+      - run: mypy .
+      # bandit needs -c pyproject.toml to pick up [tool.bandit] (venv exclusion).
+      - run: bandit -c pyproject.toml -r .
+      - run: pip-audit
+
+  tests:
+    # The offline suite (pytest -m "not network") reaches 100% coverage on its
+    # own using bundled headless Chromium against local fixture pages, so it can
+    # run on every supported platform. The live-site suite stays in its own
+    # Linux-only job below: it needs headed Chrome plus xvfb, and hitting the
+    # real ENS site once per push is enough.
+    name: Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest, windows-11-arm]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.14"
+          # cryptography (mcp -> pyjwt[crypto]) publishes no win_arm64 wheels,
+          # so an ARM-native Python cannot install the lock without a
+          # Rust+OpenSSL source build. x64 Python under Windows emulation is
+          # what a Windows-on-ARM user gets today, and it is what this job
+          # verifies. Empty string means "runner default" for the other OSes.
+          architecture: ${{ matrix.os == 'windows-11-arm' && 'x64' || '' }}
+          cache: pip
+      # Ubuntu 24.04 images restrict unprivileged user namespaces via
+      # AppArmor, which kills Chromium's sandbox at launch. Re-enabling them
+      # is the workaround Chromium documents for CI:
+      # https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md
+      - if: runner.os == 'Linux'
+        run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+      - run: pip install -r pylock.toml
+      - run: pip install -e . --no-deps
+      # System libraries for Chromium; only Linux needs (or supports) this step.
+      - if: runner.os == 'Linux'
+        run: patchright install-deps chromium
+      - run: patchright install chromium
+      - run: pytest -m "not network"
+
+  tests-live:
+    name: Tests (100% coverage, live ENS site)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.14"
+          cache: pip
+      # Real Google Chrome for the network tests, which use headed
+      # channel="chrome" to get past the ENS site's WAF (it blocks headless).
+      - uses: browser-actions/setup-chrome@c785b87e244131f27c9f19c1a33e2ead956ab7ce # v1
+        with:
+          chrome-version: stable
+      # Same AppArmor/user-namespace workaround as the matrix job above.
+      - run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+      # Same hash-verified install as the quality job (see the note there).
+      - run: pip install -r pylock.toml
+      - run: pip install -e . --no-deps
+      # Bundled Chromium (headless, channel=None) for the local_site tests.
+      - run: patchright install-deps chromium
+      - run: patchright install chromium
+      # xvfb gives headed Chrome a display; headless Chromium ignores it.
+      # The full suite enforces --cov-fail-under=100, so every test (including
+      # the network ones against gobernanza.ccn-cert.cni.es) must run here.
+      - run: xvfb-run pytest

ensmcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+# Releases are cut by pushing a version tag: bump `version` in pyproject.toml,
+# tag the commit `vX.Y.Z` and push the tag. No API tokens are stored anywhere:
+# publishing uses PyPI trusted publishing (OIDC), so PyPI accepts the upload
+# because it comes from this repo's `release.yml` running in the `pypi`
+# environment, and from nowhere else.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.14"
+      # Refuse to publish a tag that does not match the declared version:
+      # otherwise PyPI would either reject the upload later or, worse, accept
+      # an artifact whose version says something else than the tag.
+      - name: Check tag matches pyproject version
+        run: |
+          version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "v${version}" = "${GITHUB_REF_NAME}" || {
+            echo "Tag ${GITHUB_REF_NAME} does not match pyproject version ${version}" >&2
+            exit 1
+          }
+      - run: pip install build
+      - run: python -m build
+      # Smoke-test the built wheel in a clean venv. CI installs the project in
+      # editable mode, so nothing else ever exercises the packaged artifact:
+      # this is the only check that the wheel actually ships the snapshot data.
+      - name: Smoke-test wheel
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install dist/*.whl
+          /tmp/smoke/bin/python -c "from importlib.resources import files; import ensmcp; assert (files('ensmcp') / 'data' / 'anexo_ii.json').is_file()"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (OIDC)
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # The OIDC token is the credential: PyPI's trusted publisher for this
+      # project must point at this repo, this workflow and the environment.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

ensmcp-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+*.egg-info/
+build/
+dist/
+*.har
+# Guías CCN-STIC: se commitea el dato extraído, nunca el documento.
+*.pdf

ensmcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Rivero Lopez
+
+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.

ensmcp-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: ensmcp
+Version: 0.1.0
+Summary: Servidor MCP con las medidas de seguridad del ENS (Anexo II del RD 311/2022): Anexo II, Declaración de Aplicabilidad y alcance de auditoría, sin conexión
+Author-email: "Marc Rivero Lopez | @seifreed" <mriverolopez@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: patchright>=1.61.2
+Provides-Extra: dev
+Requires-Dist: bandit>=1.8; extra == 'dev'
+Requires-Dist: black>=24.10; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: packaging>=26.3; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://img.shields.io/badge/ensmcp-MCP%20Server%20ENS%20Navegable-blue?style=for-the-badge" alt="ensmcp">
+</p>
+
+<h1 align="center">ensmcp</h1>
+
+<p align="center">
+  <strong>Servidor MCP con las medidas de seguridad del ENS (Anexo II del RD 311/2022): consulta el Anexo II, genera la Declaración de Aplicabilidad y el alcance de auditoría de un sistema, y funciona sin conexión</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.14-blue?style=flat-square&logo=python&logoColor=white" alt="Python Version"></a>
+  <a href="https://github.com/seifreed/ensmcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/seifreed/ensmcp/ci.yml?style=flat-square&logo=github&label=CI" alt="CI Status"></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-2.0-black?style=flat-square" alt="MCP"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/seifreed/ensmcp/stargazers"><img src="https://img.shields.io/github/stars/seifreed/ensmcp?style=flat-square" alt="GitHub Stars"></a>
+  <a href="https://github.com/seifreed/ensmcp/issues"><img src="https://img.shields.io/github/issues/seifreed/ensmcp?style=flat-square" alt="GitHub Issues"></a>
+  <a href="https://buymeacoffee.com/seifreed"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?style=flat-square&logo=buy-me-a-coffee&logoColor=white" alt="Buy Me a Coffee"></a>
+</p>
+
+---
+
+## Qué es
+
+**ensmcp** es un servidor [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) que pone las medidas de seguridad del [ENS Navegable](https://gobernanza.ccn-cert.cni.es/ens-navegable) (Anexo II del RD 311/2022) al alcance de Claude Desktop, Claude Code y cualquier otro cliente MCP.
+
+Los datos viajan incluidos en el paquete como un snapshot, así que el servidor responde al instante y funciona sin conexión. Al arrancar, comprueba en segundo plano el sitio oficial y, si el contenido ha cambiado, actualiza los datos automáticamente; si no hay red o no hay navegador disponible, sigue funcionando con el snapshot sin más.
+
+Además del Anexo II, incorpora el cuestionario de verificación de la **guía CCN-STIC 808** (edición para el RD 311/2022): las preguntas de auditoría por medida, las comprobaciones sobre el articulado del RD y las evidencias documentales que puede pedir el auditor.
+
+### Características principales
+
+| Característica | Descripción |
+|----------------|-------------|
+| **Servidor MCP sobre stdio** | Integrable en Claude Desktop, Claude Code y otros clientes MCP |
+| **Funciona sin conexión** | El corpus completo viaja como snapshot en el paquete |
+| **Se mantiene al día** | Una comprobación en segundo plano detecta cambios en el sitio oficial y actualiza los datos |
+| **Nunca bloquea** | Sin red o sin navegador, se sigue respondiendo desde el snapshot |
+| **Declaración de Aplicabilidad** | La DdA completa de un sistema, valorando cada dimensión por separado, en una llamada |
+| **Auditoría CCN-STIC 808** | Temario de auditoría, requisitos esenciales, artículos del RD y evidencias documentales |
+
+## Tools disponibles
+
+### Consulta del Anexo II
+
+| Tool | Args | Descripción |
+|------|------|-------------|
+| `list_categories` | — | Las categorías del Anexo II con su grupo (`org`, `op`, `mp`). |
+| `list_measures` | `category_code?`, `dimension?`, `level?` | Medidas filtradas por categoría, dimensión de seguridad o nivel. |
+| `get_measure` | `code` | Una medida por código exacto (p. ej. `"org.1"`), con su texto del RD, refuerzos y niveles. |
+| `search_measures` | `query` | Búsqueda por texto en código, título, descripción y redacción del RD (ignora mayúsculas y tildes). |
+
+### Declaración de Aplicabilidad y auditoría
+
+| Tool | Args | Descripción |
+|------|------|-------------|
+| `declaracion_aplicabilidad` | `confidencialidad?`, `integridad?`, `disponibilidad?`, `autenticidad?`, `trazabilidad?` | La DdA de un sistema en una llamada: se valora cada dimensión (`basico`/`medio`/`alto`, u omitida) y devuelve las medidas exigibles con sus refuerzos. |
+| `alcance_auditoria` | mismas que la DdA | El temario de auditoría del sistema: las medidas aplicables con sus preguntas de verificación acumuladas y el nivel de madurez mínimo exigible. |
+| `requisitos_auditoria` | `code?`, `level?` | El cuestionario CCN-STIC 808 en bruto, por medida o por tramo, marcando los requisitos esenciales. |
+| `requisitos_articulos` | — | Las comprobaciones de auditoría sobre el articulado del RD (DdA formal, categorización, INES...). |
+| `evidencias_auditoria` | `code?` | La documentación que puede pedir el auditor, por medida. |
+
+### Estado y actualización
+
+| Tool | Args | Descripción |
+|------|------|-------------|
+| `refresh_live_page` | — | Comprueba ahora el sitio oficial y actualiza los datos si han cambiado. |
+| `snapshot_status` | — | Origen y frescura de los datos que se están sirviendo. |
+
+## Qué devuelve una medida
+
+Cada medida trae dos textos, y hacen falta los dos: `norm_text` es la redacción del RD 311/2022 (lo que la medida **exige**) y `description` es el cuestionario de la CCN-STIC 808 (lo que el auditor **pregunta**). Los refuerzos vienen emparejados con el nivel que los exige y con su redacción en el RD:
+
+```json
+{
+  "code": "mp.s.4",
+  "title": "Protección frente a denegación de servicio",
+  "description": "Categoría Media 1.1 ¿Se ha planificado y dotado al sistema de capacidad suficiente ...?",
+  "norm_text": "Se establecerán medidas preventivas frente a ataques de denegación de servicio ...",
+  "category_code": "mp.s",
+  "dimensions": ["disponibilidad"],
+  "levels": ["medio", "alto"],
+  "reinforcements": [
+    { "code": "R1", "level": "alto", "alternative": false, "text": "R1-Detección y reacción. ..." }
+  ],
+  "raw_levels": { "basico": "n.a.", "medio": "aplica", "alto": "+ R1" }
+}
+```
+
+`alternative` distingue los refuerzos obligatorios (`+ R1 + R2`) de los alternativos (`+ [R1 o R2]`, donde basta uno cualquiera): confundirlos cambia lo que hay que implantar.
+
+## Declaración de Aplicabilidad
+
+El ENS no aplica un nivel al sistema entero: aplica **uno por dimensión**. Se valora cada una y la tool devuelve lo que ese sistema debe cumplir:
+
+```json
+{
+  "categoria_sistema": "alto",
+  "measures": [
+    { "code": "op.acc.5", "title": "Mecanismo de autenticación (usuarios externos)",
+      "required_level": "alto",
+      "required_reinforcements": [
+        { "code": "R2", "alternative": true,  "text": "R2-..." },
+        { "code": "R5", "alternative": false, "text": "R5-..." }
+      ] }
+  ]
+}
+```
+
+La regla sale del RD 311/2022: la categoría del sistema es el mayor de los niveles valorados (Anexo I, ap. 4), las medidas marcadas «Categoría» se exigen según la categoría del sistema, las que protegen dimensiones según el nivel de esas dimensiones, y una dimensión sin valorar deja fuera las medidas que solo la protegen.
+
+## Alcance de auditoría
+
+Si la DdA contesta *«¿qué tengo que implantar?»*, `alcance_auditoria` contesta *«¿qué me va a preguntar el auditor?»*. Devuelve, por cada medida aplicable, los requisitos de verificación **acumulados** hasta su nivel exigible y el nivel de madurez mínimo que exige la guía:
+
+| Categoría | Nivel mínimo de madurez |
+|---|---|
+| BÁSICA | **L2** — Reproducible, pero intuitivo |
+| MEDIA | **L3** — Proceso definido |
+| ALTA | **L4** — Gestionado y medible |
+
+El matiz importa: los tramos que el ENS Navegable etiqueta «Categoría Básica / Media / Alta» son acumulativos según la CCN-STIC 808 §5 — «Categoría Básica» significa *exigible a todas las categorías*, no *solo para sistemas básicos*. Un sistema de categoría media responde las preguntas de básica **y** las de media. Para un sistema C=alto, I=medio, D=bajo, A=medio, T=medio, el temario real son **382 preguntas** (136 esenciales, cuyo incumplimiento bloquea la certificación), no las 73 de su tramo.
+
+`requisitos_articulos` y `evidencias_auditoria` cubren la otra mitad de la auditoría: las comprobaciones sobre el articulado del RD (si la DdA existe y está suscrita, si el sistema está categorizado formalmente, si se reporta a INES...) y las 365 evidencias documentales que la guía propone. Estos datos salen de la CCN-STIC 808; el ENS Navegable no los publica.
+
+## De dónde salen los datos
+
+- **`src/ensmcp/data/anexo_ii.json`** — el corpus del ENS Navegable (medidas, textos del RD, cuestionario, aplicabilidad por niveles), capturado del sitio oficial. Cada consulta es un lookup en memoria.
+- **`src/ensmcp/data/guia_808.json`** — el dato extraído de la guía CCN-STIC 808 con su atribución (la guía en sí no se redistribuye). `snapshot_status` indica de qué edición procede.
+
+Para regenerar el snapshot:
+
+```bash
+python scripts/build_snapshot.py
+```
+
+Para que el servidor no abra Chrome nunca por su cuenta: `ENSMCP_LIVE_CHECK=0`.
+
+## Requisitos
+
+- Python **3.14+**
+
+Solo para **actualizar** el snapshot (`refresh_live_page`, la comprobación de arranque, `scripts/build_snapshot.py`) hacen falta además:
+
+- Google Chrome instalado
+- Un display (o `xvfb` en servidores sin él)
+
+## Instalación
+
+```bash
+git clone https://github.com/seifreed/ensmcp.git
+cd ensmcp
+python3 -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install -r pylock.toml   # versiones exactas, verificadas por hash
+pip install -e . --no-deps   # el propio paquete, sin re-resolver
+patchright install chromium
+```
+
+En Linux recién instalado puede hacer falta además:
+
+```bash
+patchright install-deps chromium
+```
+
+`pyproject.toml` es el único sitio donde se declaran las dependencias; `pylock.toml` es un artefacto generado a partir de él ([PEP 751](https://peps.python.org/pep-0751/)) que fija todas las dependencias —runtime y desarrollo juntas— a versión exacta y hash, con marcadores para Windows, Linux y macOS en x64 y ARM. Para actualizar dependencias, edita los rangos en `pyproject.toml` y regenera:
+
+```bash
+uv pip compile pyproject.toml --all-extras --universal --python-version 3.14 \
+  --format pylock.toml -o pylock.toml
+```
+
+## Inicio rápido
+
+```bash
+python -m ensmcp
+```
+
+Configúralo en un cliente MCP (p. ej. Claude Desktop / Claude Code) apuntando al intérprete del entorno virtual:
+
+```json
+{
+  "mcpServers": {
+    "ensmcp": {
+      "command": "/ruta/a/ensmcp/venv/bin/python",
+      "args": ["-m", "ensmcp"]
+    }
+  }
+}
+```
+
+No hace falta configurar nada más: las consultas se responden desde el snapshot del paquete.
+
+Para inspeccionarlo manualmente:
+
+```bash
+npx @modelcontextprotocol/inspector venv/bin/python -m ensmcp
+```
+
+## Contribuir
+
+Las contribuciones son bienvenidas.
+
+1. Haz un fork del repositorio
+2. Crea tu rama de funcionalidad (`git checkout -b feature/nueva-funcionalidad`)
+3. Haz commit de tus cambios (`git commit -m 'Añade nueva funcionalidad'`)
+4. Sube la rama (`git push origin feature/nueva-funcionalidad`)
+5. Abre un Pull Request
+
+Asegúrate de que todas las gates de calidad y seguridad pasen sin errores ni warnings antes de enviar el PR.
+
+## Apoya el proyecto
+
+Si este proyecto te es útil, puedes apoyar su desarrollo:
+
+<a href="https://buymeacoffee.com/seifreed" target="_blank">
+  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50">
+</a>
+
+## Autor
+
+- **Marc Rivero López** | [@seifreed](https://github.com/seifreed)
+- Repositorio: [github.com/seifreed/ensmcp](https://github.com/seifreed/ensmcp)
+
+---
+
+<p align="center">
+  <sub>Las medidas del ENS, accesibles por MCP</sub>
+</p>