## Características

- **Escaneo de red**: Descubre dispositivos en tu red local
- **Detección de puertos**: Identifica puertos abiertos y servicios en ejecución
- **Análisis de servicios**: Detecta versiones de servicios y banners
- **Detección de vulnerabilidades**: Comprueba si hay vulnerabilidades conocidas
- **Múltiples formatos de salida**: Soporta salida en texto, JSON y XML
- **Escaneo concurrente**: Escaneo multiproceso rápido
- **Multiplataforma**: Funciona en Linux, macOS y Windows

## Instalación

### Desde el código fuente

```bash
git clone https://github.com/example/netsec-scanner.git
cd netsec-scanner
pip install -r requirements.txt

pip install netsec-scanner

python netsec_scanner.py -t 192.168.1.1

python netsec_scanner.py -t 192.168.1.0/24

python netsec_scanner.py -t 192.168.1.1 -p 22,80,443,8080

python netsec_scanner.py -t 192.168.1.1 -p 1-1000

python netsec_scanner.py -t 192.168.1.1 -o json

python netsec_scanner.py -t 192.168.1.1 -o xml

$ python netsec_scanner.py -t 192.168.1.0/24
[*] Escaneando 192.168.1.0/24...
[+] Host activo: 192.168.1.1
[+] Host activo: 192.168.1.10
[+] Host activo: 192.168.1.15
[*] Escaneo completado. 3 hosts encontrados.

$ python netsec_scanner.py -t 192.168.1.1 -p 22,80,443 -v
[*] Escaneando 192.168.1.1...
[+] Puerto 22/tcp abierto - SSH (OpenSSH 8.2p1)
[+] Puerto 80/tcp abierto - HTTP (nginx 1.18.0)
[+] Puerto 443/tcp abierto - HTTPS (nginx 1.18.0)
[*] Escaneo completado. 3 puertos abiertos encontrados.

$ python netsec_scanner.py -t 192.168.1.1 -o json
{
  "target": "192.168.1.1",
  "scan_time": "2024-01-15T10:30:00Z",
  "hosts": [
    {
      "ip": "192.168.1.1",
      "status": "up",
      "ports": [
        {
          "port": 22,
          "protocol": "tcp",
          "state": "open",
          "service": "ssh",
          "version": "OpenSSH 8.2p1"
        }
      ]
    }
  ]
}

Escanee el contexto recuperado antes de que llegue al modelo:```python
res = shield.protect(user_prompt, my_llm, context=retrieved_docs)
if res.action == "block":
    ...   # a poisoned document was caught before the model saw it

Conecta las decisiones a tu registro una vez y cada llamada queda registrada:```python
from reasongate import Shield, log_sink, file_sink

shield = Shield(audit_hook=log_sink)                    # -> "reasongate.audit" logger
shield = Shield(audit_hook=file_sink("audit.jsonl"))    # -> JSON-Lines, SIEM-ready

- Shield off, registro envenenado: el registro se envía por correo al atacante y se dispara una transferencia.
  Estos son efectos secundarios reales, escritos en disco.
- Shield on, registro envenenado: el escaneo indirecto detecta el payload antes de que se
  llame al modelo. Sin efectos secundarios.
- Shield on, registro limpio: el agente responde con normalidad.
- Shield on, ataque **reformulado**: el payload se reformula como una nota de negocio ordinaria para que
  la capa de firmas *no* lo detecte — y aun así no ocurre ningún efecto secundario, porque la
  puerta de acción (a continuación) bloquea la llamada a la herramienta: su destino (la dirección de exfiltración, la cuenta)
  se cita desde contenido no confiable, algo que ninguna reformulación puede ocultar.

Sé claro sobre lo que hace cada capa. La coincidencia de firmas tiene un límite real: reformula la
inyección para que ya no coincida con un patrón conocido y el núcleo de reglas no la detectará — por eso
el núcleo es un primer filtro, no una frontera. La cuarta ejecución es la respuesta honesta a
ese límite: no pretende que la detección haya mejorado; la detección sigue sin detectar el ataque
reformulado. Lo que detiene la brecha es una capa *diferente* que razona sobre la confianza de los datos
detrás de una acción en lugar de sobre la redacción del texto. Las cuatro condiciones se aplican como invariantes
de CI para que la demo no pueda regresar silenciosamente.

También hay un playground en vivo: <https://reasongate-demo-nvgo.onrender.com>. Ejecuta el
núcleo sin dependencias, no necesita clave de API y no envía datos fuera del servidor.

## Detectores en el núcleo

- **Normalización / desofuscación.** Elimina caracteres de ancho cero, homoglifos cirílicos,
  leetspeak (`1gn0re`), letras espaciadas y con puntos (`i.g.n.o.r.e`) y payloads en base64, de modo que
  una frase conocida disfrazada se normaliza de vuelta a algo que la capa de patrones puede detectar.
- **Patrones de inyección / jailbreak.** Una capa de reglas para frases conocidas.
- **Inyección indirecta.** Ejecuta el mismo escaneo sobre documentos recuperados y salida de herramientas antes
  de que lleguen al modelo.
- **Fuga de salida y canary.** Marca secretos y PII a la salida. Un token canary
  plantado en el prompt del sistema hace que una fuga del prompt del sistema sea demostrable en lugar de supuesta.

El motor de políticas fusiona estas señales con un noisy-OR calibrado, de modo que varias señales débiles
pueden sumar hasta un bloqueo mientras que el ruido aislado de un prompt legítimo no lo hace.

## La puerta de acción (llamadas a herramientas del agente)

Los detectores preguntan "¿es este texto una inyección?" — una pregunta que puedes perder reformulando. La
puerta de acción hace una pregunta diferente e independiente de la redacción: *¿puede proceder esta acción, dada
la confianza de los datos que la produjeron?* Es la defensa basada en capacidades contra la inyección
indirecta — rompe la "trifecta letal" de contenido no confiable, una capacidad sensible y una
vía de salida — y detecta los ataques reformulados que la capa de firmas no ve.```python
from reasongate import ToolGate, ToolPolicy, Segment

