azure-discovery 0.1.0__tar.gz

azure_discovery-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azure Discovery Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

azure_discovery-0.1.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: azure-discovery
+Version: 0.1.0
+Summary: Lightweight Azure tenant discovery and visualization via Resource Graph. Enumerates subscriptions and resources, normalizes results, and renders interactive dependency graphs. Supports public and sovereign clouds (Gov, China, Germany, Azure Stack).
+Author: David Frazer <david.frazer336@gmail.com>
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/maravedi/AzureDiscovery#readme
+Project-URL: Repository, https://github.com/maravedi/AzureDiscovery
+Project-URL: Bug Tracker, https://github.com/maravedi/AzureDiscovery/issues
+Keywords: azure,resource-graph,discovery,inventory,sovereign-cloud,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.7
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: typer>=0.12
+Requires-Dist: pyvis>=0.3.2
+Requires-Dist: azure-identity>=1.17
+Requires-Dist: azure-mgmt-resourcegraph>=8.0
+Requires-Dist: azure-mgmt-subscription>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# Azure Discovery
+
+Azure Discovery is a lightweight Azure tenant mapper that enumerates subscriptions and resources via Azure Resource Graph, normalizes the results, and renders an interactive dependency graph. The tool exposes both a Typer-based CLI (`azure-discovery`) and a FastAPI surface so the same discovery workflow can be automated or embedded in other services.
+
+The package is published on [PyPI](https://pypi.org/project/azure-discovery/) as **azure-discovery** and can be installed with `pip install azure-discovery`.
+
+## Core capabilities
+
+- Builds environment-aware credential chains (Azure CLI + DefaultAzureCredential) with guardrails for unsupported clouds.
+- Queries Azure Resource Graph with include/exclude filters, tag constraints, and resource group scopes.
+- Resolves subscriptions automatically when not provided and de-duplicates resources for consistent graph IDs.
+- Produces JSON summaries, console metrics, and PyVis HTML graphs for quick triage.
+- Offers identical request/response contracts (Pydantic models) across CLI and API, following the Receive an Object, Return an Object (RORO) pattern.
+- Supports all Azure clouds: public, Government (GCC/GCC-H), China, Germany, and Azure Stack.
+
+## Installation
+
+**From PyPI (recommended):**
+
+```bash
+pip install azure-discovery
+```
+
+**With optional development dependencies:**
+
+```bash
+pip install azure-discovery[dev]
+```
+
+**From source (e.g. for development or when embedded in another repo):**
+
+```bash
+git clone https://github.com/maravedi/AzureDiscovery.git
+cd AzureDiscovery
+pip install -e .[dev]
+```
+
+## Package layout
+
+When installed, the package provides the **azure_discovery** Python package:
+
+```
+azure_discovery/
+  __init__.py       # run_discovery, AzureDiscoveryRequest, AzureDiscoveryResponse, etc.
+  cli.py            # Typer command surface (entry point: azure-discovery)
+  api.py            # FastAPI app for /discover and visualization endpoints
+  orchestrator.py   # Async coordinator for enumeration + visualization
+  adt_types/        # Pydantic models and custom exceptions
+  enumerators/      # Resource Graph query builder and normalization
+  reporting/        # Console logging and HTML/PyVis graph generation
+  utils/            # Azure SDK clients, graph helpers, structured logging
+```
+
+**Programmatic usage:**
+
+```python
+from azure_discovery import run_discovery
+from azure_discovery.adt_types import (
+    AzureDiscoveryRequest,
+    AzureDiscoveryResponse,
+    AzureEnvironment,
+    DiscoveryFilter,
+)
+
+request = AzureDiscoveryRequest(
+    tenant_id="<tenant-guid>",
+    environment=AzureEnvironment.AZURE_GOV,
+    subscriptions=["<sub-id>"],
+    filter=DiscoveryFilter(include_types=["Microsoft.Compute/virtualMachines"]),
+)
+response = await run_discovery(request)
+# response.nodes, response.relationships, response.html_report_path
+```
+
+To pass your own credential (e.g. for sovereign cloud from another app):
+
+```python
+from azure_discovery.enumerators.azure_resources import enumerate_azure_resources
+
+response = await enumerate_azure_resources(request, credential=my_credential)
+```
+
+## Prerequisites
+
+- Python 3.11+
+- Azure CLI 2.60+ (optional, used when `--prefer-cli` is set) or service principal credentials exported as `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_CLIENT_SECRET`
+- Azure Resource Graph access (Reader or above on the subscriptions you plan to scan)
+- Network egress to `management.azure.com` and `api.azure.com` (or the sovereign cloud endpoints you select)
+
+## Required Azure permissions
+
+| Capability | Minimum RBAC role | Scope recommendation |
+| ---------- | ----------------- | -------------------- |
+| Run Resource Graph queries | `Reader`, `Resource Graph Reader`, or any custom role with `Microsoft.ResourceGraph/*/read` | Every subscription you plan to inventory or the parent management group |
+| Auto-discover subscriptions (when `--subscription` is omitted) | `Reader` on the management group or `Directory.Read.All` consent for service principals | Tenant root (`/providers/Microsoft.Management/managementGroups/<root>`) |
+| Register Microsoft.ResourceGraph (one-time) | `Contributor` or `Owner` | Each subscription being scanned |
+
+The tool never mutates resources, but it cannot enumerate subscriptions or call Resource Graph unless the identity has at least `Reader` at the relevant scope. Grant the narrowest scope that still covers your target estate (for example, a dedicated management group for security tooling).
+
+### Service principal flow (CLI based)
+
+```
+az ad sp create-for-rbac \
+  --name azure-discovery-sp \
+  --role "Reader" \
+  --scopes /subscriptions/<sub-id-1> /subscriptions/<sub-id-2> \
+  --years 1
+
+az role assignment create \
+  --assignee <appId> \
+  --role "Resource Graph Reader" \
+  --scope /subscriptions/<sub-id-1>
+```
+
+Export the emitted `appId`, `tenant`, and `password` as `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_CLIENT_SECRET`. Repeat the role assignment command for every subscription or assign at the management group scope (`/providers/Microsoft.Management/managementGroups/<mg-id>`) to cover multiple subscriptions at once.
+
+### User-assigned permissions (Portal)
+
+1. Open Azure Portal → **Subscriptions** → select each target subscription.
+2. Navigate to **Access control (IAM)** → **Add** → **Add role assignment**.
+3. Pick the `Reader` (or `Resource Graph Reader`) role, then select the user or managed identity that will run AzureDiscovery.
+4. If you want automatic subscription discovery, repeat the assignment at the tenant root management group (visible under **Management groups**). Users need the **Azure RBAC Reader** role there.
+
+### Provider registration and validation
+
+Run the following once per subscription to ensure the Resource Graph service is registered and the identity can query it:
+
+```
+az account set --subscription <sub-id>
+az provider register --namespace Microsoft.ResourceGraph
+az graph query -q "Resources | take 1"
+```
+
+Successful output from `az graph query` confirms both the provider registration and the assigned role. If the command fails with `AuthorizationFailed`, double-check the scope of the role assignments and replicate them for every subscription you intend to scan.
+
+## Getting started
+
+1. **Install** (see [Installation](#installation) above).
+
+2. **Authenticate to Azure**
+
+   - Interactive: `az login --tenant <tenant-id>` and, if multiple tenants, `az account set --subscription <sub-id>`.
+   - Service principal: export `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`, and (optionally) `AZURE_SUBSCRIPTION_ID`.
+   - For sovereign clouds (e.g. Azure Government): set `az cloud set --name AzureUSGovernment` and log in; or use a service principal with the appropriate authority.
+
+3. **Run the CLI**
+
+   After install, the `azure-discovery` console script is on your PATH:
+
+   ```bash
+   azure-discovery discover \
+     --tenant-id <tenant-guid> \
+     --subscription <sub-id-1> --subscription <sub-id-2> \
+     --include-type "Microsoft.Compute/virtualMachines" \
+     --resource-group core-infra \
+     --required-tag environment=prod \
+     --visualization-output-dir artifacts/graphs
+   ```
+
+   **Run as a module from source** (from the repo root):
+
+   ```bash
+   python -m azure_discovery.cli discover --help
+   python -m azure_discovery.cli discover --tenant-id <tenant-guid> --environment azure_gov [options...]
+   ```
+
+   The command prints the structured `AzureDiscoveryResponse` JSON and writes an interactive HTML graph under `artifacts/graphs/`.
+
+4. **Run the API (optional)**
+
+   ```bash
+   uvicorn azure_discovery.api:app --host 0.0.0.0 --port 8000 --reload
+   ```
+
+   - Health check: `curl http://localhost:8000/healthz`
+   - Discovery: `curl -X POST http://localhost:8000/discover -H "Content-Type: application/json" -d '{"tenant_id": "...", ... }'`
+   - Download visualization: `curl http://localhost:8000/visuals/<file-name> --output graph.html`
+
+## Configuration reference
+
+| Option | Description |
+| ------ | ----------- |
+| `--tenant-id` | Required Entra ID tenant GUID. |
+| `--environment` | Azure cloud (`azure_public`, `azure_gov`, `azure_china`, `azure_germany`, `azure_stack`). |
+| `--subscription/-s` | Repeatable flag to scope runs to explicit subscription IDs. Omit to auto-resolve. |
+| `--include-type` / `--exclude-type` | Filter resource types (case-insensitive). |
+| `--resource-group` | Restrict discovery to named resource groups. |
+| `--required-tag` | Enforce tag key=value pairs (repeatable). |
+| `--prefer-cli` | Place Azure CLI credentials at the front of the chain. |
+| `--visualization-output-dir` | Directory for PyVis HTML output (default `artifacts/graphs`). |
+| `--visualization-file` | Override the generated HTML file name. |
+| `--output/-o` | Write JSON output to file instead of stdout. |
+| `--quiet/-q` | Suppress all logs except errors. |
+| `--format/-f` | Output format: `json` (default) or `json-compact`. |
+
+Programmatic workflows can instantiate `AzureDiscoveryRequest` directly and call `orchestrator.run_discovery`, receiving an `AzureDiscoveryResponse` that contains resolved subscriptions, normalized nodes, inferred relationships, and an optional `html_report_path`.
+
+### Output and logging separation
+
+By default, the CLI writes JSON results to stdout and logs to stderr. This allows clean piping:
+
+```bash
+# Pipe JSON output to jq for filtering
+azure-discovery discover --tenant-id <id> | jq '.discovered_subscriptions'
+
+# Write output to file and suppress logs
+azure-discovery discover --tenant-id <id> --output results.json --quiet
+
+# Compact JSON output for scripting
+azure-discovery discover --tenant-id <id> --format json-compact
+```
+
+## Development
+
+### Quick start
+
+```bash
+# Install with development dependencies
+make install-dev
+
+# Run tests
+make test
+
+# Format code
+make format
+
+# Run linting
+make lint
+
+# Type checking
+make typecheck
+
+# Generate coverage report
+make coverage
+```
+
+### Available make commands
+
+Run `make help` to see all available commands:
+- `make install` - Install package dependencies
+- `make install-dev` - Install with development dependencies
+- `make test` - Run tests with pytest
+- `make lint` - Run ruff linter
+- `make format` - Format code with ruff
+- `make typecheck` - Run mypy type checking
+- `make coverage` - Generate test coverage report
+- `make clean` - Remove build artifacts and cache
+- `make run-api` - Run FastAPI server locally
+
+### Pre-commit hooks
+
+Install pre-commit hooks to automatically run linting and formatting on commit:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+This will run ruff formatting, linting, and mypy type checking before each commit.
+
+### Environment variables
+
+Copy `.env.example` to `.env` and configure your Azure credentials:
+
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+For detailed contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Troubleshooting
+
+- **`AzureClientError: Unable to enumerate subscriptions`** – ensure the identity has at least `Reader` on one subscription and that the Resource Graph service is registered (`az provider register --namespace Microsoft.ResourceGraph`).
+- **`Resource Graph query failure`** – check that the tenant/subscription pair belongs to the same cloud you selected, and verify network egress to the relevant `resource_manager` endpoint (see `_ENVIRONMENT_MAP` in `azure_discovery.utils.azure_clients`).
+- **`VisualizationError: Failed to render HTML graph`** – confirm the `--visualization-output-dir` path exists and is writable; the PyVis writer does not auto-create directories unless it has permissions on each parent.
+- **`401` or `interaction_required` errors** – when running non-interactively, use a service principal credential chain and set `AZURE_CLIENT_SECRET`; the default chain will otherwise attempt to launch an interactive browser flow.
+- **Empty graph output** – verify filters are not mutually exclusive (e.g., mixing include/exclude for the same type) and that `--max-batch-size` in the request (via API) is not set below the minimum (100).
+
+## Known gaps and future opportunities
+
+- **Identity & RBAC coverage** – the tool currently inventories Azure Resource Manager assets only; Entra ID objects, role assignments, and policy definitions are not ingested or visualized.
+- **Change tracking** – runs are stateless; there is no persistence layer or diffing between historical discoveries.
+- **Security context** – vulnerability, compliance, and workload insights (e.g., Defender for Cloud signals) are not integrated.
+- **API hardening** – the FastAPI surface is unprotected (no authN/Z, rate limiting, or request quotas); deploy behind an API gateway or add middleware before production use.
+- **Scale controls** – back-off and throttling are minimal (`throttle_delay_seconds` only); there is no adaptive rate control or batching heuristics for very large tenants.
+
+These items are valuable next steps if you intend to operationalize Azure Discovery beyond ad-hoc investigations.
+
+## Publishing to PyPI (maintainers)
+
+To publish a new version to PyPI:
+
+1. Bump `version` in `pyproject.toml`.
+2. Ensure tests pass: `pip install -e .[dev] && pytest`.
+3. Build: `python -m build`.
+4. Upload: `twine upload dist/azure-discovery-<version>*` (requires PyPI credentials or token).
+
+The package uses a single top-level package **azure_discovery** to avoid namespace conflicts on install. The console script **azure-discovery** is provided by the `[project.scripts]` entry in `pyproject.toml`.

azure_discovery-0.1.0/README.md

@@ -0,0 +1,299 @@
+# Azure Discovery
+
+Azure Discovery is a lightweight Azure tenant mapper that enumerates subscriptions and resources via Azure Resource Graph, normalizes the results, and renders an interactive dependency graph. The tool exposes both a Typer-based CLI (`azure-discovery`) and a FastAPI surface so the same discovery workflow can be automated or embedded in other services.
+
+The package is published on [PyPI](https://pypi.org/project/azure-discovery/) as **azure-discovery** and can be installed with `pip install azure-discovery`.
+
+## Core capabilities
+
+- Builds environment-aware credential chains (Azure CLI + DefaultAzureCredential) with guardrails for unsupported clouds.
+- Queries Azure Resource Graph with include/exclude filters, tag constraints, and resource group scopes.
+- Resolves subscriptions automatically when not provided and de-duplicates resources for consistent graph IDs.
+- Produces JSON summaries, console metrics, and PyVis HTML graphs for quick triage.
+- Offers identical request/response contracts (Pydantic models) across CLI and API, following the Receive an Object, Return an Object (RORO) pattern.
+- Supports all Azure clouds: public, Government (GCC/GCC-H), China, Germany, and Azure Stack.
+
+## Installation
+
+**From PyPI (recommended):**
+
+```bash
+pip install azure-discovery
+```
+
+**With optional development dependencies:**
+
+```bash
+pip install azure-discovery[dev]
+```
+
+**From source (e.g. for development or when embedded in another repo):**
+
+```bash
+git clone https://github.com/maravedi/AzureDiscovery.git
+cd AzureDiscovery
+pip install -e .[dev]
+```
+
+## Package layout
+
+When installed, the package provides the **azure_discovery** Python package:
+
+```
+azure_discovery/
+  __init__.py       # run_discovery, AzureDiscoveryRequest, AzureDiscoveryResponse, etc.
+  cli.py            # Typer command surface (entry point: azure-discovery)
+  api.py            # FastAPI app for /discover and visualization endpoints
+  orchestrator.py   # Async coordinator for enumeration + visualization
+  adt_types/        # Pydantic models and custom exceptions
+  enumerators/      # Resource Graph query builder and normalization
+  reporting/        # Console logging and HTML/PyVis graph generation
+  utils/            # Azure SDK clients, graph helpers, structured logging
+```
+
+**Programmatic usage:**
+
+```python
+from azure_discovery import run_discovery
+from azure_discovery.adt_types import (
+    AzureDiscoveryRequest,
+    AzureDiscoveryResponse,
+    AzureEnvironment,
+    DiscoveryFilter,
+)
+
+request = AzureDiscoveryRequest(
+    tenant_id="<tenant-guid>",
+    environment=AzureEnvironment.AZURE_GOV,
+    subscriptions=["<sub-id>"],
+    filter=DiscoveryFilter(include_types=["Microsoft.Compute/virtualMachines"]),
+)
+response = await run_discovery(request)
+# response.nodes, response.relationships, response.html_report_path
+```
+
+To pass your own credential (e.g. for sovereign cloud from another app):
+
+```python
+from azure_discovery.enumerators.azure_resources import enumerate_azure_resources
+
+response = await enumerate_azure_resources(request, credential=my_credential)
+```
+
+## Prerequisites
+
+- Python 3.11+
+- Azure CLI 2.60+ (optional, used when `--prefer-cli` is set) or service principal credentials exported as `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_CLIENT_SECRET`
+- Azure Resource Graph access (Reader or above on the subscriptions you plan to scan)
+- Network egress to `management.azure.com` and `api.azure.com` (or the sovereign cloud endpoints you select)
+
+## Required Azure permissions
+
+| Capability | Minimum RBAC role | Scope recommendation |
+| ---------- | ----------------- | -------------------- |
+| Run Resource Graph queries | `Reader`, `Resource Graph Reader`, or any custom role with `Microsoft.ResourceGraph/*/read` | Every subscription you plan to inventory or the parent management group |
+| Auto-discover subscriptions (when `--subscription` is omitted) | `Reader` on the management group or `Directory.Read.All` consent for service principals | Tenant root (`/providers/Microsoft.Management/managementGroups/<root>`) |
+| Register Microsoft.ResourceGraph (one-time) | `Contributor` or `Owner` | Each subscription being scanned |
+
+The tool never mutates resources, but it cannot enumerate subscriptions or call Resource Graph unless the identity has at least `Reader` at the relevant scope. Grant the narrowest scope that still covers your target estate (for example, a dedicated management group for security tooling).
+
+### Service principal flow (CLI based)
+
+```
+az ad sp create-for-rbac \
+  --name azure-discovery-sp \
+  --role "Reader" \
+  --scopes /subscriptions/<sub-id-1> /subscriptions/<sub-id-2> \
+  --years 1
+
+az role assignment create \
+  --assignee <appId> \
+  --role "Resource Graph Reader" \
+  --scope /subscriptions/<sub-id-1>
+```
+
+Export the emitted `appId`, `tenant`, and `password` as `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_CLIENT_SECRET`. Repeat the role assignment command for every subscription or assign at the management group scope (`/providers/Microsoft.Management/managementGroups/<mg-id>`) to cover multiple subscriptions at once.
+
+### User-assigned permissions (Portal)
+
+1. Open Azure Portal → **Subscriptions** → select each target subscription.
+2. Navigate to **Access control (IAM)** → **Add** → **Add role assignment**.
+3. Pick the `Reader` (or `Resource Graph Reader`) role, then select the user or managed identity that will run AzureDiscovery.
+4. If you want automatic subscription discovery, repeat the assignment at the tenant root management group (visible under **Management groups**). Users need the **Azure RBAC Reader** role there.
+
+### Provider registration and validation
+
+Run the following once per subscription to ensure the Resource Graph service is registered and the identity can query it:
+
+```
+az account set --subscription <sub-id>
+az provider register --namespace Microsoft.ResourceGraph
+az graph query -q "Resources | take 1"
+```
+
+Successful output from `az graph query` confirms both the provider registration and the assigned role. If the command fails with `AuthorizationFailed`, double-check the scope of the role assignments and replicate them for every subscription you intend to scan.
+
+## Getting started
+
+1. **Install** (see [Installation](#installation) above).
+
+2. **Authenticate to Azure**
+
+   - Interactive: `az login --tenant <tenant-id>` and, if multiple tenants, `az account set --subscription <sub-id>`.
+   - Service principal: export `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`, and (optionally) `AZURE_SUBSCRIPTION_ID`.
+   - For sovereign clouds (e.g. Azure Government): set `az cloud set --name AzureUSGovernment` and log in; or use a service principal with the appropriate authority.
+
+3. **Run the CLI**
+
+   After install, the `azure-discovery` console script is on your PATH:
+
+   ```bash
+   azure-discovery discover \
+     --tenant-id <tenant-guid> \
+     --subscription <sub-id-1> --subscription <sub-id-2> \
+     --include-type "Microsoft.Compute/virtualMachines" \
+     --resource-group core-infra \
+     --required-tag environment=prod \
+     --visualization-output-dir artifacts/graphs
+   ```
+
+   **Run as a module from source** (from the repo root):
+
+   ```bash
+   python -m azure_discovery.cli discover --help
+   python -m azure_discovery.cli discover --tenant-id <tenant-guid> --environment azure_gov [options...]
+   ```
+
+   The command prints the structured `AzureDiscoveryResponse` JSON and writes an interactive HTML graph under `artifacts/graphs/`.
+
+4. **Run the API (optional)**
+
+   ```bash
+   uvicorn azure_discovery.api:app --host 0.0.0.0 --port 8000 --reload
+   ```
+
+   - Health check: `curl http://localhost:8000/healthz`
+   - Discovery: `curl -X POST http://localhost:8000/discover -H "Content-Type: application/json" -d '{"tenant_id": "...", ... }'`
+   - Download visualization: `curl http://localhost:8000/visuals/<file-name> --output graph.html`
+
+## Configuration reference
+
+| Option | Description |
+| ------ | ----------- |
+| `--tenant-id` | Required Entra ID tenant GUID. |
+| `--environment` | Azure cloud (`azure_public`, `azure_gov`, `azure_china`, `azure_germany`, `azure_stack`). |
+| `--subscription/-s` | Repeatable flag to scope runs to explicit subscription IDs. Omit to auto-resolve. |
+| `--include-type` / `--exclude-type` | Filter resource types (case-insensitive). |
+| `--resource-group` | Restrict discovery to named resource groups. |
+| `--required-tag` | Enforce tag key=value pairs (repeatable). |
+| `--prefer-cli` | Place Azure CLI credentials at the front of the chain. |
+| `--visualization-output-dir` | Directory for PyVis HTML output (default `artifacts/graphs`). |
+| `--visualization-file` | Override the generated HTML file name. |
+| `--output/-o` | Write JSON output to file instead of stdout. |
+| `--quiet/-q` | Suppress all logs except errors. |
+| `--format/-f` | Output format: `json` (default) or `json-compact`. |
+
+Programmatic workflows can instantiate `AzureDiscoveryRequest` directly and call `orchestrator.run_discovery`, receiving an `AzureDiscoveryResponse` that contains resolved subscriptions, normalized nodes, inferred relationships, and an optional `html_report_path`.
+
+### Output and logging separation
+
+By default, the CLI writes JSON results to stdout and logs to stderr. This allows clean piping:
+
+```bash
+# Pipe JSON output to jq for filtering
+azure-discovery discover --tenant-id <id> | jq '.discovered_subscriptions'
+
+# Write output to file and suppress logs
+azure-discovery discover --tenant-id <id> --output results.json --quiet
+
+# Compact JSON output for scripting
+azure-discovery discover --tenant-id <id> --format json-compact
+```
+
+## Development
+
+### Quick start
+
+```bash
+# Install with development dependencies
+make install-dev
+
+# Run tests
+make test
+
+# Format code
+make format
+
+# Run linting
+make lint
+
+# Type checking
+make typecheck
+
+# Generate coverage report
+make coverage
+```
+
+### Available make commands
+
+Run `make help` to see all available commands:
+- `make install` - Install package dependencies
+- `make install-dev` - Install with development dependencies
+- `make test` - Run tests with pytest
+- `make lint` - Run ruff linter
+- `make format` - Format code with ruff
+- `make typecheck` - Run mypy type checking
+- `make coverage` - Generate test coverage report
+- `make clean` - Remove build artifacts and cache
+- `make run-api` - Run FastAPI server locally
+
+### Pre-commit hooks
+
+Install pre-commit hooks to automatically run linting and formatting on commit:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+This will run ruff formatting, linting, and mypy type checking before each commit.
+
+### Environment variables
+
+Copy `.env.example` to `.env` and configure your Azure credentials:
+
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+For detailed contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Troubleshooting
+
+- **`AzureClientError: Unable to enumerate subscriptions`** – ensure the identity has at least `Reader` on one subscription and that the Resource Graph service is registered (`az provider register --namespace Microsoft.ResourceGraph`).
+- **`Resource Graph query failure`** – check that the tenant/subscription pair belongs to the same cloud you selected, and verify network egress to the relevant `resource_manager` endpoint (see `_ENVIRONMENT_MAP` in `azure_discovery.utils.azure_clients`).
+- **`VisualizationError: Failed to render HTML graph`** – confirm the `--visualization-output-dir` path exists and is writable; the PyVis writer does not auto-create directories unless it has permissions on each parent.
+- **`401` or `interaction_required` errors** – when running non-interactively, use a service principal credential chain and set `AZURE_CLIENT_SECRET`; the default chain will otherwise attempt to launch an interactive browser flow.
+- **Empty graph output** – verify filters are not mutually exclusive (e.g., mixing include/exclude for the same type) and that `--max-batch-size` in the request (via API) is not set below the minimum (100).
+
+## Known gaps and future opportunities
+
+- **Identity & RBAC coverage** – the tool currently inventories Azure Resource Manager assets only; Entra ID objects, role assignments, and policy definitions are not ingested or visualized.
+- **Change tracking** – runs are stateless; there is no persistence layer or diffing between historical discoveries.
+- **Security context** – vulnerability, compliance, and workload insights (e.g., Defender for Cloud signals) are not integrated.
+- **API hardening** – the FastAPI surface is unprotected (no authN/Z, rate limiting, or request quotas); deploy behind an API gateway or add middleware before production use.
+- **Scale controls** – back-off and throttling are minimal (`throttle_delay_seconds` only); there is no adaptive rate control or batching heuristics for very large tenants.
+
+These items are valuable next steps if you intend to operationalize Azure Discovery beyond ad-hoc investigations.
+
+## Publishing to PyPI (maintainers)
+
+To publish a new version to PyPI:
+
+1. Bump `version` in `pyproject.toml`.
+2. Ensure tests pass: `pip install -e .[dev] && pytest`.
+3. Build: `python -m build`.
+4. Upload: `twine upload dist/azure-discovery-<version>*` (requires PyPI credentials or token).
+
+The package uses a single top-level package **azure_discovery** to avoid namespace conflicts on install. The console script **azure-discovery** is provided by the `[project.scripts]` entry in `pyproject.toml`.

azure_discovery-0.1.0/azure_discovery/__init__.py

@@ -0,0 +1,33 @@
+"""Azure Discovery: Azure tenant discovery and visualization via Resource Graph.
+
+This package can be installed from PyPI as ``azure-discovery`` and used as:
+
+  pip install azure-discovery
+  azure-discovery discover --tenant-id <id> --subscription <sub-id>
+
+Programmatic usage:
+
+  from azure_discovery import run_discovery
+  from azure_discovery.adt_types import AzureDiscoveryRequest, AzureDiscoveryResponse
+"""
+
+from .orchestrator import run_discovery
+from .adt_types import (
+    AzureDiscoveryRequest,
+    AzureDiscoveryResponse,
+    AzureEnvironment,
+    DiscoveryFilter,
+    ResourceNode,
+    ResourceRelationship,
+)
+
+__all__ = [
+    "run_discovery",
+    "AzureDiscoveryRequest",
+    "AzureDiscoveryResponse",
+    "AzureEnvironment",
+    "DiscoveryFilter",
+    "ResourceNode",
+    "ResourceRelationship",
+]
+__version__ = "0.1.0"