pdgseg-cli 1.0.0__py3-none-any.whl

pdgseg/__init__.py

@@ -0,0 +1,8 @@
+"""pdgseg: CLI de SegSoft para ejecutar el análisis de cumplimiento desde pipelines CI/CD."""
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("pdgseg-cli")
+except PackageNotFoundError:  # running from a source tree without installing
+    __version__ = "0.0.0.dev0"

pdgseg/cli.py

@@ -0,0 +1,172 @@
+"""Punto de entrada: «pdgseg analyze»."""
+
+from __future__ import annotations
+
+import os
+import sys
+import traceback
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from . import __version__
+from .client import ApiClient
+from .config import CONFIG_FILE_NAME, SERVER_ENV, example_config, load_config
+from .errors import PdgsegError
+from .flow import Progress, run_analysis
+from .output import error_json, render_text, to_json
+from .summary import EXIT_ERROR, EXIT_OK, exit_code_for, summarize
+
+TOKEN_ENV = "PDGSEG_API_TOKEN"
+DEFAULT_SARIF_PATH = "results.sarif"
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-V", "--version", prog_name="pdgseg")
+def main() -> None:
+    """CLI de SegSoft: análisis de cumplimiento de seguridad para pipelines CI/CD."""
+    _utf8_when_redirected()
+
+
+def _utf8_when_redirected() -> None:
+    """
+    On Windows, output redirected to a pipe or file (a CI log) uses the ANSI code page, so accents
+    show up garbled and a character outside it would crash. CI logs are read as UTF-8: write UTF-8
+    there. An interactive console is left alone (click writes to it through the Unicode console API).
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if not hasattr(stream, "reconfigure"):
+            continue
+        try:
+            if stream.isatty():
+                stream.reconfigure(errors="replace")
+            else:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError, AttributeError):
+            pass
+
+
+@main.command()
+@click.option("--path", "path", type=click.Path(file_okay=False, dir_okay=True, path_type=Path), default=".",
+              show_default=True, help="Directorio del proyecto a analizar.")
+@click.option("--config", "config_path", type=click.Path(dir_okay=False, path_type=Path), default=None,
+              help=f"Archivo de configuración. Por defecto, {CONFIG_FILE_NAME} dentro de --path.")
+@click.option("--output", "output_format", type=click.Choice(["text", "json", "sarif"]), default="text",
+              show_default=True, help="text: resumen legible; json: para scripts; sarif: archivo SARIF 2.1.0 "
+                                      "(para GitHub Code Scanning) más el resumen en texto.")
+@click.option("--output-path", type=click.Path(dir_okay=False, path_type=Path), default=None,
+              help=f"Dónde escribir la salida json o sarif (sarif: {DEFAULT_SARIF_PATH} por defecto; "
+                   "json: la salida estándar por defecto).")
+@click.option("--dry-run", is_flag=True, help="Analiza e informa, pero devuelve 0 aunque haya hallazgos "
+                                              "(los errores técnicos siguen devolviendo 10).")
+@click.option("--quiet", "-q", is_flag=True, help="Sin mensajes de progreso ni colores.")
+@click.option("--verbose", "-v", is_flag=True, help="Muestra cada petición HTTP y el detalle de los errores.")
+@click.option("--token", envvar=TOKEN_ENV, default=None, show_envvar=True,
+              help=f"Token de API (pdgseg_...). Mejor por la variable {TOKEN_ENV}: lo que va en la línea de "
+                   "comandos puede quedar en el historial y en los logs.")
+@click.option("--server", envvar=SERVER_ENV, default=None, show_envvar=True,
+              help="URL del backend; reemplaza «server» de la configuración.")
+def analyze(path: Path, config_path: Optional[Path], output_format: str, output_path: Optional[Path],
+            dry_run: bool, quiet: bool, verbose: bool, token: Optional[str], server: Optional[str]) -> None:
+    """Sube el proyecto, ejecuta el análisis y termina con un código de salida según los hallazgos.
+
+    \b
+    Códigos de salida:
+      0   sin hallazgos de la severidad failOnSeverity (por defecto high) o superior
+      1   hallazgos de esa severidad o superior, sin CRITICAL
+      2   al menos un hallazgo CRITICAL
+      10  error técnico (configuración, token, red, análisis fallido)
+    """
+    if quiet and verbose:
+        raise click.UsageError("--quiet y --verbose no se pueden usar juntos.")
+
+    json_to_stdout = output_format == "json" and output_path is None
+    color = not quiet and output_format != "json" and sys.stdout.isatty() and "NO_COLOR" not in os.environ
+
+    def info(message: str) -> None:
+        if not quiet:
+            click.echo(message, err=True)
+
+    def debug(message: str) -> None:
+        if verbose:
+            click.echo(click.style(message, dim=True) if color else message, err=True)
+
+    def fail(message: str) -> None:
+        if json_to_stdout:
+            click.echo(error_json(message, EXIT_ERROR))
+        click.echo(("Error: " if not message.startswith("Error") else "") + message, err=True)
+        sys.exit(EXIT_ERROR)
+
+    try:
+        config = load_config(config_path or (path / CONFIG_FILE_NAME), server_override=server)
+        if not token:
+            raise PdgsegError(f"Falta el token de API: defínelo en la variable {TOKEN_ENV} (en CI, como secreto) "
+                              f"o con --token. Se crea en SegSoft, ícono de llave, «Tokens de API».")
+        token = token.strip()
+        if dry_run:
+            click.echo(click.style("DRY-RUN: el resultado no hará fallar el pipeline.", fg="yellow", bold=True)
+                       if color else "DRY-RUN: el resultado no hará fallar el pipeline.", err=True)
+
+        info(f"pdgseg {__version__} -> {config.server}")
+        client = ApiClient(config.server, token, log=debug)
+        outcome = run_analysis(client, config, path, want_sarif=output_format == "sarif", progress=Progress(info))
+    except PdgsegError as e:
+        fail(str(e))
+        return
+    except KeyboardInterrupt:
+        fail("Interrumpido.")
+        return
+    except Exception as e:  # noqa: BLE001 - any bug must still end in exit code 10, not a traceback
+        if verbose:
+            traceback.print_exc()
+        fail(f"Error inesperado: {e}")
+        return
+
+    summary = summarize(outcome.results)
+    real_code = exit_code_for(summary, config.fail_on_severity)
+    code = EXIT_OK if dry_run else real_code
+
+    sarif_path = None
+    if output_format == "sarif":
+        sarif_path = output_path or Path(DEFAULT_SARIF_PATH)
+        try:
+            sarif_path.parent.mkdir(parents=True, exist_ok=True)
+            sarif_path.write_bytes(outcome.sarif or b"")
+        except OSError as e:
+            fail(f"No se pudo escribir {sarif_path}: {e}")
+        info(f"SARIF escrito en {sarif_path}")
+
+    if output_format == "json":
+        document = to_json(outcome, summary, exit_code=code, real_exit_code=real_code,
+                           fail_on_severity=config.fail_on_severity, dry_run=dry_run)
+        if output_path:
+            try:
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                output_path.write_text(document + "\n", encoding="utf-8")
+            except OSError as e:
+                fail(f"No se pudo escribir {output_path}: {e}")
+            info(f"JSON escrito en {output_path}")
+        else:
+            click.echo(document)
+    else:
+        click.echo(render_text(outcome, summary, exit_code=code, real_exit_code=real_code,
+                               fail_on_severity=config.fail_on_severity, dry_run=dry_run,
+                               server=config.server, color=color))
+    sys.exit(code)
+
+
+@main.command("init")
+@click.option("--path", "path", type=click.Path(file_okay=False, path_type=Path), default=".", show_default=True)
+def init(path: Path) -> None:
+    """Crea un .pdgseg.yml de ejemplo (no sobrescribe uno existente)."""
+    target = path / CONFIG_FILE_NAME
+    if target.exists():
+        click.echo(f"{target} ya existe; no se modificó.", err=True)
+        sys.exit(EXIT_ERROR)
+    target.write_text(example_config(), encoding="utf-8")
+    click.echo(f"Creado {target}. Ajusta «server» y «policySet».")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pdgseg/client.py

@@ -0,0 +1,158 @@
+"""Cliente HTTP del backend de SegSoft: TLS verificado y reintentos con backoff exponencial."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Sequence, Tuple
+
+import requests
+
+from . import __version__
+from .errors import ApiError
+
+RETRY_DELAYS: Tuple[float, ...] = (1, 2, 4)
+# Gateways that answer while the backend restarts or is unreachable (Caddy, Vercel).
+RETRYABLE_STATUSES = {502, 503, 504}
+MAX_RETRY_AFTER_SECONDS = 60
+TIMEOUT = (10, 120)  # (connect, read) seconds; uploads of large ZIPs need the long read
+
+
+class ApiClient:
+    """
+    Envuelve requests.Session. Reintenta, con esperas de 1s, 2s y 4s:
+      - fallos de conexión (DNS, conexión rechazada o cortada) en cualquier método: la petición no llegó;
+      - timeouts de lectura y respuestas 502/503/504 solo en peticiones idempotentes (GET, DELETE),
+        para no duplicar una subida o un análisis que el servidor sí recibió;
+      - 429, en cualquier método, esperando lo que indique Retry-After (máximo 60s).
+    TLS siempre se verifica (requests usa certifi, o REQUESTS_CA_BUNDLE si está definida).
+    """
+
+    def __init__(self, base_url: str, token: str, *, retry_delays: Sequence[float] = RETRY_DELAYS,
+                 sleep: Optional[Callable[[float], None]] = None, log: Optional[Callable[[str], None]] = None,
+                 session: Optional[requests.Session] = None, timeout: Tuple[float, float] = TIMEOUT):
+        self.base_url = base_url.rstrip("/")
+        self._retry_delays = tuple(retry_delays)
+        self._sleep = sleep or (lambda seconds: time.sleep(seconds))
+        self._log = log or (lambda _msg: None)
+        self._timeout = timeout
+        self._session = session or requests.Session()
+        self._session.verify = True
+        self._session.headers.update({
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+            "User-Agent": f"pdgseg-cli/{__version__}",
+        })
+
+    # ---- public API ------------------------------------------------------------------------
+
+    def get_json(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self._request("GET", path, params=params).json()
+
+    def get_bytes(self, path: str) -> bytes:
+        return self._request("GET", path, accept="application/sarif+json, application/json").content
+
+    def post_json(self, path: str, body: Any) -> Any:
+        response = self._request("POST", path, json=body)
+        return response.json() if response.content else None
+
+    def upload(self, path: str, file_path: Path, field: str = "file") -> Any:
+        def files() -> Dict[str, Any]:
+            return {field: (file_path.name, file_path.open("rb"), "application/zip")}
+        return self._request("POST", path, files_factory=files).json()
+
+    def delete(self, path: str) -> None:
+        self._request("DELETE", path)
+
+    # ---- internals -------------------------------------------------------------------------
+
+    def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                 json: Any = None, files_factory: Optional[Callable[[], Dict[str, Any]]] = None,
+                 accept: Optional[str] = None) -> requests.Response:
+        url = self.base_url + path
+        idempotent = method in ("GET", "HEAD", "DELETE", "PUT")
+        headers = {"Accept": accept} if accept else None
+        attempts = len(self._retry_delays) + 1
+
+        for attempt in range(1, attempts + 1):
+            files = files_factory() if files_factory else None
+            try:
+                self._log(f"{method} {url}" + (f" (intento {attempt}/{attempts})" if attempt > 1 else ""))
+                response = self._session.request(method, url, params=params, json=json, files=files,
+                                                 headers=headers, timeout=self._timeout)
+            except requests.exceptions.SSLError as e:
+                # A certificate problem does not fix itself by retrying.
+                raise ApiError(f"No se pudo establecer una conexión segura con {self.base_url}: el certificado "
+                               f"TLS no es válido ({_short(e)}).") from e
+            except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as e:
+                # ConnectTimeout is a ConnectionError (nothing was sent); ReadTimeout is not (it may have been).
+                never_reached_server = (isinstance(e, requests.exceptions.ConnectionError)
+                                        and not isinstance(e, requests.exceptions.ReadTimeout))
+                retryable = never_reached_server or idempotent
+                if retryable and attempt < attempts:
+                    self._wait(attempt, f"fallo de conexión ({_short(e)})")
+                    continue
+                raise ApiError(f"No se pudo conectar con {self.base_url} ({method} {path}) después de "
+                               f"{attempt} intento(s): {_short(e)}") from e
+            finally:
+                if files:
+                    for value in files.values():
+                        handle = value[1] if isinstance(value, tuple) else value
+                        if hasattr(handle, "close"):
+                            handle.close()
+
+            self._log(f"  -> {response.status_code}")
+            if response.status_code == 429 and attempt < attempts:
+                self._sleep(_retry_after(response))
+                continue
+            if response.status_code in RETRYABLE_STATUSES and idempotent and attempt < attempts:
+                self._wait(attempt, f"el servidor respondió {response.status_code}")
+                continue
+            if response.ok:
+                return response
+            raise _error_for(response, method, path)
+
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    def _wait(self, attempt: int, reason: str) -> None:
+        delay = self._retry_delays[attempt - 1]
+        self._log(f"  {reason}; reintentando en {delay:g}s")
+        self._sleep(delay)
+
+
+def _error_for(response: requests.Response, method: str, path: str) -> ApiError:
+    status = response.status_code
+    message = _server_message(response)
+    if status == 401:
+        return ApiError("El backend rechazó el token (401)" + (f": {message}" if message else "") +
+                        ". Revisa PDGSEG_API_TOKEN: debe ser un token de API vigente (pdgseg_...).", status)
+    if status == 403:
+        return ApiError("Sin permiso para esta operación (403)" + (f": {message}" if message else "."), status)
+    if status == 423:
+        return ApiError("La cuenta dueña del token está bloqueada (423)" + (f": {message}" if message else "."),
+                        status)
+    detail = f": {message}" if message else ""
+    return ApiError(f"{method} {path} respondió {status}{detail}", status)
+
+
+def _server_message(response: requests.Response) -> Optional[str]:
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    if isinstance(body, dict):
+        message = body.get("message") or body.get("error")
+        return str(message) if message else None
+    return None
+
+
+def _retry_after(response: requests.Response) -> float:
+    try:
+        return min(max(float(response.headers.get("Retry-After", "1")), 1), MAX_RETRY_AFTER_SECONDS)
+    except ValueError:
+        return 1
+
+
+def _short(error: Exception) -> str:
+    text = str(error)
+    return text if len(text) <= 200 else text[:200] + "..."

