Nyx — Explainable Live Anomaly Detector

Watching from the dark.

Nyx is a lightweight, explainable network anomaly detector for low-resource machines. It watches live traffic, scores anomalies in real time, explains why each event was flagged, maps suspicious behavior to MITRE ATT&CK heuristically, and keeps a tamper-evident audit log. Built for demo clarity, honest scope, and low RAM.

---

What Nyx Is

Nyx is an AI-assisted security tool for small SOC teams, student labs, and constrained environments. It does four things in one pipeline:

• Captures live traffic or replays safe demo traffic
• Scores anomalies using a lightweight ML detector
• Explains detections with SHAP-style feature attribution
• Logs every decision in a hash-chained audit trail

It is not a SIEM replacement. It is not a zero-day oracle. It is an explainable monitoring tool that helps analysts see suspicious behavior faster.

---

Why This Project Exists

Most hackathon security projects fall into one of these traps:

• A dashboard with fake data
• An AI wrapper with no real pipeline
• A bloated system that dies on weak hardware

Nyx is built to avoid that. It is intentionally narrow:

• One detector
• One explanation flow
• One MITRE mapping layer
• One audit trail
• One clean demo story

The constraint is the story. Nyx proves useful detection does not require enterprise infrastructure.

---

One Pipeline. Four Stages. No Smoke.

[1] Live Packet Capture
    Scapy sniffer or demo traffic generator
          ↓
[2] Anomaly Scoring + Explainability
    IsolationForest + SHAP-style attribution
          ↓
[3] MITRE ATT&CK Mapping
    Heuristic technique/tactic suggestions
          ↓
[4] Audit Trail + Dashboard
    SQLite hash chain + React UI + CLI

That is the product. Everything else is support material.

---

Core Features

Live Packet Capture

Nyx reads network traffic from an interface using Scapy or consumes synthetic demo events when live capture is unavailable. It extracts flow-level features such as:

• duration
• protocol
• src_bytes
• dst_bytes
• packet_rate
• connection_count
• port_diversity

Lightweight Anomaly Detection

Nyx uses a compact unsupervised model to score traffic and flag suspicious flows. Key goals: fast, explainable, runnable on low RAM, and demo-safe.

Explainability

When Nyx flags an event, it shows the top contributing features so an analyst can understand why the alert fired. This is the difference between:

• "the model says bad"
• "the model says bad because these features changed"

MITRE ATT&CK Mapping

Nyx maps suspicious flow patterns to likely ATT&CK techniques using explicit heuristic rules. Important: this is a starting point for investigation, not a definitive classification.

Tamper-Evident Audit Log

Nyx stores each decision in SQLite and links entries with SHA-256 hash chaining. That means:

• Every event is traceable
• Tampering breaks verification
• The chain can be rechecked at any time

Clean Dashboard

The frontend shows: live threat feed, risk gauge, explanation panel, MITRE badge, audit log, and chain verification status.

CLI

Nyx also ships with a small CLI for local use and demos.

---

Tech Stack

Layer	Technology	Purpose
Backend	Python 3.11 + FastAPI	API and WebSocket hub
Packet capture	Scapy	Live traffic sniffing
ML	scikit-learn IsolationForest	Lightweight anomaly scoring
Explainability	SHAP	Feature attribution
Threat mapping	Local MITRE ATT&CK JSON	Heuristic technique lookup
LLM assistant	Gemini API	Analyst-style summary and mitigations
Audit log	SQLite + SHA-256 hash chaining	Tamper-evident records
Frontend	React 18 + Tailwind + Recharts	Live dashboard
CLI	Click	Local command-line access

---

Project Goals

Nyx is designed to be:

• Fast enough for live demo use
• Small enough for low-resource machines
• Honest enough to survive judge questions
• Clean enough to look finished
• Useful enough to feel real

---

Folder Structure