gate = ToolGate([
    ToolPolicy("transfer_funds", sensitive=True, destination_args=("to_account",)),
    ToolPolicy("send_email",     sensitive=True, destination_args=("to",)),
])

record = Segment(text=retrieved_doc, source="crm", trust="untrusted")
decision = gate.authorize(
    {"name": "transfer_funds", "args": {"to_account": "9900", "amount": "$84,200"}},
    context=[record],
)
decision.allowed       # False — the destination account is quoted from untrusted content
print(decision.explain())

La autorización no blanquea un destino contaminado: `authorized=True` limpia
la copresencia, porque el principal solicitó la acción — no limpia un valor de
argumento que se remonta a contenido no confiable, porque el principal no eligió eso.

### Integrarlo en un agente existente```python
from reasongate.adapters.toolcalls import from_anthropic, refusal_result
from reasongate.catalog import infer_policies, describe

print(describe(infer_policies([t["name"] for t in tools])))   # draft policies, then correct them

for call in from_anthropic(response.content):
    decision = session.authorize(call)
    if not decision.allowed:
        results.append(refusal_result(call, decision))        # the model is told why
    else:
        results.append(run(call))

**No se incluye ningún juez de modelo con este paquete.** Decidir si una frase entra en conflicto con una
política de prosa requiere un modelo; sin configurar, la puerta devuelve *"no evaluado"* en lugar de
un permiso, porque una solicitud no verificada nunca debe parecer una autorizada. Un juez de modelo
es también en sí mismo un objetivo de inyección, y esto es orientativo — la capa con la que no se puede discutir
es `ToolGate`, que restringe lo que el agente puede *hacer*.

### Medido en AgentDojo