pdgseg/config.py

@@ -0,0 +1,195 @@
+"""Lectura y validación de .pdgseg.yml (schemaVersion 1)."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+from urllib.parse import urlparse
+
+import yaml
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError
+
+from .errors import ConfigError
+
+CONFIG_FILE_NAME = ".pdgseg.yml"
+SERVER_ENV = "PDGSEG_SERVER_URL"
+SEVERITY_THRESHOLDS = ("medium", "high", "critical")
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def load_schema() -> Dict[str, Any]:
+    text = files("pdgseg").joinpath("schema/pdgseg.schema.v1.json").read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+@dataclass(frozen=True)
+class PolicySource:
+    """Exactamente una de las tres formas de elegir las políticas."""
+
+    policy_set: Optional[str] = None
+    policies: Tuple[str, ...] = ()
+    framework: Optional[str] = None
+
+    def describe(self) -> str:
+        if self.policy_set:
+            return f"Policy Set «{self.policy_set}»"
+        if self.framework:
+            return f"framework {self.framework}"
+        return f"{len(self.policies)} políticas"
+
+
+@dataclass(frozen=True)
+class Config:
+    server: str
+    policy_source: PolicySource
+    fail_on_severity: str = "high"
+    exclude: Tuple[str, ...] = ()
+    timeout_minutes: int = 15
+    poll_interval_seconds: int = 5
+    path: Optional[Path] = field(default=None, compare=False)
+
+
+def load_config(path: Path, server_override: Optional[str] = None,
+                env: Optional[Mapping[str, str]] = None) -> Config:
+    """Lee, valida y construye la configuración. Cualquier problema es un ConfigError (exit code 10)."""
+    env = os.environ if env is None else env
+    if not path.is_file():
+        raise ConfigError(
+            f"No se encontró {path}. Crea un {CONFIG_FILE_NAME} en la raíz del repositorio "
+            f"(por ejemplo con «schemaVersion: 1», «server» y «policySet») o indica otro con --config.")
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as e:
+        raise ConfigError(f"{path} no es YAML válido: {e}") from e
+    except (OSError, UnicodeDecodeError) as e:
+        raise ConfigError(f"No se pudo leer {path}: {e}") from e
+
+    if raw is None:
+        raise ConfigError(f"{path} está vacío.")
+    return parse_config(raw, path=path, server_override=server_override or env.get(SERVER_ENV))
+
+
+def parse_config(raw: Any, path: Optional[Path] = None, server_override: Optional[str] = None) -> Config:
+    where = str(path) if path else CONFIG_FILE_NAME
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{where} debe ser un objeto YAML (clave: valor), no {_type_name(raw)}.")
+
+    errors = sorted(Draft202012Validator(load_schema()).iter_errors(raw), key=lambda e: list(e.absolute_path))
+    if errors:
+        details = "\n".join(f"  - {_describe(e)}" for e in errors)
+        raise ConfigError(f"{where} no es válido:\n{details}")
+
+    sources = [k for k in ("policySet", "policies", "framework") if k in raw]
+    if len(sources) != 1:
+        found = ", ".join(sources) if sources else "ninguna"
+        raise ConfigError(
+            f"{where} no es válido:\n  - indica exactamente una forma de elegir las políticas: "
+            f"policySet, policies o framework (encontradas: {found}).")
+
+    server = (server_override or raw.get("server") or "").strip()
+    if not server:
+        raise ConfigError(
+            f"{where} no es válido:\n  - falta «server» (la URL del backend de SegSoft); "
+            f"también se puede dar con la variable {SERVER_ENV} o con --server.")
+    _require_secure_server(server, where)
+
+    return Config(
+        server=server.rstrip("/"),
+        policy_source=PolicySource(
+            policy_set=raw.get("policySet"),
+            policies=tuple(raw.get("policies", ())),
+            framework=raw.get("framework"),
+        ),
+        fail_on_severity=raw.get("failOnSeverity", "high"),
+        exclude=tuple(raw.get("exclude", ())),
+        timeout_minutes=raw.get("timeoutMinutes", 15),
+        poll_interval_seconds=raw.get("pollIntervalSeconds", 5),
+        path=path,
+    )
+
+
+def _require_secure_server(server: str, where: str) -> None:
+    parsed = urlparse(server)
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        raise ConfigError(f"{where} no es válido:\n  - server: «{server}» no es una URL http(s).")
+    if parsed.scheme == "http" and parsed.hostname not in _LOCAL_HOSTS:
+        raise ConfigError(
+            f"{where} no es válido:\n  - server: usa https. El token viaja en cada petición; "
+            f"http solo se acepta para localhost.")
+
+
+def _describe(error: ValidationError) -> str:
+    """Un error del schema en una línea, nombrando el campo."""
+    location = ".".join(str(p) for p in error.absolute_path) or "(raíz)"
+    v = error.validator
+    if v == "required":
+        missing = error.message.split("'")[1] if "'" in error.message else error.message
+        return f"falta el campo obligatorio «{missing}»"
+    if v == "additionalProperties":
+        extra = sorted(set(error.instance) - set(error.schema.get("properties", {})))
+        allowed = ", ".join(error.schema.get("properties", {}))
+        return f"campo desconocido «{', '.join(extra)}»; los permitidos son: {allowed}"
+    if v == "const":
+        return f"{location}: debe ser {error.validator_value!r} (se encontró {error.instance!r})"
+    if v == "enum":
+        options = ", ".join(str(o) for o in error.validator_value)
+        return f"{location}: «{error.instance}» no es válido; usa uno de: {options}"
+    if v == "type":
+        return f"{location}: debe ser {_schema_type(error.validator_value)}, no {_type_name(error.instance)}"
+    if v in ("minimum", "maximum"):
+        word = "al menos" if v == "minimum" else "como máximo"
+        return f"{location}: debe ser {word} {error.validator_value} (se encontró {error.instance})"
+    if v == "pattern":
+        if location == "server":
+            return f"server: «{error.instance}» no es una URL http(s)"
+        return f"{location}: «{error.instance}» no es un id válido (UUID)"
+    if v == "minItems":
+        return f"{location}: no puede estar vacío"
+    if v == "minLength":
+        return f"{location}: no puede estar vacío"
+    if v == "uniqueItems":
+        return f"{location}: tiene elementos repetidos"
+    return f"{location}: {error.message}"
+
+
+_TYPE_NAMES = {"string": "un texto", "integer": "un número entero", "array": "una lista",
+               "object": "un objeto", "boolean": "true o false", "number": "un número"}
+
+
+def _schema_type(t: Any) -> str:
+    return _TYPE_NAMES.get(t, str(t)) if isinstance(t, str) else " o ".join(_TYPE_NAMES.get(x, x) for x in t)
+
+
+def _type_name(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true/false"
+    if isinstance(value, int):
+        return "un número"
+    if isinstance(value, float):
+        return "un número decimal"
+    if isinstance(value, str):
+        return "un texto"
+    if isinstance(value, list):
+        return "una lista"
+    if isinstance(value, dict):
+        return "un objeto"
+    return "nada" if value is None else type(value).__name__
+
+
+def example_config() -> str:
+    return (
+        "schemaVersion: 1\n"
+        "server: https://segsoft-icesi.westus3.cloudapp.azure.com\n"
+        "policySet: \"Perfil PDG ICESI\"\n"
+        "failOnSeverity: high\n"
+        "exclude: [\"node_modules/\", \"dist/\"]\n"
+    )
+
+
+__all__: List[str] = ["Config", "PolicySource", "load_config", "parse_config", "CONFIG_FILE_NAME",
+                      "SERVER_ENV", "SEVERITY_THRESHOLDS", "example_config"]

pdgseg/errors.py

@@ -0,0 +1,21 @@
+"""Errores técnicos: todos terminan el CLI con exit code 10."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class PdgsegError(Exception):
+    """Un error técnico con un mensaje para mostrar tal cual al usuario."""
+
+
+class ConfigError(PdgsegError):
+    """.pdgseg.yml no existe, no es YAML válido o no cumple el schema."""
+
+
+class ApiError(PdgsegError):
+    """El backend respondió con un error, o no se pudo conectar con él."""
+
+    def __init__(self, message: str, status: Optional[int] = None):
+        super().__init__(message)
+        self.status = status