CodeAlpha Cyber Security Internship · Task 4
Suricata-based Network Intrusion Detection System with custom detection rules,
EVE JSON analysis, and automated testing.
Overview • Architecture • Features • Quick Start • Detection Rules • Evidence • Security & Privacy
Authorized-use notice: This project is a defensive, educational NIDS demonstration. Use it only on systems, interfaces, traffic, and networks that you own or have explicit permission to monitor.
The CodeAlpha Network Intrusion Detection System (NIDS) is a lightweight, defensive security project built around Suricata and Python.
It demonstrates an end-to-end intrusion-detection workflow:
Authorized Lab Traffic
│
▼
Suricata IDS
│
▼
Custom Detection Rules
rules/local.rules
│
▼
Alert Match
│
┌───┴──────────────┐
│ │
▼ ▼
fast.log EVE JSON
│
▼
Python Alert Analyzer
│
▼
Sanitized Alert Summary
│
▼
Reports / Evidence
The project is intentionally scoped for an educational laboratory environment. It focuses on transparent rule logic, structured alert output, repeatable analysis, and evidence-based verification rather than enterprise-scale deployment.
This project was developed to demonstrate that a small NIDS workflow can:
- monitor authorized network traffic with Suricata
- detect selected network activity with custom signatures
- generate structured alerts in EVE JSON
- analyze alert metadata programmatically with Python
- validate the analysis component with automated tests
- document security considerations and limitations
- preserve evidence while keeping sensitive runtime telemetry out of the public repository
┌──────────────────────────────┐
│ Authorized Lab │
│ Network Traffic │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ Npcap / PCAP │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ Suricata │
│ IDS Engine │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ rules/local.rules │
│ Custom Signatures │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ Detection Alert │
└──────────────┬───────────────┘
│
┌──────┴──────┐
▼ ▼
fast.log EVE JSON
│
▼
┌──────────────────┐
│ Python Analyzer │
│ analyze_alerts.py│
└────────┬─────────┘
│
▼
reports/alert_summary.json
Configure HOME_NET
↓
Load custom rules
↓
Validate Suricata configuration
↓
Start IDS monitoring
↓
Generate authorized test traffic
↓
Confirm detection alert
↓
Inspect EVE JSON / fast.log
↓
Analyze alerts with Python
↓
Run automated tests
↓
Capture and sanitize evidence
- Suricata-based signature detection
$HOME_NET-scoped custom rules- IDS/passive monitoring workflow
- Live Npcap/PCAP capture support
- Offline authorized PCAP analysis
The current rule set demonstrates detection of:
- ICMP echo-request activity
- repeated TCP SYN activity as a reconnaissance indicator
- TCP SYN activity toward ports
22and3389 - TCP NULL-scan indicators
Suricata can produce:
- EVE JSON for machine-readable processing
fast.logfor human-readable alert review- runtime statistics and engine logs
analysis/analyze_alerts.py provides:
- total alert counts
- signature frequency
- severity distribution
- alert categories
- top source IPs
- top destination IPs
- protocol distribution
- optional JSON summary generation
The project includes:
- automated pytest coverage
- Suricata configuration validation
- custom-rule validation
- analyzer import validation
- EVE JSON analysis
- controlled alert-generation evidence
| Component | Technology |
|---|---|
| NIDS Engine | Suricata 8.0.6 |
| Packet Capture | Npcap / PCAP |
| Detection Rules | Suricata rule syntax |
| Alert Format | EVE JSON |
| Alert Analysis | Python |
| Testing | pytest |
| Configuration | YAML |
| Version Control | Git / GitHub |
| Documentation | Markdown |
CodeAlpha_NetworkIntrusionDetectionSystem/
│
├── analysis/
│ ├── analyze_alerts.py
│ └── README.md
│
├── config/
│ └── suricata.yaml
│
├── logs/
│ └── README.md
│
├── reports/
│ ├── alert_summary.json
│ ├── DETECTION_RULES.md
│ ├── SECURITY_REVIEW.md
│ └── TEST_RESULTS.md
│
├── rules/
│ └── local.rules
│
├── screenshots/
│ ├── 00_project_banner.png
│ ├── 01_suricata_setup.png
│ ├── 02_rule_loaded.png
│ ├── 03_alert_generated.png
│ ├── 04_eve_analysis.png
│ ├── 05_tests_passed.png
│ └── README.md
│
├── tests/
│ └── test_alert_analysis.py
│
├── tools/
│ └── run_nids_test.py
│
├── .gitignore
├── LICENSE
├── README.md
└── requirements.txt
| Directory | Responsibility |
|---|---|
analysis/ |
Python-based EVE JSON alert analysis |
config/ |
Project-specific Suricata configuration |
logs/ |
Local runtime output guidance |
reports/ |
Detection, security, and test documentation |
rules/ |
Custom Suricata signatures |
screenshots/ |
Visual execution evidence |
tests/ |
Automated tests |
tools/ |
Project-level validation helper |
Generated runtime telemetry, packet captures, Python caches, and temporary files are intentionally excluded from the public repository.
Install:
- Python 3.x
- Suricata 8.0.6 for the validated demonstration environment
- Npcap on Windows when using live packet capture
- pytest
- Git
cd CodeAlpha_NetworkIntrusionDetectionSystempython -m pip install -r requirements.txtpython -m pytest --versionsuricata --build-infoFor the validated Windows environment:
suricata -T -c "C:\Program Files\Suricata\suricata.yaml"A successful validation ends with:
Configuration provided was successfully loaded. Exiting.
The project-specific configuration is:
config/suricata.yaml
Set HOME_NET to the CIDR of the authorized lab network.
Example:
vars:
address-groups:
HOME_NET: "[192.168.56.0/24]"
EXTERNAL_NET: "!$HOME_NET"The example is documentation-only. Replace it with the correct range for your authorized environment.
The project rule file is:
rules/local.rules
The configuration is designed to load it through:
default-rule-path: ./rules
rule-files:
- local.rulesStructured alerts are consumed from:
logs/eve.json
Raw runtime files are intended to remain local.
The project reserves the local SID range:
1000000-1000999
Current signatures:
| SID | Detection | Classification | Revision |
|---|---|---|---|
| 1000001 | ICMP echo request | misc-activity |
1 |
| 1000002 | Repeated TCP SYN activity | attempted-recon |
1 |
| 1000003 | TCP SYN activity toward ports 22/3389 | misc-activity |
2 |
| 1000004 | TCP NULL-scan indicator | attempted-recon |
1 |
SID 1000003 is currently revision 2 and uses explicit to_server direction.
Full rule documentation is available in
reports/DETECTION_RULES.md.
These signatures are detection indicators, not automatic proof of malicious activity.
ICMP alert
≠
confirmed attack
SYN-scan indicator
≠
confirmed compromise
Context, host behavior, timing, and additional telemetry are required for meaningful investigation.
suricata -T -c "C:\Program Files\Suricata\suricata.yaml"Use the actual authorized Npcap/PCAP device identifier accepted by the installed Suricata build:
suricata -c "C:\Program Files\Suricata\suricata.yaml" -l ".\logs" -i "<AUTHORIZED_NPCAP_DEVICE>"Do not assume that a Windows InterfaceIndex such as 7 is a valid Suricata
capture identifier.
suricata -c "C:\Program Files\Suricata\suricata.yaml" -l ".\logs" -r "<AUTHORIZED_CAPTURE.pcap>"Depending on the active configuration, local runtime files can include:
logs/eve.json
logs/fast.log
logs/stats.log
logs/suricata.log
These are generated telemetry and should remain local unless deliberately reviewed and sanitized.
The Python analyzer is:
analysis/analyze_alerts.py
python analysis\analyze_alerts.py "logs\eve.json"python analysis\analyze_alerts.py "logs\eve.json" --output "reports\alert_summary.json"The analyzer reports:
Total alerts
Alerts by signature
Alerts by severity
Alerts by category
Top source IPs
Top destination IPs
Alerts by protocol
It processes alert metadata and does not execute commands represented in the input data or modify the source EVE JSON.
Run:
python -m pytest -qValidated project result:
12 passed
Run:
python tools\run_nids_test.pyValidated result:
[PASS] Project structure
[PASS] Custom rule file
[PASS] Python analyzer import
[PASS] Automated tests
Validation summary: 4/4 checks passed
All selected validation checks passed.
python tools\run_nids_test.py --validate-suricatapython tools\run_nids_test.py --eve "logs\eve.json"python tools\run_nids_test.py --validate-suricata --eve "logs\eve.json"Use actual runtime output when documenting results. Do not replace real execution results with fabricated output.
The project includes a complete visual evidence chain.
Shows the validated Suricata installation/build information and live-capture environment.
Shows successful Suricata configuration/rule validation.
Shows authorized ICMP traffic triggering the project signature:
SID 1000001
CODEALPHA NIDS - ICMP echo request observed
The evidence also shows the alert being recorded in Suricata output and EVE JSON.
Shows Python processing Suricata EVE JSON.
The demonstrated analysis includes:
Total alerts: 4
Signature: CODEALPHA NIDS - ICMP echo request observed
Severity: 3
Category: Misc activity
Protocol: ICMP
Shows the validated automated test and project-verification results:
12 passed
4/4 validation checks passed
These screenshots are intended to document actual execution in an authorized lab environment.
Do not fabricate:
- terminal output
- alert records
- test results
- screenshots
- runtime metrics
Detailed documentation for all custom SIDs, rule logic, revisions, classification, tuning considerations, and limitations.
Documents the security review scope, configuration review, detection coverage, privacy considerations, findings, and final assessment.
Documents automated tests, Suricata validation, controlled detection testing, EVE JSON verification, and evidence requirements.
Machine-readable summary of the demonstrated alert-analysis results.
The raw EVE JSON and raw Suricata logs from the live demonstration are not published.
This repository is intended for educational and portfolio use.
Do not commit:
- raw production traffic
- private packet captures
- credentials
- API keys
- authentication tokens
- sensitive payload data
- unnecessary internal network details
- raw EVE JSON
- raw Suricata runtime logs
- Python cache directories
The public file:
reports/alert_summary.json
uses documentation-safe IP addresses instead of the private LAN addresses used during the local demonstration.
Publication note: The structured alert report is sanitized for public release. The evidence screenshots were captured during an authorized local lab test and may contain the original lab addresses used during execution.
Before committing:
git status --shortVerify generated runtime files are ignored:
git check-ignore -v `
".pytest_cache" `
"analysis\__pycache__" `
"tests\__pycache__" `
"tools\__pycache__" `
"logs\eve.json" `
"logs\fast.log" `
"logs\stats.log" `
"logs\suricata.log"The sanitized reports/alert_summary.json should remain trackable and should
not be listed as ignored.
| Task 4 Requirement | Implementation |
|---|---|
| Build/configure a NIDS | Suricata-based NIDS |
| Monitor authorized traffic | Npcap/PCAP live capture or authorized PCAP |
| Configure detection rules | rules/local.rules |
| Detect selected suspicious activity | Four custom Suricata signatures |
| Generate alerts | EVE JSON and fast.log |
| Analyze detected activity | analysis/analyze_alerts.py |
| Produce structured results | reports/alert_summary.json |
| Test the solution | pytest + project validation helper |
| Validate Suricata | suricata -T |
| Document rules | reports/DETECTION_RULES.md |
| Document security review | reports/SECURITY_REVIEW.md |
| Document testing | reports/TEST_RESULTS.md |
| Provide evidence | screenshots/ |
| Apply responsible-use controls | Authorization, privacy, and repository hygiene |
This project is an educational NIDS implementation, not an enterprise security platform.
It does not provide:
- comprehensive attack coverage
- endpoint detection and response
- SIEM integration
- automated incident response
- complete threat-intelligence enrichment
- high-availability sensor architecture
- enterprise-scale performance benchmarking
- production-grade rule tuning
Signature-based detection can produce false positives and false negatives. Real deployments require broader detection coverage, environment-specific baselines, threshold tuning, operational monitoring, and analyst investigation.
A detection alert should be treated as an investigation signal, not automatic proof of compromise.
Project structure ✅
Suricata installation validation ✅
Custom detection rules ✅
Suricata rule loading ✅
Live ICMP detection demonstration ✅
EVE JSON alert generation ✅
Python alert analysis ✅
Automated tests ✅
Security documentation ✅
Evidence screenshots ✅
Public-report sanitization ✅
GitHub repository ✅
Suricata version: 8.0.6
Custom signatures: 4
Demonstrated alerts: 4
Python tests: 12 passed
Project checks: 4/4 passed
Evidence screenshots: 5
This project is intended for:
Owned systems
Authorized laboratory environments
Explicitly authorized networks
Do not use it to monitor third-party infrastructure without permission, intercept unauthorized traffic, conduct unauthorized reconnaissance, or expose confidential security telemetry.
Subhadeep Adhikary
CodeAlpha Cyber Security Intern
This project is licensed under the MIT License.
See LICENSE for the complete license text.