La puerta tiene ahora sus propios números, sobre el benchmark construido para esta amenaza
([AgentDojo](https://github.com/ethz-spylab/agentdojo): cuatro suites de agentes que usan herramientas,
atacadas a través de los datos que el agente lee). Sin modelo en el bucle — las propias
secuencias de herramientas de referencia del benchmark se reproducen a través de la puerta como un agente completamente secuestrado, y
los propios verificadores de AgentDojo puntúan el resultado:

| | Éxito del ataque | Utilidad en tráfico limpio |
|---|---:|---:|
| Sin puerta | 97.4% | 100% |
| Solo contaminación de argumentos | **12.6%** | 64.9% |
| Estricta (co-presencia) | 3.4% | 41.2% |

Con un modelo en el bucle (Claude Haiku 4.5, banking) el panorama es aún más nítido: el
modelo rechazó por sí solo todas las inyecciones, así que la puerta no añadió seguridad y costó 12.5
puntos de utilidad — un seguro contra el caso en que el juicio del modelo falla, con su precio.
Lee ambas columnas. Los 35 puntos de utilidad que cuesta la puerta son destinos legítimos que el
agente leyó de un almacén — el IBAN de la factura que se le pidió pagar — que la contaminación no puede distinguir
del IBAN de un atacante en el mismo archivo, porque no mira las palabras. Lo que se cuela son tres formas documentadas: objetivos que son lecturas, destinos consultados en lugar de citados, y daño en un campo que no es el destino. Método, números por suite y advertencias:
[RESULTS.md → The gate on AgentDojo](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md#the-gate-on-agentdojo).

El razonamiento detrás de esta capa — el modelo de amenaza, por qué la detección de texto es estructuralmente
insuficiente, y las garantías *y no garantías* de la puerta — está escrito en
[docs/threat-model.md](https://github.com/cgrtml/reasongate/blob/main/docs/threat-model.md). Lo que todavía se le escapa, medido y citado
de un corpus real, está en [docs/coverage-gaps.md](https://github.com/cgrtml/reasongate/blob/main/docs/coverage-gaps.md).

## Benchmarks

La metodología completa, el arnés y los resultados negativos están en [RESULTS.md](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md).
Tres números merecen leerse juntos: lo que bloquea en exceso, lo que detecta y lo que te
cuesta por solicitud.

**Sobredefensa.** Muchos guardas bloquean en exceso prompts benignos que simplemente contienen palabras desencadenantes
como *ignore*, *system* o *bypass*. En [NotInject](https://huggingface.co/datasets/leolee99/NotInject)
(339 prompts benignos pero cargados de palabras desencadenantes) el núcleo de reglas tiene una **tasa de falsos positivos del 0.0%**
y 100% de precisión benigna en offline.

**Recall de evasión en patrones conocidos.** Cuando un ataque conocido se ofusca, la normalización
recupera la mayor parte:

| | Recall bajo evasión | FPR | F1 |
|---|---:|---:|---:|
| Solo regex | 21.2% | 3.3% | 0.349 |
| Núcleo (normalizar + indirecto) | 78.1% | 6.7% | 0.871 |

Esto es recall sobre *variantes ofuscadas de patrones que el núcleo ya conoce*. No es
recall sobre formulaciones novedosas — esa es la cifra del 0% mencionada arriba.

**Coste por solicitud.** Medido con `eval/latency.py` (p50/p95 por ruta de llamada, Apple M3 Pro):

| Entrada | p50 | p95 |
|---|---:|---:|
| Prompt de chat (60 caracteres) | 0.178 ms | 0.202 ms |
| Documento de 2 KB, limpio | 8.51 ms | 8.94 ms |
| Documento de 50 KB, limpio (el techo de entrada) | 211 ms | 216 ms |
| `ToolGate.authorize` (una llamada a herramienta, cualquier tamaño) | 0.020 ms | 0.021 ms |

Un proceso maneja ~5,400 prompts de chat/s y el núcleo no mantiene estado, así que escala con
procesos. La parte que conviene saber antes de desplegarlo: **la ruta de entrada es lineal en
la longitud de la entrada — unos 4.2 ms por KB para un documento limpio, 1.7 ms una vez que un patrón ya
ha coincidido.** A tamaño de chat eso es ~650x más barato que un guarda basado en modelo (ProtectAI
deberta-v3, ~116 ms); a 50 KB es *peor*, porque un transformer trunca a 512 tokens
y nosotros escaneamos todo. El cruce está alrededor de 25 KB — protege documentos enteros y pagas
por ellos. La puerta de acciones no tiene esta propiedad: lee argumentos de herramientas y confianza de segmentos, no prosa, así que es gratis a cualquier tamaño.

**El detector ML (complemento separado).** Un clasificador basado en embeddings maneja los
ataques con formulación natural que el núcleo de reglas no puede. Estos son sus números, no los del núcleo:

| Configuración | Recall | FPR | F1 |
|---|---:|---:|---:|
| Test reservado (~5.5k, datos reales combinados) | 96.1% | 0.3% | 0.978 |
| Validación cruzada de 5 particiones | 95.5% ± 0.8 | 2.5% ± 1.3 | 0.963 ± 0.010 |
| Fuera de distribución (entrenar A+B, test C no visto) | 87.6% | 10.9% | 0.882 |

Datos: `deepset/prompt-injections`, `jackhhao/jailbreak-classification`,
`xTRam1/safe-guard-prompt-injection`. Un resultado negativo que merece mencionarse: un modelo anterior
entrenado con datos sintéticos obtuvo 0.98 de F1, pero una ablación mostró que la puntuación y el uso de mayúsculas
por sí solos alcanzaban 0.96 — la puntuación era un artefacto del generador de datos. El clasificador explicable
es lo que sacó eso a la luz. La caída fuera de distribución de 0.97 a 0.88 es el
número real de generalización: se degrada, no se derrumba.

Reproduce cualquiera de ellos — agrupados por lo que cada script necesita realmente, porque desde 0.2.0
el modelo entrenado vive en el complemento y solo los benchmarks del núcleo de reglas se ejecutan contra este
repositorio por sí solo:```bash
# Offline, no key, no add-on — runs against this repo as-is:
python eval/public_bench.py     # over-defense on NotInject (339 benign)
python eval/adversarial.py      # evasion robustness of the rule core
python eval/latency.py          # cost per request: p50/p95/p99 and throughput

# Needs `pip install reasongate[eval]` and a VOYAGE_API_KEY (embeddings):
python eval/pipeline_real.py    # train/val/test with a validation-tuned threshold
python eval/validate.py         # leakage check, trivial baselines, 5-fold CV, 5x2cv

# Needs the enterprise add-on (the trained model moved there in 0.2.0):
python eval/ood_test.py         # out-of-distribution generalization
python eval/head_to_head.py     # vs ProtectAI deberta-v3

# Needs `pip install agentdojo` (Python 3.10+), no key — the action gate on AgentDojo:
python eval/agentdojo_gate.py   # ASR and utility, gate off / taint / strict