Fragments

What Fragments is, in one screen

Fragments discovers every device on a local network, assigns each a 0–100 risk score, visualizes the topology in real time, and exposes the whole picture through a retrieval-augmented chat, an attack-path simulator, a compliance assessor, and exportable PDF reports. It ships with a mock mode so the entire product runs offline, with no root and no network access, against a fixed 15-device fixture.

The stack, precisely labeled

How the pieces fit together

A single FastAPI process fronts six subsystems and two data stores. The browser talks to it over REST for commands and over one WebSocket for live events. Everything that could touch the network or an LLM is isolated behind the scanner and AI subsystems respectively.

%%{init: {'theme':'base','themeVariables':{'background':'#0c0c0e','primaryColor':'#151517','primaryTextColor':'#e6e6e6','primaryBorderColor':'#00ff41','lineColor':'#555','secondaryColor':'#111','tertiaryColor':'#0a0a0a','clusterBkg':'#0c0c0e','clusterBorder':'#262626','fontFamily':'JetBrains Mono, monospace','fontSize':'13px','textColor':'#c0c0c0'}}}%%
flowchart TB
  subgraph CLIENT["Browser · Next.js 16"]
    UI["Dashboard · Devices · Threats
Simulate · Chat · Compliance · Report"]
    WSH["useWebSocket hook
(auto-reconnect)"]
  end

  subgraph API["FastAPI process (async)"]
    REST["REST router
/api/*"]
    WS["WebSocket /ws
ConnectionManager"]
    BG["Background scan loop
every SCAN_INTERVAL"]
  end

  subgraph SUB["Subsystems"]
    SCAN["scanner/
ARP · nmap · OUI · OS"]
    THREAT["threat/
risk_scorer · cve_lookup"]
    AI["ai/
analyzer · attack_sim · RAG"]
    COMP["compliance/
parser · assessor · report"]
    RPT["report.py
PDF builder"]
  end

  subgraph DATA["State"]
    SQL[("SQLite · WAL")]
    VEC[("ChromaDB · cosine")]
  end

  subgraph EXT["Outside the host"]
    NET["LAN — raw sockets
(root)"]
    LLM["Ollama :11434
qwen3:30b-a3b"]
    NVD["NVD API
(enrichment)"]
  end

  UI -->|"fetch"| REST
  WSH -->|"events"| WS
  REST --> SCAN & THREAT & AI & COMP & RPT
  BG --> SCAN
  SCAN --> NET
  SCAN --> THREAT
  THREAT -.->|"roadmap"| NVD
  AI --> VEC
  AI --> LLM
  COMP --> AI
  REST --> SQL
  SCAN --> SQL
  SCAN -->|"auto-ingest"| VEC
  WS -.->|"broadcast"| WSH

Fig. 1 — Component architecture. Dashed edges are planned enrichment paths (see §12).

The core loop: scan → score → store → ingest → broadcast

A scan is the spine of the system — every other feature reads what a scan produces. The sequence below is the live path; mock mode swaps the first step for a fixture load and skips the network entirely.

%%{init: {'theme':'base','themeVariables':{'background':'#0c0c0e','primaryColor':'#151517','primaryTextColor':'#e6e6e6','primaryBorderColor':'#00ff41','lineColor':'#555','actorBkg':'#151517','actorBorder':'#00ff41','actorTextColor':'#e6e6e6','signalColor':'#666','signalTextColor':'#c0c0c0','noteBkgColor':'#111','noteTextColor':'#c0c0c0','noteBorderColor':'#333','fontFamily':'JetBrains Mono, monospace','fontSize':'12px'}}}%%
sequenceDiagram
  participant U as Browser
  participant A as FastAPI
  participant S as Scanner
  participant R as Risk scorer
  participant DB as SQLite
  participant C as ChromaDB
  participant O as Ollama

  U->>A: POST /api/scan
  A->>S: run_scan()
  S->>S: ARP sweep + ICMP fallback + nmap -sV
  S->>R: score_device() per host
  R-->>S: 0–100 risk
  A->>DB: upsert devices + scan record
  A->>A: rogue check → insert alerts
  A->>C: ingest_scan_data() (chunk + embed)
  A-->>U: WS "scan_complete" / "alert"
  Note over U,A: later — analyst asks a question
  U->>A: POST /api/rag/query
  A->>C: retrieve(top_k=10, cosine)
  C-->>A: ranked chunks
  A->>O: chat(system + context + question)
  O-->>A: grounded answer
  A-->>U: response + sources

Fig. 2 — Scan and RAG data flow. The answer is grounded only in retrieved scan chunks.

Design decisions & the trade-offs behind them

Discovery: why ARP first, then ICMP

Live discovery leads with a scapy ARP broadcast because ARP operates at layer 2 and returns real MAC addresses — the stable identity the whole system keys on. Two augmentations show the network knowledge worth defending:

• Self-inclusion. ARP never returns the scanning host's own interface, so it is added explicitly from conf.iface. Miss this and the scanner is invisible to itself.
• ICMP sweep fallback. On NAT-isolated networks — phone hotspots with AP client isolation — ARP broadcasts don't reach peers. An icmplib ping sweep catches them, bounded to ≤1024 addresses so a /16 can't blow up scan time. Hosts found this way get their MAC from the kernel ARP cache.

Port and service detection is nmap (-sV -T4 --top-ports 100 --host-timeout 30s), run inside asyncio.to_thread because python-nmap is blocking — this keeps the event loop responsive while a scan runs.

Risk scoring: a transparent weighted model

The 0–100 score is a deterministic additive model across five capped bands. It is intentionally simple and explainable — you can point at any device and reproduce its score by hand, which matters more for trust than a black box would.

The honest framing: this is a transparent heuristic v1, not a calibrated model. The weights are hand-chosen and the CVE band counts rather than weighting by severity — deliberate simplicity for a number people need to trust, with a clear upgrade path.

RAG: retrieval that can't hallucinate the inventory

Each device becomes a summary chunk plus one chunk per open port; alerts become their own chunks. These are upserted into ChromaDB, which — with no embedding function specified — uses its default model, all-MiniLM-L6-v2 (384-dim), over cosine space. At query time the analyzer retrieves the top-k, builds a character-budgeted context, and instructs the local LLM to answer only from that context and cite devices by IP/MAC. If ChromaDB or the LLM is unreachable, it degrades to a deterministic rule-based summary rather than failing.

Attack simulation: deterministic by design

Despite living under ai/, the simulator makes no LLM call. It is a greedy graph traversal: from a chosen origin it walks up to five hops, at each step picking the highest-value reachable target (servers and databases weighted up) where a lateral method exists — an open SSH/SMB/RDP/DB port, a shared CVE, or an untrusted host. The narration is templated. This is a deliberate choice: deterministic, reproducible, and incapable of inventing an attack path that isn't there.

Data model

Seven SQLite tables, all accessed through parameterized queries with a row-factory helper; WAL mode for concurrent reads during a scan; device writes are idempotent upserts keyed on MAC that deliberately preserve the manually-set is_trusted flag across rescans.

The tool is itself an attack surface

A network-reconnaissance tool that runs as root and holds a complete map of a network's weaknesses is a high-value target — so it has to be threat-modeled like one. The crown jewels are the scan database (hosts, ports, OS versions, CVEs) and the generated reports: everything an attacker would want for free.

%%{init: {'theme':'base','themeVariables':{'background':'#0c0c0e','primaryColor':'#151517','primaryTextColor':'#e6e6e6','primaryBorderColor':'#00ff41','lineColor':'#555','clusterBkg':'#0c0c0e','clusterBorder':'#262626','fontFamily':'JetBrains Mono, monospace','fontSize':'12px','textColor':'#c0c0c0'}}}%%
flowchart LR
  subgraph Z1["Zone: Browser (untrusted client)"]
    B["Next.js dashboard"]
  end
  subgraph Z2["Zone: Host — runs as ROOT"]
    F["FastAPI · single process"]
    P["Doc parsers"]
    D[("SQLite + ChromaDB
plaintext at rest")]
  end
  subgraph Z3["Zone: LAN (semi-trusted)"]
    N["Active scanning
scapy / nmap"]
  end
  subgraph Z4["Zone: External"]
    L["Ollama (local by default)"]
    V["NVD API"]
  end
  B ==>|"TB①  auth boundary"| F
  P ==>|"TB②  untrusted upload"| F
  F ==>|"TB③  root raw sockets"| N
  F -->|"TB④  recon data at rest"| D
  F -->|"TB⑤  local by default"| L
  F --> V

Fig. 3 — Trust boundaries. TB① and TB② are the highest-severity crossings.

STRIDE

Running it

Mock mode — the demo path (no root, no network)

# Backend — offline, deterministic 15-device fixture
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
FRAGMENTS_MOCK=1 uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

# Frontend
cd frontend && npm install && npm run dev   # http://localhost:3000

Mock mode is the demo path. It exercises every feature — scoring, topology, attack sim, RAG chat, compliance, PDF — with zero external dependencies. If Ollama isn't running, the AI endpoints fall back to deterministic summaries, so the demo never dead-ends.

Live mode — real scanning

# Requires root for scapy/nmap raw sockets; Ollama for AI
export SCAN_SUBNET=192.168.1.0/24
sudo -E .venv/bin/uvicorn backend.main:app --host 127.0.0.1 --port 8000

Environment variables that matter

What's covered, and what comes next

The backend has 23 pytest tests across five files, all forced into mock mode, each with an isolated temp database via an autouse fixture — no test pollutes another's state.

The pyramid, honestly

The base — unit tests on the pure scoring and parsing logic — is solid. The next tiers are scoped and known: an integration layer driving the FastAPI app over httpx.ASGITransport with the mock scanner; a small end-to-end smoke test through the WebSocket event sequence; and CI gating all three. Naming precisely what's missing and in what order it gets built is itself part of the strategy.

A six-minute live walkthrough

Run in mock mode so nothing depends on the network or a model server. The fixture has two built-in villains — 192.168.1.100 (unknown host, Telnet + FTP, risk 88) and 192.168.1.52 (IoT camera, RTSP + Telnet, risk 78). Drive toward them.

• 0:00Open the dashboard. Name what's on screen: 15 devices in a star topology, node color = risk, node size = open-port count, live stat tiles for average risk and open alerts.
• 0:30Hit Scan. Narrate the WebSocket events — nodes pulse, and three rogue device alerts fire for the untrusted hosts. "This is the event bus, not a page refresh."
• 1:15Click 192.168.1.100. Walk the risk breakdown live: dangerous ports + identity gaps + unknown OS + a CVE + insecure protocols → 88. "Every point is traceable — no black box."
• 2:15Open Attack Simulation from that host. Show the greedy path hopping toward the database server on 3306. Pre-empt the question: "This is deterministic — a weighted graph walk, not a model guessing."
• 3:15Go to Chat. Ask: "Which devices are riskiest and why?" Show the grounded answer with device citations. "The model only sees retrieved scan chunks, and it runs locally — this network map never leaves the host."
• 4:15Compliance: upload a small JSON framework, run the assessment, show the Compliant / Partial / Non-Compliant split tied back to real findings (Telnet → an encryption control fails).
• 5:15Generate the security report PDF. Open it — executive summary, inventory, vulnerability findings, remediation checklist. Close on the roadmap, not the features.

Ninety seconds, no jargon

The technical explanation

The questions this project invites

Grouped by where the pressure comes from. The answers concede real limitations on purpose — a strong panel rewards that far more than a confident dodge.

On the AI layer

On the risk model

On securing the tool itself

On architecture & scale

The honest roadmap

Stated the way a credible engineer would: current constraints first, then the ordered path out of them.

Known limitations, tracked as findings

Auditing your own system is the core security-engineering discipline, so this project is documented like any other target — each limitation logged as a severity-tagged finding with a fix. This is the roadmap from a winning hackathon build toward production hardening.