gettopology 0.1.0a3

CLI tool for generating Azure VNet topology diagrams with enhanced features

GetTopology

⚠️ Alpha Release - This is an alpha version. Features may change and bugs may exist.

CLI tool for generating Azure VNet topology diagrams with enhanced features.

Installation

pip install gettopology

For the latest alpha version:

pip install gettopology==0.1.0a3

Requirements

• Python 3.10 or higher
• Azure subscription with appropriate permissions
• Azure CLI installed and configured (or Service Principal credentials)
• For Markmap diagrams: Node.js and npm installed
  • Installing Node.js and npm:
    • Windows:
      • Download installer: Download and install from nodejs.org (npm is included with Node.js)
      • Using Chocolatey: choco install nodejs (requires Chocolatey)
      • Using winget: winget install OpenJS.NodeJS (Windows 10/11)
      • Using Scoop: scoop install nodejs (requires Scoop)
    • macOS:
      • Download installer: Download and install from nodejs.org (npm is included with Node.js)
      • Using Homebrew: brew install node
    • Linux (Ubuntu/Debian): sudo apt-get update && sudo apt-get install nodejs npm
    • Linux (RHEL/CentOS): sudo yum install nodejs npm or sudo dnf install nodejs npm
    • Verify installation: node --version and npm --version
  • After installing Node.js/npm, install markmap CLI: npm install -g markmap-cli
  • Required only when using the -vnet flag to generate interactive VNet markmap visualizations

Internet Access Requirements:

• Draw.io files (.drawio): Can be opened offline in Draw.io desktop app or VS Code extension
• Index.html dashboard: Requires internet access to load the Draw.io viewer JavaScript (CDN)
• Markmap HTML files: Require internet access for CDN resources (d3.js, markmap libraries)

Usage

After installation, use the gettopology command:

# Get topology for all VNets in all accessible subscriptions
gettopology

# Get topology for specific subscriptions [optional]
gettopology -s "subscription-id-1,subscription-id-2"

# Get topology from subscriptions listed in a file on new line[optional]
gettopology -f subscriptions.txt

# Specify output directory for diagrams [optional]
# If not specified, creates a timestamped directory: topology_YYYYMMDD_HHMMSS
gettopology -s "sub-id" -o ./diagrams

# Generate markmap HTML visualizations for each VNet (requires markmap-cli)
gettopology -vnet

Command Line Arguments

• -s, --subscriptions: Comma-separated subscription IDs (optional)
• -f, --subscriptions-file: Path to file containing subscription IDs, one per line (optional)
• -vnet, --virtual-network: Generate interactive markmap HTML visualizations for each VNet (requires markmap-cli to be installed)
• -o, --output: Output directory for generated diagrams (default: creates timestamped directory topology_YYYYMMDD_HHMMSS)
• --log-level: Logging level - DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
• --skip-roles: Skip role verification. By default, the tool verifies that the authenticated user/service principal has at least 'Reader' role on subscriptions before proceeding (optional)
• --version: Display version information

Authentication

The tool supports multiple authentication methods, tried in this order:

1. Azure CLI (first): Uses az login credentials - tried first if available
2. Service Principal (second): Provide via CLI arguments, environment variables, or .env file
3. Managed Identity (third): Automatically used when running in Azure (e.g., Azure VM, App Service, Functions)

For Service Principal authentication:

gettopology --client-id "your-client-id" \
  --client-secret "your-secret" \
  --tenant-id "your-tenant-id"

Or use environment variables:

export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-secret"
export AZURE_TENANT_ID="your-tenant-id"
gettopology

Or create a .env file in your project directory:

# .env file
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-secret
AZURE_TENANT_ID=your-tenant-id

Priority order for Service Principal credentials:

1. CLI arguments (--client-id, --client-secret, --tenant-id)
2. Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
3. .env file (in current directory or project root)

Output

The tool generates organized output in a timestamped directory (or specified output directory) with the following structure:

output_dir/
├── hld/
│   └── topology-hld.drawio    # High-Level Diagram (always generated)
├── vnet/
│   ├── vnet1-markmap.html      # Interactive markmap for each VNet (if -vnet flag used)
│   ├── vnet2-markmap.html
│   └── ...
└── index.html                  # Interactive dashboard (always generated)

Note: A zip file (output_dir.zip) is automatically created in the parent directory, containing all generated files. This makes it easy to download and share the complete topology visualization package.

High-Level Diagram (HLD)

The Draw.io (.drawio) format diagram can be opened in:

• Draw.io (web)
• diagrams.net (desktop)
• Visual Studio Code (with Draw.io extension)

Diagrams include:

• Hub and spoke VNets with visual distinction
• Peering connections with color-coded lines
• Subnet details within VNet boxes (including all address prefixes)
• External VNets (cross-subscription/tenant peerings)
• Separate pages for hubless spokes and orphan VNets
• Azure Firewall , Expressoute and VPN Gateway Check(apart from subnet) are checked before putting the icons on subnet
• NSG and Route table icons on Subnet
• DDoS Protection and Private Endpoint icons where applicable
• Markmap shows UDR in tables.

Markmap Visualizations (Optional)

When using the -vnet flag, the tool additionally generates:

• Interactive HTML markmaps for each VNet showing:
  • VNet details (address space, location, subscription)
  • Subnet information (name, address prefixes, route tables)
  • Route table routes (if accessible)
  • Network security groups
  • Connected resources (NAT Gateways, Private Endpoints, etc.)
• These markmap files are placed in the vnet/ subdirectory and linked from index.html

Note: Markmap generation requires markmap-cli to be installed globally:

npm install -g markmap-cli

Development

This project uses several code quality tools:

• Ruff: Fast Python linter and formatter
• mypy: Static type checker
• Bandit: Security vulnerability scanner
• pytest: Testing framework

To install development dependencies:

# Using uv (installs from [dependency-groups])
uv sync --group dev

# Or install in editable mode with dev dependencies
uv pip install -e ".[dev]"

Run code quality checks:

# Linting
uv run ruff check src/

# Type checking
uv run mypy src/

# Security scanning
uv run bandit -r src/ -c pyproject.toml

# Tests will be added on later version
uv run pytest tests/

License

This project is licensed under the MIT License - see the LICENSE file for details.