nyx/
├── backend/
│   ├── main.py                  # FastAPI app + WebSocket hub
│   ├── monitor.py               # Scapy sniffer + feature extraction
│   ├── demo.py                  # Synthetic traffic generator
│   ├── audit.py                 # SQLite + SHA-256 hash chain
│   ├── mitre.py                 # Heuristic MITRE mapper
│   ├── agent.py                 # Gemini analyst summary
│   ├── ml/
│   │   ├── train.py             # Synthetic training data + model build
│   │   ├── detector.py          # Model wrapper + scoring
│   │   ├── explainer.py         # SHAP feature attribution
│   │   └── model.pkl            # Pretrained model
│   ├── data/
│   │   └── enterprise-attack.json
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── App.jsx
│   │   ├── index.css
│   │   └── components/
│   │       ├── ThreatFeed.jsx
│   │       ├── RiskGauge.jsx
│   │       ├── ShapPanel.jsx
│   │       ├── MitreTag.jsx
│   │       ├── AgentCard.jsx
│   │       └── AuditLog.jsx
│   └── package.json
├── cli/
│   └── nyx.py
├── docker-compose.yml
└── README.md

---

Data Flow

1. Traffic enters from live capture or demo mode
2. Features are extracted per flow
3. The detector scores the event
4. SHAP-style attribution explains the score
5. The MITRE mapper proposes a likely technique
6. Gemini returns a short analyst-friendly summary
7. The event is hash-chained into audit storage
8. The frontend updates live

---

Detection Logic

The model produces a risk score for each event.

score = model.decision_function(X)   # lower = more anomalous
risk = normalize_to_0_100(score)
flagged = risk > threshold

The threshold is tunable so the demo can balance precision and recall.

---

Explainability

Nyx shows the top reasons an event was flagged. Example output:

[
    ("port_diversity", 0.42),
    ("packet_rate", 0.31),
    ("connection_count", 0.18)
]

That makes alerts understandable instead of magical.

---

MITRE ATT&CK Mapping

Nyx uses heuristic mapping from observable traffic behavior to likely ATT&CK techniques.

def map_to_attack(features: dict) -> dict:
    if features["port_diversity"] > 50:
        return {
            "technique_id": "T1046",
            "technique": "Network Service Scanning",
            "tactic_id": "TA0007",
            "tactic": "Discovery",
            "confidence": "medium",
        }

    if features["connection_count"] > 100:
        return {
            "technique_id": "T1110",
            "technique": "Brute Force",
            "tactic_id": "TA0006",
            "tactic": "Credential Access",
            "confidence": "medium",
        }

    if features["packet_rate"] > 1000:
        return {
            "technique_id": "T1498",
            "technique": "Network Denial of Service",
            "tactic_id": "TA0040",
            "tactic": "Impact",
            "confidence": "high",
        }

    return {
        "technique_id": "T1071",
        "technique": "Application Layer Protocol",
        "tactic_id": "TA0011",
        "tactic": "Command and Control",
        "confidence": "low",
    }

Important: This mapping is heuristic, not authoritative. It gives analysts a likely starting point, not a final verdict.

---

Gemini Analyst Assistant

Nyx calls Gemini to produce a short analyst-friendly summary and suggested mitigations. The model is not used for detection — it is used for interpretation and response formatting.

prompt = f"""
You are a network security analyst assistant.
A network anomaly was detected with:

- Risk score: {risk}/100
- Top anomaly indicators: {shap_top3}
- Likely MITRE technique: {mitre["technique"]} ({mitre["technique_id"]})
- Confidence: {mitre["confidence"]}

Return JSON only:
{{
    "summary": "one sentence explanation",
    "severity": "low|medium|high|critical",
    "mitigations": ["action 1", "action 2", "action 3"],
    "analyst_note": "what to investigate next"
}}
"""

---

Audit Trail

Nyx writes every decision into SQLite. Each entry includes:

• Event ID
• Timestamp
• Extracted features
• Risk score
• MITRE mapping
• Gemini response
• Previous hash
• Current hash

Each row includes the hash of the previous row. If anyone edits one record, the chain breaks — giving you tamper detection, traceability, replayable history, and a clean audit story for the demo.

