# urban20/scannerip architecture

> Architecture diagram of the GitHub repository urban20/scannerip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urban20/scannerip
- Repository: https://github.com/urban20/scannerip

## Overview

1. **Propósito general**
   - Scip3 es una herramienta de reconocimiento de redes y OSINT orientada a escaneo de hosts, enumeración de puertos, fingerprinting de servicios y consulta de reputación/exposición pública vía Shodan.
   - El repositorio está organizado como una aplicación de línea de comandos, no como un servicio web.

2. **Punto de entrada y orquestación**
   - `src/scip3.py` actúa como entrypoint principal.
   - Su rol es interpretar argumentos, decidir el modo de operación y coordinar los módulos de escaneo, OSINT, salida y persistencia.

3. **Capa de configuración y parámetros**
   - `src/params.py` y `src/opciones.json` concentran la definición/lectura de parámetros de ejecución.
   - Esta capa determina cosas como modo normal/agresivo/SYN/descubrimiento, cantidad de hilos, timeout, rango de puertos y flags de salida.

4. **Motor de escaneo, dividido por estrategia**
   - `src/escaneos/lineales.py` parece cubrir escaneos secuenciales o “normales”.
   - `src/escaneos/agresivo.py` implementa el modo concurrente con multihilos.
   - `src/escaneos/scapy_escan.py` cubre el escaneo SYN/ACK de bajo nivel, dependiente de Scapy y de privilegios en Linux.
   - Esta separación sugiere un boundary claro: el orquestador elige un motor y cada motor encapsula su propia forma de sondear puertos.

5. **Pipeline de descubrimiento y fingerprinting**
   - `src/fingerprint.py` se usa para inferir servicios o dispositivos a partir de respuestas de red y payloads.
   - `src/data.py`, junto con archivos JSON bajo `src/json/`, aporta tablas auxiliares para mapear puertos, estados y TTLs.
   - En la arquitectura, esto funciona como una etapa posterior al escaneo: primero se detecta apertura/estado y luego se intenta clasificar el servicio o sistema.

6. **Descubrimiento de red y OSINT**
   - El README describe un modo de descubrimiento de red (`-d`) que identifica hosts activos y, en Linux, puede inferir fabricante por MAC, hostname y sistema operativo por TTL.
   - También existe un modo OSINT con Shodan (`-s`) para geolocalización, reputación, histórico de puertos y URLs asociadas.
   - Shodan es la única dependencia externa claramente central en la arquitectura de inteligencia de red.

7. **Modelo de objetos y utilidades compartidas**
   - `src/objetos.py` probablemente define estructuras de datos para hosts, puertos, resultados y metadatos.
   - `src/func.py` concentra utilidades transversales: formateo, validación, conversión, filtrado o helpers de red.
   - Estas piezas reducen acoplamiento entre el CLI, los motores de escaneo y la persistencia.

8. **Persistencia y gestión de resultados**
   - `src/archivos/archivos.py` maneja lectura/escritura de resultados e ისტორiales.
   - El README menciona persistencia en TXT, generación de informes personalizados, apertura de sesiones previas y borrado de historial.
   - En términos de arquitectura, este es el boundary de salida: los escáneres producen hallazgos y el subsistema de archivos los materializa.

9. **Tablas y catálogos de apoyo**
   - Los JSON en `src/json/` (`puertos.json`, `data_puertos.json`, `status.json`, `ttl.json`) actúan como catálogos locales.
   - Su función es mapear puertos conocidos, estados de escaneo y heurísticas de TTL, evitando lógica hardcodeada en el motor.
   - Esto sugiere una arquitectura de reconocimiento apoyada en lookup tables estáticas más que en servicios internos.

10. **Separación por plataforma**
   - El proyecto apunta a Windows, Linux y Termux, pero algunas capacidades son específicas de Linux, especialmente el modo SYN y parte del descubrimiento de red.
   - Esa diferencia de plataforma es importante para el diagrama: no todos los módulos se ejecutan en todos los entornos con la misma capacidad.

11. **Flujo principal de datos**
   - Entrada del usuario en CLI → parsing de opciones → selección del modo → ejecución del motor de escaneo/OSINT → enriquecimiento con tablas JSON y fingerprinting → formateo de salida → persistencia/log.
   - En paralelo, cuando se usa `-s`, el flujo se desvía hacia Shodan para enriquecer el objetivo con datos externos antes o durante la presentación de resultados.

12. **Límites arquitectónicos relevantes**
   - No hay señales de backend persistente, base de datos relacional o API propia.
   - El sistema es básicamente un toolkit local, centrado en ejecución interactiva, acceso a red, consumo de APIs externas y escritura de resultados en disco.
   - Su complejidad está en los modos de escaneo y el enriquecimiento de datos, no en infraestructura de despliegue.

