Metadata-Version: 2.4
Name: gettopology
Version: 0.1.0a2
Summary: CLI tool for generating Azure VNet topology diagrams with enhanced features
Author-email: Panda <pandaeatsbamboomailer@pm.me>
License: MIT
Project-URL: Homepage, https://www.pandaeatsbamboo.com
Project-URL: Documentation, https://github.com/PandaEatsBambooBlog
Project-URL: Repository, https://github.com/PandaEatsBambooBlog
Project-URL: Issues, https://github.com/PandaEatsBambooBlog
Keywords: azure,networking,vnet,topology,diagram,drawio,cloud
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: azure-identity>=1.25.1
Requires-Dist: azure-mgmt-resource>=24.0.0
Requires-Dist: azure-mgmt-network>=30.1.0
Requires-Dist: azure-mgmt-resourcegraph>=8.0.1
Requires-Dist: azure-mgmt-authorization>=4.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.14.10; extra == "dev"
Requires-Dist: mypy>=1.19.1; extra == "dev"
Requires-Dist: bandit>=1.9.2; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install gettopology
```

For the latest alpha version:
```bash
pip install gettopology==0.1.0a1
```


## Requirements

- Python 3.10 or higher
- Azure subscription with appropriate permissions
- Azure CLI installed and configured (or Service Principal credentials)

## Usage

After installation, use the `gettopology` command:

```bash
# 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 [optional]
gettopology -f subscriptions.txt

# Get topology for specific VNets across all subscriptions [optional]
gettopology -vnet "vnet-name-1,vnet-name-2"

# Combine filters: specific subscriptions and VNets [optional]
gettopology -s "sub-id-1,sub-id-2" -vnet "vnet-1,vnet-2"

# Specify output directory for diagrams [optional]
gettopology -s "sub-id" -o ./diagrams

# Set log level
gettopology --log-level DEBUG 

# Skip role verification (role checking is enabled by default)
gettopology --skip-roles
```

### 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`: Comma-separated list of VNet names to filter (optional)
- `-o, --output`: Output directory for generated diagrams (default: current directory)
- `--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)

**What is Managed Identity?**  
Managed Identity is Azure's way of providing Azure resources (like VMs, App Services, etc.) with an automatically managed identity. When the tool runs inside Azure, it can authenticate using the resource's managed identity without needing explicit credentials. This is the third fallback method if Azure CLI and Service Principal authentication are not available.

For Service Principal authentication:
```bash
gettopology --client-id "your-client-id" \
            --client-secret "your-secret" \
            --tenant-id "your-tenant-id"
```

Or use environment variables:
```bash
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:
```bash
# .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 Draw.io (`.drawio`) format diagrams that can be opened in:
- [Draw.io](https://app.diagrams.net/) (web)
- [diagrams.net](https://www.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
- External VNets (cross-subscription/tenant peerings)
- Separate pages for hubless spokes and orphan VNets

## 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:
```bash
# 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:
```bash
# 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](LICENSE) file for details.

