A multi-VM security lab and automated framework for evaluating firewall enforcement, IDS/IPS detection, network visibility, and security-event correlation under controlled and reproducible network conditions.
Project status: Lab operational — log pipeline and scanner scripts in progress
Environment: VirtualBox, Linux, pfSense
Primary focus: Network security testing, detection engineering, telemetry collection, and reproducible benchmarking
Every experiment follows a fixed standard. Read these in order:
| Document | Purpose |
|---|---|
docs/LAB-STANDARD.md |
Directory layout, naming, README rules, runner rules, checklist |
docs/OUTPUT-SCHEMA.md |
Exact output format, storage layout, normalized event schema |
docs/ANALYSIS.md |
How to analyze many experiments without drowning in logs |
docs/MISTAKES-AND-FIXES.md |
Known bugs and how to avoid them |
templates/ |
Copy these files when creating a new lab |
runner/README.md |
YAML-driven experiment runner |
Rules in one line: one lab per folder, one README from the template, one baseline + one variant, record UTC start/end, store raw + normalized + report.
This project builds a controlled, multi-VM security environment to evaluate how different network security controls behave under predefined and reproducible traffic conditions.
The lab integrates:
- pfSense for routing, NAT, and firewall enforcement.
- Snort and Suricata for network intrusion detection and prevention.
- Zeek for network protocol analysis and connection telemetry.
- A custom log collection pipeline for ingesting, normalizing, and storing events from pfSense, Snort, Suricata, and Zeek.
- Nmap, Scapy, and custom NSE scripts for generating controlled test traffic.
- A centralized experiment runner and analysis pipeline for correlating events.
The framework generates authorized test traffic, collects telemetry from multiple security controls, associates events with experiment IDs, and produces benchmark results.
- Evaluate firewall policy enforcement and NAT behaviour.
- Compare signature-based and behavioural network detection.
- Measure detection latency, event volume, false positives, and telemetry coverage.
- Identify and document detection, visibility, and enforcement gaps under controlled conditions.
- Develop custom detection rules and evaluate their impact.
- Automate experiments and generate reproducible reports.
- Build an extensible reconnaissance scanner around Nmap.
- Extend the lab to enterprise-style Windows/Linux/Active Directory networks.
The project is intended for authorized testing in isolated lab environments and explicitly permitted infrastructure.
Kali Linux
172.21.50.199/22
Scanner / Tests
|
| WAN network
| 172.21.48.0/22
|
+-----+------+
| pfSense |
| |
| WAN | 172.21.50.85
| LAN | 192.168.1.1/24
+-----+------+
|
| Internal LAN
| 192.168.1.0/24
|
+---------------+---------------+
| | |
+-------------+ +-------------+ +-------------+
| Victim 1 | | Innocent | | Monitor VM |
| .100 | | (Victim 2) | | .101 |
| Basic tests | | All services| | Snort |
| | | .102 | | Suricata |
+-------------+ +-------------+ | Zeek |
| Collectors |
+-------------+
| Component | Interface / Network | Address |
|---|---|---|
| Kali | eth0 / WAN network | 172.21.50.199/22 |
| pfSense WAN | WAN network | 172.21.50.85 |
| pfSense LAN | Internal LAN | 192.168.1.1/24 |
Victim 1 (ubuntu_victim_anc) |
Internal LAN | 192.168.1.100 |
Innocent (Innocent, Victim 2 — all services) |
Internal LAN | 192.168.1.102 |
| Monitor | Internal LAN / management | 192.168.1.101 |
WAN subnet: 172.21.48.0/22
Internal LAN subnet: 192.168.1.0/24
Host roles:
- Kali — authorized scanner and traffic generator.
- pfSense — router, firewall, NAT device, and log source.
- Victim 1 — minimal target used for basic reachability and service tests.
- Innocent (Victim 2) — second victim running a full service set (FTP, SSH, SMTP, DNS, HTTP, HTTPS, MySQL) so findings can be validated against a host that is not tailored to a single experiment.
- Monitor — passive sensor host running Snort, Suricata, Zeek, and the log collectors.
The addresses above describe the current lab configuration. WAN-side addresses are assigned by DHCP and may change between sessions; LAN addresses are static. Always confirm the current addresses before running an experiment.
Visibility note: the monitor observes the LAN side. Scans against pfSense's WAN IP terminate at pfSense and are not visible to the LAN sensors. To capture a scan on the monitor, either scan a victim through a pfSense port-forward or enable pfSense remote syslog to the monitor.
The monitor uses three virtual NICs with distinct purposes.
| NIC | Purpose | Attachment |
|---|---|---|
| NIC 1 | Management, SSH, updates, and log access | Dedicated management network |
| NIC 2 | Internal/LAN traffic observation | LAN-side capture network |
| NIC 3 | WAN traffic observation | WAN-side capture network |
The capture interfaces are intended for passive monitoring. Promiscuous mode alone does not guarantee visibility of unicast traffic in VirtualBox.
Packet visibility must be validated with tcpdump. Where necessary, use a
supported mirroring/TAP arrangement or an inline sensor configuration as a
separately documented experiment.
The management interface remains logically separate from monitored traffic.
| Component | Role |
|---|---|
| pfSense | Routing, firewall policy, NAT, connection enforcement, and firewall logging |
| Snort | Rule-based network intrusion detection |
| Suricata | Network IDS/IPS, signature detection, and EVE JSON event generation |
| Zeek | Network protocol analysis, connection records, and behavioural telemetry |
| Custom log collection pipeline | Collects, normalizes, and stores events from pfSense, Snort, Suricata, and Zeek |
| Nmap / Scapy | Controlled test traffic generation |
| Wireshark / tcpdump | Packet capture and protocol analysis |
| Python scripts | Experiment orchestration, event processing, and analysis |
The primary operating mode is continuous live monitoring.
Controlled Test Traffic
|
v
pfSense
Firewall / NAT Logs
|
v
Victim Services
|
v
Monitor VM
+---------+---------+
| | |
Snort Suricata Zeek
| | |
Alerts EVE JSON Protocol Logs
| | |
+---------+---------+
|
Custom Log Collector
|
v
Experiment Storage
|
v
Normalization / Analysis
|
v
Benchmark Reports
Snort, Suricata, and Zeek run as managed background services.
The custom collector ingests their output, associates events with experiment IDs, preserves raw records, and generates a common normalized event format.
- pfSense firewall logs, exported through syslog or another supported method.
- Snort alert and portscan logs.
- Suricata EVE JSON and fast log.
- Zeek connection, DNS, HTTP, TLS, and notice logs.
- Optional packet captures for selected experiments.
Packet capture is not retained continuously. PCAPs are stored selectively for important experiments, detection gaps, false positives, and rule-development investigations.
Every test run receives a unique experiment ID.
Example:
sharad/EXP-0001
reja/EXP-0001
sai_pranav/EXP-0001
The unique key is (owner, experiment_id), so each team member can run their
own EXP-0001 without collisions.
Each experiment records:
- Experiment ID and description.
- Owner.
- Source and destination systems.
- Traffic generator and version.
- Start and end UTC timestamps.
- Sensor versions and configurations.
- Enabled ruleset versions.
- Expected firewall and detection outcomes.
- Observed alerts and telemetry.
Example experiment structure:
results/
└── <owner>/
└── EXP-0001/
├── metadata.json
├── test-results.json
├── raw/
│ ├── baseline.xml
│ ├── baseline.gnmap
│ ├── baseline.nmap
│ └── ...
├── sensors/
│ ├── pfsense/
│ ├── snort/
│ ├── suricata/
│ └── zeek/
├── normalized/
│ └── events.jsonl
└── report/
└── report.md
The benchmark evaluates security-control behaviour under controlled and documented traffic conditions.
| Category | Examples |
|---|---|
| Baseline traffic | Normal HTTP, DNS, SSH, and TCP connections |
| TCP reconnaissance | Controlled SYN and targeted port scans |
| UDP reconnaissance | Controlled UDP probing |
| Service discovery | Service/version detection in the lab |
| Firewall enforcement | Allowed/blocked ports, NAT, and policy validation |
| Detection configurations | Default rules, additional rules, and custom detection |
| Enterprise environment | Windows/Linux hosts, domain services, and segmentation |
All tests are performed against lab systems or explicitly authorized targets.
| Metric | Description |
|---|---|
| Enforcement outcome | Whether the firewall allowed or blocked traffic as expected |
| Detection outcome | Whether an IDS/IPS generated an alert or notice |
| Detection latency | Time from the test event to the resulting alert |
| Telemetry coverage | Whether connection/activity records were generated |
| False positives | Alerts produced during defined benign workloads |
| Event volume | Raw event and alert counts |
| Attribution | Availability of source, destination, protocol, and port information |
| Correlation | Ability to associate events across different sensors |
| Resource usage | CPU, memory, and storage requirements |
Firewall enforcement, IDS alerts, Zeek telemetry, and normalized events are evaluated as separate outcomes.
A missing IDS alert is not automatically classified as a firewall bypass or security-control failure. The expected outcome and relevant control policy must be defined for each test.
The project evaluates existing rulesets before introducing custom rules.
Planned work:
- Establish a baseline using the installed Snort and Suricata rulesets.
- Record ruleset versions and enabled detection configurations.
- Evaluate existing scan-related detection and behavioural policies.
- Develop custom rules for predefined lab traffic patterns.
- Compare detection coverage, alert volume, and false positives before and after changes.
- Document conditions under which each detector does or does not generate an event.
The goal is to understand detection behaviour and improve detection quality, not to assume that a single rule can identify every scanning tool.
Repository layout:
adv_network_scanner/
├── docs/
├── templates/
├── runner/
├── labs/
├── results/
│ └── <owner>/
│ └── EXP-XXXX/
├── old_scripts/
└── README.md
The collector preserves raw logs and creates normalized JSONL events.
A normalized event may contain:
{
"experiment_id": "EXP-0001",
"timestamp": "...",
"sensor": "suricata",
"event_type": "alert",
"src_ip": "...",
"src_port": 0,
"dest_ip": "...",
"dest_port": 0,
"protocol": "TCP",
"signature": "...",
"severity": null
}This is the proposed common schema. Sensor-specific fields are retained in the raw records or an additional metadata field to avoid losing information.
Log rotation, retention limits, and disk usage monitoring prevent unbounded
storage growth. See docs/ANALYSIS.md for the three-tier
data model and retention rules.
| Area | Status | Notes |
|---|---|---|
| Lab setup (VirtualBox, pfSense, victims, monitor) | ✅ Done | Routing, NAT, and LAN topology working |
| Snort deployment | ✅ Done | Running on monitor; portscan detection verified |
| Suricata deployment | ✅ Done | EVE JSON and fast.log verified |
| Zeek deployment | ✅ Done | Running; conn.log verified |
| NSE script library | 🟡 In progress | LAB-NSE-06/08/09 drafted and tested |
| Custom log collection pipeline | 🟡 In progress | Collectors and normalization being built |
| Experiment runner | 🟡 Partially done | YAML runner and summarizer work; automated sensor collection pending |
| Benchmark reports | ⬜ Planned | Report generator not yet built |
| Detection rule tuning | ⬜ Planned | Depends on baseline experiments |
| Enterprise lab extension | ⬜ Planned | Windows/Linux/AD environment |
| Person | Responsibility |
|---|---|
| 1 | pfSense + Snort + victim: setup, firewall rules, authorized scans, and firewall/IDS/victim log collection |
| 2 | pfSense + Suricata + victim: setup, rules, tests, and log/alert collection |
| 3 | Zeek + log collection: deploy Zeek, verify protocol logs, and collect network events |
| 4 | Scanning & Analysis: Nmap/Scapy scripts, automated experiments, packet analysis, and detection benchmarking |
| 5 | Log pipeline generation and analysis of the experiments |
- Establish the VirtualBox lab and pfSense routing/NAT.
- Configure Snort as a managed service and verify alert logging.
- Configure Suricata and verify EVE JSON output.
- Install and configure Zeek for live monitoring.
- Validate packet visibility on the LAN monitor interface.
- Build the initial NSE script library (LAB-NSE-06, 08, 09).
- Implement per-owner experiment storage and the YAML runner.
- Finalize the custom log collection pipeline.
- Add automated sensor log collection to the runner.
- Normalize Snort, Suricata, Zeek, and pfSense events.
- Complete baseline and variant experiments.
- Generate benchmark reports.
- Evaluate and develop custom detection rules.
- Extend the lab to enterprise-style Windows/Linux/AD networks.
- Package the reconnaissance framework as a reusable scanner.
Advanced Modular Network Reconnaissance Scanner
An extensible reconnaissance framework built around Nmap that automates network discovery, service enumeration and protocol-specific reconnaissance through custom scripts and configurable scan workflows.
To be decided.