pdgseg-cli 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pdgseg/flow.py ADDED
@@ -0,0 +1,160 @@
1
+ """El flujo de «pdgseg analyze» contra la API del backend."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ import tempfile
7
+ import time
8
+ from dataclasses import dataclass
9
+ from pathlib import Path
10
+ from typing import Any, Callable, Dict, List, Optional, Tuple
11
+
12
+ from .client import ApiClient
13
+ from .config import Config, PolicySource
14
+ from .errors import ApiError, PdgsegError
15
+ from .packager import Package, build_zip
16
+
17
+ _UUID = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
18
+ TERMINAL_STATUSES = {"COMPLETED", "FAILED", "CANCELLED"}
19
+
20
+
21
+ @dataclass
22
+ class Outcome:
23
+ repository_id: str
24
+ analysis_id: str
25
+ package: Package
26
+ results: Dict[str, Any]
27
+ sarif: Optional[bytes] = None
28
+
29
+
30
+ class Progress:
31
+ """Mensajes de avance (a stderr, salvo --quiet). Separado para poder silenciarlo en tests."""
32
+
33
+ def __init__(self, emit: Callable[[str], None] = lambda _m: None):
34
+ self.emit = emit
35
+
36
+ def __call__(self, message: str) -> None:
37
+ self.emit(message)
38
+
39
+
40
+ def run_analysis(client: ApiClient, config: Config, root: Path, *, want_sarif: bool = False,
41
+ progress: Optional[Progress] = None, sleep: Optional[Callable[[float], None]] = None,
42
+ monotonic: Optional[Callable[[], float]] = None) -> Outcome:
43
+ progress = progress or Progress()
44
+ sleep = sleep or (lambda seconds: time.sleep(seconds))
45
+ monotonic = monotonic or (lambda: time.monotonic())
46
+
47
+ # Resolve the policies first: a typo in .pdgseg.yml should fail before uploading anything.
48
+ selection = resolve_policies(client, config.policy_source)
49
+ progress(f"Políticas: {config.policy_source.describe()}")
50
+
51
+ with tempfile.TemporaryDirectory(prefix="pdgseg-") as tmp:
52
+ package = build_zip(root, Path(tmp) / f"{root.resolve().name or 'repo'}.zip", config.exclude)
53
+ progress(f"Comprimidos {package.file_count} archivos ({package.size_bytes / 1024 / 1024:.1f} MB); subiendo...")
54
+ repository = client.upload("/api/v1/repositories", package.path)
55
+
56
+ repository_id = str(repository["id"])
57
+ if repository.get("status") != "READY_FOR_ANALYSIS":
58
+ reason = repository.get("errorMessage") or repository.get("status")
59
+ raise PdgsegError(f"El backend no pudo preparar el proyecto subido: {reason}")
60
+ progress(f"Repositorio {repository_id} listo ({repository.get('fileCount', package.file_count)} archivos).")
61
+
62
+ kind, value = selection
63
+ if kind == "set":
64
+ client.post_json(f"/api/v1/repositories/{repository_id}/policy-selection/apply-set", {"policySetId": value})
65
+ else:
66
+ client.post_json(f"/api/v1/repositories/{repository_id}/policy-selection", {"policyIds": value})
67
+
68
+ analysis = client.post_json("/api/v1/analyses", {"repositoryId": repository_id})
69
+ analysis_id = str(analysis["id"])
70
+ progress(f"Análisis {analysis_id} iniciado.")
71
+
72
+ analysis = _wait_until_done(client, analysis_id, config, progress, sleep, monotonic)
73
+ if analysis["status"] == "FAILED":
74
+ raise PdgsegError(f"El análisis {analysis_id} falló: {analysis.get('errorMessage') or 'sin detalle'}")
75
+ if analysis["status"] == "CANCELLED":
76
+ raise PdgsegError(f"El análisis {analysis_id} fue cancelado.")
77
+
78
+ results = client.get_json(f"/api/v1/analyses/{analysis_id}/results")
79
+ sarif = client.get_bytes(f"/api/v1/analyses/{analysis_id}/sarif") if want_sarif else None
80
+ return Outcome(repository_id=repository_id, analysis_id=analysis_id, package=package,
81
+ results=results, sarif=sarif)
82
+
83
+
84
+ def resolve_policies(client: ApiClient, source: PolicySource) -> Tuple[str, Any]:
85
+ """("set", policySetId) o ("policies", [policyId, ...])."""
86
+ if source.policy_set:
87
+ return "set", _resolve_policy_set(client, source.policy_set)
88
+ if source.framework:
89
+ return "policies", _framework_policies(client, source.framework)
90
+ return "policies", list(source.policies)
91
+
92
+
93
+ def _resolve_policy_set(client: ApiClient, name_or_id: str) -> str:
94
+ if _UUID.match(name_or_id):
95
+ try:
96
+ found = client.get_json(f"/api/v1/policy-sets/{name_or_id}")
97
+ except ApiError as e:
98
+ if e.status == 404:
99
+ raise PdgsegError(f"No existe un Policy Set con id {name_or_id}.") from e
100
+ raise
101
+ if found.get("status") not in (None, "ACTIVE"):
102
+ raise PdgsegError(f"El Policy Set {name_or_id} está {found.get('status')}; usa uno activo.")
103
+ return name_or_id
104
+
105
+ page = client.get_json("/api/v1/policy-sets", params={"search": name_or_id, "size": 100})
106
+ candidates: List[Dict[str, Any]] = page.get("content") or []
107
+ exact = [c for c in candidates if str(c.get("name", "")).strip().lower() == name_or_id.strip().lower()]
108
+ if len(exact) == 1:
109
+ return str(exact[0]["id"])
110
+ if len(exact) > 1:
111
+ raise PdgsegError(f"Hay {len(exact)} Policy Sets activos llamados «{name_or_id}»; usa su id en policySet.")
112
+ similar = ", ".join(f"«{c.get('name')}»" for c in candidates[:5])
113
+ hint = f" Parecidos: {similar}." if similar else ""
114
+ raise PdgsegError(f"No hay un Policy Set activo llamado «{name_or_id}».{hint}")
115
+
116
+
117
+ def _framework_policies(client: ApiClient, framework: str) -> List[str]:
118
+ ids: List[str] = []
119
+ page_number = 0
120
+ while True:
121
+ page = client.get_json("/api/v1/policies", params={
122
+ "framework": framework, "status": "ACTIVE", "page": page_number, "size": 100})
123
+ ids.extend(str(p["id"]) for p in page.get("content") or [])
124
+ if page.get("last", True) or page_number + 1 >= int(page.get("totalPages") or 0):
125
+ break
126
+ page_number += 1
127
+ if not ids:
128
+ raise PdgsegError(f"No hay políticas activas del framework {framework}.")
129
+ return ids
130
+
131
+
132
+ def _wait_until_done(client: ApiClient, analysis_id: str, config: Config, progress: Progress,
133
+ sleep: Callable[[float], None], monotonic: Callable[[], float]) -> Dict[str, Any]:
134
+ deadline = monotonic() + config.timeout_minutes * 60
135
+ last_line = None
136
+ while True:
137
+ analysis = client.get_json(f"/api/v1/analyses/{analysis_id}")
138
+ status = analysis.get("status")
139
+ line = _progress_line(analysis)
140
+ if line != last_line:
141
+ progress(line)
142
+ last_line = line
143
+ if status in TERMINAL_STATUSES:
144
+ return analysis
145
+ if monotonic() >= deadline:
146
+ try:
147
+ client.delete(f"/api/v1/analyses/{analysis_id}")
148
+ except ApiError:
149
+ pass # the timeout is what matters; a failed cancel just leaves it running
150
+ raise PdgsegError(f"El análisis {analysis_id} no terminó en {config.timeout_minutes} minutos "
151
+ f"(timeoutMinutes en .pdgseg.yml); se pidió cancelarlo.")
152
+ sleep(config.poll_interval_seconds)
153
+
154
+
155
+ def _progress_line(analysis: Dict[str, Any]) -> str:
156
+ status = analysis.get("status")
157
+ executed, total = analysis.get("rulesExecuted"), analysis.get("rulesTotal")
158
+ if status == "RUNNING" and total:
159
+ return f" {status}: {executed or 0}/{total} reglas"
160
+ return f" {status}"
pdgseg/output.py ADDED
@@ -0,0 +1,115 @@
1
+ """Salida del CLI: resumen en texto para personas y JSON para scripts."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import Any, Dict, List, Optional
7
+
8
+ import click
9
+
10
+ from .flow import Outcome
11
+ from .summary import EXIT_CRITICAL, EXIT_FINDINGS, EXIT_OK, SEVERITIES, Summary
12
+
13
+ SEVERITY_COLORS = {"CRITICAL": "red", "HIGH": "red", "MEDIUM": "yellow", "LOW": "blue"}
14
+ STATUS_LABELS = {"COMPLIANT": "cumple", "NON_COMPLIANT": "no cumple", "REQUIRES_REVIEW": "requiere revisión"}
15
+ MAX_FINDINGS_LISTED = 20
16
+
17
+
18
+ def render_text(outcome: Outcome, summary: Summary, *, exit_code: int, real_exit_code: int,
19
+ fail_on_severity: str, dry_run: bool, server: str, color: bool) -> str:
20
+ def style(text: str, **kw: Any) -> str:
21
+ return click.style(text, **kw) if color else text
22
+
23
+ lines: List[str] = ["", style("Resultado del análisis de SegSoft", bold=True)]
24
+ lines.append(f" Análisis: {outcome.analysis_id}")
25
+ if summary.compliance_percentage is not None:
26
+ lines.append(f" Cumplimiento: {summary.compliance_percentage:.1f}%"
27
+ + (f" (ponderado {summary.weighted_compliance_percentage:.1f}%)"
28
+ if summary.weighted_compliance_percentage is not None else ""))
29
+ lines.append(f" Hallazgos: {summary.total_findings}")
30
+
31
+ lines += ["", style("Hallazgos por severidad", bold=True)]
32
+ for severity in SEVERITIES:
33
+ count = summary.by_severity.get(severity, 0)
34
+ label = f" {severity:<9}{count:>5}"
35
+ lines.append(style(label, fg=SEVERITY_COLORS[severity]) if count else label)
36
+
37
+ if summary.by_category:
38
+ lines += ["", style("Hallazgos por categoría", bold=True)]
39
+ lines += [f" {category:<28}{count:>5}" for category, count in summary.by_category.items()]
40
+
41
+ if summary.policies:
42
+ lines += ["", style("Políticas", bold=True)]
43
+ for status in ("NON_COMPLIANT", "REQUIRES_REVIEW", "COMPLIANT"):
44
+ group = summary.policies_with(status)
45
+ if group:
46
+ lines.append(f" {STATUS_LABELS[status]}: {len(group)}")
47
+ if status != "COMPLIANT":
48
+ lines += [f" - {p.name} ({p.findings} hallazgos)" for p in group]
49
+
50
+ if summary.findings:
51
+ lines += ["", style("Hallazgos", bold=True)]
52
+ for f in summary.findings[:MAX_FINDINGS_LISTED]:
53
+ location = f.get("filePath") or "?"
54
+ if f.get("lineNumber"):
55
+ location += f":{f['lineNumber']}"
56
+ severity = str(f.get("severity"))
57
+ lines.append(f" {style(f'[{severity}]', fg=SEVERITY_COLORS.get(severity))} {location} "
58
+ f"- {f.get('policyName') or f.get('category')}")
59
+ if len(summary.findings) > MAX_FINDINGS_LISTED:
60
+ lines.append(f" ... y {len(summary.findings) - MAX_FINDINGS_LISTED} más. "
61
+ f"Detalle completo en {server.rstrip('/')}, sección Análisis.")
62
+
63
+ if summary.rule_execution_errors:
64
+ lines += ["", style(f"Aviso: {summary.rule_execution_errors} regla(s) no se pudieron ejecutar; "
65
+ f"el resultado puede estar incompleto.", fg="yellow")]
66
+
67
+ lines += ["", _verdict(real_exit_code, fail_on_severity, style)]
68
+ if dry_run and real_exit_code != EXIT_OK:
69
+ lines.append(style(f"DRY-RUN: el código de salida real sería {real_exit_code}; se devuelve {exit_code}.",
70
+ fg="yellow", bold=True))
71
+ return "\n".join(lines)
72
+
73
+
74
+ def _verdict(code: int, threshold: str, style: Any) -> str:
75
+ if code == EXIT_OK:
76
+ return style(f"OK: no hay hallazgos de severidad {threshold} o superior (exit code 0).", fg="green", bold=True)
77
+ if code == EXIT_CRITICAL:
78
+ return style("FALLA: hay hallazgos CRITICAL (exit code 2).", fg="red", bold=True)
79
+ if code == EXIT_FINDINGS:
80
+ return style(f"FALLA: hay hallazgos de severidad {threshold} o superior (exit code 1).", fg="red", bold=True)
81
+ return style(f"exit code {code}", bold=True)
82
+
83
+
84
+ def to_json(outcome: Outcome, summary: Summary, *, exit_code: int, real_exit_code: int,
85
+ fail_on_severity: str, dry_run: bool, sarif_path: Optional[str] = None) -> str:
86
+ document: Dict[str, Any] = {
87
+ "analysisId": outcome.analysis_id,
88
+ "repositoryId": outcome.repository_id,
89
+ "status": summary.analysis_status,
90
+ "compliancePercentage": summary.compliance_percentage,
91
+ "weightedCompliancePercentage": summary.weighted_compliance_percentage,
92
+ "totalFindings": summary.total_findings,
93
+ "findingsBySeverity": summary.by_severity,
94
+ "findingsByCategory": summary.by_category,
95
+ "policies": [{"name": p.name, "status": p.status, "findings": p.findings} for p in summary.policies],
96
+ "ruleExecutionErrors": summary.rule_execution_errors,
97
+ "failOnSeverity": fail_on_severity,
98
+ "dryRun": dry_run,
99
+ "exitCode": exit_code,
100
+ "findings": [_finding(f) for f in summary.findings],
101
+ }
102
+ if dry_run:
103
+ document["wouldExitWith"] = real_exit_code
104
+ if sarif_path:
105
+ document["sarifPath"] = sarif_path
106
+ return json.dumps(document, ensure_ascii=False, indent=2)
107
+
108
+
109
+ def error_json(message: str, exit_code: int) -> str:
110
+ return json.dumps({"error": message, "exitCode": exit_code}, ensure_ascii=False, indent=2)
111
+
112
+
113
+ def _finding(f: Any) -> Dict[str, Any]:
114
+ keys = ("severity", "category", "policyName", "filePath", "lineNumber", "cweId", "suggestedAction")
115
+ return {k: f.get(k) for k in keys}
pdgseg/packager.py ADDED
@@ -0,0 +1,141 @@
1
+ """Comprime el directorio a analizar en un ZIP, respetando las exclusiones."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import re
7
+ import zipfile
8
+ from dataclasses import dataclass
9
+ from functools import lru_cache
10
+ from pathlib import Path
11
+ from typing import Iterable, Iterator, List, Optional, Sequence, Tuple
12
+
13
+ from .errors import PdgsegError
14
+
15
+ MAX_ZIP_BYTES = 100 * 1024 * 1024 # spring.servlet.multipart.max-file-size of the backend
16
+
17
+ # Never worth uploading: VCS data, dependencies, virtualenvs, caches and IDE settings.
18
+ DEFAULT_EXCLUDES: Tuple[str, ...] = (
19
+ ".git/", ".hg/", ".svn/",
20
+ "node_modules/", ".venv/", "venv/", "__pycache__/", ".pytest_cache/", ".mypy_cache/", ".tox/",
21
+ ".idea/", ".vscode/", ".DS_Store",
22
+ )
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class Package:
27
+ path: Path
28
+ file_count: int
29
+ size_bytes: int
30
+
31
+
32
+ def build_zip(root: Path, dest: Path, excludes: Sequence[str] = (),
33
+ max_bytes: int = MAX_ZIP_BYTES) -> Package:
34
+ """
35
+ Comprime los archivos de root (rutas relativas a root, con «/») en dest.
36
+ No sigue enlaces simbólicos: un enlace podría sacar archivos de fuera del repositorio.
37
+ """
38
+ root = root.resolve()
39
+ if not root.is_dir():
40
+ raise PdgsegError(f"{root} no es un directorio.")
41
+ patterns = list(DEFAULT_EXCLUDES) + [p for p in excludes if p.strip()]
42
+ dest_resolved = dest.resolve()
43
+
44
+ count = 0
45
+ with zipfile.ZipFile(dest, "w", compression=zipfile.ZIP_DEFLATED) as zf:
46
+ for file_path, rel in _walk(root, patterns):
47
+ if file_path.resolve() == dest_resolved:
48
+ continue
49
+ zf.write(file_path, rel)
50
+ count += 1
51
+
52
+ size = dest.stat().st_size
53
+ if count == 0:
54
+ raise PdgsegError(f"No hay archivos que analizar en {root} (¿las exclusiones lo cubren todo?).")
55
+ if size > max_bytes:
56
+ raise PdgsegError(
57
+ f"El ZIP del proyecto pesa {size / 1024 / 1024:.1f} MB y el máximo es {max_bytes // 1024 // 1024} MB. "
58
+ f"Agrega a «exclude» en .pdgseg.yml las carpetas que no son código fuente (builds, datos, binarios).")
59
+ return Package(path=dest, file_count=count, size_bytes=size)
60
+
61
+
62
+ def _walk(root: Path, patterns: List[str]) -> Iterator[Tuple[Path, str]]:
63
+ for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
64
+ current = Path(dirpath)
65
+ rel_dir = current.relative_to(root).as_posix()
66
+ rel_dir = "" if rel_dir == "." else rel_dir
67
+
68
+ kept = []
69
+ for name in sorted(dirnames):
70
+ rel = f"{rel_dir}/{name}" if rel_dir else name
71
+ if (current / name).is_symlink() or is_excluded(rel, True, patterns):
72
+ continue
73
+ kept.append(name)
74
+ dirnames[:] = kept # prune in place so os.walk does not descend
75
+
76
+ for name in sorted(filenames):
77
+ full = current / name
78
+ rel = f"{rel_dir}/{name}" if rel_dir else name
79
+ if full.is_symlink() or is_excluded(rel, False, patterns):
80
+ continue
81
+ yield full, rel
82
+
83
+
84
+ def is_excluded(rel_path: str, is_dir: bool, patterns: Iterable[str]) -> bool:
85
+ """
86
+ Subconjunto de .gitignore (sin negaciones):
87
+ - «*.min.js», «build»: sin «/», se compara con el nombre, en cualquier nivel;
88
+ - «dist/»: solo carpetas; «docs/**»: todo lo que hay dentro de docs;
89
+ - «src/gen/*.py», «/config»: con «/» (al inicio o en medio), se compara desde la raíz;
90
+ - «*» no cruza carpetas, «**» sí, «?» es un carácter.
91
+ Excluir una carpeta excluye todo lo que contiene.
92
+ """
93
+ parts = rel_path.split("/")
94
+ # The path itself and each of its parent folders: (path from the root, name, is a folder).
95
+ candidates = [("/".join(parts[:i]), parts[i - 1], i < len(parts) or is_dir) for i in range(1, len(parts) + 1)]
96
+ for raw in patterns:
97
+ rule = _compile(raw)
98
+ if rule is None:
99
+ continue
100
+ regex, anchored, dir_only = rule
101
+ for sub, name, is_folder in candidates:
102
+ if dir_only and not is_folder:
103
+ continue
104
+ if regex.fullmatch(sub if anchored else name):
105
+ return True
106
+ return False
107
+
108
+
109
+ @lru_cache(maxsize=256)
110
+ def _compile(raw: str) -> Optional[Tuple["re.Pattern[str]", bool, bool]]:
111
+ pattern = raw.strip()
112
+ dir_only = pattern.endswith("/")
113
+ pattern = pattern.rstrip("/")
114
+ anchored = "/" in pattern # decided before dropping "/**": "docs/**" is anchored, "dist/" is not
115
+ if pattern.endswith("/**"):
116
+ pattern, dir_only = pattern[:-3], True
117
+ pattern = pattern.lstrip("/")
118
+ if not pattern:
119
+ return None
120
+ return re.compile(_glob_to_regex(pattern)), anchored, dir_only
121
+
122
+
123
+ def _glob_to_regex(glob: str) -> str:
124
+ out, i = [], 0
125
+ while i < len(glob):
126
+ if glob.startswith("**/", i):
127
+ out.append("(?:.*/)?")
128
+ i += 3
129
+ elif glob.startswith("**", i):
130
+ out.append(".*")
131
+ i += 2
132
+ elif glob[i] == "*":
133
+ out.append("[^/]*")
134
+ i += 1
135
+ elif glob[i] == "?":
136
+ out.append("[^/]")
137
+ i += 1
138
+ else:
139
+ out.append(re.escape(glob[i]))
140
+ i += 1
141
+ return "".join(out)
@@ -0,0 +1,63 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://segsoft.website/schemas/pdgseg.schema.v1.json",
4
+ "title": ".pdgseg.yml (schemaVersion 1)",
5
+ "description": "Configuración del CLI pdgseg en la raíz del repositorio.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": ["schemaVersion"],
9
+ "properties": {
10
+ "schemaVersion": {
11
+ "description": "Versión del formato de este archivo.",
12
+ "const": 1
13
+ },
14
+ "server": {
15
+ "description": "URL base del backend de SegSoft. La variable PDGSEG_SERVER_URL o --server la reemplazan.",
16
+ "type": "string",
17
+ "pattern": "^https?://[^\\s/]+(/[^\\s]*)?$"
18
+ },
19
+ "policySet": {
20
+ "description": "Nombre o id del Policy Set a aplicar.",
21
+ "type": "string",
22
+ "minLength": 1
23
+ },
24
+ "policies": {
25
+ "description": "Ids de las políticas a aplicar.",
26
+ "type": "array",
27
+ "minItems": 1,
28
+ "uniqueItems": true,
29
+ "items": {
30
+ "type": "string",
31
+ "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
32
+ }
33
+ },
34
+ "framework": {
35
+ "description": "Aplica todas las políticas activas de un framework.",
36
+ "enum": ["OWASP_TOP_10_2021", "ISO_27001", "OWASP_ASVS", "NIST_SP_800_53", "DEVSECOPS", "CUSTOM"]
37
+ },
38
+ "failOnSeverity": {
39
+ "description": "Severidad mínima que hace fallar el pipeline (exit code 1, o 2 si hay CRITICAL).",
40
+ "enum": ["medium", "high", "critical"],
41
+ "default": "high"
42
+ },
43
+ "exclude": {
44
+ "description": "Patrones de archivos o carpetas que no se suben (estilo glob: 'dist/', '*.min.js', 'docs/**').",
45
+ "type": "array",
46
+ "items": { "type": "string", "minLength": 1 }
47
+ },
48
+ "timeoutMinutes": {
49
+ "description": "Tiempo máximo de espera del análisis.",
50
+ "type": "integer",
51
+ "minimum": 1,
52
+ "maximum": 120,
53
+ "default": 15
54
+ },
55
+ "pollIntervalSeconds": {
56
+ "description": "Cada cuánto se consulta el estado del análisis.",
57
+ "type": "integer",
58
+ "minimum": 2,
59
+ "maximum": 60,
60
+ "default": 5
61
+ }
62
+ }
63
+ }
pdgseg/summary.py ADDED
@@ -0,0 +1,90 @@
1
+ """Resumen de los resultados de un análisis y su código de salida."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections import Counter
6
+ from dataclasses import dataclass
7
+ from typing import Any, Dict, List, Mapping, Optional
8
+
9
+ SEVERITIES = ("CRITICAL", "HIGH", "MEDIUM", "LOW") # most severe first
10
+ _RANK = {"LOW": 1, "MEDIUM": 2, "HIGH": 3, "CRITICAL": 4}
11
+ _THRESHOLD_RANK = {"medium": 2, "high": 3, "critical": 4}
12
+
13
+ EXIT_OK = 0
14
+ EXIT_FINDINGS = 1
15
+ EXIT_CRITICAL = 2
16
+ EXIT_ERROR = 10
17
+
18
+
19
+ @dataclass(frozen=True)
20
+ class PolicyLine:
21
+ name: str
22
+ status: str
23
+ findings: int
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class Summary:
28
+ analysis_status: str
29
+ compliance_percentage: Optional[float]
30
+ weighted_compliance_percentage: Optional[float]
31
+ by_severity: Dict[str, int]
32
+ by_category: Dict[str, int]
33
+ policies: List[PolicyLine]
34
+ rule_execution_errors: int
35
+ findings: List[Mapping[str, Any]]
36
+
37
+ @property
38
+ def total_findings(self) -> int:
39
+ return sum(self.by_severity.values())
40
+
41
+ @property
42
+ def worst_severity(self) -> Optional[str]:
43
+ return next((s for s in SEVERITIES if self.by_severity.get(s)), None)
44
+
45
+ def policies_with(self, status: str) -> List[PolicyLine]:
46
+ return [p for p in self.policies if p.status == status]
47
+
48
+
49
+ def summarize(results: Mapping[str, Any]) -> Summary:
50
+ """results: la respuesta de GET /api/v1/analyses/{id}/results."""
51
+ findings = list(results.get("findings") or [])
52
+ severities = Counter(str(f.get("severity") or "LOW").upper() for f in findings)
53
+ categories = Counter(str(f.get("category") or "SIN_CATEGORIA") for f in findings)
54
+ policies = [
55
+ PolicyLine(name=p.get("policyName") or str(p.get("policyId")), status=p.get("status") or "?",
56
+ findings=int(p.get("findingsCount") or 0))
57
+ for p in results.get("policyResults") or []
58
+ ]
59
+ analysis = results.get("analysis") or {}
60
+ return Summary(
61
+ analysis_status=analysis.get("status", "COMPLETED"),
62
+ compliance_percentage=_number(results.get("compliancePercentage")),
63
+ weighted_compliance_percentage=_number(results.get("weightedCompliancePercentage")),
64
+ by_severity={s: severities.get(s, 0) for s in SEVERITIES},
65
+ by_category=dict(sorted(categories.items(), key=lambda kv: (-kv[1], kv[0]))),
66
+ policies=policies,
67
+ rule_execution_errors=len(results.get("ruleExecutionErrors") or []),
68
+ findings=sorted(findings, key=lambda f: (-_RANK.get(str(f.get("severity")).upper(), 0),
69
+ str(f.get("filePath")), f.get("lineNumber") or 0)),
70
+ )
71
+
72
+
73
+ def exit_code_for(summary: Summary, fail_on_severity: str = "high") -> int:
74
+ """
75
+ 0 sin hallazgos, o todos por debajo del umbral failOnSeverity;
76
+ 2 hay al menos un CRITICAL (y el umbral lo alcanza, cosa que pasa con cualquier umbral);
77
+ 1 hay hallazgos en el umbral o por encima, sin CRITICAL.
78
+ Con el umbral por defecto (high): LOW/MEDIUM -> 0, HIGH -> 1, CRITICAL -> 2.
79
+ """
80
+ worst = summary.worst_severity
81
+ if worst is None or _RANK[worst] < _THRESHOLD_RANK[fail_on_severity]:
82
+ return EXIT_OK
83
+ return EXIT_CRITICAL if worst == "CRITICAL" else EXIT_FINDINGS
84
+
85
+
86
+ def _number(value: Any) -> Optional[float]:
87
+ try:
88
+ return None if value is None else float(value)
89
+ except (TypeError, ValueError):
90
+ return None