auditagent-toolkit 0.2.0__py3-none-any.whl

auditagent_tools/exclusion_policy.py

@@ -0,0 +1,84 @@
+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_exclusion_policy(
+    root: str | Path,
+    request_template: str | Path,
+    command_template: str,
+    option_key: str = "options.exclude_patterns",
+    timeout_seconds: int = 120
+) -> dict:
+    """Comprueba exclusiones reutilizables sobre archivos y directorios generados."""
+    started = datetime.now(timezone.utc).isoformat()
+    repo = Path(root).expanduser().resolve()
+    template = Path(request_template).expanduser().resolve()
+    patterns = ["*.bak", "state/*.result.json", "*.egg-info", "*.egg-info/**", "__pycache__", "__pycache__/**"]
+    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-exclusion-") as temp:
+        t = Path(temp); workspace = t / "workspace"
+        (workspace / "state").mkdir(parents=True)
+        (workspace / "pkg.egg-info").mkdir()
+        (workspace / "__pycache__").mkdir()
+        (workspace / "keep.txt").write_text("keep\n", encoding="utf-8")
+        (workspace / "notes.bak").write_text("bak\n", encoding="utf-8")
+        (workspace / "state" / "scan.result.json").write_text("{}\n", encoding="utf-8")
+        (workspace / "pkg.egg-info" / "SOURCES.txt").write_text("gen\n", encoding="utf-8")
+        (workspace / "__pycache__" / "x.pyc").write_bytes(b"\0")
+        req = json.loads(template.read_text(encoding="utf-8"))
+        req["root"] = str(workspace); set_dotted(req, option_key, patterns)
+        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)
+    forbidden = {"notes.bak", "state/scan.result.json", "pkg.egg-info", "pkg.egg-info/SOURCES.txt", "__pycache__", "__pycache__/x.pyc"}
+    leaks = sorted(forbidden & paths)
+    missing_keep = "keep.txt" not in paths
+    findings = []
+    if leaks: findings.append({"severity": "MEDIUM", "title": "Artefactos excluidos presentes", "detail": ", ".join(leaks)})
+    if missing_keep: findings.append({"severity": "MEDIUM", "title": "Archivo válido ausente", "detail": "keep.txt no apareció."})
+    return {
+        "schema_version": "1.0", "module": "exclusion_policy",
+        "status": "FAIL" if leaks or missing_keep else "PASS",
+        "confidence": "high", "root": str(repo),
+        "summary": {"leaks": len(leaks), "keep_present": not missing_keep, "returncode": cp.returncode},
+        "findings": findings,
+        "evidence": [{"patterns": patterns, "paths": sorted(paths), "command": cmd, "stderr": cp.stderr[-2000:]}],
+        "limitations": ["No prueba todas las diferencias de semántica entre glob, fnmatch y sistemas de archivos case-insensitive."],
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Prueba de exclusiones.")
+    p.add_argument("root")
+    p.add_argument("--request", required=True)
+    p.add_argument("--command", required=True)
+    p.add_argument("--option-key", default="options.exclude_patterns")
+    p.add_argument("--timeout", type=int, default=120)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_exclusion_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/git_state.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+import argparse
+import json
+import re
+import subprocess
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_git_state(root: str | Path = ".") -> dict:
+    """Audita estado, historial, ignorados e identidad Git sin modificar el repositorio."""
+    started = datetime.now(timezone.utc).isoformat()
+    repo = Path(root).expanduser().resolve()
+    def run(*args: str) -> tuple[int, str, str]:
+        cp = subprocess.run(
+            ["git", *args], cwd=repo, text=True,
+            capture_output=True, timeout=30, check=False
+        )
+        return cp.returncode, cp.stdout.strip(), cp.stderr.strip()
+    code, top, err = run("rev-parse", "--show-toplevel")
+    if code != 0:
+        return {
+            "schema_version": "1.0", "module": "git_state", "status": "NOT_RUN",
+            "confidence": "high", "root": str(repo), "summary": {"is_git_repo": False},
+            "findings": [{"severity": "OBSERVATION", "title": "No es repositorio Git", "detail": err or "git rev-parse falló"}],
+            "evidence": [], "limitations": [], "started_at": started,
+            "finished_at": datetime.now(timezone.utc).isoformat(),
+        }
+    repo = Path(top)
+    _, status, _ = run("status", "--short", "--branch", "--ignored")
+    _, tracked, _ = run("ls-files")
+    _, history, _ = run("log", "--format=%H%x09%an%x09%ae%x09%s", "--all", "-n", "100")
+    _, remotes, _ = run("remote", "-v")
+    findings = []
+    email_pattern = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+    identities = []
+    for line in history.splitlines():
+        parts = line.split("\t")
+        if len(parts) >= 4:
+            commit, name, email, subject = parts[:4]
+            identities.append({"commit": commit, "name": name, "email": email, "subject": subject})
+            if email_pattern.match(email) and not email.endswith((".invalid", "@users.noreply.github.com")):
+                findings.append({
+                    "severity": "LOW", "title": "Correo personal o publicable en historial",
+                    "detail": f"El commit {commit[:12]} contiene una dirección de correo no anonimizada.",
+                    "path": ".git"
+                })
+    dirty = any(
+        line and not line.startswith("##") and not line.startswith("!!")
+        for line in status.splitlines()
+    )
+    if dirty:
+        findings.append({"severity": "LOW", "title": "Árbol de trabajo con cambios", "detail": "Existen cambios no confirmados o no rastreados."})
+    return {
+        "schema_version": "1.0", "module": "git_state",
+        "status": "WARN" if findings else "PASS",
+        "confidence": "high", "root": str(repo),
+        "summary": {
+            "is_git_repo": True,
+            "dirty": dirty,
+            "tracked_files": len([x for x in tracked.splitlines() if x]),
+            "commits_inspected": len(identities),
+            "remotes": len([x for x in remotes.splitlines() if x]),
+        },
+        "findings": findings,
+        "evidence": [{"status": status, "identities": identities, "remotes": remotes.splitlines()}],
+        "limitations": ["La ausencia de secretos en el historial requiere un módulo específico de contenido sensible."],
+        "started_at": started,
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Auditoría Git independiente.")
+    p.add_argument("root", nargs="?", default=".")
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_git_state(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)

auditagent_tools/hidden_policy.py

@@ -0,0 +1,85 @@
+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_hidden_policy(
+    root: str | Path,
+    request_template: str | Path,
+    command_template: str,
+    option_key: str = "options.include_hidden",
+    timeout_seconds: int = 120
+) -> dict:
+    """Compara include_hidden=false y true sobre un workspace temporal."""
+    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
+    cases = {}
+    with tempfile.TemporaryDirectory(prefix="auditagent-hidden-") as temp:
+        t = Path(temp); workspace = t / "workspace"
+        (workspace / ".hidden").mkdir(parents=True)
+        (workspace / "visible").mkdir()
+        (workspace / ".root-hidden.txt").write_text("x\n", encoding="utf-8")
+        (workspace / ".hidden" / "inside.txt").write_text("x\n", encoding="utf-8")
+        (workspace / "visible" / ".nested-hidden.txt").write_text("x\n", encoding="utf-8")
+        (workspace / "visible" / "keep.txt").write_text("x\n", encoding="utf-8")
+        for flag in (False, True):
+            req = json.loads(template.read_text(encoding="utf-8"))
+            req["root"] = str(workspace)
+            set_dotted(req, option_key, flag)
+            request, output = t / f"request-{flag}.json", t / f"output-{flag}.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 {}
+            cases[str(flag).lower()] = {"returncode": cp.returncode, "paths": sorted(collect_paths(data)), "stderr": cp.stderr[-2000:]}
+    hidden_false = [p for p in cases["false"]["paths"] if any(part.startswith(".") for part in Path(p).parts)]
+    hidden_true = [p for p in cases["true"]["paths"] if any(part.startswith(".") for part in Path(p).parts)]
+    findings = []
+    if hidden_false:
+        findings.append({"severity": "MEDIUM", "title": "Ocultos presentes con include_hidden=false", "detail": ", ".join(hidden_false)})
+    if not hidden_true:
+        findings.append({"severity": "LOW", "title": "No se observaron ocultos con include_hidden=true", "detail": "La opción puede no estar implementada o el formato no fue reconocido."})
+    return {
+        "schema_version": "1.0", "module": "hidden_policy",
+        "status": "FAIL" if hidden_false else ("WARN" if not hidden_true else "PASS"),
+        "confidence": "medium", "root": str(repo),
+        "summary": {"hidden_when_false": len(hidden_false), "hidden_when_true": len(hidden_true)},
+        "findings": findings, "evidence": [cases],
+        "limitations": ["La detección de rutas depende de campos llamados path en la salida JSON."],
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Prueba de archivos ocultos.")
+    p.add_argument("root")
+    p.add_argument("--request", required=True)
+    p.add_argument("--command", required=True)
+    p.add_argument("--option-key", default="options.include_hidden")
+    p.add_argument("--timeout", type=int, default=120)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_hidden_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/inventory.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+import argparse
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_inventory(root: str | Path = ".", max_depth: int = 12) -> dict:
+    """Inventaría archivos sin modificarlos. Autodetecta la raíz 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", "package.json", "Cargo.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
+    ignored_parts = {".git", ".venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
+    files, dirs, symlinks, errors = [], [], [], []
+    for path in sorted(repo.rglob("*")):
+        try:
+            rel = path.relative_to(repo)
+        except ValueError:
+            continue
+        if len(rel.parts) > max_depth:
+            continue
+        if any(part in ignored_parts or part.endswith(".egg-info") for part in rel.parts):
+            continue
+        try:
+            if path.is_symlink():
+                symlinks.append({"path": rel.as_posix(), "target": str(path.readlink())})
+            elif path.is_dir():
+                dirs.append(rel.as_posix())
+            elif path.is_file():
+                st = path.stat()
+                files.append({
+                    "path": rel.as_posix(),
+                    "size_bytes": st.st_size,
+                    "suffix": path.suffix.lower(),
+                    "mtime_ns": st.st_mtime_ns,
+                })
+        except OSError as exc:
+            errors.append({"path": rel.as_posix(), "error": type(exc).__name__})
+    status = "PASS" if not errors else "WARN"
+    return {
+        "schema_version": "1.0",
+        "module": "inventory",
+        "status": status,
+        "confidence": "high",
+        "root": str(repo),
+        "summary": {
+            "files": len(files), "directories": len(dirs),
+            "symlinks": len(symlinks), "errors": len(errors),
+            "total_bytes": sum(x["size_bytes"] for x in files),
+        },
+        "findings": [
+            {"severity": "LOW", "title": "Errores de inventario", "detail": str(x), "path": x["path"]}
+            for x in errors
+        ],
+        "evidence": [{"files": files, "directories": dirs, "symlinks": symlinks}],
+        "limitations": ["No interpreta reglas .gitignore; excluye solo directorios técnicos conocidos."],
+        "started_at": started,
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Inventario independiente del repositorio.")
+    parser.add_argument("root", nargs="?", default=".")
+    parser.add_argument("--max-depth", type=int, default=12)
+    parser.add_argument("--json-output")
+    args = parser.parse_args()
+    result = audit_inventory(args.root, args.max_depth)
+    payload = json.dumps(result, ensure_ascii=False, indent=2)
+    if args.json_output:
+        Path(args.json_output).write_text(payload + "\n", encoding="utf-8")
+    else:
+        print(payload)

auditagent_tools/json_contracts.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+import argparse
+import json
+import re
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_json_contracts(root: str | Path = ".") -> dict:
+    """Descubre JSON y esquemas, valida sintaxis y busca evidencia de aplicación real."""
+    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
+    documents, schemas_found, invalid = [], [], []
+    for path in sorted(repo.rglob("*.json")):
+        rel = path.relative_to(repo)
+        if any(part in {".git", ".venv", "__pycache__"} or part.endswith(".egg-info") for part in rel.parts):
+            continue
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            documents.append({"path": rel.as_posix(), "top_type": type(data).__name__})
+            if isinstance(data, dict) and ("$schema" in data or "$id" in data) and "properties" in data:
+                schemas_found.append(rel.as_posix())
+        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+            invalid.append({"path": rel.as_posix(), "error": str(exc)})
+    source_text = ""
+    for path in repo.rglob("*.py"):
+        if any(part in {".git", ".venv", "__pycache__"} for part in path.relative_to(repo).parts):
+            continue
+        try:
+            source_text += "\n" + path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError):
+            pass
+    validators = sorted(set(re.findall(r"\b(?:jsonschema|Draft20\d{2}Validator|validate)\b", source_text)))
+    findings = [
+        {"severity": "MEDIUM", "title": "JSON inválido", "detail": x["error"], "path": x["path"]}
+        for x in invalid
+    ]
+    if schemas_found and not validators:
+        findings.append({
+            "severity": "MEDIUM", "title": "Esquemas presentes sin evidencia clara de aplicación",
+            "detail": "Se encontraron contratos JSON, pero no referencias inequívocas a un validador JSON Schema."
+        })
+    return {
+        "schema_version": "1.0", "module": "json_contracts",
+        "status": "FAIL" if invalid else ("WARN" if findings else "PASS"),
+        "confidence": "medium", "root": str(repo),
+        "summary": {
+            "json_documents": len(documents), "schemas": len(schemas_found),
+            "invalid_json": len(invalid), "validator_tokens": validators
+        },
+        "findings": findings,
+        "evidence": [{"schemas": schemas_found, "documents": documents}],
+        "limitations": ["La búsqueda de aplicación del esquema es estática y heurística; no demuestra rutas dinámicas."],
+        "started_at": started,
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Auditoría de contratos JSON.")
+    p.add_argument("root", nargs="?", default=".")
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_json_contracts(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)

auditagent_tools/output_boundary.py

@@ -0,0 +1,72 @@
+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_output_boundary(
+    root: str | Path,
+    request_template: str | Path,
+    command_template: str,
+    timeout_seconds: int = 120
+) -> dict:
+    """Prueba que varias rutas equivalentes dentro del workspace sean rechazadas."""
+    started = datetime.now(timezone.utc).isoformat()
+    repo = Path(root).expanduser().resolve()
+    template = Path(request_template).expanduser().resolve()
+    cases = []
+    with tempfile.TemporaryDirectory(prefix="auditagent-boundary-") as temp:
+        t = Path(temp)
+        workspace = t / "workspace"
+        (workspace / "subdir").mkdir(parents=True)
+        (workspace / "file.txt").write_text("data\n", encoding="utf-8")
+        req = json.loads(template.read_text(encoding="utf-8"))
+        req["root"] = str(workspace)
+        request = t / "request.json"
+        request.write_text(json.dumps(req, ensure_ascii=False, indent=2), encoding="utf-8")
+        outputs = [
+            workspace / "result.json",
+            workspace / "subdir" / "result.json",
+            workspace / ".." / "workspace" / "result-2.json",
+            workspace / "subdir" / ".." / "result-3.json",
+        ]
+        for output in outputs:
+            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)
+            cases.append({
+                "output": str(output), "resolved_output": str(output.resolve()),
+                "returncode": cp.returncode, "created": output.exists(),
+                "stdout": cp.stdout[-2000:], "stderr": cp.stderr[-2000:]
+            })
+    bypasses = [x for x in cases if x["returncode"] == 0 or x["created"]]
+    return {
+        "schema_version": "1.0", "module": "output_boundary",
+        "status": "FAIL" if bypasses else "PASS",
+        "confidence": "high", "root": str(repo),
+        "summary": {"cases": len(cases), "bypasses": len(bypasses)},
+        "findings": [
+            {"severity": "HIGH", "title": "Salida interna no rechazada", "detail": x["resolved_output"]}
+            for x in bypasses
+        ],
+        "evidence": cases,
+        "limitations": ["No cubre carreras TOCTOU ni todos los esquemas de symlink de padres inexistentes."],
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Prueba de frontera de salida.")
+    p.add_argument("root")
+    p.add_argument("--request", required=True)
+    p.add_argument("--command", required=True)
+    p.add_argument("--timeout", type=int, default=120)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_output_boundary(a.root, a.request, a.command, 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/permission_handling.py

@@ -0,0 +1,73 @@
+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_permission_handling(
+    root: str | Path,
+    request_template: str | Path,
+    command_template: str,
+    timeout_seconds: int = 120
+) -> dict:
+    """Prueba un archivo chmod 000 y registra si el entorno realmente impide leerlo."""
+    started = datetime.now(timezone.utc).isoformat()
+    repo = Path(root).expanduser().resolve()
+    template = Path(request_template).expanduser().resolve()
+    with tempfile.TemporaryDirectory(prefix="auditagent-permission-") as temp:
+        t = Path(temp); workspace = t / "workspace"; workspace.mkdir()
+        readable = workspace / "readable.txt"; unreadable = workspace / "unreadable.txt"
+        readable.write_text("ok\n", encoding="utf-8"); unreadable.write_text("secret\n", encoding="utf-8")
+        unreadable.chmod(0)
+        actually_unreadable = False
+        try:
+            unreadable.read_bytes()
+        except PermissionError:
+            actually_unreadable = True
+        req = json.loads(template.read_text(encoding="utf-8")); req["root"] = str(workspace)
+        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)
+        unreadable.chmod(0o600)
+        output_valid = False
+        if output.exists():
+            try:
+                json.loads(output.read_text(encoding="utf-8")); output_valid = True
+            except Exception:
+                pass
+    limitations = []
+    if not actually_unreadable:
+        limitations.append("El usuario del proceso pudo leer chmod 000; el caso no demuestra manejo real de PermissionError.")
+    findings = []
+    if actually_unreadable and cp.returncode != 0:
+        findings.append({"severity": "MEDIUM", "title": "Fallo total ante archivo ilegible", "detail": cp.stderr[-2000:]})
+    if output.exists() and not output_valid:
+        findings.append({"severity": "HIGH", "title": "Salida inválida tras error de permisos", "detail": "El archivo de salida no es JSON válido."})
+    return {
+        "schema_version": "1.0", "module": "permission_handling",
+        "status": "FAIL" if findings else ("WARN" if not actually_unreadable else "PASS"),
+        "confidence": "low" if not actually_unreadable else "medium", "root": str(repo),
+        "summary": {"actually_unreadable": actually_unreadable, "returncode": cp.returncode, "output_valid_json": output_valid},
+        "findings": findings,
+        "evidence": [{"command": cmd, "stdout": cp.stdout[-3000:], "stderr": cp.stderr[-3000:]}],
+        "limitations": limitations,
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Prueba de errores de permisos.")
+    p.add_argument("root")
+    p.add_argument("--request", required=True)
+    p.add_argument("--command", required=True)
+    p.add_argument("--timeout", type=int, default=120)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_permission_handling(a.root, a.request, a.command, 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/readonly_immutability.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+import argparse
+import hashlib
+import json
+import os
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+from datetime import datetime, timezone
+
+def audit_readonly_immutability(
+    root: str | Path,
+    request_template: str | Path,
+    command_template: str,
+    timeout_seconds: int = 120
+) -> dict:
+    """Ejecuta una herramienta contra un workspace temporal y compara snapshot antes/después."""
+    started = datetime.now(timezone.utc).isoformat()
+    repo = Path(root).expanduser().resolve()
+    template = Path(request_template).expanduser().resolve()
+    def snapshot(base: Path) -> dict:
+        out = {}
+        for p in sorted(base.rglob("*")):
+            if p.is_file() and not p.is_symlink():
+                raw = p.read_bytes()
+                st = p.stat()
+                out[p.relative_to(base).as_posix()] = {
+                    "sha256": hashlib.sha256(raw).hexdigest(),
+                    "size": st.st_size, "mtime_ns": st.st_mtime_ns, "mode": st.st_mode
+                }
+        return out
+    with tempfile.TemporaryDirectory(prefix="auditagent-ro-") as temp:
+        temp_path = Path(temp)
+        workspace = temp_path / "workspace"
+        workspace.mkdir()
+        (workspace / "nested").mkdir()
+        (workspace / "alpha.txt").write_text("alpha\n", encoding="utf-8")
+        (workspace / "nested" / "beta.md").write_text("beta\n", encoding="utf-8")
+        req = json.loads(template.read_text(encoding="utf-8"))
+        req["root"] = str(workspace)
+        request = temp_path / "request.json"
+        request.write_text(json.dumps(req, ensure_ascii=False, indent=2), encoding="utf-8")
+        output = temp_path / "output.json"
+        before = snapshot(workspace)
+        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)
+        after = snapshot(workspace)
+        changed = {
+            key: {"before": before.get(key), "after": after.get(key)}
+            for key in sorted(set(before) | set(after))
+            if before.get(key) != after.get(key)
+        }
+    findings = []
+    if changed:
+        findings.append({"severity": "HIGH", "title": "Workspace modificado", "detail": f"{len(changed)} entradas cambiaron."})
+    if cp.returncode != 0:
+        findings.append({"severity": "MEDIUM", "title": "Comando auditado falló", "detail": cp.stderr[-2000:]})
+    return {
+        "schema_version": "1.0", "module": "readonly_immutability",
+        "status": "FAIL" if changed else ("WARN" if cp.returncode else "PASS"),
+        "confidence": "high", "root": str(repo),
+        "summary": {"returncode": cp.returncode, "changed_entries": len(changed), "output_created": output.exists()},
+        "findings": findings,
+        "evidence": [{"command": cmd, "changes": changed, "stdout": cp.stdout[-4000:], "stderr": cp.stderr[-4000:]}],
+        "limitations": ["Demuestra solo el caso temporal ejecutado; no impide carreras ni escrituras por rutas no cubiertas."],
+        "started_at": started, "finished_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="Prueba independiente de inmutabilidad.")
+    p.add_argument("root")
+    p.add_argument("--request", required=True)
+    p.add_argument("--command", required=True, help="Use {request}, {output} y {root}.")
+    p.add_argument("--timeout", type=int, default=120)
+    p.add_argument("--json-output")
+    a = p.parse_args()
+    r = audit_readonly_immutability(a.root, a.request, a.command, 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)