Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.
Python ai-agentsautonomous-agentskali-linuxllm-agentsoffensive-securityooda-looppentestingplaywrightsecurity
"""Tests stdlib-only del scope-guard opt-in (`docker/kali/scope_guard.py`).
No importan `mcp`/`anyio`: sólo librería estándar + pytest (patrón de
``tests/test_finding_store.py``). Cubren los 13 casos del plan §10:
1. scope ausente -> no gate (passthrough).
2. ``enabled: false`` -> no gate.
3. kill-switch ``SCOPE_ENFORCE=0`` -> no gate aunque el archivo diga enabled.
4. target en allow CIDR -> allowed.
5. host literal en allow -> allowed; un sufijo NO coincide.
6. deny tiene prioridad sobre allow.
7. puerto fuera de ``ports`` -> bloquea; sin puerto con ports definido -> permitido por host.
8. sin ``targets`` con scope activo -> bloquea.
9. cinturón best-effort bloquea una IP obvia no declarada; una IP en allow no basta sola.
10. URL normalizada (http host:3000, https IP con 443 inferido).
11. config corrupta/JSON inválido/CIDR inválido -> ScopeError.
12. ``format_violation_message`` produce el texto esperado.
13. logging aislado de la violación: finding_store.read recupera el SCOPE_VIOLATION.
"""
from __future__ import annotations
import json
import sys
from pathlib import Path
import pytest
# Los módulos bajo prueba viven en docker/kali/ (el servidor MCP NO se importa: arrastra
# `mcp`/`anyio`). Se añade el padre al path explícitamente.
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
import finding_store # noqa: E402
import scope_guard # noqa: E402
@pytest.fixture(autouse=True)
def _clear_enforce(monkeypatch):
"""Asegura que SCOPE_ENFORCE no esté puesto por el entorno del CI."""
monkeypatch.delenv("SCOPE_ENFORCE", raising=False)
def _cfg(**over):
"""ScopeConfig enabled construido desde un dict (parse_scope, pura)."""
data = {"enabled": True}
data.update(over)
return scope_guard.parse_scope(data)
# ------------------------------------------------------------------ 1. scope ausente
def test_absent_scope_file_no_gate(tmp_path, monkeypatch):
missing = tmp_path / "nope.json"
monkeypatch.setenv("SCOPE_FILE", str(missing))
config = scope_guard.load_scope()
assert config is None
decision = scope_guard.evaluate(config, None, "nmap 10.0.0.5")
assert decision.allowed is True
assert decision.enforced is False
# ------------------------------------------------------------------ 2. enabled:false
def test_enabled_false_no_gate():
config = scope_guard.parse_scope({"enabled": False, "allow": [{"cidr": "10.0.0.0/24"}]})
assert scope_guard.is_enforcing(config) is False
decision = scope_guard.evaluate(config, None, "nmap 8.8.8.8")
assert decision.allowed is True
assert decision.enforced is False
# ------------------------------------------------------------------ 3. kill-switch
def test_kill_switch_scope_enforce_zero(monkeypatch):
monkeypatch.setenv("SCOPE_ENFORCE", "0")
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}])
assert scope_guard.is_enforcing(config) is False
decision = scope_guard.evaluate(config, None, "nmap 8.8.8.8")
assert decision.allowed is True
assert decision.enforced is False
# ------------------------------------------------------------------ 4. allow CIDR
def test_target_in_allow_cidr():
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}])
decision = scope_guard.evaluate(config, ["10.0.0.5"], "nmap -sV 10.0.0.5")
assert decision.allowed is True
assert decision.enforced is True
# ------------------------------------------------------------------ 5. host literal
def test_host_literal_in_allow_and_suffix_does_not_match():
config = _cfg(allow=[{"host": "juice-shop"}])
ok = scope_guard.evaluate(config, ["juice-shop"], "curl juice-shop")
assert ok.allowed is True
bad = scope_guard.evaluate(config, ["juice-shop.evil"], "curl juice-shop.evil")
assert bad.allowed is False # match literal: un sufijo NO coincide
# ------------------------------------------------------------------ 6. deny prioridad
def test_deny_takes_priority_over_allow():
config = _cfg(
allow=[{"cidr": "10.0.0.0/24"}],
deny=[{"cidr": "10.0.0.5/32"}],
)
decision = scope_guard.evaluate(config, ["10.0.0.5"], "nmap 10.0.0.5")
assert decision.allowed is False
assert any("deny" in v["reason"] for v in decision.violations)
def test_deny_host_priority():
config = _cfg(allow=[{"host": "juice-shop"}], deny=[{"host": "juice-shop"}])
decision = scope_guard.evaluate(config, ["juice-shop"], "curl juice-shop")
assert decision.allowed is False
# ------------------------------------------------------------------ 7. ports
def test_port_outside_ports_blocks():
config = _cfg(allow=[{"host": "juice-shop"}], ports=[3000])
bad = scope_guard.evaluate(config, ["juice-shop:8080"], "curl juice-shop:8080")
assert bad.allowed is False
ok = scope_guard.evaluate(config, ["juice-shop:3000"], "curl juice-shop:3000")
assert ok.allowed is True
def test_no_port_with_ports_defined_allowed_by_host():
config = _cfg(allow=[{"host": "juice-shop"}], ports=[3000])
decision = scope_guard.evaluate(config, ["juice-shop"], "nmap juice-shop")
assert decision.allowed is True # sin puerto, se permite por host
# ------------------------------------------------------------------ 8. sin targets
def test_no_targets_with_scope_active_blocks():
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}])
none = scope_guard.evaluate(config, None, "nmap 10.0.0.5")
empty = scope_guard.evaluate(config, [], "nmap 10.0.0.5")
assert none.allowed is False
assert empty.allowed is False
assert any(v.get("target") is None for v in none.violations)
# ------------------------------------------------------------------ 9. cinturón extra
def test_belt_blocks_obvious_undeclared_ip():
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}])
# targets declarados en allow, pero el comando toca una IP fuera de allow.
decision = scope_guard.evaluate(
config, ["10.0.0.5"], "nmap 10.0.0.5 && curl http://8.8.8.8"
)
assert decision.allowed is False
assert any("8.8.8.8" == v.get("target") for v in decision.violations)
def test_belt_blocks_deny_ip_in_command():
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}], deny=[{"cidr": "10.0.0.9/32"}])
decision = scope_guard.evaluate(config, ["10.0.0.5"], "nmap 10.0.0.5 10.0.0.9")
assert decision.allowed is False
assert any("10.0.0.9" == v.get("target") for v in decision.violations)
def test_belt_does_not_approve_without_targets():
# Una IP en allow dentro del comando NO basta: sin targets declarados, se bloquea.
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}])
decision = scope_guard.evaluate(config, None, "nmap 10.0.0.5")
assert decision.allowed is False
assert any(v.get("target") is None for v in decision.violations)
# ------------------------------------------------------------------ 10. URL normalizada
def test_url_normalized_http_host_port():
config = _cfg(allow=[{"host": "juice-shop"}], ports=[3000])
decision = scope_guard.evaluate(
config, ["http://juice-shop:3000/rest/products"], "curl http://juice-shop:3000/rest/products"
)
assert decision.allowed is True
def test_url_normalized_https_ip_infers_443():
t = scope_guard.normalize_target("https://10.0.0.5")
assert t.host == "10.0.0.5"
assert t.ip is not None
assert t.port == 443
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}], ports=[443])
decision = scope_guard.evaluate(config, ["https://10.0.0.5"], "curl https://10.0.0.5")
assert decision.allowed is True
# ------------------------------------------------------------------ 11. config corrupta
def test_invalid_json_raises_scope_error(tmp_path, monkeypatch):
bad = tmp_path / "scope.json"
bad.write_text("{ not valid json", encoding="utf-8")
monkeypatch.setenv("SCOPE_FILE", str(bad))
with pytest.raises(scope_guard.ScopeError):
scope_guard.load_scope()
def test_invalid_cidr_raises_scope_error():
with pytest.raises(scope_guard.ScopeError):
scope_guard.parse_scope({"enabled": True, "allow": [{"cidr": "no-es-cidr"}]})
def test_invalid_ports_raises_scope_error():
with pytest.raises(scope_guard.ScopeError):
scope_guard.parse_scope({"enabled": True, "ports": ["80"]})
def test_non_dict_root_raises_scope_error():
with pytest.raises(scope_guard.ScopeError):
scope_guard.parse_scope(["enabled", True])
# ------------------------------------------------------------------ 12. mensaje
def test_format_violation_message_lists_target_and_allowed():
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}, {"host": "juice-shop"}])
decision = scope_guard.evaluate(config, ["8.8.8.8"], "nmap 8.8.8.8")
msg = scope_guard.format_violation_message(decision, config)
assert msg.startswith("SCOPE_VIOLATION: target 8.8.8.8 is outside allowed scope")
assert "10.0.0.0/24" in msg
assert "juice-shop" in msg
def test_format_violation_message_no_targets():
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}])
decision = scope_guard.evaluate(config, None, "nmap 10.0.0.5")
msg = scope_guard.format_violation_message(decision, config)
assert "no 'targets' were declared" in msg
# ------------------------------------------------------------------ 13. logging aislado
def _log_violation(engagement_id, decision, config, command):
"""Réplica del logging best-effort del servidor para probarlo de forma AISLADA.
Escribe un finding ``state="discarded"`` ``title="SCOPE_VIOLATION"`` con los targets
rechazados + el comando + el motivo. El servidor hace exactamente esto envuelto en
try/except; aquí se prueba que el registro es recuperable por ``finding_store.read``.
"""
message = scope_guard.format_violation_message(decision, config)
rejected = [v.get("target") for v in decision.violations if v.get("target") is not None]
finding_store.append(
engagement_id or "_scope-violations",
{
"title": "SCOPE_VIOLATION",
"state": "discarded",
"phase": "act",
"target": ", ".join(str(t) for t in rejected),
"evidence": {"command": command, "output": message},
},
)
def test_violation_logging_recoverable(tmp_path, monkeypatch):
monkeypatch.setenv("KALI_ARTIFACTS_DIR", str(tmp_path))
config = _cfg(allow=[{"cidr": "10.0.0.0/24"}])
command = "nmap 8.8.8.8"
decision = scope_guard.evaluate(config, ["8.8.8.8"], command)
assert decision.allowed is False
_log_violation("eng-x", decision, config, command)
page = finding_store.read("eng-x")
assert page["total"] == 1
rec = page["findings"][0]
assert rec["title"] == "SCOPE_VIOLATION"
assert rec["state"] == "discarded"
assert "8.8.8.8" in rec["target"]
assert rec["evidence"]["command"] == command