auditagent-toolkit 0.2.0__py3-none-any.whl

auditagent_tools/result_coherence.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+import argparse
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_result_coherence(scan_result: str | Path, index_result: str | Path) -> dict:
+    """Compara rutas, tamaños, hashes y sumarios de dos resultados JSON."""
+    started = datetime.now(timezone.utc).isoformat()
+    scan_path = Path(scan_result).expanduser().resolve()
+    index_path = Path(index_result).expanduser().resolve()
+    scan = json.loads(scan_path.read_text(encoding="utf-8"))
+    index = json.loads(index_path.read_text(encoding="utf-8"))
+    scan_files = {
+        x["path"]: x for x in scan.get("entries", [])
+        if isinstance(x, dict) and x.get("kind") == "file" and isinstance(x.get("path"), str)
+    }
+    index_docs = {
+        x["path"]: x for x in index.get("documents", [])
+        if isinstance(x, dict) and isinstance(x.get("path"), str)
+    }
+    scan_paths, index_paths = set(scan_files), set(index_docs)
+    only_scan, only_index = sorted(scan_paths - index_paths), sorted(index_paths - scan_paths)
+    mismatches = []
+    for path in sorted(scan_paths & index_paths):
+        for field in ("size_bytes", "sha256"):
+            if scan_files[path].get(field) != index_docs[path].get(field):
+                mismatches.append({
+                    "path": path, "field": field,
+                    "scan": scan_files[path].get(field), "index": index_docs[path].get(field)
+                })
+    scan_bytes = sum(int(x.get("size_bytes", 0)) for x in scan_files.values())
+    index_bytes = sum(int(x.get("size_bytes", 0)) for x in index_docs.values())
+    token_sum = sum(int(x.get("token_count", 0)) for x in index_docs.values())
+    findings = []
+    if only_scan: findings.append({"severity": "MEDIUM", "title": "Solo en escaneo", "detail": ", ".join(only_scan)})
+    if only_index: findings.append({"severity": "HIGH", "title": "Solo en índice", "detail": ", ".join(only_index)})
+    if mismatches: findings.append({"severity": "HIGH", "title": "Hashes o tamaños divergentes", "detail": f"{len(mismatches)} diferencias."})
+    if scan.get("summary", {}).get("total_bytes") != scan_bytes:
+        findings.append({"severity": "MEDIUM", "title": "Resumen de bytes del escaneo inconsistente", "detail": f"declarado={scan.get('summary', {}).get('total_bytes')} recalculado={scan_bytes}"})
+    if index.get("summary", {}).get("tokens") != token_sum:
+        findings.append({"severity": "MEDIUM", "title": "Resumen de tokens inconsistente", "detail": f"declarado={index.get('summary', {}).get('tokens')} recalculado={token_sum}"})
+    return {
+        "schema_version": "1.0", "module": "result_coherence",
+        "status": "FAIL" if any(x["severity"] == "HIGH" for x in findings) else ("WARN" if findings else "PASS"),
+        "confidence": "high", "root": str(scan.get("root") or index.get("root") or ""),
+        "summary": {
+            "scan_files": len(scan_files), "index_documents": len(index_docs),
+            "only_scan": len(only_scan), "only_index": len(only_index),
+            "mismatches": len(mismatches), "scan_bytes_recalculated": scan_bytes,
+            "index_bytes_recalculated": index_bytes, "tokens_recalculated": token_sum
+        },
+        "findings": findings,
+        "evidence": [{"only_scan": only_scan, "only_index": only_index, "mismatches": mismatches}],
+        "limitations": ["No valida semántica de tokenización ni conformidad completa con JSON Schema."],
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Coherencia independiente entre escaneo e índice.")
+    p.add_argument("scan_result")
+    p.add_argument("index_result")
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_result_coherence(a.scan_result, a.index_result)
+    s = json.dumps(r, ensure_ascii=False, indent=2)
+    Path(a.json_output).write_text(s + "\n", encoding="utf-8") if a.json_output else print(s)

auditagent_tools/score_module.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+import argparse
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+def score_module_result(result_file: str | Path) -> dict:
+    """Puntúa un único resultado modular sin requerir el resto de la auditoría."""
+    started = datetime.now(timezone.utc).isoformat()
+    path = Path(result_file).expanduser().resolve()
+    result = json.loads(path.read_text(encoding="utf-8"))
+    base = {"PASS": 100, "WARN": 75, "FAIL": 30, "NOT_RUN": 0, "ERROR": 0}.get(result.get("status"), 0)
+    penalties = {"CRITICAL": 40, "HIGH": 25, "MEDIUM": 12, "LOW": 4, "OBSERVATION": 0}
+    score = base
+    breakdown = []
+    for finding in result.get("findings", []):
+        severity = finding.get("severity", "OBSERVATION")
+        penalty = penalties.get(severity, 0)
+        score -= penalty
+        breakdown.append({"severity": severity, "penalty": penalty, "title": finding.get("title")})
+    confidence_factor = {"high": 1.0, "medium": 0.9, "low": 0.75}.get(result.get("confidence"), 0.75)
+    score = max(0, min(100, round(score * confidence_factor)))
+    return {
+        "schema_version": "1.0", "module": "score_module",
+        "status": "PASS", "confidence": "high", "root": str(path),
+        "summary": {
+            "target_module": result.get("module"),
+            "raw_status": result.get("status"),
+            "target_confidence": result.get("confidence"),
+            "score": score,
+            "scale": 100
+        },
+        "findings": [],
+        "evidence": [{"penalty_breakdown": breakdown, "confidence_factor": confidence_factor}],
+        "limitations": ["La puntuación mide el resultado de un módulo, no la seguridad total del proyecto."],
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Puntuación independiente de un módulo.")
+    p.add_argument("result_file")
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = score_module_result(a.result_file)
+    s = json.dumps(r, ensure_ascii=False, indent=2)
+    Path(a.json_output).write_text(s + "\n", encoding="utf-8") if a.json_output else print(s)

auditagent_tools/sensitive_data.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+import argparse
+import json
+import re
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_sensitive_data(root: str | Path = ".", max_file_bytes: int = 2_000_000) -> dict:
+    """Busca secretos, credenciales, correos y rutas locales; siempre redacta el valor."""
+    started = datetime.now(timezone.utc).isoformat()
+    start = Path(root).expanduser().resolve()
+    start = start if start.is_dir() else start.parent
+    markers = (".git", ".colmena", "pyproject.toml")
+    probe = start
+    while probe.parent != probe and not any((probe / m).exists() for m in markers):
+        probe = probe.parent
+    repo = probe if any((probe / m).exists() for m in markers) else start
+    skip = {".git", ".venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
+    patterns = [
+        ("PRIVATE_KEY", "HIGH", re.compile(r"-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----")),
+        ("TOKEN", "HIGH", re.compile(r"\b(?:sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{20,}|xox[baprs]-[A-Za-z0-9-]{10,})\b")),
+        ("SENSITIVE_ASSIGNMENT", "MEDIUM", re.compile(r"\b(?:api[_-]?key|client[_-]?secret|access[_-]?token|password|passwd|secret)\b\s*[:=]\s*[\"']?[^\"'\s,}]{4,}", re.I)),
+        ("CREDENTIAL_URL", "HIGH", re.compile(r"\b[a-z][a-z0-9+.-]*://[^/\s:@]+:[^/\s@]+@", re.I)),
+        ("EMAIL", "LOW", re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.I)),
+        ("LOCAL_PATH", "LOW", re.compile(r"(?:/home/|/Users/)[^/\s\"']+|[A-Za-z]:\\Users\\[^\\\s\"']+", re.I)),
+    ]
+    findings, scanned, skipped = [], 0, 0
+    for path in sorted(repo.rglob("*")):
+        if not path.is_file() or path.is_symlink():
+            continue
+        rel = path.relative_to(repo)
+        if any(part in skip or part.endswith(".egg-info") for part in rel.parts) or path.suffix == ".pyc":
+            continue
+        try:
+            raw = path.read_bytes()
+        except OSError:
+            skipped += 1
+            continue
+        if len(raw) > max_file_bytes or b"\x00" in raw:
+            skipped += 1
+            continue
+        scanned += 1
+        text = raw.decode("utf-8", errors="replace")
+        for lineno, line in enumerate(text.splitlines(), 1):
+            for label, severity, pattern in patterns:
+                if pattern.search(line):
+                    findings.append({
+                        "severity": severity, "title": label,
+                        "detail": "Coincidencia redactada; revisar contexto y descartar falsos positivos.",
+                        "path": rel.as_posix(), "line": lineno, "redacted": True
+                    })
+    high = any(x["severity"] in {"CRITICAL", "HIGH"} for x in findings)
+    return {
+        "schema_version": "1.0", "module": "sensitive_data",
+        "status": "FAIL" if high else ("WARN" if findings else "PASS"),
+        "confidence": "medium", "root": str(repo),
+        "summary": {"files_scanned": scanned, "files_skipped": skipped, "matches": len(findings)},
+        "findings": findings,
+        "evidence": [{"redaction": "Los valores coincidentes nunca se incluyen en la salida."}],
+        "limitations": ["Las expresiones regulares producen falsos positivos y no sustituyen un escáner de secretos con entropía e historial Git."],
+        "started_at": started,
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Escaneo redactado de información sensible.")
+    p.add_argument("root", nargs="?", default=".")
+    p.add_argument("--max-file-bytes", type=int, default=2_000_000)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_sensitive_data(a.root, a.max_file_bytes)
+    s = json.dumps(r, ensure_ascii=False, indent=2)
+    Path(a.json_output).write_text(s + "\n", encoding="utf-8") if a.json_output else print(s)

auditagent_tools/size_limits.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+import argparse
+import json
+import os
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_size_limits(
+    root: str | Path,
+    request_template: str | Path,
+    command_template: str,
+    limit: int = 1024,
+    option_key: str = "options.max_file_bytes",
+    timeout_seconds: int = 120
+) -> dict:
+    """Prueba límite-1, límite y límite+1 sin depender del nombre del proyecto."""
+    started = datetime.now(timezone.utc).isoformat()
+    repo = Path(root).expanduser().resolve()
+    template = Path(request_template).expanduser().resolve()
+    def set_dotted(obj: dict, dotted: str, value) -> None:
+        cur = obj
+        parts = dotted.split(".")
+        for part in parts[:-1]: cur = cur.setdefault(part, {})
+        cur[parts[-1]] = value
+    def collect_paths(obj) -> set[str]:
+        found = set()
+        if isinstance(obj, dict):
+            for k, v in obj.items():
+                if k == "path" and isinstance(v, str): found.add(v)
+                found |= collect_paths(v)
+        elif isinstance(obj, list):
+            for v in obj: found |= collect_paths(v)
+        return found
+    with tempfile.TemporaryDirectory(prefix="auditagent-size-") as temp:
+        t = Path(temp); workspace = t / "workspace"; workspace.mkdir()
+        sizes = {"below.bin": max(0, limit - 1), "equal.bin": limit, "above.bin": limit + 1}
+        for name, size in sizes.items(): (workspace / name).write_bytes(b"a" * size)
+        req = json.loads(template.read_text(encoding="utf-8"))
+        req["root"] = str(workspace); set_dotted(req, option_key, limit)
+        request, output = t / "request.json", t / "output.json"
+        request.write_text(json.dumps(req, ensure_ascii=False, indent=2), encoding="utf-8")
+        cmd = [x.format(request=str(request), output=str(output), root=str(workspace)) for x in shlex.split(command_template)]
+        env = os.environ.copy(); env.update({"PYTHONDONTWRITEBYTECODE": "1", "TMPDIR": temp})
+        cp = subprocess.run(cmd, cwd=repo, env=env, text=True, capture_output=True, timeout=timeout_seconds, check=False)
+        data = json.loads(output.read_text(encoding="utf-8")) if output.exists() else {}
+        paths = collect_paths(data)
+    findings = []
+    if "below.bin" not in paths: findings.append({"severity": "MEDIUM", "title": "Archivo bajo límite ausente", "detail": "below.bin"})
+    if "equal.bin" not in paths: findings.append({"severity": "LOW", "title": "Semántica del límite exacto", "detail": "equal.bin no apareció; confirmar si el límite es inclusivo."})
+    return {
+        "schema_version": "1.0", "module": "size_limits",
+        "status": "FAIL" if any(x["severity"] == "MEDIUM" for x in findings) else ("WARN" if findings else "PASS"),
+        "confidence": "medium", "root": str(repo),
+        "summary": {"limit": limit, "paths_observed": sorted(paths), "returncode": cp.returncode},
+        "findings": findings,
+        "evidence": [{"sizes": sizes, "command": cmd, "stderr": cp.stderr[-2000:]}],
+        "limitations": ["La presencia de la ruta no siempre indica que el contenido haya sido indexado; revisar campos de estado del formato específico."],
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Prueba de límites de tamaño.")
+    p.add_argument("root")
+    p.add_argument("--request", required=True)
+    p.add_argument("--command", required=True)
+    p.add_argument("--limit", type=int, default=1024)
+    p.add_argument("--option-key", default="options.max_file_bytes")
+    p.add_argument("--timeout", type=int, default=120)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_size_limits(a.root, a.request, a.command, a.limit, a.option_key, a.timeout)
+    s = json.dumps(r, ensure_ascii=False, indent=2)
+    Path(a.json_output).write_text(s + "\n", encoding="utf-8") if a.json_output else print(s)

auditagent_tools/symlink_policy.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+import argparse
+import json
+import os
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_symlink_policy(
+    root: str | Path,
+    request_template: str | Path,
+    command_template: str,
+    option_key: str = "options.follow_symlinks",
+    timeout_seconds: int = 120
+) -> dict:
+    """Prueba enlaces internos, externos, rotos y de directorio con follow_symlinks=false."""
+    started = datetime.now(timezone.utc).isoformat()
+    repo = Path(root).expanduser().resolve()
+    template = Path(request_template).expanduser().resolve()
+    def set_dotted(obj: dict, dotted: str, value) -> None:
+        cur = obj
+        parts = dotted.split(".")
+        for part in parts[:-1]:
+            cur = cur.setdefault(part, {})
+        cur[parts[-1]] = value
+    def collect_paths(obj) -> set[str]:
+        found = set()
+        if isinstance(obj, dict):
+            for k, v in obj.items():
+                if k == "path" and isinstance(v, str):
+                    found.add(v)
+                found |= collect_paths(v)
+        elif isinstance(obj, list):
+            for v in obj:
+                found |= collect_paths(v)
+        return found
+    with tempfile.TemporaryDirectory(prefix="auditagent-symlink-") as temp:
+        t = Path(temp)
+        workspace, external = t / "workspace", t / "external"
+        workspace.mkdir(); external.mkdir()
+        (workspace / "inside.txt").write_text("inside\n", encoding="utf-8")
+        (external / "outside.txt").write_text("outside\n", encoding="utf-8")
+        (workspace / "link-internal").symlink_to(workspace / "inside.txt")
+        (workspace / "link-external").symlink_to(external / "outside.txt")
+        (workspace / "link-dir-external").symlink_to(external, target_is_directory=True)
+        (workspace / "link-broken").symlink_to(t / "missing.txt")
+        req = json.loads(template.read_text(encoding="utf-8"))
+        req["root"] = str(workspace)
+        set_dotted(req, option_key, False)
+        request, output = t / "request.json", t / "output.json"
+        request.write_text(json.dumps(req, ensure_ascii=False, indent=2), encoding="utf-8")
+        cmd = [x.format(request=str(request), output=str(output), root=str(workspace)) for x in shlex.split(command_template)]
+        env = os.environ.copy(); env.update({"PYTHONDONTWRITEBYTECODE": "1", "TMPDIR": temp})
+        cp = subprocess.run(cmd, cwd=repo, env=env, text=True, capture_output=True, timeout=timeout_seconds, check=False)
+        data = json.loads(output.read_text(encoding="utf-8")) if output.exists() else {}
+        paths = collect_paths(data)
+    escaped = [p for p in paths if "outside.txt" in p or p.startswith("../")]
+    findings = []
+    if escaped:
+        findings.append({"severity": "HIGH", "title": "Contenido externo alcanzado", "detail": ", ".join(sorted(escaped))})
+    if cp.returncode != 0:
+        findings.append({"severity": "MEDIUM", "title": "Ejecución fallida", "detail": cp.stderr[-2000:]})
+    return {
+        "schema_version": "1.0", "module": "symlink_policy",
+        "status": "FAIL" if escaped else ("WARN" if cp.returncode else "PASS"),
+        "confidence": "medium", "root": str(repo),
+        "summary": {"returncode": cp.returncode, "paths_observed": len(paths), "external_paths": len(escaped)},
+        "findings": findings,
+        "evidence": [{"command": cmd, "paths": sorted(paths), "stdout": cp.stdout[-3000:], "stderr": cp.stderr[-3000:]}],
+        "limitations": ["La interpretación depende del formato de salida y no demuestra resistencia a sustitución concurrente de rutas."],
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Prueba de política de symlinks.")
+    p.add_argument("root")
+    p.add_argument("--request", required=True)
+    p.add_argument("--command", required=True)
+    p.add_argument("--option-key", default="options.follow_symlinks")
+    p.add_argument("--timeout", type=int, default=120)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_symlink_policy(a.root, a.request, a.command, a.option_key, a.timeout)
+    s = json.dumps(r, ensure_ascii=False, indent=2)
+    Path(a.json_output).write_text(s + "\n", encoding="utf-8") if a.json_output else print(s)

auditagent_tools/test_runner.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+import argparse
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_test_runner(root: str | Path = ".", timeout_seconds: int = 180) -> dict:
+    """Ejecuta compilación y pruebas con cachés y temporales fuera del repositorio."""
+    started = datetime.now(timezone.utc).isoformat()
+    start = Path(root).expanduser().resolve()
+    start = start if start.is_dir() else start.parent
+    markers = (".git", ".colmena", "pyproject.toml")
+    probe = start
+    while probe.parent != probe and not any((probe / m).exists() for m in markers):
+        probe = probe.parent
+    repo = probe if any((probe / m).exists() for m in markers) else start
+    commands = []
+    python_files = [
+        p for p in repo.rglob("*.py")
+        if not any(part in {".git", ".venv", "__pycache__"} or part.endswith(".egg-info") for part in p.relative_to(repo).parts)
+    ]
+    if python_files:
+        commands.append([os.sys.executable, "-m", "py_compile", *[str(p) for p in python_files]])
+    if (repo / "tests").exists():
+        commands.append([os.sys.executable, "-m", "unittest", "discover", "-s", "tests", "-p", "test_*.py", "-v"])
+    results = []
+    with tempfile.TemporaryDirectory(prefix="auditagent-tests-") as temp:
+        env = os.environ.copy()
+        env.update({
+            "PYTHONDONTWRITEBYTECODE": "1",
+            "PYTHONPYCACHEPREFIX": str(Path(temp) / "pycache"),
+            "TMPDIR": temp,
+        })
+        for cmd in commands:
+            try:
+                cp = subprocess.run(cmd, cwd=repo, env=env, text=True, capture_output=True, timeout=timeout_seconds, check=False)
+                results.append({
+                    "command": cmd, "returncode": cp.returncode,
+                    "stdout": cp.stdout[-12000:], "stderr": cp.stderr[-12000:]
+                })
+            except subprocess.TimeoutExpired:
+                results.append({"command": cmd, "returncode": None, "timeout": True})
+    failed = [x for x in results if x.get("returncode") not in (0,)]
+    return {
+        "schema_version": "1.0", "module": "test_runner",
+        "status": "FAIL" if failed else ("PASS" if results else "NOT_RUN"),
+        "confidence": "high", "root": str(repo),
+        "summary": {"commands": len(results), "failed": len(failed), "python_files": len(python_files)},
+        "findings": [
+            {"severity": "HIGH", "title": "Comando de prueba fallido", "detail": " ".join(map(str, x["command"]))}
+            for x in failed
+        ],
+        "evidence": results,
+        "limitations": ["No instala dependencias ni ejecuta suites que requieran servicios externos."],
+        "started_at": started,
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Compilación y pruebas independientes.")
+    p.add_argument("root", nargs="?", default=".")
+    p.add_argument("--timeout", type=int, default=180)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_test_runner(a.root, a.timeout)
+    s = json.dumps(r, ensure_ascii=False, indent=2)
+    Path(a.json_output).write_text(s + "\n", encoding="utf-8") if a.json_output else print(s)

auditagent_tools/write_surface.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+import argparse
+import ast
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_write_surface(root: str | Path = ".") -> dict:
+    """Localiza APIs de escritura en Python y las clasifica sin ejecutar el código."""
+    started = datetime.now(timezone.utc).isoformat()
+    start = Path(root).expanduser().resolve()
+    start = start if start.is_dir() else start.parent
+    markers = (".git", ".colmena", "pyproject.toml")
+    probe = start
+    while probe.parent != probe and not any((probe / m).exists() for m in markers):
+        probe = probe.parent
+    repo = probe if any((probe / m).exists() for m in markers) else start
+    write_names = {
+        "write_text", "write_bytes", "mkdir", "unlink", "remove", "rename",
+        "replace", "rmdir", "chmod", "chown", "symlink_to", "hardlink_to",
+        "touch", "mkstemp", "NamedTemporaryFile", "atomic_write_json"
+    }
+    findings, parsed, parse_errors = [], 0, []
+    for path in sorted(repo.rglob("*.py")):
+        rel = path.relative_to(repo)
+        if any(part in {".git", ".venv", "__pycache__"} or part.endswith(".egg-info") for part in rel.parts):
+            continue
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+            parsed += 1
+        except (OSError, UnicodeError, SyntaxError) as exc:
+            parse_errors.append({"path": rel.as_posix(), "error": type(exc).__name__})
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                name = None
+                if isinstance(node.func, ast.Name):
+                    name = node.func.id
+                elif isinstance(node.func, ast.Attribute):
+                    name = node.func.attr
+                if name in write_names:
+                    in_tests = any(part.lower().startswith("test") or part == "tests" for part in rel.parts)
+                    findings.append({
+                        "severity": "OBSERVATION" if in_tests else "MEDIUM",
+                        "title": f"API de escritura: {name}",
+                        "detail": "Requiere revisión contextual; una escritura de salida externa puede ser legítima.",
+                        "path": rel.as_posix(), "line": getattr(node, "lineno", None)
+                    })
+                if name == "open" and len(node.args) >= 2 and isinstance(node.args[1], ast.Constant):
+                    mode = str(node.args[1].value)
+                    if any(x in mode for x in ("w", "a", "x", "+")):
+                        findings.append({
+                            "severity": "OBSERVATION" if "tests" in rel.parts else "MEDIUM",
+                            "title": f"open() con modo {mode!r}",
+                            "detail": "Revisar el destino y la guarda aplicada.",
+                            "path": rel.as_posix(), "line": getattr(node, "lineno", None)
+                        })
+    return {
+        "schema_version": "1.0", "module": "write_surface",
+        "status": "WARN" if findings or parse_errors else "PASS",
+        "confidence": "high", "root": str(repo),
+        "summary": {"python_files_parsed": parsed, "write_sites": len(findings), "parse_errors": len(parse_errors)},
+        "findings": findings + [
+            {"severity": "LOW", "title": "Archivo no analizado", "detail": x["error"], "path": x["path"]}
+            for x in parse_errors
+        ],
+        "evidence": [{"method": "Python AST", "write_api_names": sorted(write_names)}],
+        "limitations": ["No detecta escrituras indirectas por librerías externas, llamadas dinámicas, shell o extensiones nativas."],
+        "started_at": started,
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Superficie estática de escritura.")
+    p.add_argument("root", nargs="?", default=".")
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_write_surface(a.root)
+    s = json.dumps(r, ensure_ascii=False, indent=2)
+    Path(a.json_output).write_text(s + "\n", encoding="utf-8") if a.json_output else print(s)