gettopology 0.1.0a5

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 CLoud shell
pip install gettopology --user 

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
  • After installing Node.js/npm, install markmap CLI:
    • Regular environments: npm install -g markmap-cli
    • Azure Cloud Shell: npm install markmap-cli (local install, no -g flag)
  • 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.