Skip to main content

​
Prerequisites

Before starting, confirm the following:
  • All Python dependencies installed (see Installation)
  • Npcap is installed and active on Windows
  • The five model .pkl files are present in the project root
  • You are running the terminal as Administrator (required for IPS blocking)
Run your terminal as Administrator. Without elevated privileges, IPS blocking falls back to simulated mode — the dashboard will show “Bloqueo simulado” in the IPS panel instead of applying real firewall rules.

​
Launch and monitor

1

Start the GUI

Launch the main dashboard from the project root:
python interfasc.py
The PyQt5 window opens with several tabs: the main events table, a live traffic panel, SOC metrics, charts, and the IPS response panel.
2

Select your network interface and start monitoring

In the dashboard toolbar, find the interface dropdown (a QComboBox listing your available network adapters, e.g. Ethernet, Wi-Fi).Select your active interface and click Iniciar Monitoreo.The status bar at the bottom will confirm the sniffer is active. The AsyncSniffer from Scapy starts capturing all IP traffic on the selected interface in a background thread.
If you leave the dropdown on the default selection, Scapy uses the system’s default interface (conf.iface). Explicitly selecting your interface is recommended to avoid capturing on a wrong adapter.
3

Observe live traffic and detected events

Two panels update in real time:
  • Tráfico en Vivo — Shows a rolling summary of every captured packet (e.g. Ether / IP / TCP 192.168.1.5:54321 > 10.0.0.1:80 S). Limited to the last 500 lines.
  • Events table — Shows only detected intrusions, with columns for timestamp, source IP, destination IP, port, protocol, flag, and attack type.
Detected events appear in the table with labels such as:
Example labelMeaning
SYN Flood (ML: 98.4%)ML classified with high confidence
Escaneo de Puertos (Heurística)Heuristic rule triggered; ML confidence below 70%
Posible Exploit (ML: 73.2%)ML-confirmed exploit attempt
Each attack type is color-coded in the table for quick visual triage.
4

Enable IPS mode

Toggle the IPS checkbox in the dashboard toolbar to activate automatic IP blocking.When IPS mode is active:
  • Attacks classified with ML confidence ≥ 70% trigger a real firewall block.
  • Attacks detected by heuristic rules (critical severity: Exploit, SYN Flood, DDoS) are blocked immediately, regardless of ML confidence.
  • Each blocked IP appears in the IPS panel with a 60-second countdown timer. The row turns “Expirado” automatically when the block expires.
  • A Telegram alert is sent asynchronously for every detected event (requires Telegram configuration).
You can click Desbloquear on any row in the IPS panel to manually release a blocked IP. The row is marked blue (“Desbloqueado”) rather than deleted, keeping a visible audit trail.
5

Test detection with the attack simulator

In a separate terminal (also run as Administrator), launch the attack simulator:
python simular_varios_ataques.py
At the prompt, choose option 1 (Port Scan) for the fastest visible detection:
========================================
[*] SIMULADOR DE ATAQUES PARA IDS (MACHINE LEARNING)
========================================
Elige el ataque a simular:
1) Escaneo de Puertos (Port Scan)
2) DDoS Distribuido (Múltiples IPs origen)
3) UDP Flood (Tráfico saturado DNS/Juegos)
4) Posible Exploit (Conexiones a SMB, RDP, FTP, SSH)

Opción [1-4]: 1
The simulator sends 999 TCP SYN packets to sequential ports from a spoofed source IP (192.168.100.5) using Layer 2 (sendp), ensuring the packets are visible to the Windows Npcap driver.Within seconds you should see the event Escaneo de Puertos (Heurística) or Escaneo de Puertos (ML: XX%) appear in the events table. If IPS mode is enabled, the spoofed IP is blocked and appears in the IPS panel.
The simulator uses IP spoofing (random or fixed fake source IPs) on each run. This prevents the IDS from silently skipping events because the same IP was already blocked from a previous test run.

​
Programmatic usage

You can control the IDS engine directly from Python without the GUI by importing ids.py: 
import ids
import time

# Enable IPS blocking mode (optional)
ids.ips_activo = True

# Start capture on a specific interface
# Pass iface=None to use Scapy's system default (conf.iface)
ids.iniciar_monitoreo(iface="Ethernet")

# Run for 30 seconds
time.sleep(30)

# Stop capture and release the socket
ids.detener_monitoreo()
The ComunicadorIDS signals (nuevo_evento, nuevo_bloqueo, nuevo_trafico) are PyQt5 pyqtSignal objects. To consume them outside a Qt application you need a running QApplication event loop, or you can read from ids.eventos_detectados (a deque) directly after capture.

​
What to expect

After a successful Port Scan test:
  1. The events table shows one or more rows with Escaneo de Puertos.
  2. If IPS is enabled, the IPS panel shows the spoofed IP (192.168.100.5) with a 60-second countdown.
  3. A Telegram message is dispatched (if configured) with the source IP, protocol, and port.
  4. The event is persisted to intrusiones.db (SQLite) and appended to the CSV dataset for future model retraining.

Build docs developers (and LLMs) love

Get started for freeTalk to us