# PTES Passive Reconnaissance AI Agent

> **Agente Autónomo de Inteligencia Pasiva y Reconocimiento OSINT alineado con la metodología PTES (Penetration Testing Execution Standard).**

---

## 🎯 Concepto del Agente

El **PTES Passive Reconnaissance AI Agent** es una solución avanzada de ciberseguridad impulsada por Inteligencia Artificial, diseñada para automatizar y estandarizar la **Fase 2 (Reconocimiento e Inteligencia Pasiva)** del marco PTES[cite: 2].

A diferencia de los escáneres tradicionales, este agente utiliza un enfoque basado en **orquestación por grafos de estado (LangGraph)** y **mecanismos de control estricto (Guardrails)**. Su objetivo principal es recolectar, estructurar y almacenar información de fuentes abiertas (OSINT) sobre infraestructuras o entidades objetivo sin realizar interacción directa no autorizada ni escaneos activos que puedan ser detectados o violar normativas legales.

---

## 🤖 Tipo de Agente y Función Principal

### Tipo de Agente
* **Categoría:** Agente Cognitivo de Seguridad / OSINT Orchestrator Agent.
* **Modelo de Control:** Determinista guiado por grafos de estado (**LangGraph State Graph**).
* **Paradigma de Memoria:** Memoria a largo plazo vectorial distribuida (**ChromaDB**).
* **Arquitectura de Herramientas:** Servidor extensible mediante el protocolo estándar **MCP (Model Context Protocol)**.

### Función Principal
1. **Onboarding & Gobierno de Alcance:** Clasifica el activo objetivo (*infraestructura de red* o *entidad/persona*) y genera un archivo JSON formal de Reglas de Compromiso (**RoE / Rules of Engagement**)[cite: 2].
2. **Validación de Seguridad (Guardrails):** Garantiza que ninguna operación se ejecute fuera de los dominios o rangos IP explícitamente autorizados mediante su motor `ScopeEnforcer`[cite: 2].
3. **Recolección Pasiva (OSINT):** Agrega datos de inteligencia pasiva (descubrimiento de subdominios, registros corporativos, huellas digitales)[cite: 2].
4. **Persistencia Vectorial:** Indexa y convierte las evidencias en *embeddings* para permitir consultas contextuales y búsquedas semánticas en fases posteriores del análisis[cite: 2].

---

## 💡 Casos de Uso

* **Equipos de Red Team & Pentesting:** Automatización de la fase inicial de footprinting reduciendo tiempos de recolección de horas a segundos.
* **Equipos de Blue Team & Threat Intelligence:** Identificación de la superficie de ataque expuesta (*External Attack Surface Management - EASM*) antes de que sea explotada por terceros.
* **Auditorías de Cumplimiento e Infraestructura:** Verificación de la huella digital pasiva corporativa bajo alineación estricta de alcance legal.

---

## 🏗️ Estructura del Proyecto

├── src/
│   ├── agent/
│   │   ├── onboarding.py          # Clasificación de objetivos y generación automática de RoE
│   │   ├── state.py               # Definición del esquema de estado del agente (TypedDict)
│   │   ├── guardrails.py          # ScopeEnforcer: Validación de límites de IP/FQDN autorizados
│   │   ├── memory_manager.py      # Conector y gestor de persistencia en ChromaDB
│   │   └── graph_orchestrator.py  # Orquestador del flujo condicional mediante LangGraph
│   └── mcp_server/
│       └── passive_dorks_server.ts # Servidor TypeScript basado en MCP para herramientas pasivas
├── tests/                         # Pruebas unitarias y de validación de guardrails
├── scope/                         # Directorio donde se almacenan los archivos RoE generados
├── docker-compose.yml             # Configuración de despliegue en contenedores
├── Dockerfile                     # Construcción de entorno híbrido (Python + Node.js)
├── requirements.txt               # Dependencias de Python
└── package.json                   # Dependencias y scripts de TypeScript/MCP

---

## 🚀 Puesta en Marcha Rápida

### Requisitos Previos
* **Python** 3.11+
* **Node.js** v18+ y `npm`

### 1. Instalación Local

# Clone el repositorio
git clone <URL_DEL_REPOSITORIO>
cd ptes-passive-recon-agent

# Instale dependencias de Python y Node.js
pip install -r requirements.txt
npm install && npm run build

### 2. Configuración de Variables de Entorno

Copie el archivo de ejemplo y configure sus llaves de API:

cp .env.example .env

### 3. Ejecución del Agente

Ejecute el orquestador principal para iniciar la sesión interactiva de CLI[cite: 2]:

python src/agent/graph_orchestrator.py

### 4. Ejecución con Docker Compose

Si prefiere ejecutar el entorno completamente aislado[cite: 2]:

docker-compose up --build -d