Main entry points: [`src/scip3.py`](https://github.com/urban20/scannerip/blob/main/src/scip3.py) (scip3.py), [`src/fingerprint.py`](https://github.com/urban20/scannerip/blob/main/src/fingerprint.py) (fingerprint.py), [`src/objetos.py`](https://github.com/urban20/scannerip/blob/main/src/objetos.py) (objetos.py), [`src/escaneos/lineales.py`](https://github.com/urban20/scannerip/blob/main/src/escaneos/lineales.py) (Lineales)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & control"]
  node_src_scip3["scip3.py<br/>entrypoint<br/>[scip3.py]"]
  node_src_params["params.py<br/>config<br/>[params.py]"]
  node_src_opciones["opciones.json<br/>options<br/>[opciones.json]"]
end

subgraph group_scan["Scanning"]
  node_src_lineales["Lineales<br/>scan engine<br/>[lineales.py]"]
  node_src_agresivo["Agresivo<br/>scan engine<br/>[agresivo.py]"]
  node_src_scapy["Scapy scan<br/>syn scanner<br/>[scapy_escan.py]"]
end

subgraph group_intel["Enrichment"]
  node_src_fingerprint["fingerprint.py<br/>fingerprinter<br/>[fingerprint.py]"]
  node_src_data["data.py<br/>mapping layer<br/>[data.py]"]
  node_src_usuarios["objetos.py<br/>models<br/>[objetos.py]"]
  node_src_func["func.py<br/>helpers<br/>[func.py]"]
end

subgraph group_store["Results"]
  node_src_archivos["archivos.py<br/>persistence<br/>[archivos.py]"]
end

subgraph group_data["Lookup data"]
  node_src_puertos["puertos.json<br/>port catalog<br/>[puertos.json]"]
  node_src_data_puertos["data_puertos.json<br/>port data<br/>[data_puertos.json]"]
  node_src_status["status.json<br/>status map<br/>[status.json]"]
  node_src_ttl["ttl.json<br/>ttl map<br/>[ttl.json]"]
end

node_src_scip3 -->|"loads"| node_src_params
node_src_scip3 -->|"selects"| node_src_lineales
node_src_scip3 -->|"selects"| node_src_agresivo
node_src_scip3 -->|"selects"| node_src_scapy
node_src_scip3 -->|"enriches"| node_src_fingerprint
node_src_scip3 -->|"persists"| node_src_archivos
node_src_params -->|"reads"| node_src_opciones
node_src_lineales -->|"uses"| node_src_data
node_src_agresivo -->|"uses"| node_src_data
node_src_scapy -->|"uses"| node_src_data
node_src_lineales -->|"builds"| node_src_usuarios
node_src_agresivo -->|"builds"| node_src_usuarios
node_src_scapy -->|"builds"| node_src_usuarios
node_src_fingerprint -->|"looks up"| node_src_puertos
node_src_fingerprint -->|"looks up"| node_src_data_puertos
node_src_fingerprint -->|"maps"| node_src_status
node_src_fingerprint -->|"infers"| node_src_ttl
node_src_fingerprint -->|"uses"| node_src_func
node_src_archivos -->|"stores"| node_src_usuarios
node_src_archivos -->|"uses"| node_src_func
node_src_scip3 -->|"orchestrates"| node_src_usuarios
node_src_scip3 -->|"uses"| node_src_func

click node_src_scip3 "https://github.com/urban20/scannerip/blob/main/src/scip3.py"
click node_src_params "https://github.com/urban20/scannerip/blob/main/src/params.py"
click node_src_opciones "https://github.com/urban20/scannerip/blob/main/src/opciones.json"
click node_src_lineales "https://github.com/urban20/scannerip/blob/main/src/escaneos/lineales.py"
click node_src_agresivo "https://github.com/urban20/scannerip/blob/main/src/escaneos/agresivo.py"
click node_src_scapy "https://github.com/urban20/scannerip/blob/main/src/escaneos/scapy_escan.py"
click node_src_fingerprint "https://github.com/urban20/scannerip/blob/main/src/fingerprint.py"
click node_src_data "https://github.com/urban20/scannerip/blob/main/src/data.py"
click node_src_usuarios "https://github.com/urban20/scannerip/blob/main/src/objetos.py"
click node_src_func "https://github.com/urban20/scannerip/blob/main/src/func.py"
click node_src_archivos "https://github.com/urban20/scannerip/blob/main/src/archivos/archivos.py"
click node_src_puertos "https://github.com/urban20/scannerip/blob/main/src/json/puertos.json"
click node_src_data_puertos "https://github.com/urban20/scannerip/blob/main/src/json/data_puertos.json"
click node_src_status "https://github.com/urban20/scannerip/blob/main/src/json/status.json"
click node_src_ttl "https://github.com/urban20/scannerip/blob/main/src/json/ttl.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_scip3,node_src_params,node_src_opciones toneBlue
class node_src_lineales,node_src_agresivo,node_src_scapy toneAmber
class node_src_fingerprint,node_src_data,node_src_usuarios,node_src_func toneMint
class node_src_archivos toneRose
class node_src_puertos,node_src_data_puertos,node_src_status,node_src_ttl toneIndigo
```

## Components

### CLI & control

Command-line entrypoint, option handling, and shared runtime settings.

- [scip3.py](https://github.com/urban20/scannerip/blob/main/src/scip3.py): entrypoint · Main CLI entrypoint that parses arguments and orchestrates execution. · `src/scip3.py`
- [params.py](https://github.com/urban20/scannerip/blob/main/src/params.py): config · Runtime parameter definitions and option loading. · `src/params.py`
- [opciones.json](https://github.com/urban20/scannerip/blob/main/src/opciones.json): options · Serialized execution options and defaults. · `src/opciones.json`

### Scanning

Port scanning strategies and low-level probing engines.

- [Lineales](https://github.com/urban20/scannerip/blob/main/src/escaneos/lineales.py): scan engine · Sequential or normal scanning mode. · `src/escaneos/lineales.py`
- [Agresivo](https://github.com/urban20/scannerip/blob/main/src/escaneos/agresivo.py): scan engine · Concurrent multithreaded scanning mode. · `src/escaneos/agresivo.py`
- [Scapy scan](https://github.com/urban20/scannerip/blob/main/src/escaneos/scapy_escan.py): syn scanner · Low-level SYN/ACK probing path for Linux and privileged execution. · `src/escaneos/scapy_escan.py`

### Enrichment

Fingerprinting, discovery heuristics, and external OSINT lookup.

- [fingerprint.py](https://github.com/urban20/scannerip/blob/main/src/fingerprint.py): fingerprinter · Service and device inference from network responses. · `src/fingerprint.py`
- [data.py](https://github.com/urban20/scannerip/blob/main/src/data.py): mapping layer · Shared lookup and enrichment helpers for scan results. · `src/data.py`
- [objetos.py](https://github.com/urban20/scannerip/blob/main/src/objetos.py): models · Core result and host objects shared across modules. · `src/objetos.py`
- [func.py](https://github.com/urban20/scannerip/blob/main/src/func.py): helpers · Cross-cutting utility functions used by scanning and output code. · `src/func.py`

### Results

Persistence, reporting, and session/history handling.

- [archivos.py](https://github.com/urban20/scannerip/blob/main/src/archivos/archivos.py): persistence · Read/write of results, history, and saved sessions. · `src/archivos/archivos.py`

### Lookup data

Static catalogs used to map ports, statuses, and TTL heuristics.

- [puertos.json](https://github.com/urban20/scannerip/blob/main/src/json/puertos.json): port catalog · Known port catalog for enrichment and presentation. · `src/json/puertos.json`
- [data_puertos.json](https://github.com/urban20/scannerip/blob/main/src/json/data_puertos.json): port data · Additional port metadata used during classification. · `src/json/data_puertos.json`
- [status.json](https://github.com/urban20/scannerip/blob/main/src/json/status.json): status map · State labels and scan-status mapping. · `src/json/status.json`
- [ttl.json](https://github.com/urban20/scannerip/blob/main/src/json/ttl.json): ttl map · TTL heuristics for host and OS inference. · `src/json/ttl.json`

## Connections

- scip3.py → params.py: loads · Entrypoint reads runtime parameters and mode selection.
- scip3.py → Lineales: selects · Routes normal scans to the sequential engine.
- scip3.py → Agresivo: selects · Routes aggressive scans to the concurrent engine.
- scip3.py → Scapy scan: selects · Routes low-level SYN scanning to the Scapy path.
- scip3.py → fingerprint.py: enriches · Coordinates fingerprinting after probe results are available.
- scip3.py → archivos.py: persists · Sends final results and session actions to storage.
- params.py → opciones.json: reads · Option definitions and defaults are stored in JSON.
- Lineales → data.py: uses · Sequential scan consults shared enrichment helpers.
- Agresivo → data.py: uses · Concurrent scan consults shared enrichment helpers.
- Scapy scan → data.py: uses · Low-level scan consults shared enrichment helpers.
- Lineales → objetos.py: builds · Produces host and port result objects.
- Agresivo → objetos.py: builds · Produces host and port result objects.
- Scapy scan → objetos.py: builds · Produces host and port result objects.
- fingerprint.py → puertos.json: looks up · Maps observed ports to known services.
- fingerprint.py → data_puertos.json: looks up · Uses auxiliary port metadata for classification.
- fingerprint.py → status.json: maps · Normalizes scan outcomes to status labels.
- fingerprint.py → ttl.json: infers · Uses TTL heuristics for network and OS hints.
- fingerprint.py → func.py: uses · Shares formatting and transformation helpers.
- archivos.py → objetos.py: stores · Persists structured results and sessions.
- archivos.py → func.py: uses · Relies on helpers for formatting and validation.
- scip3.py → objetos.py: orchestrates · Main flow passes structured results between stages.
- scip3.py → func.py: uses · CLI layer uses shared utility helpers.