---

Dashboard

The dashboard is intentionally restrained.

Panels:

• Threat Feed — Live list of suspicious events
• Risk Gauge — A simple 0–100 risk visualization
• SHAP Panel — Top features contributing to the alert
• MITRE Badge — Likely technique and tactic
• Agent Card — Gemini-generated analyst summary and mitigations
• Audit Log — Hash chain view with verification

Visual style: dark theme, one neon accent, one warning color, one critical color, minimal motion, no 3D clutter. The UI should look finished, not expensive.

---

CLI

nyx scan
nyx scan --interface eth0
nyx scan --demo
nyx report
nyx report --export json
nyx verify
nyx status

---

API Endpoints

GET   /health
WS    /ws/events
GET   /api/events
GET   /api/events/{id}/shap
GET   /api/audit
POST  /api/mitigate/{id}
POST  /api/demo/trigger
GET   /api/stats

---

Demo Mode

If live traffic is unavailable, Nyx switches to demo mode. Demo mode generates synthetic traffic, is clearly labeled in the UI, requires no root permissions, and keeps the demo reproducible.

---

Performance Goals

Target footprint:

• Backend: low hundreds of MB
• Frontend: lightweight browser UI
• Model: small serialized artifact
• Demo mode: safe for weak hardware

Target latency:

• Event scoring: under a second
• Explanation: near real-time
• UI update: live through WebSocket

---

Limitations

Nyx is honest about what it does not do:

• Does not perform deep packet inspection
• Does not decrypt traffic
• Does not replace a real SOC platform
• Does not claim definitive ATT&CK classification
• Does not claim production-grade detection across all environments

Those are future improvements, not current claims.

---

Roadmap

• Stronger evaluation on public intrusion datasets
• Better calibration of risk scores
• TLS fingerprinting for encrypted traffic
• More precise MITRE matching
• Optional local LLM support
• Replayable packet timelines
• Multi-host correlation

---

Build Order

Day 1

1. Build feature extraction
2. Train and save the detector
3. Wire the explainability layer
4. Implement MITRE mapping
5. Implement audit storage
6. Connect the API
7. Test the full backend pipeline

Day 2

1. Build the dashboard
2. Wire WebSocket updates
3. Add the CLI
4. Create demo mode
5. Polish README and screenshots
6. Record the demo video

---

90-Second Demo Flow

Time	Event
0:00	Dashboard idle
0:10	Demo attack triggered
0:20	Risk score rises
0:30	Click alert
0:40	SHAP reasons appear
0:50	MITRE technique shown
1:00	Gemini summary appears
1:10	Event is audited and verified
1:20	End on chain intact + clean UI

The demo should be short, controlled, and impossible to misunderstand.

---

Installation

git clone <repo>
cd nyx
pip install -r backend/requirements.txt
cd frontend && npm install

Run backend:

cd backend
uvicorn main:app --reload

Run frontend:

cd frontend
npm run dev

Run demo mode:

nyx scan --demo

---

Environment Variables

GEMINI_API_KEY=your_key_here
NYX_HOST=0.0.0.0
NYX_PORT=8000
NYX_INTERFACE=eth0
NYX_LOG_LEVEL=INFO

---

Requirements

fastapi==0.111.0
uvicorn[standard]==0.30.0
websockets==12.0
scapy==2.5.0
scikit-learn==1.5.0
shap==0.45.0
google-generativeai==0.7.0
sqlalchemy==2.0.30
joblib==1.4.2
numpy==1.26.4
pandas==2.2.2
click==8.1.7
pytest==8.2.0

---

Honest Pitch

Nyx is an explainable live network anomaly detector for low-resource machines. It flags suspicious traffic, explains why it was flagged, maps likely techniques to MITRE ATT&CK, and stores decisions in a tamper-evident audit trail.

That is the whole story. No fake autonomy. No inflated claims. No bloated architecture. Just a clean, real pipeline that judges can understand in one breath.

---

License

MIT