Topology Validator

Validate network topologies for security design flaws — with an interactive PBQ-style simulator.

A Python tool that reads network topologies (JSON or plain text) and flags common security design flaws — databases exposed to the DMZ, missing firewall layers, single points of failure, and more. Includes a --interactive mode that acts like a CompTIA/Cisco-style PBQ: build a topology command by command, validate on demand, and watch your security score change.

Features

• 📄 Two input formats — JSON (structured) or plain text (PBQ-style)
• 🛡️ Six security rules — edge checks + BFS-based path analysis
• 📊 Security score — 0–100 with letter grade (A–F)
• 🖼️ Visualization — color-coded PNG of the topology
• 📤 Multiple report formats — terminal, JSON, self-contained HTML
• ⚡ Interactive REPL — build, modify, validate topologies live
• 🧪 Tested — unit tests for parsers, rules, and scoring

Installation

From PyPI

pip install toposec

This installs a topology-validator command on your PATH.

Quick start

Validate a JSON topology:

topology-validator secure.json

Output:

============================================================
  NETWORK TOPOLOGY SECURITY REPORT
============================================================

  Total findings: 1
    MEDIUM   : 1

  Security Score: 96 / 100   (Grade: A)
  ...

Input formats

JSON

{
  "devices": [
    {"id": "internet", "type": "internet", "zone": "external"},
    {"id": "fw1", "type": "firewall", "zone": "dmz"},
    {"id": "web1", "type": "web_server", "zone": "dmz"},
    {"id": "fw2", "type": "firewall", "zone": "internal"},
    {"id": "app1", "type": "app_server", "zone": "internal"},
    {"id": "db1", "type": "database", "zone": "internal"}
  ],
  "connections": [
    {"from": "internet", "to": "fw1"},
    {"from": "fw1", "to": "web1"},
    {"from": "web1", "to": "fw2"},
    {"from": "fw2", "to": "app1"},
    {"from": "app1", "to": "db1"}
  ]
}

Text (PBQ-style)

device internet internet external
device fw1      firewall dmz
device web1     web_server dmz
device fw2      firewall internal
device app1     app_server internal
device db1      database internal

internet -- fw1
fw1 -- web1
web1 -- fw2
fw2 -- app1
app1 -- db1

Rules

Scoring

Score = max(0, 100 − total penalties). Grades: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F < 60.

CLI options

Exit codes: 0 = clean, 1 = findings present, 2 = error.

Interactive mode

topology-validator -i

> add internet internet external
> add fw1 firewall dmz
> add db1 database internal
> connect internet fw1
> connect fw1 db1
> check

Available commands: add, remove, connect, disconnect, show, check, score, render, save, load, clear, help, quit.

Examples

Visualize a topology

topology-validator insecure.json --visualize

Generates insecure.png — a color-coded diagram with flagged nodes outlined in red.

Generate an HTML report

topology-validator insecure.json -f html --visualize

Produces a self-contained insecure.report.html with the diagram and findings embedded.

Machine-readable output for CI

topology-validator insecure.json -f json -o report.json || echo "Topology has flaws!"

Development

pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.